📝 Add headless-forks goal, design, plan and build plan; session-harness app report

2026-10-16 08:15:44 +02:00
parent a7ce5db3a0
commit d3736898fc
6 changed files with 1549 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 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.)*
+
+## 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.