diff --git a/docs/archive/PLAN_HISTORY.md b/docs/archive/PLAN_HISTORY.md index a4e1a3865..d83fae78b 100644 --- a/docs/archive/PLAN_HISTORY.md +++ b/docs/archive/PLAN_HISTORY.md @@ -3,6 +3,187 @@ This file is the active POC-line plan archive for `memory/PLAN.md`. Legacy pre-`next` history was moved out of the live docs tree with the old archived implementation. +## 2026-07-02 Sync archive + +Archived from `memory/PLAN.md` during the 2026-07-02 `ln-sync`, at the close of the `orchestrator-cutover` arc (FE-1089 → FE-1118, PR stack #274/#275/#278/#279/#282, branch tip `ka/fe-1118-executor-host-promotion`). Durable architecture lives in `memory/SPEC.md` D101-L / I56-L and the co-located `src/executor/TOPOLOGY.md` + `src/app/TOPOLOGY.md`; these are the completion records plus retired full definitions. + +**Reference-drift note:** in the archived bodies below, in-body citations of `D99-L` ("land-substrate finding" / "execution-ports refinement") and `I52-L` ("one explicit side effect per tool") predate the current register numbering; the corresponding live rows are `D101-L` (executor cutover) and `I56-L` (bounded execute-mode ports). Live `D99-L`/`I52-L` mean reviewed-advisory-capture settlement and basis/settlement orthogonality. + +### elicitor-capability-spine — retired arc block + +### elicitor-capability-spine — ✓ done + +- **Goal:** build `capture` / `generate` / `project` over the elicitor capability spine without reviving the retired `strategy` / `lens` / `method` runtime axes (A35-L), on top of the skill-substrate arc. +- **Members:** + - `capture` ✓ done via generalized capture (D80-L–D82-L). + - `generate` ✓ done through promoted real-model fan-out evidence (FE-1059): one plane-parameterized `generate-proposal` method, `present_candidates` unstubbed, fan-in as method conduct (`pick` / `synthesize` / `compose`), promoted I51-L no-write evidence. + - `project` ✓ done via FE-1085: distinct first-level live `project` guidance derives downstream plane material from accepted graph anchors over existing exchange and review-set seams (D100-L). + - `acquire` rides the completed subagent-reconciliation substrate (A34-L), not its own frontier. +- **Done-definition:** all three capabilities have live non-stub homes/evidence appropriate to their seam: `capture` and `generate` carry promoted model/runtime evidence; `project` is prompt-resource guidance only, witnessed through the live manifest/prompt path because FE-1085 adds no product tool or schema seam. +- **Anchors:** D95-L, D96-L; A31-L–A35-L; I51-L. + +### Retired frontier definitions (orchestrator-cutover arc + done elicitor frontiers) + +### orchestrator-alpha-cutover + +- **Name:** Reconcile executor with alpha branch +- **Linear:** [FE-1089](https://linear.app/hash/issue/FE-1089/reconcile-executor-with-alpha-branch) +- **Branch:** `ka/fe-1089-orchestrator-alpha-cutover` +- **Kind:** structural / execute-mode orchestration cutover +- **Status:** active; read-only executor footholds active, descriptive lifecycle scaffold registered but gated. +- **Certainty:** proving. +- **Current execution pointer:** first real execution boundary for agent/test runs; keep host git mutation, real promotion, and land out of scope until explicitly accepted. +- **Objective:** Cut the old `main` cook orchestrator off the divergent stable branch and re-grow it natively on alpha's CODE/executor substrate. The current active bridge is `ExecutionSpecSnapshot v1` plus read-only executable-plan projections. Bounded artifact/lifecycle tools are registered and test-covered on this branch but stay inactive in CODE mode until the real-execution stack lands, avoiding independently reachable placeholders. +- **Acceptance:** + - ✓ Side-effect-free tools project/check/outline/draft/preview selected-spec execution input. + - ✓ Bounded artifact tools write only declared files under `.brunch/execution-reports` or `.brunch/cook`. + - ✓ Run/worktree/source/report/slice/result/Petri/promotion-preparation tools descriptively advance run metadata with one explicit side effect per step. + - Next: real agent/test execution boundary. +- **Traceability:** D39-L, D40-L, D58-L, D90-L, D91-L, D92-L, D93-L, D98-L, D101-L / I49-L, I50-L, I56-L; `src/executor/TOPOLOGY.md`, `src/.pi/extensions/TOPOLOGY.md`. + +### orchestrator-tool-port + +- **Name:** Port cook orchestration into CODE/executor tools +- **Linear:** [FE-1107](https://linear.app/hash/issue/FE-1107/port-cook-orchestration-into-codeexecutor-tools) +- **Branch:** tbd +- **Kind:** structural / execute-mode tool boundary +- **Status:** superseded as a separate frontier by `orchestrator-alpha-cutover` / FE-1089. +- **Certainty:** proving. +- **Objective:** Historical precursor for porting reusable cook logic into CODE/executor tools. FE-1089 now owns the active alpha cutover. +- **Acceptance:** See `orchestrator-alpha-cutover`. +- **Traceability:** D39-L, D40-L, D90-L, D91-L, D92-L, D93-L, D98-L, D101-L / I49-L, I56-L. + +### executor-sandbox + +- **Name:** Reconcile executor sandbox worktrees and test runner ports +- **Linear:** [FE-1109](https://linear.app/hash/issue/FE-1109/reconcile-executor-sandbox-worktrees-and-test-runner-ports) — reconcile executor sandbox worktrees and test runner ports +- **Branch:** `ka/fe-1109-cook-sandbox` (created from `ka/fe-1089-orchestrator-alpha-cutover`; Graphite tracking pending while PR #274 remains open/non-Graphite) +- **Kind:** structural / execute-mode runner substrate (`orchestrator-cutover` arc) +- **Status:** built; both port slices (`GitWorktreePort`, `TestRunnerPort`) delivered. Ready to tie off once reviewed. +- **Current execution pointer:** frontier complete — real git worktree + real verify-subprocess ingestion both landed; next arc frontier is `executor-agent-runner`. +- **Certainty:** proving. +- **Why now / unlocks:** the FE-1089 chain proved the cook lifecycle shape with `fs`-only descriptive footholds, but every step simulates execution (copied-dir "worktree", prewritten-ingested agent/test results, no git). A meaningful run needs a real, runnable, verifiable workspace first. This is the lowest-blast-radius real-execution layer (subprocess only, no LLM). +- **Design verdict (chosen):** real execution enters executor core through an **injected capability-port bag**, not a deep environment object or an effect-program rewrite. Port *types* live in `src/executor/execution-ports.ts` (`ExecutionPorts` = `{ GitWorktreePort, AgentRunnerPort, TestRunnerPort, GitLandPort }`); real implementations live in the app layer (`src/app/git-worktree-port.ts`, and future `src/app/*-port.ts`) and are injected by the Pi adapters, preserving the D52-L/I52-L boundary (no git/subprocess in core). See SPEC D99-L execution-ports refinement. +- **Objective:** Implement and inject `GitWorktreePort` (real `git worktree add`, replacing `worktree.ts`'s `mkdir`) and `TestRunnerPort` (real verify subprocess), so a run becomes a real, runnable, verifiable git workspace — keeping the one-explicit-side-effect-per-tool discipline (I52-L). +- **Acceptance (to refine via `ln-scope`):** + - Done: `src/executor/execution-ports.ts` defines the `ExecutionPorts` bag as types only; executor core imports no git/subprocess. + - Done: `GitWorktreePort` makes the per-run worktree a real `git worktree`, replacing the `mkdir` substrate in `worktree.ts`; app-layer `src/app/git-worktree-port.ts` runs `git worktree add --detach HEAD` and the Pi adapter injects it. If the worktree fails, run metadata is not advanced. + - Done: `TestRunnerPort` runs the real verify subprocess (`npm run verify`) in the run worktree and ingests its true verdict/exit code, replacing the prewritten `test-result.json` ingest path; app-layer `src/app/test-runner-port.ts` owns the subprocess. A failing verdict still advances the run; a runner that cannot execute (`test_run_failed`) leaves metadata unchanged. + - Done: app-layer implementations under `src/app/*-port.ts`; adapters inject the bag; focused tests cover the port contracts. +- **Traceability:** D39-L, D40-L, D52-L, D90-L, D91-L, D92-L, D93-L, D98-L, D99-L (land-substrate finding + execution-ports refinement) / I49-L, I52-L; depends on `orchestrator-alpha-cutover`; `src/executor/TOPOLOGY.md`. + +### executor-agent-runner + +- **Name:** Reconcile executor agent runner +- **Linear:** [FE-1111](https://linear.app/hash/issue/FE-1111/reconcile-executor-agent-runner) — reconcile executor agent runner +- **Branch:** `ka/fe-1111-executor-agent-runner` (stacked on `ka/fe-1109-cook-sandbox`) +- **Kind:** structural / execute-mode runner substrate (`orchestrator-cutover` arc) +- **Status:** done. +- **Current execution pointer:** none — frontier complete. Port contract, sealed worker tracer, default runner composition proof, and faux-provider witness probe built (`memory/cards/executor-agent-runner--agent-runner-port.md`, `memory/cards/executor-agent-runner--sealed-code-worker.md`, `memory/cards/executor-agent-runner--default-runner-composition.md`, `memory/cards/executor-agent-runner--worker-witness-probe.md`). +- **Certainty:** proving. +- **Why now / unlocks:** with a real sandbox, a run can finally produce real changes. This frontier introduces the only LLM-bearing port and reuses the sealed subagent substrate rather than a new agent runtime. +- **Objective:** Implement and inject `AgentRunnerPort` so a run actually produces real diffs via a code-owned write-capable CODE worker reusing the D90-L–D93-L sealed subagent substrate, retiring the prewritten-ingest tool (`execute_agent_result`) in favor of the real runner. +- **Acceptance (to refine via `ln-scope`):** + - Done: `AgentRunnerPort` has concrete arg/result types; `execute_agent_result` invokes it for the active slice's worktree/request/result paths and no longer reads a prewritten `result.json`. + - Done: Pi registration injects `AgentRunnerPort`; the default app-layer runner fails closed until the real worker lands. + - Done: `AgentRunnerPort` implementation (app layer) launches the sealed `worker` subagent over the `executor-sandbox` worktree under the D90-L–D93-L grant model, with bounded `read` + `write_worktree_file` authority and no shell/nesting grant. + - Done: default Pi composition wires `execute_agent_result` through the app-composed `AgentRunnerPort` when sealed subagent deps are injected; no explicit fake port is required. + - Done: `execute_agent_result` is re-grounded on the real runner; no prewritten `result.json` ingest remains on this layer. + - Done: focused tests cover the runner contract and observe a real sandbox-worktree file change through the deterministic fake worker path. + - Done: `src/probes/executor-agent-runner-witness.ts` provides a runnable faux-provider witness and portable artifact writer for the default runner → sealed worker → worktree write path. + - Done: faux-provider witness is the right oracle for runner wiring/tool authority; real-provider content-quality evidence is not a frontier blocker. +- **Traceability:** D39-L, D40-L, D52-L, D90-L, D91-L, D92-L, D93-L, D98-L, D99-L / I49-L, I52-L; depends on `executor-sandbox`. + +### executor-promotion + +- **Name:** Reconcile run-local executor promotion +- **Linear:** [FE-1112](https://linear.app/hash/issue/FE-1112/reconcile-run-local-executor-promotion) — reconcile run-local executor promotion +- **Branch:** `ka/fe-1112-executor-promotion` (stacked on `ka/fe-1111-executor-agent-runner`) +- **Kind:** structural / execute-mode runner substrate (`orchestrator-cutover` arc) +- **Status:** done. +- **Current execution pointer:** none — frontier complete. Run-local `GitLandPort` and promotion metadata recovery built (`memory/cards/executor-promotion--run-local-git-land-port.md`, `memory/cards/executor-promotion--promotion-metadata-recovery.md`); host promotion remains explicitly deferred beyond this frontier. +- **Certainty:** proving. +- **Why now / unlocks:** only once a run produces real, verified diffs does a truthful land have a source (D99-L land-substrate finding). This layer lands last so the hard-to-reverse git mutation is the final, independently-reviewable step. +- **Objective:** Implement and inject `GitLandPort` so a run's real diffs are promoted — run-local promotion first, host promotion later — consuming/validating the Petri + promotion artifacts rather than re-deriving run state. +- **Acceptance (to refine via `ln-scope`):** + - Done: `GitLandPort` implementation (app layer) performs a run-local promotion of verified worktree diffs first; host promotion is a later, explicitly-accepted slice. + - Done: the promotion path consumes existing Petri/run metadata and writes `promotion.json` with the run-local commit SHA rather than re-deriving run state. + - Done: `execute_status` `pendingTools` drops `land` because real run-local git promotion exists; host promotion remains explicitly deferred beyond this frontier. + - Done: recover/idempotently complete promotion metadata if the run-local git commit succeeds but `promotion.json` or `run.json` persistence fails before status advancement. +- **Traceability:** D39-L, D40-L, D52-L, D98-L, D99-L (land-substrate finding) / I49-L, I52-L; depends on `executor-agent-runner`; `src/executor/TOPOLOGY.md`. + +### executor-host-promotion + +- **Name:** Reconcile host executor promotion +- **Linear:** [FE-1118](https://linear.app/hash/issue/FE-1118/reconcile-host-executor-promotion) — reconcile host executor promotion +- **Branch:** `ka/fe-1118-executor-host-promotion` (stacked on `ka/fe-1112-executor-promotion`) +- **Kind:** structural / execute-mode host mutation seam (`orchestrator-cutover` arc) +- **Status:** built; ready for tie-off. +- **Current execution pointer:** none — review hardening is complete. +- **Certainty:** proving. +- **Why now / unlocks:** FE-1112 proves real run-local promotion, but executor output remains trapped inside the run worktree until a separate, explicit host-apply seam exists. This is the externally visible hard-to-reverse boundary and must start with a no-mutation preflight. +- **Objective:** Apply a verified run-local promotion commit/diff back to the host project branch through an explicit host-promotion path. Host mutation must be deliberate, validated, and recoverable; first slice is preflight only. +- **Acceptance (to refine via `ln-scope`):** + - Done: Host preflight consumes existing run metadata and `promotion.json`; it validates the promoted commit SHA exists in the run worktree. + - Done: Host preflight computes/reports the diff that would be applied to the host branch without mutating host files, branches, refs, or index state. + - Done: Helper-level host apply performs explicit accepted mutation only after preflight passes; it mutates host files only and does not commit, create refs, switch branches, or stage the host index. + - Done: CODE-mode Pi tools expose host preflight and accepted host apply with explicit acceptance, active-tool policy inclusion, `execute_status` visibility, and machine-readable side-effect details. + - Done: Review hardening proves the real `git diff --binary` / `git apply --check` / `git apply` path against temp repos, narrows apply result states, and removes the dead report-path alias. +- **Traceability:** D52-L, D99-L / I52-L; depends on `executor-promotion`; `src/executor/TOPOLOGY.md`. + +### elicitor-project + +- **Name:** Elicitor `project` capability — cross-plane derivation +- **Linear:** [FE-1085](https://linear.app/hash/issue/FE-1085) — elicitor project capability design +- **Branch:** `ln/fe-1085-elicitor-project-prep` +- **Kind:** structural / capability +- **Status:** done. +- **Certainty:** proving. +- **Retires:** A33-L by materializing the branch-implied distinct `project` surface into canon and the live skill manifest. +- **Lights up:** requirements/design/oracle cross-plane derivation over the frozen elicitor capability axes. +- **Objective:** Materialize cross-plane derivation as a distinct first-level live `project` move over the existing exchange triad and review-set commitment path, without introducing a new tool, schema family, or direct graph-write seam. +- **Acceptance:** done. + - `memory/SPEC.md`, `memory/PLAN.md`, and the touched parent topology homes state one consistent shape: `project` is a distinct first-level live skill home, not a `generate` branch. + - The live skill manifest includes `project`, and its guidance covers accepted-graph derivation lanes such as intent → design and design → oracle. + - `project` reuses `present_candidates`, `request_response`, `present_review_set`, and the existing `map` / review-set commitment boundary; it does not add a new product tool or exchange schema family. + - D97-L provenance applies: cite ontology/render surfaces, do not copy vocabulary lists into the skill. +- **Traceability:** D95-L, D96-L, D97-L / A33-L / I51-L, I54-L; D60-L. + +### structured-exchange-affordance + +- **Name:** Structured-exchange affordance hardening +- **Linear:** [FE-1108](https://linear.app/hash/issue/FE-1108/harden-structured-exchange-affordances) +- **Branch:** `ln/fe-1108-structured-exchange-affordance` +- **Kind:** hardening / earned contract cleanup +- **Status:** done. +- **Certainty:** earned. +- **Absorbs:** the former `exchange-symmetry-audit` cleanup; the remaining delete pass is residue of exchange hardening, not a separate dependency boundary. +- **Closes:** recurring "enforced but untaught" failures where the model sees legal schemas but not the intended present-vs-response, discriminant-companion, or nested review-set payload contract. +- **Canonicalizes:** structured-exchange schema descriptions, prompt guidelines, renderer/context language, and the final kept-vs-deleted exchange projection/render inventory around `present_question`, `present_candidates`, `present_review_set`, `request_response`, and their companion detail shapes. +- **Objective:** Tighten the live structured-exchange authoring contract after the `request_response` collapse so the model-facing surface teaches the legal shape directly instead of relying on deep validator failures or legacy pairing prose, then delete any exchange-layer mirrors that no longer earn a shared home. +- **Acceptance:** done. + - Present-side choice vs freeform vs candidate selection rules are explicit where the model authors them; stale legacy request-tool pairing language is removed. + - Review-set nested payload companions (`grounding`, `pitch`, `epistemicStatus`, related discriminants) are described or re-shaped at the authoring boundary, not only rejected deep in graph validation. + - `present_candidates` / `request_response` wording stays aligned with I51-L: recognition only until a later review-set or graph-mutation commitment path. + - Unjustified `projections/exchanges/*` and `agents/contexts/exchanges/*` symmetry survivors are inlined or deleted; retained modules name a real multi-consumer or model-facing-text ownership reason. + - `src/projections/TOPOLOGY.md` and the touched exchange topology homes agree on the final kept-vs-deleted inventory. + - Tests cover the affordance-level shapes that previously generated review findings, not just the deepest schema rejection points. +- **Traceability:** I23-L, I51-L, I53-L, D27-L, D37-L, D38-L, D65-L, D66-L, D84-L, D86-L, D96-L, D100-L; `docs/design/STRUCTURED_EXCHANGE_COLLAPSE.md`, `src/projections/TOPOLOGY.md`, `src/agents/contexts/exchanges/TOPOLOGY.md`. + +### Recently Completed entries trimmed from the live window + +- 2026-06-30 `orchestrator-alpha-cutover` (FE-1089) — **descriptive cutover scaffold done** (arc member of `orchestrator-cutover`). Landed the `ExecutionSpecSnapshot` projection seam plus the full `fs`-only cook lifecycle simulation through `execute_promotion_prepare`, establishing the thin-Pi-adapter / one-explicit-side-effect-per-tool pattern with zero real execution. Scoping real land surfaced the D101-L land-substrate finding (copied-dir worktree, prewritten-ingested results, no git in core), so real execution + land were reordered into the `executor-sandbox` → `executor-agent-runner` → `executor-land` frontiers. +- 2026-06-30 `structured-exchange-affordance` (FE-1108) — exchange authoring guidance now teaches present-side response rules and review-set nested companions at the boundary; one unearned exchange projection adapter was inlined into its RPC consumer, and topology inventories name the retained model-facing/projection homes. +- 2026-06-30 `elicitor-project` (FE-1085) — project canonicalized as a first-level live skill home over existing exchange/review-set seams; A33-L validated, D100-L added, and the prompt manifest witnesses `project`. +- 2026-06-29 `spec-structural-relief` — SPEC slimmed from long-form register to compact live index; pre-slim snapshot archived in `docs/archive/SPEC_HISTORY.md`. +- 2026-06-26 `renderer-golden-coverage` (FE-1091) — context pipeline done; prompt/subagent topology flattened and locked. +- 2026-06-26 `data-model-legibility` (FE-1090) — reference substrate complete; generated ontology tables and authored graph heuristics have canonical homes. +- 2026-07-01 `portable-resource-paths--manifest-location` (bugfix, `ln-induct` from PR #273) — skill manifest `location` is now the loader-resolved absolute `Skill.filePath` instead of a hardcoded repo-relative string, so it resolves under any process cwd or `dist/`-only install; dead `liveBrunchSkillRepoPath`/`bundledAgentBodyRepoPath` builders removed; the two prompt-composition goldens normalize the machine root to a `/…` token. See SPEC §Acknowledged Blind Spots "Live-vs-harness wiring divergence". +- 2026-07-01 `promoted-run-path-normalization` (tooling) — `.fixtures/runs/**` no longer leaks developer-workstation absolute paths; `npm run check:promoted-run-paths` guards committed evidence going forward. `.fixtures/seeds/**` is untouched (separate seed-curation concern). Not a `fixture-vs-real-audit` sweep. +- 2026-07-01 `executor-promotion` (FE-1112) — **run-local promotion built** (arc member of `orchestrator-cutover`). Added injected `GitLandPort`, app-layer run-local git commit promotion, promotion report commit SHA recording, failure/no-change non-advancement, and `execute_status.pendingTools: []`. Host branch promotion remains explicitly deferred beyond this frontier. +- 2026-07-01 `executor-agent-runner` (FE-1111) — **sealed worker runner built** (arc member of `orchestrator-cutover`). Replaced prewritten `execute_agent_result` ingest with injected `AgentRunnerPort`; added sealed `worker` subagent with bounded `read` + `write_worktree_file` authority; proved default app composition and portable faux-provider witness (`executor-agent-runner-witness`) for worker tool use and sandbox worktree writes. Real-provider content-quality evidence is not a frontier blocker; richer write/shell authority, if needed, should be scoped separately before or after promotion. +- 2026-07-01 `executor-sandbox` (FE-1109) — **real runnable sandbox built** (arc member of `orchestrator-cutover`). Landed `GitWorktreePort` for real per-run git worktrees and `TestRunnerPort` for real verify-subprocess ingestion, completing the no-LLM substrate needed by `executor-agent-runner`. + ## 2026-06-24 Sync archive Archived from `memory/PLAN.md` during the 2026-06-24 `ln-sync`, once `ontology-revision` (FE-1052) was done and its full frontier definition no longer carried live rationale for nearby work — its forward constraints survive as the Sequencing done-anchor (`-[unblocks]-> coherence-first-class, oracle-design-plan-graphs`). Durable architecture lives in `memory/SPEC.md` D87-L/D88-L/D89-L; this is the completion record plus the retired full definition. diff --git a/memory/PLAN.md b/memory/PLAN.md index aa96eb87f..608dd4513 100644 --- a/memory/PLAN.md +++ b/memory/PLAN.md @@ -13,9 +13,9 @@ ## Context -Brunch-next has delivered the original composition spine: the host, sealed Pi profile, transcript substrate, SQLite graph plane, public RPC, TUI/web observer shape, generalized capture, review-set commitment path, and public-entry ship gate all have evidence. The live plan is no longer organized around the old delivery cut. Active work is now the elicitor capability spine and the remaining hardening frontiers that build on that substrate. +Brunch-next has delivered the original composition spine: the host, sealed Pi profile, transcript substrate, SQLite graph plane, public RPC, TUI/web observer shape, generalized capture, review-set commitment path, and public-entry ship gate all have evidence. The live plan is no longer organized around the old delivery cut. -**Live arc.** The **elicitor-capability-spine** arc (`capture` / `generate` / `project`) is done for the current POC capability surface. The retired strategy/lens/method runtime trees are no longer part of live product topology; current capability work routes through the code-owned first-level skill manifest and activity-named skill homes. Closed arc detail no longer lives in the rolling plan. +**Live arc.** Both prior arcs are closed: the **elicitor-capability-spine** (`capture` / `generate` / `project`) and the **orchestrator-cutover** (real CODE-mode cook execution behind injected `ExecutionPorts`, D101-L). The orchestrator-cutover stack (PRs #274 → #282) awaits review sign-off and bottom-up Graphite merge. `elicitation-gap-guidance` is already in flight in parallel as FE-1116 on `ln/fe-1116-elicitation-gap-guidance` (PR #280), which carries its own PLAN/SPEC reconciliation. **Topology and evidence discipline.** Directory `TOPOLOGY.md` files under `src/**` own current topology state. `memory/SPEC.md` owns the thin product contract and live decision/invariant index; long-form SPEC history is archived in `docs/archive/SPEC_HISTORY.md`. `memory/PLAN.md` owns only rolling frontier state. Scratch probe artifacts under `.fixtures/scratch/` are not durable evidence until reviewed and promoted to `.fixtures/runs/`. @@ -30,58 +30,37 @@ Brunch-next has delivered the original composition spine: the host, sealed Pi pr including reconciliation of co-located topology files and discharge of any standing-obligation residue scoped to it. Arc completion is the trigger for residue that no future frontier touches. --> -### elicitor-capability-spine — ✓ done +- **elicitor-capability-spine** — ✓ closed 2026-06-30: `capture` / `generate` / `project` live over the frozen capability axes without reviving the retired strategy/lens/method runtime trees (D95-L, D96-L, D100-L; A31-L–A35-L; I51-L). Full arc block: `docs/archive/PLAN_HISTORY.md` (2026-07-02 archive). -- **Goal:** build `capture` / `generate` / `project` over the elicitor capability spine without reviving the retired `strategy` / `lens` / `method` runtime axes (A35-L), on top of the skill-substrate arc. -- **Members:** - - `capture` ✓ done via generalized capture (D80-L–D82-L). - - `generate` ✓ done through promoted real-model fan-out evidence (FE-1059): one plane-parameterized `generate-proposal` method, `present_candidates` unstubbed, fan-in as method conduct (`pick` / `synthesize` / `compose`), promoted I51-L no-write evidence. - - `project` ✓ done via FE-1085: distinct first-level live `project` guidance derives downstream plane material from accepted graph anchors over existing exchange and review-set seams (D100-L). - - `acquire` rides the completed subagent-reconciliation substrate (A34-L), not its own frontier. -- **Done-definition:** all three capabilities have live non-stub homes/evidence appropriate to their seam: `capture` and `generate` carry promoted model/runtime evidence; `project` is prompt-resource guidance only, witnessed through the live manifest/prompt path because FE-1085 adds no product tool or schema seam. -- **Anchors:** D95-L, D96-L; A31-L–A35-L; I51-L. +### orchestrator-cutover — ✓ done -### orchestrator-cutover — ◐ active - -- **Goal:** re-grow the old `main` cook orchestrator natively on alpha's CODE/executor substrate (D101-L), layer by layer: projection seam → descriptive lifecycle shape → real runnable sandbox → real change-producing agent → real promotion/land. Split by capability layer + risk + reversibility so each layer is independently reviewable and the hard-to-reverse git seam lands last. -- **Members:** - - `orchestrator-alpha-cutover` (FE-1089) ✓ done — `ExecutionSpecSnapshot` projection seam + the descriptive `fs`-only cook lifecycle scaffold (`execute_plan_file` → … → `execute_promotion_prepare`). Proved the lifecycle shape + thin-adapter/one-side-effect-per-tool pattern with zero real execution. - - `executor-sandbox` (FE-1109) ✓ built — `GitWorktreePort` + `TestRunnerPort`: a run becomes a real, runnable, verifiable git workspace (no LLM, subprocess only). - - `executor-agent-runner` (FE-1111) → active — `AgentRunnerPort` reusing the D90-L–D93-L sealed subagent substrate: a run actually produces real changes via a code-owned write-capable CODE worker. - - `executor-promotion` → last — `GitLandPort`: a run's real changes get promoted (run-local promotion first, host promotion later); the only externally-visible, hard-to-reverse seam. -- **Done-definition:** a selected-spec cook run can be planned, executed against a real git worktree by a real CODE worker that produces real diffs, verified by real tests, and promoted — each layer behind the established injected-capability-port seam (SPEC D101-L executor cutover), no faked side effects, topology immutable in execution, and `execute_status` `pendingTools` empty. Open follow-ups (adaptive replan, real Petri-net execution) ride their own horizon items, not arc blockers. -- **Anchors:** D39-L, D40-L, D52-L, D90-L–D93-L, D98-L, D101-L / I49-L, I56-L. +- **Goal:** re-grow the old `main` cook orchestrator natively on alpha's CODE/executor substrate (D101-L), layered by capability, risk, and reversibility so the hard-to-reverse git seam landed last. +- **Members (all landed on the FE-1089 → FE-1118 Graphite stack, PRs #274/#275/#278/#279/#282):** `orchestrator-alpha-cutover` (FE-1089) ✓ · `executor-sandbox` (FE-1109) ✓ · `executor-agent-runner` (FE-1111) ✓ · `executor-promotion` (FE-1112) ✓ · `executor-host-promotion` (FE-1118) ✓. +- **Done-definition held 2026-07-02:** a selected-spec cook run is planned, executed in a real git worktree by the sealed CODE worker, verified by the real verify subprocess, promoted run-locally, and host-applied behind accepted-SHA preflight — each layer behind injected `ExecutionPorts`, no faked side effects, `execute_status.pendingTools` `[]` (I56-L). Topology homes (`src/executor/`, `src/app/`) reconciled and exhausted scope cards deleted in the 2026-07-02 sync. Adaptive replan and real Petri-net execution ride horizon items, not arc blockers. +- **Residue:** merge the stack bottom-up (#274 → #282); retire this block to `docs/archive/PLAN_HISTORY.md` at the post-merge sync. +- **Anchors:** D39-L, D40-L, D52-L, D90-L–D93-L, D98-L, D101-L / I49-L, I56-L; `src/executor/TOPOLOGY.md`, `src/app/TOPOLOGY.md`. ## Sequencing ### Active -- `executor-host-promotion` (FE-1118, `orchestrator-cutover` arc) — **built; ready for tie-off.** Apply a verified run-local executor promotion back to the host project branch through an explicit host-promotion path. Preflight validates the promoted SHA and computes/reports the host diff without mutation; accepted apply mutates host files only after accepted SHA confirmation; CODE-mode Pi tools expose both surfaces with side-effect details. Review hardening added real git apply/conflict oracles and tightened the apply result shape. Stacks on `ka/fe-1112-executor-promotion`. -- `elicitation-gap-guidance` — **proving frontier.** Generate "what next?" gap guidance from graph shape/readiness, distinct from ranking already-registered gaps. +- `elicitation-gap-guidance` (FE-1116) — **in flight on `ln/fe-1116-elicitation-gap-guidance` (PR #280, @ln)**, in parallel with this stack. Its design supersedes the older definition below: session-local elicitation gaps from a graph-derived seed, retiring the spec-global persisted `elicitation_gaps` register and count-based readiness scoring. That branch carries its own PLAN/SPEC edits; reconcile at whichever merge lands second. +- The `orchestrator-cutover` stack (PRs #274 → #282) is in review/merge; review changes, if any, land on the existing branches. ### Recently Completed -- 2026-07-01 `portable-resource-paths--manifest-location` (bugfix, `ln-induct` from PR #273) — skill manifest `location` is now the loader-resolved absolute `Skill.filePath` instead of a hardcoded repo-relative string, so it resolves under any process cwd or `dist/`-only install; dead `liveBrunchSkillRepoPath`/`bundledAgentBodyRepoPath` builders removed; the two prompt-composition goldens normalize the machine root to a `/…` token. See SPEC §Acknowledged Blind Spots "Live-vs-harness wiring divergence". -- 2026-07-01 `promoted-run-path-normalization` (tooling) — `.fixtures/runs/**` no longer leaks developer-workstation absolute paths; `npm run check:promoted-run-paths` guards committed evidence going forward. `.fixtures/seeds/**` is untouched (separate seed-curation concern). Not a `fixture-vs-real-audit` sweep. -- 2026-06-30 `orchestrator-alpha-cutover` (FE-1089) — **descriptive cutover scaffold done** (arc member of `orchestrator-cutover`). Landed the `ExecutionSpecSnapshot` projection seam plus the full `fs`-only cook lifecycle simulation through `execute_promotion_prepare`, establishing the thin-Pi-adapter / one-explicit-side-effect-per-tool pattern with zero real execution. Scoping real land surfaced the D101-L land-substrate finding (copied-dir worktree, prewritten-ingested results, no git in core), so real execution + land were reordered into the `executor-sandbox` → `executor-agent-runner` → `executor-land` frontiers. -- 2026-07-01 `executor-promotion` (FE-1112) — **run-local promotion built** (arc member of `orchestrator-cutover`). Added injected `GitLandPort`, app-layer run-local git commit promotion, promotion report commit SHA recording, failure/no-change non-advancement, and `execute_status.pendingTools: []`. Host branch promotion remains explicitly deferred beyond this frontier. -- 2026-07-01 `executor-agent-runner` (FE-1111) — **sealed worker runner built** (arc member of `orchestrator-cutover`). Replaced prewritten `execute_agent_result` ingest with injected `AgentRunnerPort`; added sealed `worker` subagent with bounded `read` + `write_worktree_file` authority; proved default app composition and portable faux-provider witness (`executor-agent-runner-witness`) for worker tool use and sandbox worktree writes. Real-provider content-quality evidence is not a frontier blocker; richer write/shell authority, if needed, should be scoped separately before or after promotion. -- 2026-07-01 `executor-sandbox` (FE-1109) — **real runnable sandbox built** (arc member of `orchestrator-cutover`). Landed `GitWorktreePort` for real per-run git worktrees and `TestRunnerPort` for real verify-subprocess ingestion, completing the no-LLM substrate needed by `executor-agent-runner`. -- 2026-06-30 `structured-exchange-affordance` (FE-1108) — exchange authoring guidance now teaches present-side response rules and review-set nested companions at the boundary; one unearned exchange projection adapter was inlined into its RPC consumer, and topology inventories name the retained model-facing/projection homes. -- 2026-06-30 `elicitor-project` (FE-1085) — project canonicalized as a first-level live skill home over existing exchange/review-set seams; A33-L validated, D100-L added, and the prompt manifest witnesses `project`. -- 2026-06-29 `spec-structural-relief` — SPEC slimmed from long-form register to compact live index; pre-slim snapshot archived in `docs/archive/SPEC_HISTORY.md`. -- 2026-06-26 `renderer-golden-coverage` (FE-1091) — context pipeline done; prompt/subagent topology flattened and locked. -- 2026-06-26 `data-model-legibility` (FE-1090) — reference substrate complete; generated ontology tables and authored graph heuristics have canonical homes. +- 2026-07-02 `executor-host-promotion` (FE-1118, `orchestrator-cutover` arc) — host-promotion boundary built: preflight validates the promoted SHA and reports the host diff without mutation; accepted apply mutates host files only after accepted-SHA confirmation and a rerun preflight; CODE-mode Pi tools expose both with side-effect details; review hardening added real temp-git apply/conflict oracles. Closes the arc. +- 2026-07-01 executor real-execution layers (FE-1109 / FE-1111 / FE-1112, `orchestrator-cutover` arc) — real git worktrees + verify subprocess (`GitWorktreePort`, `TestRunnerPort`), sealed-worker agent runner (`AgentRunnerPort`, faux-provider witness), and run-local git promotion with metadata recovery (`GitLandPort`); `execute_status.pendingTools` emptied. +- 2026-07-01 `portable-resource-paths--manifest-location` (bugfix) and `promoted-run-path-normalization` (tooling) — loader-resolved absolute skill-manifest locations (see SPEC §Acknowledged Blind Spots "Live-vs-harness wiring divergence") and `npm run check:promoted-run-paths` guarding committed run evidence against absolute workstation paths. - Older completed frontiers: `docs/archive/PLAN_HISTORY.md`. ### Next -- `executor-promotion` (`orchestrator-cutover` arc) — **last; the only hard-to-reverse seam.** Inject the `GitLandPort` so a run's real diffs get promoted (run-local promotion first, host promotion later), consuming the Petri + promotion artifacts rather than re-deriving run state. Drops `land` from `execute_status` `pendingTools`. Stacks on `executor-agent-runner`. -- `elicitation-gap-guidance` +1. Next frontier selection after the two in-flight merge trains land (`ln-plan` pass; candidates ride §Horizon and FE-1115's paused `component-preview-dx` / split `bordered-chrome-production`). ### Parallel / Low-Conflict -- _None._ +- `component-preview-dx` / `bordered-chrome-production` (FE-1115, PR #281, @ln) — standalone `.pi/components` preview harness; paused/split on its own branch with its own PLAN/SPEC/PLAN_HISTORY edits. Not tracked further here until it merges. - **Standing obligations:** `probes-and-transcripts-evolution` and `topology-readmes-and-boundaries` ride the frontier that triggers them; they are not standalone cleanup buckets. ### Horizon @@ -91,7 +70,7 @@ Brunch-next has delivered the original composition spine: the host, sealed Pi pr - `web-driver-streaming` — remaining consumer/UI and non-freeform answer legs after the built topology-A relay battery. - `flue-pattern-adoption` — post-POC harness-pattern adoption. - `framework-direction-stubs` — discretionary structural stubs only when downstream pressure makes a stub cheaper than a hole. -- `geolog-and-petri-execution` — exploratory, parallel to Brunch proper. +- `geolog-and-petri-execution` — exploratory, parallel to Brunch proper; now also owns real Petri-net execution follow-ups from the closed `orchestrator-cutover` arc. ### Retired / Never @@ -99,159 +78,20 @@ Brunch-next has delivered the original composition spine: the host, sealed Pi pr ## Frontier Definitions -### orchestrator-alpha-cutover - -- **Name:** Reconcile executor with alpha branch -- **Linear:** [FE-1089](https://linear.app/hash/issue/FE-1089/reconcile-executor-with-alpha-branch) -- **Branch:** `ka/fe-1089-orchestrator-alpha-cutover` -- **Kind:** structural / execute-mode orchestration cutover -- **Status:** active; read-only executor footholds active, descriptive lifecycle scaffold registered but gated. -- **Certainty:** proving. -- **Current execution pointer:** first real execution boundary for agent/test runs; keep host git mutation, real promotion, and land out of scope until explicitly accepted. -- **Objective:** Cut the old `main` cook orchestrator off the divergent stable branch and re-grow it natively on alpha's CODE/executor substrate. The current active bridge is `ExecutionSpecSnapshot v1` plus read-only executable-plan projections. Bounded artifact/lifecycle tools are registered and test-covered on this branch but stay inactive in CODE mode until the real-execution stack lands, avoiding independently reachable placeholders. -- **Acceptance:** - - ✓ Side-effect-free tools project/check/outline/draft/preview selected-spec execution input. - - ✓ Bounded artifact tools write only declared files under `.brunch/execution-reports` or `.brunch/cook`. - - ✓ Run/worktree/source/report/slice/result/Petri/promotion-preparation tools descriptively advance run metadata with one explicit side effect per step. - - Next: real agent/test execution boundary. -- **Traceability:** D39-L, D40-L, D58-L, D90-L, D91-L, D92-L, D93-L, D98-L, D101-L / I49-L, I50-L, I56-L; `src/executor/TOPOLOGY.md`, `src/.pi/extensions/TOPOLOGY.md`. - -### orchestrator-tool-port - -- **Name:** Port cook orchestration into CODE/executor tools -- **Linear:** [FE-1107](https://linear.app/hash/issue/FE-1107/port-cook-orchestration-into-codeexecutor-tools) -- **Branch:** tbd -- **Kind:** structural / execute-mode tool boundary -- **Status:** superseded as a separate frontier by `orchestrator-alpha-cutover` / FE-1089. -- **Certainty:** proving. -- **Objective:** Historical precursor for porting reusable cook logic into CODE/executor tools. FE-1089 now owns the active alpha cutover. -- **Acceptance:** See `orchestrator-alpha-cutover`. -- **Traceability:** D39-L, D40-L, D90-L, D91-L, D92-L, D93-L, D98-L, D101-L / I49-L, I56-L. - -### executor-sandbox - -- **Name:** Reconcile executor sandbox worktrees and test runner ports -- **Linear:** [FE-1109](https://linear.app/hash/issue/FE-1109/reconcile-executor-sandbox-worktrees-and-test-runner-ports) — reconcile executor sandbox worktrees and test runner ports -- **Branch:** `ka/fe-1109-cook-sandbox` (created from `ka/fe-1089-orchestrator-alpha-cutover`; Graphite tracking pending while PR #274 remains open/non-Graphite) -- **Kind:** structural / execute-mode runner substrate (`orchestrator-cutover` arc) -- **Status:** built; both port slices (`GitWorktreePort`, `TestRunnerPort`) delivered. Ready to tie off once reviewed. -- **Current execution pointer:** frontier complete — real git worktree + real verify-subprocess ingestion both landed; next arc frontier is `executor-agent-runner`. -- **Certainty:** proving. -- **Why now / unlocks:** the FE-1089 chain proved the cook lifecycle shape with `fs`-only descriptive footholds, but every step simulates execution (copied-dir "worktree", prewritten-ingested agent/test results, no git). A meaningful run needs a real, runnable, verifiable workspace first. This is the lowest-blast-radius real-execution layer (subprocess only, no LLM). -- **Design verdict (chosen):** real execution enters executor core through an **injected capability-port bag**, not a deep environment object or an effect-program rewrite. Port *types* live in `src/executor/execution-ports.ts` (`ExecutionPorts` = `{ GitWorktreePort, AgentRunnerPort, TestRunnerPort, GitLandPort }`); real implementations live in the app layer (`src/app/git-worktree-port.ts`, and future `src/app/*-port.ts`) and are injected by the Pi adapters, preserving the D52-L/I52-L boundary (no git/subprocess in core). See SPEC D99-L execution-ports refinement. -- **Objective:** Implement and inject `GitWorktreePort` (real `git worktree add`, replacing `worktree.ts`'s `mkdir`) and `TestRunnerPort` (real verify subprocess), so a run becomes a real, runnable, verifiable git workspace — keeping the one-explicit-side-effect-per-tool discipline (I52-L). -- **Acceptance (to refine via `ln-scope`):** - - Done: `src/executor/execution-ports.ts` defines the `ExecutionPorts` bag as types only; executor core imports no git/subprocess. - - Done: `GitWorktreePort` makes the per-run worktree a real `git worktree`, replacing the `mkdir` substrate in `worktree.ts`; app-layer `src/app/git-worktree-port.ts` runs `git worktree add --detach HEAD` and the Pi adapter injects it. If the worktree fails, run metadata is not advanced. - - Done: `TestRunnerPort` runs the real verify subprocess (`npm run verify`) in the run worktree and ingests its true verdict/exit code, replacing the prewritten `test-result.json` ingest path; app-layer `src/app/test-runner-port.ts` owns the subprocess. A failing verdict still advances the run; a runner that cannot execute (`test_run_failed`) leaves metadata unchanged. - - Done: app-layer implementations under `src/app/*-port.ts`; adapters inject the bag; focused tests cover the port contracts. -- **Traceability:** D39-L, D40-L, D52-L, D90-L, D91-L, D92-L, D93-L, D98-L, D99-L (land-substrate finding + execution-ports refinement) / I49-L, I52-L; depends on `orchestrator-alpha-cutover`; `src/executor/TOPOLOGY.md`. - -### executor-agent-runner - -- **Name:** Reconcile executor agent runner -- **Linear:** [FE-1111](https://linear.app/hash/issue/FE-1111/reconcile-executor-agent-runner) — reconcile executor agent runner -- **Branch:** `ka/fe-1111-executor-agent-runner` (stacked on `ka/fe-1109-cook-sandbox`) -- **Kind:** structural / execute-mode runner substrate (`orchestrator-cutover` arc) -- **Status:** done. -- **Current execution pointer:** none — frontier complete. Port contract, sealed worker tracer, default runner composition proof, and faux-provider witness probe built (`memory/cards/executor-agent-runner--agent-runner-port.md`, `memory/cards/executor-agent-runner--sealed-code-worker.md`, `memory/cards/executor-agent-runner--default-runner-composition.md`, `memory/cards/executor-agent-runner--worker-witness-probe.md`). -- **Certainty:** proving. -- **Why now / unlocks:** with a real sandbox, a run can finally produce real changes. This frontier introduces the only LLM-bearing port and reuses the sealed subagent substrate rather than a new agent runtime. -- **Objective:** Implement and inject `AgentRunnerPort` so a run actually produces real diffs via a code-owned write-capable CODE worker reusing the D90-L–D93-L sealed subagent substrate, retiring the prewritten-ingest tool (`execute_agent_result`) in favor of the real runner. -- **Acceptance (to refine via `ln-scope`):** - - Done: `AgentRunnerPort` has concrete arg/result types; `execute_agent_result` invokes it for the active slice's worktree/request/result paths and no longer reads a prewritten `result.json`. - - Done: Pi registration injects `AgentRunnerPort`; the default app-layer runner fails closed until the real worker lands. - - Done: `AgentRunnerPort` implementation (app layer) launches the sealed `worker` subagent over the `executor-sandbox` worktree under the D90-L–D93-L grant model, with bounded `read` + `write_worktree_file` authority and no shell/nesting grant. - - Done: default Pi composition wires `execute_agent_result` through the app-composed `AgentRunnerPort` when sealed subagent deps are injected; no explicit fake port is required. - - Done: `execute_agent_result` is re-grounded on the real runner; no prewritten `result.json` ingest remains on this layer. - - Done: focused tests cover the runner contract and observe a real sandbox-worktree file change through the deterministic fake worker path. - - Done: `src/probes/executor-agent-runner-witness.ts` provides a runnable faux-provider witness and portable artifact writer for the default runner → sealed worker → worktree write path. - - Done: faux-provider witness is the right oracle for runner wiring/tool authority; real-provider content-quality evidence is not a frontier blocker. -- **Traceability:** D39-L, D40-L, D52-L, D90-L, D91-L, D92-L, D93-L, D98-L, D99-L / I49-L, I52-L; depends on `executor-sandbox`. - -### executor-promotion - -- **Name:** Reconcile run-local executor promotion -- **Linear:** [FE-1112](https://linear.app/hash/issue/FE-1112/reconcile-run-local-executor-promotion) — reconcile run-local executor promotion -- **Branch:** `ka/fe-1112-executor-promotion` (stacked on `ka/fe-1111-executor-agent-runner`) -- **Kind:** structural / execute-mode runner substrate (`orchestrator-cutover` arc) -- **Status:** done. -- **Current execution pointer:** none — frontier complete. Run-local `GitLandPort` and promotion metadata recovery built (`memory/cards/executor-promotion--run-local-git-land-port.md`, `memory/cards/executor-promotion--promotion-metadata-recovery.md`); host promotion remains explicitly deferred beyond this frontier. -- **Certainty:** proving. -- **Why now / unlocks:** only once a run produces real, verified diffs does a truthful land have a source (D99-L land-substrate finding). This layer lands last so the hard-to-reverse git mutation is the final, independently-reviewable step. -- **Objective:** Implement and inject `GitLandPort` so a run's real diffs are promoted — run-local promotion first, host promotion later — consuming/validating the Petri + promotion artifacts rather than re-deriving run state. -- **Acceptance (to refine via `ln-scope`):** - - Done: `GitLandPort` implementation (app layer) performs a run-local promotion of verified worktree diffs first; host promotion is a later, explicitly-accepted slice. - - Done: the promotion path consumes existing Petri/run metadata and writes `promotion.json` with the run-local commit SHA rather than re-deriving run state. - - Done: `execute_status` `pendingTools` drops `land` because real run-local git promotion exists; host promotion remains explicitly deferred beyond this frontier. - - Done: recover/idempotently complete promotion metadata if the run-local git commit succeeds but `promotion.json` or `run.json` persistence fails before status advancement. -- **Traceability:** D39-L, D40-L, D52-L, D98-L, D99-L (land-substrate finding) / I49-L, I52-L; depends on `executor-agent-runner`; `src/executor/TOPOLOGY.md`. - -### executor-host-promotion - -- **Name:** Reconcile host executor promotion -- **Linear:** [FE-1118](https://linear.app/hash/issue/FE-1118/reconcile-host-executor-promotion) — reconcile host executor promotion -- **Branch:** `ka/fe-1118-executor-host-promotion` (stacked on `ka/fe-1112-executor-promotion`) -- **Kind:** structural / execute-mode host mutation seam (`orchestrator-cutover` arc) -- **Status:** built; ready for tie-off. -- **Current execution pointer:** none — review hardening is complete. -- **Certainty:** proving. -- **Why now / unlocks:** FE-1112 proves real run-local promotion, but executor output remains trapped inside the run worktree until a separate, explicit host-apply seam exists. This is the externally visible hard-to-reverse boundary and must start with a no-mutation preflight. -- **Objective:** Apply a verified run-local promotion commit/diff back to the host project branch through an explicit host-promotion path. Host mutation must be deliberate, validated, and recoverable; first slice is preflight only. -- **Acceptance (to refine via `ln-scope`):** - - Done: Host preflight consumes existing run metadata and `promotion.json`; it validates the promoted commit SHA exists in the run worktree. - - Done: Host preflight computes/reports the diff that would be applied to the host branch without mutating host files, branches, refs, or index state. - - Done: Helper-level host apply performs explicit accepted mutation only after preflight passes; it mutates host files only and does not commit, create refs, switch branches, or stage the host index. - - Done: CODE-mode Pi tools expose host preflight and accepted host apply with explicit acceptance, active-tool policy inclusion, `execute_status` visibility, and machine-readable side-effect details. - - Done: Review hardening proves the real `git diff --binary` / `git apply --check` / `git apply` path against temp repos, narrows apply result states, and removes the dead report-path alias. -- **Traceability:** D52-L, D99-L / I52-L; depends on `executor-promotion`; `src/executor/TOPOLOGY.md`. - -### elicitor-project - -- **Name:** Elicitor `project` capability — cross-plane derivation -- **Linear:** [FE-1085](https://linear.app/hash/issue/FE-1085) — elicitor project capability design -- **Branch:** `ln/fe-1085-elicitor-project-prep` -- **Kind:** structural / capability -- **Status:** done. -- **Certainty:** proving. -- **Retires:** A33-L by materializing the branch-implied distinct `project` surface into canon and the live skill manifest. -- **Lights up:** requirements/design/oracle cross-plane derivation over the frozen elicitor capability axes. -- **Objective:** Materialize cross-plane derivation as a distinct first-level live `project` move over the existing exchange triad and review-set commitment path, without introducing a new tool, schema family, or direct graph-write seam. -- **Acceptance:** done. - - `memory/SPEC.md`, `memory/PLAN.md`, and the touched parent topology homes state one consistent shape: `project` is a distinct first-level live skill home, not a `generate` branch. - - The live skill manifest includes `project`, and its guidance covers accepted-graph derivation lanes such as intent → design and design → oracle. - - `project` reuses `present_candidates`, `request_response`, `present_review_set`, and the existing `map` / review-set commitment boundary; it does not add a new product tool or exchange schema family. - - D97-L provenance applies: cite ontology/render surfaces, do not copy vocabulary lists into the skill. -- **Traceability:** D95-L, D96-L, D97-L / A33-L / I51-L, I54-L; D60-L. - -### structured-exchange-affordance - -- **Name:** Structured-exchange affordance hardening -- **Linear:** [FE-1108](https://linear.app/hash/issue/FE-1108/harden-structured-exchange-affordances) -- **Branch:** `ln/fe-1108-structured-exchange-affordance` -- **Kind:** hardening / earned contract cleanup -- **Status:** done. -- **Certainty:** earned. -- **Absorbs:** the former `exchange-symmetry-audit` cleanup; the remaining delete pass is residue of exchange hardening, not a separate dependency boundary. -- **Closes:** recurring "enforced but untaught" failures where the model sees legal schemas but not the intended present-vs-response, discriminant-companion, or nested review-set payload contract. -- **Canonicalizes:** structured-exchange schema descriptions, prompt guidelines, renderer/context language, and the final kept-vs-deleted exchange projection/render inventory around `present_question`, `present_candidates`, `present_review_set`, `request_response`, and their companion detail shapes. -- **Objective:** Tighten the live structured-exchange authoring contract after the `request_response` collapse so the model-facing surface teaches the legal shape directly instead of relying on deep validator failures or legacy pairing prose, then delete any exchange-layer mirrors that no longer earn a shared home. -- **Acceptance:** done. - - Present-side choice vs freeform vs candidate selection rules are explicit where the model authors them; stale legacy request-tool pairing language is removed. - - Review-set nested payload companions (`grounding`, `pitch`, `epistemicStatus`, related discriminants) are described or re-shaped at the authoring boundary, not only rejected deep in graph validation. - - `present_candidates` / `request_response` wording stays aligned with I51-L: recognition only until a later review-set or graph-mutation commitment path. - - Unjustified `projections/exchanges/*` and `agents/contexts/exchanges/*` symmetry survivors are inlined or deleted; retained modules name a real multi-consumer or model-facing-text ownership reason. - - `src/projections/TOPOLOGY.md` and the touched exchange topology homes agree on the final kept-vs-deleted inventory. - - Tests cover the affordance-level shapes that previously generated review findings, not just the deepest schema rejection points. -- **Traceability:** I23-L, I51-L, I53-L, D27-L, D37-L, D38-L, D65-L, D66-L, D84-L, D86-L, D96-L, D100-L; `docs/design/STRUCTURED_EXCHANGE_COLLAPSE.md`, `src/projections/TOPOLOGY.md`, `src/agents/contexts/exchanges/TOPOLOGY.md`. + ### elicitation-gap-guidance - **Name:** Elicitation gap guidance from graph shape -- **Linear:** unassigned -- **Branch:** tbd +- **Linear:** [FE-1116](https://linear.app/hash/issue/FE-1116) — session-local elicitation gaps from a graph-derived seed +- **Branch:** `ln/fe-1116-elicitation-gap-guidance` (PR #280, @ln — in flight in parallel with the orchestrator-cutover stack) - **Kind:** structural / elicitor guidance -- **Status:** active candidate; sequence second after structured-exchange affordances are tightened. +- **Status:** in flight on its own branch. **Design supersession note (2026-07-02):** FE-1116's chosen design retires the spec-global persisted `elicitation_gaps` register and count-based readiness scoring in favor of session-local gaps seeded from graph facts — it supersedes the acceptance bullets below where they assume the persisted register survives. That branch's own PLAN/SPEC edits are authoritative for the final shape; this definition is retained only until it merges. - **Certainty:** proving. - **Lights up:** model-facing "what next?" guidance derived from graph topology, readiness bands, and current elicitation state. - **Stabilizes:** the boundary between the stored `elicitation_gaps` register, a derived asking agenda, advisory graph signal, and persisted `reconciliation_need` follow-up. @@ -268,37 +108,19 @@ Brunch-next has delivered the original composition spine: the host, sealed Pi pr ```text frontiers: Active: - executor-host-promotion (FE-1118, orchestrator-cutover arc) - status: active; first slice scoped - depends_on: executor-promotion, D101-L executor cutover, D52-L, I56-L - stacks_on: ka/fe-1112-executor-promotion - - executor-agent-runner (FE-1111, orchestrator-cutover arc) - status: done; sealed worker runner and faux-provider witness built - depends_on: executor-sandbox (FE-1109), D90-L..D93-L, D52-L, I49-L, I56-L - ports: AgentRunnerPort - stacks_on: ka/fe-1109-cook-sandbox - - executor-sandbox (FE-1109, orchestrator-cutover arc) - status: built; ready to tie off - depends_on: orchestrator-alpha-cutover (FE-1089), D52-L, D101-L executor cutover, I56-L - ports: GitWorktreePort, TestRunnerPort - stacks_on: ka/fe-1089-orchestrator-alpha-cutover - - elicitation-gap-guidance - status: second / proving - depends_on: readiness bands, data-model legibility, elicitor-generate, and a stable exchange affordance surface for asking/proposal loops - - Recently Completed: - executor-promotion (FE-1112), executor-agent-runner (FE-1111), executor-sandbox (FE-1109), orchestrator-alpha-cutover (FE-1089), structured-exchange-affordance, elicitor-project, spec-structural-relief, renderer-golden-coverage, data-model-legibility + elicitation-gap-guidance (FE-1116, PR #280, @ln — parallel branch, own PLAN/SPEC edits) + status: in flight / proving + depends_on: readiness bands (D94-L), data-model legibility, elicitor-generate, + stable exchange affordance surface, D99-L advisory settlement semantics + orchestrator-cutover stack in review/merge (PRs #274 -> #282) Next: - executor-land (orchestrator-cutover arc) - status: last; only hard-to-reverse seam - depends_on: executor-agent-runner, D101-L executor cutover, D52-L, I56-L - ports: GitLandPort - unblocks: host executor promotion; drops `land` from execute_status pendingTools - stacks_on: executor-agent-runner + next-frontier selection via ln-plan after the in-flight merge trains land + + Recently Completed: + executor-host-promotion (FE-1118), executor-promotion (FE-1112), + executor-agent-runner (FE-1111), executor-sandbox (FE-1109), + portable-resource-paths--manifest-location, promoted-run-path-normalization Parallel / Low-Conflict: none @@ -320,6 +142,7 @@ done anchors: subagent-reconciliation -> acquisition arm + future subagent diversity readiness-bands-interrogation -> renderer-golden-coverage ontology-revision -> renderer-golden-coverage, elicitor-project + orchestrator-cutover -> adaptive replan, geolog-and-petri-execution follow-ups rules: candidates never commit graph truth (I51-L) diff --git a/memory/SPEC.md b/memory/SPEC.md index cc2a312ae..d61f5d1fb 100644 --- a/memory/SPEC.md +++ b/memory/SPEC.md @@ -78,7 +78,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c #### Runtime profile & prompting 25. Brunch must run the embedded Pi harness through a sealed Brunch Pi Profile: programmatic settings, resource-loader, extension-factory, keybinding, tool, and prompt policy must determine product behavior; ambient user/project `.pi/` resources must not influence Brunch sessions unless Brunch deliberately imports them. -26. Brunch must distinguish transport modes from operational modes and agent roles: operational mode is the only user-changeable session-agent state, exposed as `SPEC` or `CODE` (D98-L). `SPEC` runs the elicitor for specification-building work. `CODE` runs the executor: a Brunch-aware coding assistant that merges the prior `orchestrator` and `pi-coder` directions, can use Brunch graph/session context, and owns an `orchestrate` tool for plan execution rather than splitting planning orchestration from coding assistance. Background agents may still share the `AgentManifest` shape (D90-L), but strategy/lens/method are suspended as runtime state. +26. Brunch must distinguish transport modes from operational modes and agent roles: operational mode is the only user-changeable session-agent state, exposed as `SPEC` or `CODE` (D98-L). `SPEC` runs the elicitor for specification-building work. `CODE` runs the executor: a Brunch-aware coding assistant that merges the prior `orchestrator` and `pi-coder` directions, can use Brunch graph/session context, and owns the `execute_*` orchestration tool family for plan execution (D101-L) rather than splitting planning orchestration from coding assistance. Background agents may still share the `AgentManifest` shape (D90-L), but strategy/lens/method are suspended as runtime state. ## Live Architecture Register @@ -259,19 +259,11 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c | D97-L | Skill ontology-heuristic provenance: two sources — consumed context renders and hand-authored judgment over schema-owned vocabulary — kept distinct. Skill bodies that teach the agent how to think about the graph model must not blur dynamic instance context with durable reasoning guidance; schema-owned graph vocabulary remains in `src/graph/schema/**` and `src/graph/policy/**`, while richer agent-facing explanations live in authored references. | [`src/agents/references/data-model.md`](src/agents/references/data-model.md), [`src/agents/skills/map/references/mapping-kinds.md`](src/agents/skills/map/references/mapping-kinds.md) | active | | D98-L | Operational mode only: suspend strategy/lens/method runtime axes; target product modes are SPEC and CODE. The architectural correction is that the `strategy` / `lens` / `method` model is not yet proven as the right product/runtime abstraction. It may still organize prompt-resource files and concise agent-readable references, but it must not be a user-facing TUI picker, ... | See archive snapshot for full rationale. | active | | D100-L | `project` is a distinct first-level live SPEC-mode skill home for cross-plane derivation, not a `generate` sub-mode. `generate` fans out alternatives within a target plane from context; `project` starts from accepted upstream graph anchors and derives downstream plane candidates/drafts plus connecting edge intent. It uses the existing structured-exchange triad (`present_candidates`, `request_response`, `present_review_set`) and hands exact graph expression back to `map` / review-set commitment; it adds no product tool, exchange schema family, or direct graph-write path. Depends on: D95-L, D96-L, D97-L, I51-L. | [`src/agents/skills/TOPOLOGY.md`](src/agents/skills/TOPOLOGY.md), [`src/agents/subagents/TOPOLOGY.md`](src/agents/subagents/TOPOLOGY.md) | active | -| D101-L | Execute orchestration cutover starts with bounded native executor tools, not a revived orchestrator role or shelling out to the old CLI. FE-1089 grows the old cook lifecycle back on alpha as `execute_*` Pi tools over product-core contracts: side-effect-free projection/check/outline/draft/preview tools are active in CODE mode; bounded artifact writers under `.brunch/execution-reports` / `.brunch/cook` plus descriptive run/worktree/source/report/slice/result/Petri/promotion-preparation tools are registered and test-covered but intentionally inactive until the real-execution stack lands, so placeholders are not independently reachable. No real agent/test execution or host git mutation occurs until a later accepted boundary. Depends on: D39-L, D40-L, D58-L, D90-L, D93-L, D98-L. | [`src/executor/TOPOLOGY.md`](src/executor/TOPOLOGY.md), [`src/.pi/extensions/TOPOLOGY.md`](src/.pi/extensions/TOPOLOGY.md) | active | +| D101-L | Execute orchestration cutover starts with bounded native executor tools, not a revived orchestrator role or shelling out to the old CLI. FE-1089 grows the old cook lifecycle back on alpha as `execute_*` Pi tools over product-core contracts: side-effect-free projections and bounded artifact writers under `.brunch/execution-reports` / `.brunch/cook` came first; the real-execution stack then landed layer by layer through the injected `ExecutionPorts` bag: `GitWorktreePort` + `TestRunnerPort` (FE-1109), `AgentRunnerPort` over the sealed `worker` subagent (FE-1111), run-local `GitLandPort` promotion (FE-1112), and accepted-SHA host preflight/apply via `GitHostPromotionPort` (FE-1118). The full `execute_*` lifecycle is active in CODE mode; host mutation stays file-apply-only per I56-L. Depends on: D39-L, D40-L, D52-L, D58-L, D90-L, D93-L, D98-L. | [`src/executor/TOPOLOGY.md`](src/executor/TOPOLOGY.md), [`src/.pi/extensions/TOPOLOGY.md`](src/.pi/extensions/TOPOLOGY.md) | active | ### Critical Invariants -> D101-L GitWorktreePort implementation refinement (2026-07-01, FE-1109): `execute_worktree_create` now creates the run workspace through an injected `GitWorktreePort` rather than direct `mkdir`. The executor core (`src/executor/worktree.ts`) owns only the port type, worktree path, metadata transition, and explicit `git_worktree_add` / `write_file` side-effect report; the app layer (`src/app/git-worktree-port.ts`) owns the `git worktree add --detach HEAD` subprocess and Pi composition injects it via `ExecutionPorts`. If git worktree creation fails, run metadata is not advanced (`status:"worktree_create_failed"`, no side effects). `TestRunnerPort`, `AgentRunnerPort`, and `GitLandPort` remain pending layers of the real-execution stack. - -> D101-L TestRunnerPort implementation refinement (2026-07-01, FE-1109): `execute_test_result` now runs the real verify subprocess in the run's worktree through an injected `TestRunnerPort` rather than reading a prewritten `agent-output//test-result.json`. The executor core (`src/executor/test-result.ts`) owns only the port type, the `slice_test_result` report append (carrying the true verdict + exit code), and the metadata transition; the app layer (`src/app/test-runner-port.ts`) owns the `npm run verify` subprocess and Pi composition injects it via `ExecutionPorts`. A failing verdict is a real outcome and still advances the run to `status:"test_result_ingested"`; only a runner that cannot execute returns `status:"test_run_failed"` and leaves metadata unchanged (no side effects). The prewritten-file `testResultPath` model is removed. This completes the `executor-sandbox` frontier's two port slices; `AgentRunnerPort` and `GitLandPort` remain pending layers of `executor-agent-runner` / `executor-land`. - -> D101-L AgentRunnerPort implementation refinement (2026-07-01, FE-1111): `execute_agent_result` now runs an injected `AgentRunnerPort` for the active requested slice rather than reading a prewritten `agent-output//result.json`. The executor core (`src/executor/agent-result.ts`) owns only the port type, active run/slice/worktree/request/result paths, Pi model-runtime handoff, the `slice_agent_result` report append, and the metadata transition; the app layer (`src/app/agent-runner-port.ts`) launches the registry-owned sealed `worker` subagent when subagent deps are injected, otherwise failing closed. The worker is a code-owned background definition (`src/agents/subagents/worker.md`) with bounded `read` + `write_worktree_file` authority over the sandbox worktree, no shell, no graph mutation, and no subagent nesting. Runner failure returns `status:"agent_run_failed"` and leaves metadata unchanged (no side effects). The prewritten-file `missing_agent_result` path is removed from this layer; focused tests and the portable faux-provider witness probe prove the contract and a deterministic worker file change, while real-provider/manual worker evidence remains frontier work. - -> D101-L GitLandPort run-local promotion refinement (2026-07-01, FE-1112): `execute_promotion_prepare` now runs an injected `GitLandPort` before writing `promotion.json`. The executor core (`src/executor/promotion.ts`) owns only the port type, existing run/Petri/report metadata, promotion report append, and metadata transition; the app layer (`src/app/git-land-port.ts`) owns run-local git operations in the run worktree (`git status --porcelain`, `git add -A`, `git commit`, `git rev-parse HEAD`). This first promotion layer commits verified sandbox worktree diffs locally and records the promoted commit SHA in `promotion.json` / `run.json`; host branch/ref promotion remains deferred. `no_changes` and port failures do not advance run metadata and report no side effects. Because real run-local git promotion exists, `execute_status.pendingTools` is empty; host promotion is explicitly deferred rather than a remaining pending execute foothold. - -> D101-L host-promotion preflight/apply refinement (2026-07-01, FE-1118): `preflightHostPromotion` validates a `promotion_prepared` run's `run.json.promotionCommitSha` against `promotion/promotion.json` and delegates promoted-commit diff inspection to injected `GitHostPromotionPort`. `applyHostPromotion` requires an accepted commit SHA, reruns preflight, refuses stale acceptance, and then delegates patch application. The executor core (`src/executor/host-promotion.ts`) reads existing run/promotion metadata only; preflight returns `missing_run`, `run_not_promoted`, `promotion_not_found`, `preflight_failed`, or `preflight_ready` with `sideEffects: []`, while accepted apply reports a bounded `host_worktree_apply` side effect. The app layer (`src/app/git-host-promotion-port.ts`) owns read-only git inspection in the run worktree plus host-file patch application via `git diff --binary` from the run worktree and `git apply --check` / `git apply` in the host cwd. CODE-mode exposes this through `execute_host_promotion_preflight` and `execute_host_promotion_apply`; the apply tool requires `acceptedCommitSha`, both tools preserve helper result details, executor active-tool policy admits them, and `execute_status` lists them as ported. Apply mutates host files only; host commits, refs, branch switching, and index staging remain out of scope. + @@ -332,7 +324,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c | I53-L | `session.submitExchangeResponse` review-set approval validates the rehydrated pending `reviewSet` against the canonical `zReviewSetDetailsPayload` schema (owned by `src/.pi/extensions/exchanges/schemas/present.ts`) before constructing a `ReviewSetProposalPayload`; malformed persisted details surface as `structural_illegal` diagnostics rather than an unsafe-cast runtime throw. | covered (`src/rpc/__tests__/handlers.test.ts` malformed-pending-review-set and valid-approval RPC tests) | D27-L; I15-L, I20-L | | I54-L | Every id in `LIVE_BRUNCH_SKILL_IDS` (`src/agents/skills/registry.ts`) has a packaged `dist/agents/skills//SKILL.md` after `npm run build`; `scripts/copy-skill-resources.mjs` derives the copy/cleanup list from the compiled registry rather than a second hardcoded id list, so a published install cannot silently miss a live skill's runtime-loaded resource or retain a retired one. | covered (`src/agents/skills/__tests__/registry.test.ts` source-file check always runs; dist-file check runs whenever `dist/` is present, i.e. after `npm run build`) | D39-L, D52-L, D95-L, D100-L | | I55-L | No committed `.fixtures/runs/**` promoted-evidence file contains an absolute developer-workstation path (`/Users//…`, `/home//…`); leaked cwd/prompt-resource/tool-call paths are normalized to a portable placeholder (``, ``, ``, ``) that preserves replay/review value without machine-specific roots. `.fixtures/seeds/**` is out of scope — curated source-domain input, not run evidence. | covered (`npm run check:promoted-run-paths` enumerates via `git ls-files .fixtures/runs`, wired into `npm run check`) | requirement 24 | -| I56-L | Execute-mode orchestration footholds remain bounded until the runner frontier explicitly accepts host git mutation. Active CODE-mode tools are read-only and report `sideEffects: []`; writer/lifecycle scaffold tools remain registered/testable but inactive until the real-execution stack lands. Those inactive tools write only declared files under `.brunch/execution-reports` or `.brunch/cook` when invoked directly by tests; `execute_worktree_create` uses injected `GitWorktreePort` for the real `git_worktree_add`, `execute_agent_result` uses injected `AgentRunnerPort` for the active slice's worktree/request/result paths and sealed worker launch, `execute_test_result` uses injected `TestRunnerPort` for the real verify subprocess in the run worktree, `execute_promotion_prepare` uses injected `GitLandPort` for run-local worktree promotion, and `execute_host_promotion_preflight` / `execute_host_promotion_apply` use injected `GitHostPromotionPort` for explicit accepted-SHA host file application without creating commits, refs, branch switches, index staging, or graph mutations. The worker may write only through bounded worktree tools (`write_worktree_file` in this tracer). | covered (`src/.pi/extensions/__tests__/agent-runtime-runtime.test.ts` proves lifecycle tools are inactive in execute mode; `src/.pi/extensions/__tests__/registry.test.ts` and `src/executor/__tests__/*` cover tool registration, side-effect details, bounded paths, port injection, run metadata transitions, and path traversal guards; `src/.pi/extensions/__tests__/subagents.test.ts` proves the worker registry/grant boundary; `src/app/__tests__/agent-runner-port.test.ts`, `src/app/__tests__/git-host-promotion-port.test.ts`, `src/app/__tests__/git-land-port.test.ts`, `src/app/__tests__/git-worktree-port.test.ts`, and `src/app/__tests__/test-runner-port.test.ts` cover app-layer runner/git/verify contracts) | D39-L, D40-L, D52-L, D58-L, D90-L, D91-L, D92-L, D93-L, D98-L, D101-L | +| I56-L | Execute-mode orchestration stays bounded behind injected `ExecutionPorts`. Every `execute_*` tool advances run metadata with at most one explicit, declared side effect; executor core imports no git/subprocess/SDK — real capabilities enter only through app-layer port implementations (`GitWorktreePort`, `AgentRunnerPort`, `TestRunnerPort`, `GitLandPort`, `GitHostPromotionPort`); writers touch only declared files under `.brunch/execution-reports`, `.brunch/cook`, or the run worktree; the sealed `worker` writes only through bounded worktree tools (`write_worktree_file` in this tracer); port failure (`worktree_create_failed`, `agent_run_failed`, `test_run_failed`, promotion/apply failures) leaves run metadata unadvanced; and host mutation is limited to accepted-SHA file application via `execute_host_promotion_apply` after a rerun preflight — no host commits, refs, branch switches, index staging, or graph mutations. | covered (`src/.pi/extensions/__tests__/agent-runtime-runtime.test.ts` proves CODE-mode activation matches the executor tool allowlist, including the host-promotion tools; `src/.pi/extensions/__tests__/registry.test.ts` and `src/executor/__tests__/*` cover tool registration, side-effect details, bounded paths, port injection, run metadata transitions, and path traversal guards; `src/.pi/extensions/__tests__/subagents.test.ts` proves the worker registry/grant boundary; `src/app/__tests__/agent-runner-port.test.ts`, `src/app/__tests__/git-host-promotion-port.test.ts`, `src/app/__tests__/git-land-port.test.ts`, `src/app/__tests__/git-worktree-port.test.ts`, and `src/app/__tests__/test-runner-port.test.ts` cover app-layer runner/git/verify contracts) | D39-L, D40-L, D52-L, D58-L, D90-L, D91-L, D92-L, D93-L, D98-L, D101-L | ## Future Direction Register @@ -431,6 +423,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c | **Agent role** | A worker identity. The **foreground session-agent role** (`elicitor` for SPEC, `executor` for CODE) drives the main turn and is *derived* from operational mode 1:1 (D93-L/D98-L), … | | **Agent definition** | Composition control unit (D58-L/D90-L): a keyed agent's identity/system prompt, model/thinking preset, mode-gated tool authority summary, resource grants, and delegation allow-list. … | | **Session agent** | The main-thread agent that drives the session forward — `elicitor` in SPEC mode, `executor` in CODE mode — resolved 1:1 from operational mode (D93-L/D98-L). It is the only agent represented in session state (D40-L); … | +| **Execution ports (`ExecutionPorts`)** | The injected capability-port bag through which real execution enters executor core (D101-L): port types live in `src/executor/execution-ports.ts`; app-layer implementations (`src/app/*-port.ts`) own git/subprocess/SDK effects; Pi composition injects them. Core stays free of external-capability imports (I56-L). | | **Subagent** | A main-agent-invoked, blocking background child session (D44-L/D91-L): caller chooses a background `AgentManifest`, Brunch starts a sealed in-process SDK `AgentSession`, … | | **Strategy** | Suspended as runtime state by D98-L. The term may survive only as prompt-resource or reference vocabulary for interaction shapes if a concrete agent behavior proves it useful; it is not a user-changeable axis, … | | **Lens** | Suspended as runtime state by D98-L. The term may survive only as prompt-resource or reference vocabulary for topical/plane framing (`intent`, `design`, `oracle`) if a concrete agent behavior proves it useful; … | @@ -728,6 +721,8 @@ The first required probe is M0: after manual TUI interaction, a checker proves ` | I48-L | Inner — seed CLI contract tests for target workspace resolution, seed-ref filtering, explicit all-seeds mode, `CommandExecutor`/change-log routing, and destination reporting. … | | I49-L | Middle (covered by `subagent-reconciliation` slice 4) — negative-space invariant over the code-owned op_mode→delegatable-set allowlist: spawnable agents per op_mode equal the allowlist; … | + + ### Design Notes - **Prompt-resource manifests before eager prompt injection.** For live skill and reference guidance, prefer a deterministic per-turn manifest plus agent-driven `read` loading over a Brunch state machine that selects and concatenates large semantic prompt bodies. Inner-loop tests prove manifest legality and filtering; behavioral probes judge whether the agent loads and applies the right resource. @@ -760,6 +755,7 @@ The first required probe is M0: after manual TUI interaction, a checker proves ` | Capture confidence-classification + gap abstract-map quality | The LLM's confidence banding (hi vs lo) and its abstract-mapping of a low-confidence noticing to the *right* existing gap (vs spawning a redundant one) are semantic judgments with … | Manual review via `.brunch/debug/*` prompt-composition inspection and live testing; … | | Subagent digest / world-read quality (`subagent-reconciliation`) | A background child's session digest + graph read carry a *slice* of the parent world; … | The seal/isolation oracle proves the child reads only legal, parent-`specId`-scoped data; … | | Subagent snapshot staleness (`subagent-reconciliation`) | World binding is snapshot-at-spawn (D91-L); graph/session changes during a child's run are not seen by that child. | Accepted by design for run-to-completion children — the snapshot is consistent for the child's lifetime; the staleness window is named in D91-L, not silently tolerated. | +| Executor worker content quality (real provider) | The FE-1111 faux-provider witness proves runner wiring, sealed-worker tool authority, and a deterministic worktree write — not that a real model produces useful slice diffs that pass verify. | Faux witness (`src/probes/executor-agent-runner-witness.ts`) stays the wiring oracle; real-provider cook-run evidence rides future outer-loop probe runs, judged as fitness, not a merge gate. | ### Acceptance Criteria diff --git a/memory/cards/executor-agent-runner--agent-runner-port.md b/memory/cards/executor-agent-runner--agent-runner-port.md deleted file mode 100644 index 9f48d22a1..000000000 --- a/memory/cards/executor-agent-runner--agent-runner-port.md +++ /dev/null @@ -1,63 +0,0 @@ -# executor-agent-runner — AgentRunnerPort contract slice - -## Orientation - -- Containing seam: `orchestrator-cutover` real-execution substrate, after `executor-sandbox` proved real git worktrees and real verify subprocesses behind injected capability ports. -- Frontier item: `executor-agent-runner` (FE-1111) on `ka/fe-1111-executor-agent-runner`, stacked on `ka/fe-1109-cook-sandbox`. -- Handoff state: no `HANDOFF.md` present; parent branch says FE-1109 is built and ready to tie off. -- Main open risk: the write-capable CODE worker must reuse the D90-L-D93-L sealed subagent substrate without punching an ambient write/shell hole into executor core or resurrecting prewritten `result.json` ingest. - -## Scope Weight - -Full scope card. This slice establishes the LLM-bearing execution-port seam and crosses executor core, Pi tool registration, app composition, and the sealed subagent substrate. - -## Target Behavior - -`execute_agent_result` runs an injected `AgentRunnerPort` for the active requested slice and records the runner's real output as the slice agent result. - -## Boundary Crossings - -```text -execute_agent_result Pi tool -→ src/executor/agent-result.ts -→ src/executor/execution-ports.ts AgentRunnerPort contract -→ injected app-layer runner implementation/fake -→ run worktree agent-output/report metadata -``` - -## Risks and Assumptions - -- RISK: implementing the real write-capable worker and the orchestration transition in one slice obscures whether the port boundary is right. → MITIGATION: first prove the port contract and Pi injection with a fake runner; leave the concrete CODE worker body/catalog for the next slice. -- RISK: the old prewritten-file path remains live and masks that no worker ran. → MITIGATION: remove `missing_agent_result` / `readFile(result.json)` behavior from the tool path; focused tests must fail if no runner is injected or if the runner is not invoked. -- ASSUMPTION: `slice_execution_requested` metadata already carries enough context for the runner contract: run id, active epic/slice, worktree path, and request artifact path. → VALIDATE: the port args asserted in executor tests include those fields and no app/Pi imports enter `src/executor`. -- ASSUMPTION: a runner execution failure should not advance run metadata, matching `GitWorktreePort` and `TestRunnerPort` failure posture. → VALIDATE: focused failure test returns an explicit failure status with `sideEffects: []` and leaves `run.json` unchanged. - -## Acceptance Criteria - -✓ `src/executor/__tests__/agent-result.test.ts` — `ingestAgentResult` invokes an injected `AgentRunnerPort`, appends `slice_agent_result`, records `agentResultPath` / runner summary, and never reads a prewritten `agent-output//result.json`. - -✓ `src/executor/__tests__/agent-result.test.ts` — runner failure returns an explicit non-advancing status with no side effects and preserves `status:"slice_execution_requested"`. - -✓ `src/.pi/extensions/__tests__/registry.test.ts` — the registered `execute_agent_result` tool is wired with the injected fake runner and no longer describes itself as prewritten-result ingestion. - -✓ `src/executor/execution-ports.ts` — `AgentRunnerPort` has concrete arg/result types and executor core still imports no `src/app`, `.pi`, git, subprocess, or SDK implementation modules. - -## Verification Approach - -- Inner: focused Vitest contract tests for `agent-result` and Pi registry injection prove the port call, metadata transition, side-effect report, and failure posture. -- Middle: `npm run fix` after edits proves lint/format and catches type-aware seam drift. -- Gate: `npm run verify` before commit. - -## Promotion Checklist - -- [x] Does this change a requirement? It materializes D99-L's `AgentRunnerPort` layer. -- [ ] Does this create, retire, or invalidate an assumption? -- [x] Does this make or reverse a non-trivial design decision? It chooses the first runner transition shape: injected runner result instead of prewritten file ingest. -- [x] Does this establish a new seam-level invariant? Runner failure must not advance run metadata; executor core remains implementation-free. -- [x] Does it cross more than two major seams? -- [x] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Build it with `ln-build`. diff --git a/memory/cards/executor-agent-runner--default-runner-composition.md b/memory/cards/executor-agent-runner--default-runner-composition.md deleted file mode 100644 index 5f58f11e5..000000000 --- a/memory/cards/executor-agent-runner--default-runner-composition.md +++ /dev/null @@ -1,16 +0,0 @@ -# executor-agent-runner — default runner composition proof - -## Objective - -Prove `execute_agent_result` uses the default app-composed `AgentRunnerPort` when sealed subagent deps are injected, instead of requiring a manually supplied fake port. - -## Acceptance Criteria - -✓ `src/.pi/extensions/__tests__/registry.test.ts` — `createBrunchPiExtensions` with `subagents` but without an explicit `agentRunner` registers `execute_agent_result` through the default runner. - -✓ The default runner launches the sealed `worker` over the run worktree, observes a real file change in that worktree, writes the result artifact, and preserves the existing metadata/report transition. - -## Verification Approach - -- Inner: focused registry test for default runner composition. -- Gate: `npm run verify`. diff --git a/memory/cards/executor-agent-runner--sealed-code-worker.md b/memory/cards/executor-agent-runner--sealed-code-worker.md deleted file mode 100644 index 3fac5a5f3..000000000 --- a/memory/cards/executor-agent-runner--sealed-code-worker.md +++ /dev/null @@ -1,66 +0,0 @@ -# executor-agent-runner — sealed CODE worker tracer slice - -## Orientation - -- Containing seam: `orchestrator-cutover` real-execution substrate; FE-1111 now has the `AgentRunnerPort` contract and Pi injection path, but the default app-layer runner still fails closed. -- Frontier item: `executor-agent-runner` (FE-1111) on `ka/fe-1111-executor-agent-runner`, stacked on `ka/fe-1109-cook-sandbox`. -- Handoff state: no `HANDOFF.md` present; the built port slice proved `execute_agent_result` no longer reads prewritten `result.json` and failure does not advance metadata. -- Main open risk: the real worker needs Pi execution context plus write capability without reopening ambient `~/.pi`, parent conversation, or unrestricted shell/write access. - -## Scope Weight - -Full scope card. This slice implements the first real write-capable worker over the sealed subagent substrate and may refine the `AgentRunnerPort` args to carry Pi model context. - -## Target Behavior - -`execute_agent_result` can launch a sealed CODE worker that writes a real sandbox-worktree change for the active slice. - -## Boundary Crossings - -```text -execute_agent_result Pi tool -→ AgentRunnerPort args carrying run/worktree/request/result paths plus Pi model context -→ src/app/agent-runner-port.ts concrete runner -→ src/.pi/extensions/subagents sealed child-session runner/catalog -→ src/agents/subagents/worker.md body/frontmatter -→ sandbox worktree file diff -``` - -## Risks and Assumptions - -- RISK: write-capable subagent grants accidentally expose ambient filesystem or shell authority. → MITIGATION: add only a bounded Brunch-owned worktree write/edit tool to the subagent catalog; do not grant shell in this slice. -- RISK: the app-layer runner cannot build a child session from the port args because model/modelRegistry/signal currently live in the Pi tool execution context, not the core run metadata. → MITIGATION: thread only the required Pi execution context through `execute_agent_result` into `AgentRunnerPort.run`; keep executor core unaware of SDK implementation types where possible and isolate SDK-specific types to the Pi/app boundary if needed. -- RISK: a live model run is too expensive/flaky for the inner loop. → MITIGATION: prove the worker through the existing injectable child-session/faux-provider path, with a deterministic fake child that calls the bounded write tool and returns a summary; leave real-provider/manual evidence for a later witness if needed. -- ASSUMPTION: a single bounded write/edit tool is enough to prove real sandbox diffs before adding shell or richer patch application. → VALIDATE: focused test observes an actual file change under the worktree after `execute_agent_result`. - -## Acceptance Criteria - -✓ `src/.pi/extensions/subagents/__tests__/agents.test.ts` or adjacent subagent tests — a `worker` background definition is registry-owned, validates frontmatter, and is not spawnable by SPEC/elicitor delegation. - -✓ `src/.pi/extensions/subagents/__tests__/agents.test.ts` or adjacent subagent tests — the worker grant resolves only bounded worktree read/write tools needed for this tracer and does not include shell, ambient discovery, graph mutation, or `subagent` nesting. - -✓ `src/app/__tests__/agent-runner-port.test.ts` — the concrete app-layer `AgentRunnerPort` launches the sealed worker over the requested worktree and produces an actual file change under that worktree using a deterministic fake child-session path. - -✓ `src/.pi/extensions/__tests__/registry.test.ts` — `execute_agent_result` threads the required Pi model context/signal into the injected runner while preserving the existing metadata/report transition and failure posture. - -✓ `src/executor/agent-result.ts` / architecture checks — executor core remains free of `src/app`, `.pi`, SDK, git, subprocess, and shell implementation imports. - -## Verification Approach - -- Inner: focused Vitest tests for subagent definition/catalog grants, app-layer runner contract, and Pi registry context threading. -- Middle: `npm run fix` after edits. -- Gate: `npm run verify` before commit. - -## Promotion Checklist - -- [x] Does this change a requirement? It materializes FE-1111's real change-producing worker layer. -- [x] Does this create, retire, or invalidate an assumption? It validates whether bounded write/edit authority is enough before shell. -- [x] Does this make or reverse a non-trivial design decision? It chooses a bounded worktree write/edit tracer rather than immediate shell authority. -- [x] Does this establish a new seam-level invariant? Worker write authority is catalog-bounded and op-mode/delegation-gated, not ambient. -- [x] Does it cross more than two major seams? -- [ ] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Build it with `ln-build`. diff --git a/memory/cards/executor-agent-runner--worker-witness-probe.md b/memory/cards/executor-agent-runner--worker-witness-probe.md deleted file mode 100644 index 43e65ccec..000000000 --- a/memory/cards/executor-agent-runner--worker-witness-probe.md +++ /dev/null @@ -1,16 +0,0 @@ -# executor-agent-runner — worker witness probe - -## Objective - -Add a runnable witness probe for the default executor agent-runner path. - -## Acceptance Criteria - -✓ `src/probes/__tests__/executor-agent-runner-witness.test.ts` — runs the default `AgentRunnerPort` through the sealed `worker` over a faux provider and observes an actual worktree write via `write_worktree_file`. - -✓ Probe artifact writer persists portable request/result/proof/report files under `runs/executor-agent-runner-witness//` when given a fixture root. - -## Verification Approach - -- Inner: focused witness probe tests. -- Gate: `npm run verify`. diff --git a/memory/cards/executor-host-promotion--apply-hardening.md b/memory/cards/executor-host-promotion--apply-hardening.md deleted file mode 100644 index 4799a7044..000000000 --- a/memory/cards/executor-host-promotion--apply-hardening.md +++ /dev/null @@ -1,51 +0,0 @@ -# executor-host-promotion — host apply hardening slice - -## Orientation - -- Containing seam: `executor-host-promotion` (FE-1118), after helper/app/Pi host promotion surfaces are built. -- Frontier item: `executor-host-promotion` on `ka/fe-1118-executor-host-promotion`, stacked on `ka/fe-1112-executor-promotion`. -- Review trigger: `ln-review` found the real `git apply` stdin boundary lacks an integration oracle, the apply result type admits an impossible state, and a dead path alias remains. - -## Scope Weight - -Light scope card. This is bounded hardening inside the established FE-1118 host-promotion seam. - -## Objective - -Harden host apply by proving the real git patch path and tightening the public apply result shape. - -## Acceptance Criteria - -✓ `src/app/__tests__/git-host-promotion-port.test.ts` uses real temp git repositories to prove a promoted commit patch applies to host files without changing host HEAD or staging the index. - -✓ `src/app/__tests__/git-host-promotion-port.test.ts` uses real temp git repositories to prove conflicting host edits fail at `git apply --check` without mutating host files. - -✓ `HostPromotionApplyResult` excludes the impossible `preflight_ready` pass-through state. - -✓ The unused `hostPromotionReportPath` alias is deleted unless a real caller exists. - -## Verification Approach - -- Inner: focused Vitest tests for `git-host-promotion-port` and `host-promotion` type/behavior coverage. -- Gate: `npm run verify`. - -## Build Result - -- Done: real temp-git success and conflict tests cover the app-layer patch path. -- Done: `HostPromotionApplyResult` excludes `preflight_ready`. -- Done: unused `hostPromotionReportPath` alias deleted. -- Verification: focused host-promotion tests pass; full gate pending at the time this card was reconciled. - -## Promotion Checklist - -- [ ] Does this change a requirement? -- [ ] Does this create, retire, or invalidate an assumption? -- [ ] Does this make or reverse a non-trivial design decision? -- [ ] Does this establish a new seam-level invariant? -- [ ] Does it cross more than two major seams? -- [ ] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Build it with `ln-build`. diff --git a/memory/cards/executor-host-promotion--host-apply.md b/memory/cards/executor-host-promotion--host-apply.md deleted file mode 100644 index 2c7c063ec..000000000 --- a/memory/cards/executor-host-promotion--host-apply.md +++ /dev/null @@ -1,61 +0,0 @@ -# executor-host-promotion — explicit host apply slice - -## Orientation - -- Containing seam: `executor-host-promotion` (FE-1118), after preflight established read-only diff inspection. -- Frontier item: `executor-host-promotion` on `ka/fe-1118-executor-host-promotion`, stacked on `ka/fe-1112-executor-promotion`. -- Main risk: this is the first deliberate host-file mutation; branch/ref/index mutation must still stay out of scope. - -## Scope Weight - -Full scope card. This crosses the hard host-mutation boundary and establishes the explicit-acceptance apply seam. - -## Target Behavior - -Host apply mutates the host worktree to match a validated promoted run diff after explicit acceptance. - -## Boundary Crossings - -```text -future host-promotion Pi tool or core helper -→ run metadata / promotion.json -→ host-promotion preflight -→ run worktree promoted commit patch -→ host worktree file mutation report -``` - -## Risks and Assumptions - -- RISK: apply mutates the wrong host state or stale promotion. → MITIGATION: rerun preflight inside apply and require the accepted commit SHA to match the current promoted SHA before mutation. -- RISK: apply clobbers local host edits. → MITIGATION: app-layer apply must run a no-write check first and fail closed when the patch cannot apply cleanly. -- RISK: apply accidentally creates a commit, branch, ref, or staged index state. → MITIGATION: tests assert host HEAD/ref and index remain unchanged; only host worktree files may change. -- ASSUMPTION: applying the promoted commit patch to the host worktree without committing is the right first host-mutation layer. → VALIDATE: focused tests prove accepted apply changes files and leaves branch/ref/index unchanged. - -## Acceptance Criteria - -✓ Core apply returns `needs_acceptance` without side effects when no accepted commit SHA is supplied. - -✓ Core apply reruns preflight and refuses stale or mismatched accepted commit SHA before mutation. - -✓ App/core apply checks the promoted patch before writing and reports `apply_failed` without host file/index/ref mutation on conflicts. - -✓ App/core apply changes only host worktree files for the promoted diff; it does not commit, create refs, switch branches, or stage the host index. - -## Verification Approach - -- Inner: focused Vitest tests for explicit acceptance, stale metadata, conflict/no-write failure, and successful host file mutation with unchanged HEAD/ref/index. -- Gate: `npm run verify`. - -## Promotion Checklist - -- [x] Does this change a requirement? It materializes FE-1118's first accepted host-file mutation layer. -- [x] Does this create, retire, or invalidate an assumption? It validates that patch-to-worktree without commit/ref/index mutation is the right first host apply layer. -- [x] Does this make or reverse a non-trivial design decision? It chooses host worktree patch application before any host commit/ref operation. -- [x] Does this establish a new seam-level invariant? Host apply requires accepted commit SHA confirmation and reruns preflight before mutation. -- [x] Does it cross more than two major seams? -- [ ] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Scope Pi tool exposure if FE-1118 needs user-drivable CODE-mode host apply before tie-off. diff --git a/memory/cards/executor-host-promotion--pi-tool.md b/memory/cards/executor-host-promotion--pi-tool.md deleted file mode 100644 index a25822dc2..000000000 --- a/memory/cards/executor-host-promotion--pi-tool.md +++ /dev/null @@ -1,61 +0,0 @@ -# executor-host-promotion — Pi tool exposure slice - -## Orientation - -- Containing seam: `executor-host-promotion` (FE-1118), after helper-level preflight and accepted host-file apply are built. -- Frontier item: `executor-host-promotion` on `ka/fe-1118-executor-host-promotion`, stacked on `ka/fe-1112-executor-promotion`. -- Main risk: exposing host mutation to CODE mode must preserve explicit acceptance and make side effects inspectable at the Pi tool boundary. - -## Scope Weight - -Full scope card. This exposes the host-mutation helper through the user/agent tool surface and crosses the Pi adapter boundary. - -## Target Behavior - -CODE mode can run host-promotion preflight and accepted host apply through explicit Pi tools. - -## Boundary Crossings - -```text -CODE-mode Pi tool call -→ .pi agent-runtime registrar -→ executor host-promotion helper -→ GitHostPromotionPort -→ tool result details / side-effect report -``` - -## Risks and Assumptions - -- RISK: host apply becomes callable without explicit acceptance. → MITIGATION: the apply tool must require `acceptedCommitSha` and return `needs_acceptance` / `acceptance_mismatch` without mutation when absent or stale. -- RISK: tool result hides host mutation side effects. → MITIGATION: details must preserve the helper result and sideEffects array exactly, and content must summarize changed files and side effects. -- RISK: default app composition forgets the new port/tool wiring. → MITIGATION: registry tests inject a fake `GitHostPromotionPort` and prove both tools register and call it. -- ASSUMPTION: two explicit tools (`execute_host_promotion_preflight`, `execute_host_promotion_apply`) are clearer than overloading `execute_promotion_prepare`. → VALIDATE: focused registry tests prove separate no-mutation and mutation surfaces with distinct parameter shapes. - -## Acceptance Criteria - -✓ Pi registry exposes `execute_host_promotion_preflight` when `GitHostPromotionPort` is injected and returns the preflight helper result with `sideEffects: []`. - -✓ Pi registry exposes `execute_host_promotion_apply` when `GitHostPromotionPort` is injected and requires `acceptedCommitSha` before host mutation. - -✓ Apply tool result preserves `host_worktree_apply` side effects and changed files in machine-readable details. - -✓ Default extension composition wires the concrete app `GitHostPromotionPort` alongside existing execution ports without changing existing execute tool behavior. - -## Verification Approach - -- Inner: focused Vitest registry tests for tool registration, parameter handling, result details, and explicit-acceptance failure. -- Gate: `npm run verify`. - -## Promotion Checklist - -- [x] Does this change a requirement? It makes FE-1118 host promotion user-drivable from CODE mode. -- [x] Does this create, retire, or invalidate an assumption? It validates that separate preflight/apply tools are clearer than overloading run-local promotion prepare. -- [x] Does this make or reverse a non-trivial design decision? It exposes accepted host-file mutation at the Pi adapter boundary while preserving the helper seam. -- [x] Does this establish a new seam-level invariant? Host apply remains explicit-acceptance gated at the tool boundary and reports side effects in details. -- [x] Does it cross more than two major seams? -- [ ] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Review or tie off FE-1118. diff --git a/memory/cards/executor-host-promotion--preflight.md b/memory/cards/executor-host-promotion--preflight.md deleted file mode 100644 index 47e851d0e..000000000 --- a/memory/cards/executor-host-promotion--preflight.md +++ /dev/null @@ -1,59 +0,0 @@ -# executor-host-promotion — host preflight slice - -## Orientation - -- Containing seam: `executor-host-promotion` (FE-1118), after FE-1112 built run-local promotion and recovery. -- Frontier item: `executor-host-promotion` on `ka/fe-1118-executor-host-promotion`, stacked on `ka/fe-1112-executor-promotion`. -- Main risk: host branch mutation is the externally visible, hard-to-reverse seam; first slice must inspect only. - -## Scope Weight - -Full scope card. This establishes the host-promotion boundary while deliberately keeping mutation out of scope. - -## Target Behavior - -Host promotion preflight validates a run-local promotion and reports the host diff that would be applied without changing the host branch. - -## Boundary Crossings - -```text -future host-promotion Pi tool or core helper -→ run metadata / promotion.json -→ run worktree git commit/diff inspection -→ host preflight report -``` - -## Risks and Assumptions - -- RISK: preflight accidentally mutates host files, refs, branch, or index. → MITIGATION: tests assert host cwd contents and git status are unchanged. -- RISK: preflight trusts stale promotion metadata. → MITIGATION: validate `promotionCommitSha` / `promotion.json` against the run worktree before producing an applyable diff report. -- ASSUMPTION: a diff/report-only slice is enough to make the host apply seam reviewable before mutation. → VALIDATE: focused tests prove the report contains the promoted SHA and changed files while host state is unchanged. - -## Acceptance Criteria - -✓ Core preflight returns `missing_run`, `run_not_promoted`, or `promotion_not_found` without side effects for invalid inputs. - -✓ Core preflight validates `run.json.promotionCommitSha` and `promotion.json.land.commitSha` agree. - -✓ App/core preflight computes the promoted worktree diff against its parent/base and reports changed files / patch summary without mutating the host cwd. - -✓ No host branch/ref/index/file mutation occurs in this slice. - -## Verification Approach - -- Inner: focused Vitest tests for preflight success, stale metadata, and no host mutation. -- Gate: `npm run verify`. - -## Promotion Checklist - -- [x] Does this change a requirement? It materializes FE-1118's inspection-only host-promotion boundary. -- [x] Does this create, retire, or invalidate an assumption? It validates that a preflight-only slice can make host apply reviewable before mutation. -- [x] Does this make or reverse a non-trivial design decision? It chooses read-only run-worktree diff inspection before explicit host apply. -- [x] Does this establish a new seam-level invariant? Host-promotion preflight must not mutate host files, refs, or index state. -- [x] Does it cross more than two major seams? -- [ ] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Scope the explicit host-apply slice with `ln-scope`. diff --git a/memory/cards/executor-promotion--promotion-metadata-recovery.md b/memory/cards/executor-promotion--promotion-metadata-recovery.md deleted file mode 100644 index 77f6de0ab..000000000 --- a/memory/cards/executor-promotion--promotion-metadata-recovery.md +++ /dev/null @@ -1,47 +0,0 @@ -# executor-promotion — promotion metadata recovery - -## Orientation - -- Containing seam: `executor-promotion` (FE-1112), after run-local `GitLandPort` landed. -- Review finding: `preparePromotion` performs the run-local git commit before writing `promotion.json` and updating `run.json`. -- Main risk: if `promotion.json` or `run.json` persistence fails after the git commit, retry sees a clean worktree and returns `promotion_no_changes`, leaving the run stuck at `petri_exported` despite a promoted commit existing. - -## Scope Weight - -Full scope card. This fixes a failure-mode invariant at the first real git mutation seam. - -## Target Behavior - -`execute_promotion_prepare` can recover or idempotently complete promotion metadata after a prior successful run-local git commit. - -## Boundary Crossings - -```text -execute_promotion_prepare Pi tool -→ src/executor/promotion.ts -→ GitLandPort result/recovery contract -→ promotion.json / run.json persistence -``` - -## Risks and Assumptions - -- RISK: no-change retry hides a prior successful promotion commit. → MITIGATION: teach the promotion path to distinguish “no changes because already promoted” from “nothing was ever promoted,” using durable promotion metadata or a port-reported current commit. -- RISK: recovery logic re-derives run topology. → MITIGATION: recovery may use only existing run metadata, worktree commit identity, and promotion artifact paths; it must not inspect or rewrite plan/Petri topology. -- ASSUMPTION: recording the promoted commit SHA before or during report persistence is enough to make retry safe. → VALIDATE: focused test simulates commit success followed by persistence failure, then reruns promotion and observes `promotion_prepared` with the same SHA. - -## Acceptance Criteria - -✓ `src/executor/__tests__/promotion.test.ts` — simulates successful `GitLandPort` commit followed by failed promotion metadata persistence; retry completes `promotion.json` / `run.json` instead of returning `promotion_no_changes`. - -✓ `src/app/__tests__/git-land-port.test.ts` — app-layer port exposes enough commit identity on a clean already-promoted worktree, or the core recovery path does not require app-layer changes because commit identity is already durable. - -✓ Failure paths that truly have no prior promoted commit still do not advance metadata. - -## Verification Approach - -- Inner: focused promotion recovery tests. -- Gate: `npm run verify`. - -## Recommended Next Route - -Build it with `ln-build`. diff --git a/memory/cards/executor-promotion--run-local-git-land-port.md b/memory/cards/executor-promotion--run-local-git-land-port.md deleted file mode 100644 index 1c2fee6a9..000000000 --- a/memory/cards/executor-promotion--run-local-git-land-port.md +++ /dev/null @@ -1,65 +0,0 @@ -# executor-promotion — run-local GitLandPort slice - -## Orientation - -- Containing seam: `orchestrator-cutover` real-execution substrate; `executor-sandbox` supplies a real git worktree and real verify runner, and `executor-agent-runner` supplies a sealed worker that can make sandbox diffs. -- Frontier item: `executor-promotion` (FE-1112) on `ka/fe-1112-executor-promotion`, stacked on `ka/fe-1111-executor-agent-runner`. -- Handoff state: FE-1111 is complete; `execute_promotion_prepare` is still descriptive and `execute_status.pendingTools` still reports `land`. -- Main open risk: promotion is the first hard-to-reverse git seam, so the first slice must stay run-local and consume existing run artifacts instead of touching host branches. - -## Scope Weight - -Full scope card. This slice establishes the `GitLandPort` capability boundary and changes the promotion seam from descriptive-only to a real, run-local git mutation. - -## Target Behavior - -`execute_promotion_prepare` promotes a completed run's verified sandbox worktree diff through an injected `GitLandPort` without mutating host branches. - -## Boundary Crossings - -```text -execute_promotion_prepare Pi tool -→ src/executor/promotion.ts -→ src/executor/execution-ports.ts GitLandPort contract -→ src/app/git-land-port.ts app-layer git implementation -→ run worktree git state / promotion artifact -``` - -## Risks and Assumptions - -- RISK: host branch/ref mutation sneaks into the first land slice. → MITIGATION: `GitLandPort` first supports run-local promotion only; tests assert no host `.git` branch/ref mutation and no writes outside the run/worktree/promotion paths. -- RISK: promotion re-derives run state and diverges from Petri/report artifacts. → MITIGATION: require `promotion_prepared` inputs to come from existing run metadata, Petri artifact, completed slices, and worktree path; no fresh plan topology derivation. -- RISK: no-op worktrees make promotion look successful without a diff. → MITIGATION: first port result must report an explicit `no_changes` / failure-style status that does not advance metadata, or a real promoted commit/ref artifact with changed files. -- ASSUMPTION: run-local commit/ref is enough to unlock the next reviewable layer before host promotion. → VALIDATE: focused tests prove a diff in the run worktree becomes a run-local promotion artifact, while host branch promotion remains absent. - -## Acceptance Criteria - -✓ `src/executor/__tests__/promotion.test.ts` — `preparePromotion` invokes an injected `GitLandPort` for a Petri-exported run with a worktree and records a real run-local promotion result. - -✓ `src/executor/__tests__/promotion.test.ts` — `GitLandPort` failure or no changes do not advance run metadata and report no side effects. - -✓ `src/app/__tests__/git-land-port.test.ts` — app-layer `GitLandPort` performs only run-local git operations inside the worktree/promotion area and returns the promoted commit/ref metadata. - -✓ `src/.pi/extensions/__tests__/registry.test.ts` — `execute_promotion_prepare` is wired with injected `GitLandPort`; `execute_status.pendingTools` remains `land` until the run-local layer is accepted as enough to drop it. - -✓ `src/executor/promotion.ts` / architecture checks — executor core imports no app, Pi, git, subprocess, or UI modules. - -## Verification Approach - -- Inner: focused Vitest tests for promotion core, app-layer git port, and Pi registry injection. -- Middle: `npm run fix`. -- Gate: `npm run verify`. - -## Promotion Checklist - -- [x] Does this change a requirement? It materializes FE-1112's first real promotion layer. -- [x] Does this create, retire, or invalidate an assumption? It validates whether run-local promotion is enough before host promotion. -- [x] Does this make or reverse a non-trivial design decision? It chooses run-local git promotion before host branch mutation. -- [x] Does this establish a new seam-level invariant? First promotion slice must not mutate host branches/refs. -- [x] Does it cross more than two major seams? -- [ ] Is this the first touch in an unfamiliar seam from a fresh thread? -- [ ] Can you not name the containing seam or current rationale from the live docs? - -## Recommended Next Route - -Build it with `ln-build`. diff --git a/memory/cards/orchestrator-tool-port--plan-check-tool.md b/memory/cards/orchestrator-tool-port--plan-check-tool.md deleted file mode 100644 index 1f889f143..000000000 --- a/memory/cards/orchestrator-tool-port--plan-check-tool.md +++ /dev/null @@ -1,111 +0,0 @@ -# Orchestrator Plan Check Tool - -Frontier: orchestrator-tool-port -Status: active -Mode: single -Created: 2026-06-25 - -## Orientation - -- Containing seam: the foreground `executor` agent in target-CODE / current-`execute` mode and the `.pi/extensions` adapter boundary; this slice replaces the branch-local standup stub with the first real cook-plan inspection tool. -- Relevant frontier item: `orchestrator-tool-port` / FE-1107, inherited as the Linear issue and branch boundary from `memory/PLAN.md`. -- Volatile handoff state: none in `HANDOFF.md` (absent); source context comes from the prior port analysis and the external `../brunch` orchestrator docs/source. -- Main open risk: accidentally importing the CLI's execution side effects before the read-only tool boundary is proved; preserve the D39-L sealed profile and D90-L-D93-L/I49-L code-owned authority model. - -Posture: proving (inherited from `orchestrator-tool-port`) - -## Target Behavior - -The foreground executor can inspect a cook plan through a product-registered, read-only `cook_plan_check` tool whose result contains plan shape plus contract findings. - -## Full-card cold-start reads - -- `memory/SPEC.md` — decisions / invariants: D39-L, D40-L, D90-L, D91-L, D92-L, D93-L, I49-L. -- `memory/PLAN.md` — frontier: `orchestrator-tool-port`. -- `src/.pi/extensions/TOPOLOGY.md` — adapter-only ownership and boundary rules. -- `src/agents/prompts/executor.md` — current execute-mode foreground prompt and stub wording to retire. -- `src/agents/runtime/executor/TOPOLOGY.md` and `src/agents/runtime/TOPOLOGY.md` — current CODE-mode runtime split; execute tool policy is a live runtime seam under `runtime/executor/`, and new execute seams should stay in that live runtime tree. -- `src/session/schema/tool-names.ts` — shared tool-name constants. -- `/Users/lunelson/Code/hashintel/brunch/ORCHESTRATOR.md` — source CLI behavior and plan format. -- `/Users/lunelson/Code/hashintel/brunch/src/orchestrator/src/{types.ts,plan-loader.ts,plan-contract.ts,cook-cli.ts}` — portable plan model, loader, contract, and plan-resolution behavior to adapt. - -## Boundary Crossings - -```text -→ foreground `executor` prompt/control assembly -→ executor active-tool allowlist + blocked-tool guard (do not reintroduce a second legacy runtime-policy tree) -→ `.pi/extensions/agent-runtime` Pi tool adapter -→ product-owned `src/orchestrator` plan loader + contract core -→ workspace cook plan path -→ typed Pi tool result content/details -``` - -## Risks and Assumptions - -- RISK: CLI code pulls in process exits, git worktree creation, model auth, or child Pi sessions too early → MITIGATION: port only pure/read-only plan loading and contract checking in this slice; no sandbox, engine, Petrinaut stream, or worker session imports. -- RISK: The foreground `executor` gains accidental write authority while replacing the stub → MITIGATION: keep `bash`, `edit`, and `write` blocked in the Pi runtime tool-call guard; register only the read-only `cook_plan_check` tool for this card. -- RISK: External source names leak as temporary compatibility aliases → MITIGATION: canonicalize the product-facing tool name now; delete the `orchestrator_stub` tool path when the real tool is registered. -- ASSUMPTION: The external cook plan contract is the right first tracer boundary for the port. - → IMPACT IF FALSE: the later `cook_run` surface may need a different plan source/result model, but this slice's blast radius is limited to read-only validation and prompt/tool naming. - → VALIDATE: focused tests over valid, malformed, and design-invalid plan fixtures plus runtime-policy assertions. - -## Posture check - -This is a proving tracer. It scores on proof of life by making execute mode call real cook-plan product code, on invariants by locking the foreground no-direct-write boundary while still exposing orchestration capability, and on uncertainty by testing that the external `brunch cook` plan contract can be ported without shell-wrapping the CLI. - -No separate spike is cheaper than this slice: the useful proof is whether the product registry, prompt, runtime policy, and plan contract all line up through the real execute-mode tool boundary. - -## Acceptance Criteria - -✓ `cook_plan_check` is product-registered for execute mode and returns a typed result for a valid plan path containing mode, epic count, slice count, policy-relevant findings, and source path. -✓ Invalid or contract-failing plans return deterministic typed findings/errors without creating `.brunch/cook/runs`, git worktrees, Petrinaut artifacts, or child Pi sessions. -✓ The branch-local executor stub is no longer advertised to the foreground executor, and the old stub registration path is retired. -✓ The Pi runtime tool-call guard still blocks direct `bash`, `edit`, and `write` for the foreground executor, with tests or assertions covering the new tool grant. -✓ `src/agents/prompts/executor.md` tells the foreground agent to use the real plan-check tool and preserves the no-direct-write instruction. - -## Verification Approach - -- Inner: focused unit/contract tests — plan loader/contract result shape, tool execution result, runtime policy grant/block invariants. -- Middle: `npm run fix` — project lint/format after edits. -- Gate: `npm run verify` — full fix/test/build before tying off the branch. - -## Cross-cutting obligations - -- Preserve D39-L sealed-profile discipline: no ambient Pi discovery, dynamic import scanning, or shell-wrapped CLI escape hatch. -- Preserve D90-L-D93-L/I49-L authority: foreground `executor` remains low-privilege; any future write-capable worker must be code-owned and explicitly allowlisted. -- Keep `.pi/extensions` adapter-only: reusable plan-contract logic belongs in product core, not hidden extension memory. -- Treat `.brunch/cook/runs/` as an execution artifact for later `cook_run`, not an artifact this read-only slice creates. - -## Expected touched paths (tentative) - -```text -memory/ -├── PLAN.md ~ -└── cards/ - └── orchestrator-tool-port--plan-check-tool.md + -src/ -├── orchestrator/ -│ ├── plan-contract.ts + -│ ├── plan-loader.ts + -│ ├── types.ts + -│ └── __tests__/ -│ └── plan-check.test.ts + -├── agents/ -│ ├── prompts/ -│ │ └── executor.md ~ -│ └── runtime/ -│ ├── TOPOLOGY.md ~ -│ └── shared/ or executor/ ? (new live execute policy seam if earned) -├── .pi/ -│ ├── extensions/ -│ │ ├── agent-runtime/ ~ -│ │ └── agent-runtime/orchestrator-stub/ - -│ └── __tests__/ ? -├── app/ -│ └── pi-extensions.ts ~ -└── session/ - └── schema/ - └── tool-names.ts ~ -package.json ? -package-lock.json ? -``` diff --git a/src/agents/runtime/executor/active-tools.ts b/src/agents/runtime/executor/active-tools.ts index 67a102918..5caf4b8b4 100644 --- a/src/agents/runtime/executor/active-tools.ts +++ b/src/agents/runtime/executor/active-tools.ts @@ -12,8 +12,8 @@ export const EXECUTOR_ALLOWED_TOOL_NAMES = [ 'read_session_context', 'read_graph', 'orchestrator_stub', - // Execute-mode orchestration footholds (FE-1089). Registered-but-inactive - // unless the executor admits them; side-effect-bounded per I52-L. + // Execute-mode orchestration tools (FE-1089..FE-1118). Registered tools are + // inactive unless admitted here; side-effect-bounded per I56-L. 'execute_status', 'execute_snapshot', 'execute_plan_check', diff --git a/src/executor/TOPOLOGY.md b/src/executor/TOPOLOGY.md index e88c2fb14..6b62f3b33 100644 --- a/src/executor/TOPOLOGY.md +++ b/src/executor/TOPOLOGY.md @@ -1,10 +1,10 @@ # executor/ — execute-mode projection contracts -SPEC decisions: FE-1089 cutover frontier; `brunch-orchestrator-cutover-to-next.md` Arc 1 data bridge. +SPEC decisions: D101-L (executor cutover over injected ports), D52-L (layer boundary) / I56-L (bounded execute-mode ports). ## Owns -Pure contracts and projection helpers that turn `next` graph facts into execute-mode orchestration inputs. This subtree is product core: it imports graph DTOs and emits stable orchestration DTOs, but it does not register Pi tools, read SQLite, run Petri nets, execute slices, or promote/land changes. +Pure contracts and orchestration helpers that turn `next` graph facts into execute-mode cook runs. This subtree is product core: it imports graph DTOs, owns run metadata/report transitions and the `ExecutionPorts` contract types, but it does not register Pi tools, read SQLite, or own subprocess/git/SDK effects — real capabilities enter only through app-layer port implementations (`src/app/*-port.ts`) injected by Pi composition. ```text executor/ @@ -45,7 +45,7 @@ rules: executor/ x> db/, .pi/, app/, rpc/, web/ [no storage, adapter, transport, or UI effects] ``` -`ExecutionSpecSnapshot` is the durable projection seam between the spec/graph product and the native execute-mode orchestrator. Both `main`-derived imports and `next` graph reads can target this shape while their internal models continue to evolve. Artifact writers in this subtree may write only explicit execution artifacts under `.brunch/execution-reports`; cook helpers may create only the side effects accepted below. They must not run agents, compile Petri nets, write report logs, promotion refs, land branches, or graph mutations. +`ExecutionSpecSnapshot` is the durable projection seam between the spec/graph product and the native execute-mode orchestrator. Both `main`-derived imports and `next` graph reads can target this shape while their internal models continue to evolve. Every helper advances run metadata with at most one explicit, declared side effect (I56-L): plan/outline artifact writers touch only `.brunch/execution-reports`; cook helpers write only the declared files under `.brunch/cook` or the run worktree described per module below; agent/test/promotion effects are delegated to injected ports; port failure leaves run metadata unadvanced. No helper mutates the graph, and host mutation is limited to the accepted-SHA file apply in `host-promotion.ts`. ## Cook plan preview compatibility