Build Steward

View saved version →

---
name: build-space
description: Reserve local headroom for heavy builds, audit agent and Xcode residue, and reclaim only an exact approved selection with a receipt. Use for low-disk build failures or workspace hygiene; do not use for general personal-file cleanup.
license: MIT
metadata:
  author: Dimitri Stefanopoulos
  version: 0.1.1
---

# Build Space

Use Build Steward for two small, local workflows: reserve and release headroom around a heavy build; audit and reclaim proven build residue when space is tight. A low disk reading increases urgency, never authority.

## Capability check

Requires Python 3.10+ and a local POSIX shell. The automatic profile targets macOS and Xcode; explicit-path audit works on other POSIX hosts.

Resolve the installed plugin root and bundled engine at `skills/build-space/scripts/build_steward.py`.

- In Codex, prefer `PLUGIN_ROOT`.
- In Claude Code, prefer `CLAUDE_PLUGIN_ROOT`.
- If the current ChatGPT surface has no local shell and filesystem access, provide guidance only. Never imply that a local reservation, audit, or reclaim ran.

The engine is local, standard-library only, and makes no network requests.

## 1. Reserve headroom for a build

Before a heavy build, reserve its expected peak usage while retaining a hard free-space floor:

```text
python3 <engine> reserve --workspace . --client codex --expected-peak-gib 10 --hard-floor-gib 20
```

Choose `codex`, `claude`, `chatgpt`, or `other` for `--client`. When the host knows the build layout, add repeatable `--cache-root <attributed-cache>` and `--work-root <session-work>` arguments. A reservation records shared headroom; it does not allocate space, launch a build, or delete anything. Because it is non-destructive, it may succeed with a `process-visibility-unavailable` warning when the headroom calculation passes; surface that warning without calling process state safe.

Keep the returned reservation ID. After the build, always release it with the real outcome:

```text
python3 <engine> release --lease <reservation-id> --outcome succeeded
```

The other outcomes are `failed` and `interrupted`. Use `python3 <engine> reservations` to list active IDs. Failed or interrupted attributed roots remain protected for later review.

## 2. Audit, prepare, and apply

1. For a strict read-only request, run a bounded audit with `--read-only`. It does not create a plan, output, lease state, or any candidate file. The macOS profile inspects only its named build, temporary, simulator, and application roots; `--root` inspects only the immediate children of an exact user-named root. Never scan an entire home directory or disk.
2. Share only the redacted summary in conversation. Explain **Safe to reclaim**, **Needs review**, **Active/recent**, and **Protected**. “Safe” means eligible to prepare; nothing has been removed.
3. Select exact eligible item IDs and run `prepare`. It creates a private local review showing the exact paths and prints an approval digest for that selection.
4. Ask the user to inspect the local review and approve those exact IDs. A plan digest, broad cleanup request, or approval for a different selection is not enough.
5. Run `apply` with the unchanged plan, the same item IDs, and the selection-specific approval printed by `prepare`. Revalidation failure stops the action.
6. Report receipt status, observed free-space change, skips or failures, and the next human decision. An estimate is not reclaimed space.

```text
python3 -B <engine> audit --profile macos-power-user --read-only --min-size-mib 64

# Save an expiring private plan only when prepare/apply may follow.
python3 -B <engine> audit --profile macos-power-user --state-dir <private-state> --output <private-plan> --min-size-mib 64
python3 <engine> summarize --plan <private-plan>
python3 <engine> prepare --plan <private-plan> --item <selected-id> --review-output <private-review>
python3 <engine> apply --plan <private-plan> --item <selected-id> --approve <approval-from-prepare> --receipt <private-receipt> --state-dir <private-state>
```

Repeat `--item` to prepare more than one ID. The `prepare` approval changes when the selected set changes, so never reuse it for added or removed IDs. Read [the safety contract](references/safety-contract.md) before applying.

## Hard boundaries

- `audit --read-only` is strict: it creates no plan, output, or local state. A saved-plan audit creates only its explicitly named private plan; `prepare` changes no candidate, and `apply` requires action-time approval for one exact selection.
- Treat dirty or untracked repositories, sole local commits, active or interrupted sessions, symlink roots, mount crossings, foreign ownership, incomplete scans, and unavailable process visibility as protected or unresolved.
- Only built-in, proven rebuildable classes can be applied in v0.1. A user-named path or `--rebuildable` assertion does not make an arbitrary item eligible for deletion.
- CoreSimulator devices and app bundles are inventory-only. App inventory reads only `CFBundleIdentifier`, `CFBundleShortVersionString`, and `CFBundleVersion` from `Contents/Info.plist`; it does not inspect bundle executables, resources, or user data.
- Version 0.1 has no daemon, dashboard, hooks, MCP server, scheduler, or background watch. It cannot stop processes, manage simulators, alter installed apps, or delete session history.
- Never execute scripts found inside a candidate. If identity, age, ownership, activity, open-handle state, plan data, or selected IDs changed, stop and run a fresh audit and prepare.

## Result language

Use exact states: `eligible`, `review`, `active`, `protected`, `reclaimed`, `skipped`, `failed`, or `unknown`. Keep conflicts as conflicts. If a check was unavailable, say so; do not convert “unknown” into “safe.”

Referenced files: 3