77 lines
7.4 KiB
Markdown
77 lines
7.4 KiB
Markdown
# Goal: Trained implementer, forked per block — headless forks inside Spire (version TBD)
|
|
|
|
**Set**: 2026-10-16, Igor session [2026-10-15-21-grotto-work](../journals/2026-10-15-21-grotto-work.md)
|
|
**Relates to**: [lean-athanor-0.2.1](./lean-athanor-0.2.1.md) — its "Trunk and forks is tested, not assumed" criterion. This goal restores the user's original shape, which 0.2.0 lost (see provenance report below).
|
|
**Inputs**:
|
|
- [Athanor trunk/fork provenance](../reports/2026-10-15-23-athanor-trunk-fork-provenance.md)
|
|
- [Headless fork sessions: mechanics + follow-up](../research/2026-10-16-00-claude-headless-fork-sessions.md)
|
|
- [Spire vs. superpowers experiment](../reports/2026-10-15-22-spire-vs-superpowers-plan-and-build-experiment.md), §5 (accounting gaps, inline blocks)
|
|
|
|
## Intent (user, 2026-10-15/16)
|
|
|
|
The Athanor learns plans, design and implementer reports, not code. For hard work it trains **one** implementer early with background information, then **forks that implementer** once per block or subsection. The forks need only a small "you are continuing" brief. Bookkeeping (cache lifetime, which base is warm, tokens) is deterministic, done by a tool and not by agent attention. Solve it inside Spire now, without waiting for Dirigent. A Dirigent harness or MCP tool can come later and take this over.
|
|
|
|
## Success criteria
|
|
|
|
### Mechanism
|
|
- [ ] Spire ships a small deterministic helper (a script in the skill; MCP is a later option) that owns the `claude -p` command line. It covers: train a base, fork the base with a brief, update the base, report usage, and list or expire bases.
|
|
- [ ] Each base is stored with its full launch fingerprint: binary path, full model id, flags, permission mode and tools, cwd, agent file. Every fork reuses that fingerprint exactly, because any difference loses the prompt cache (research F-table).
|
|
- [ ] The environment is scrubbed of Desktop-host variables before launch; auth works without `--bare` or with an explicit key (user's choice).
|
|
- [ ] Per call, the helper returns the real model (`modelUsage`, not the init event), the tokens per usage column, and the per-fork delta cost. It writes them to the run log, so per-block cost is known, including for work the Athanor would previously have done inline.
|
|
|
|
### Bookkeeping
|
|
- [ ] The registry records the last cache hit per base. "Keep warm / let expire / re-train" is computed from the cache lifetime (1 h on a subscription within plan usage, otherwise 5 min; a hit resets it) and the base's training cost. It is not left to the agent's judgment.
|
|
|
|
### Process
|
|
- [ ] The Athanor procedure (athanor.md, implementation SKILL.md) describes the trained-implementer shape. In it, the Athanor holds the plan, design, trunk notes and reports, and does not read code itself.
|
|
- [ ] Forks don't see each other's work. The procedure says who keeps the base current: re-basing it with a summary of what changed between blocks, or a delta brief for each fork. It also says when each applies.
|
|
- [ ] A project agent file can specialize the trained implementer (`--agent` / `--agents`).
|
|
- [ ] The spawning reference gets the verified rows from today's research (Agent-tool fork copies the caller only; forks can't fork; fork mode makes everything background; headless fork mechanics; nested-process depth is per process and fails silently).
|
|
|
|
### Proven, not assumed
|
|
- [ ] Trial on a real multi-block plan comparing the trained-implementer forks against the current shape on quality, tokens (all four columns, priced) and wall time, with every orchestrator counted, including the root.
|
|
|
|
## Open decisions (user)
|
|
|
|
- Where the helper lives: the implementation skill (assumed from "inside the skill"), or its own Spire skill.
|
|
- Update the base vs. delta brief per fork as the default.
|
|
- Auth: OAuth with a scrubbed env vs. `--bare` + API key.
|
|
- Whether headless forks replace Agent-tool fork options in athanor.md or sit beside them.
|
|
- Plan mode upgrades Haiku to Sonnet silently: accept as a floor, or always pass an explicit model.
|
|
|
|
### Decided 2026-10-16 (user, session [2026-10-15-21-grotto-work](../journals/2026-10-15-21-grotto-work.md))
|
|
|
|
- **Location**: its own Spire skill, which the implementation skill references. This makes it easier to lift into Dirigent later.
|
|
- **Fork sync**: by default each fork gets a delta brief (what changed since the base). At phase boundaries, or when the delta grows, the Athanor updates the base and forks from the new one.
|
|
- **Auth**: OAuth with a scrubbed env (subscription → 1 h cache lifetime). No `--bare`.
|
|
- **Agent-tool forks**: replaced. Complex blocks go to forks of the trained implementer, and fresh Agent-tool agents stay for mechanical or distant blocks. The Agent-tool fork path is dropped from athanor.md.
|
|
- **Model**: always an explicit full model id. The fingerprint requires it anyway, which also sidesteps plan mode's silent Haiku→Sonnet upgrade. *(Igor's default, not asked; user may override.)*
|
|
|
|
### Decided 2026-10-16, naming (user)
|
|
|
|
- A headless worker launched by the helper is a **gremlin**. The skill becomes `spire:gremlins` and the helper `gremlins.py`; the env marker, state folder and ledger names follow.
|
|
- The command that creates one is **`spawn`**. Forking the base (`--resume <base> --fork-session`) is one *way* to spawn. Keeping `spawn` separate from `fork` leaves room for other spawn methods later.
|
|
- The trained session stays the **base**. "Mogwai" was considered and dropped (trademark-adjacent, a second invented word).
|
|
- When: a mechanical rename block at the start of Phase 3, before the skill and procedure text is written, so the release ships with the final names.
|
|
|
|
### Decided 2026-10-16, platforms (user)
|
|
|
|
- 0.3.0 ships **Windows-only**. On any other platform, `where` fails closed (`ok: false` with a clear reason), and the Athanor falls back to the 0.2.2 shape (fresh agents, no gremlins). SKILL.md says so.
|
|
- Linux testing is a follow-up (WSL Ubuntu and Docker are available on the dev host). macOS stays unsupported until someone can test it.
|
|
|
|
### Amended 2026-10-16, release gating (user)
|
|
|
|
- 0.3.0 is **not released from Windows alone**. The work stays on the `headless-forks` branch, which gets pushed but not merged. When the Windows phases are done, an Igor on a native Linux machine and one on a Mac check out the branch, test, fix their platform and lift the fail-closed gate for it. Only then is the branch merged and released. WSL is fine for development.
|
|
- The Windows build still ends with a handoff document for those Igors (what to test, known POSIX gaps M14 and the /proc tree walk, the smoke recipe).
|
|
- Strongly suggested by the user: pick this up as Rust work right away as well (see reports/2026-10-16-01-session-harness-app-forms.md). Not started yet.
|
|
|
|
### Decided 2026-10-16, platform seam (user)
|
|
|
|
- Phase 3 adds a refactor block. All platform-specific code (detached spawn, process table, tree kill, liveness, locks, path normalisation) moves behind one interface, with `WindowsPlatform` and `PosixPlatform` implementations. No scattered `IS_WINDOWS` branches stay outside it. The green Windows suite guards the refactor.
|
|
- Plus: a path-form test matrix (`C:\…`, `C:/…`, MINGW `/c/…`, `/tmp/…`, UNC, WSL `/mnt/c/…`) and a WSL check: does the helper run under WSL Ubuntu, and does PATH interop wrongly resolve `claude` to the Windows exe? Findings feed the Linux and Mac handoff. WSL stays fail-closed unless it passes.
|
|
|
|
## Later
|
|
|
|
- Dirigent harness / MCP tool takes over the helper's job ("stable for the constables").
|
|
- Token-count access for agents beyond the helper's per-call returns.
|