Update to Build Steward

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 283
    },
    {
      "relative_path": "references/safety-contract.md",
      "size_in_bytes": 4483
    },
    {
      "relative_path": "scripts/build_steward.py",
      "size_in_bytes": 79048
    }
  ],
  "name": "build-space",
  "skill_md_contents": "---\nname: build-space\ndescription: 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.\nlicense: MIT\nmetadata:\n  author: Dimitri Stefanopoulos\n  version: 0.1.1\n---\n\n# Build Space\n\nUse 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.\n\n## Capability check\n\nRequires Python 3.10+ and a local POSIX shell. The automatic profile targets macOS and Xcode; explicit-path audit works on other POSIX hosts.\n\nResolve the installed plugin root and bundled engine at `skills/build-space/scripts/build_steward.py`.\n\n- In Codex, prefer `PLUGIN_ROOT`.\n- In Claude Code, prefer `CLAUDE_PLUGIN_ROOT`.\n- 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.\n\nThe engine is local, standard-library only, and makes no network requests.\n\n## 1. Reserve headroom for a build\n\nBefore a heavy build, reserve its expected peak usage while retaining a hard free-space floor:\n\n```text\npython3 <engine> reserve --workspace . --client codex --expected-peak-gib 10 --hard-floor-gib 20\n```\n\nChoose `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.\n\nKeep the returned reservation ID. After the build, always release it with the real outcome:\n\n```text\npython3 <engine> release --lease <reservation-id> --outcome succeeded\n```\n\nThe other outcomes are `failed` and `interrupted`. Use `python3 <engine> reservations` to list active IDs. Failed or interrupted attributed roots remain protected for later review.\n\n## 2. Audit, prepare, and apply\n\n1. 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.\n2. 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.\n3. 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.\n4. 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.\n5. Run `apply` with the unchanged plan, the same item IDs, and the selection-specific approval printed by `prepare`. Revalidation failure stops the action.\n6. Report receipt status, observed free-space change, skips or failures, and the next human decision. An estimate is not reclaimed space.\n\n```text\npython3 -B <engine> audit --profile macos-power-user --read-only --min-size-mib 64\n\n# Save an expiring private plan only when prepare/apply may follow.\npython3 -B <engine> audit --profile macos-power-user --state-dir <private-state> --output <private-plan> --min-size-mib 64\npython3 <engine> summarize --plan <private-plan>\npython3 <engine> prepare --plan <private-plan> --item <selected-id> --review-output <private-review>\npython3 <engine> apply --plan <private-plan> --item <selected-id> --approve <approval-from-prepare> --receipt <private-receipt> --state-dir <private-state>\n```\n\nRepeat `--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.\n\n## Hard boundaries\n\n- `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.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n\n## Result language\n\nUse 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.”\n"
}