README.md

# Build Steward

**Know what’s safe. Reclaim with receipts.**

Build Steward is a local-first plugin for power users running many Codex, ChatGPT, Claude Code, Xcode, and automation sessions on one machine. It audits the build residue those workflows leave behind, separates proven rebuildable data from live or ambiguous work, and can reclaim only exact items approved from an expiring plan.

It is intentionally not a general disk cleaner.

## What v0.1.1 handles

- Xcode DerivedData candidates and temporary Xcode distribution pipelines
- large agent/session directories under explicitly inspected temporary roots
- repository and worktree protection
- simulator-state inventory without deletion
- duplicate or rollback-looking app inventory without deletion
- plan digest, object-identity revalidation, executor lock, and before/after receipt

The automatic profile is macOS/Xcode focused. Explicit-path inventory works on other POSIX systems with Python 3.10+.

## Safety defaults

- `audit --read-only` creates no plan, output, or local state; it only prints a redacted in-memory summary.
- A saved-plan audit writes only its explicitly named private plan; no target mutation occurs during inventory.
- No network calls, telemetry, package install, or background service.
- No file-content reads; inventory hashes filesystem metadata only.
- Exact roots and opaque item IDs; no glob or parent cleanup.
- Process/open-handle uncertainty stops cleanup.
- Dirty repositories, version-control roots, simulator devices, and app bundles stay protected.
- Final receipts distinguish estimated bytes from observed free-space change.

## Host behavior

Codex and Claude Code can run the bundled local engine when the user grants their normal shell/filesystem permissions. The OpenAI plugin listing is shared by ChatGPT and Codex, but a ChatGPT surface without local execution can only guide an audit or analyze a user-supplied redacted summary; it must not claim it changed the machine.

## Local development

From this plugin directory:

```sh
python3 skills/build-space/scripts/build_steward.py --version
python3 skills/build-space/scripts/build_steward.py preflight --path . --required-gib 20
```

Test Claude Code directly from the repository’s marketplace root:

```sh
claude --plugin-dir ./plugins/build-steward
```

Run all deterministic tests from the repository root:

```sh
python3 -m unittest discover -s tests -v
```

## Status

Version 0.1.1 is a skills-plus-local-engine release. Hooks, scheduled monitoring, automatic policies, application management, and simulator deletion are deliberately out of scope.

Published by Dimitri Stefanopoulos through [FibonacciAi](https://github.com/FibonacciAi). See the [repository](https://github.com/FibonacciAi/build-steward), [privacy policy](https://github.com/FibonacciAi/build-steward/blob/main/docs/privacy.md), [terms](https://github.com/FibonacciAi/build-steward/blob/main/docs/terms.md), and [issue tracker](https://github.com/FibonacciAi/build-steward/issues).