From 08d0ceea1392c628d89e55e1fd4e552a697e4b3a Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 18:00:34 +0200 Subject: [PATCH 01/35] major ln-sync pass --- .../ln-review/references/contract-lenses.md | 4 + .pi/settings.json | 3 + docs/archive/PLAN_HISTORY.md | 25 +- docs/design/WEB_UI_ARCHITECTURE.md | 2 +- memory/PLAN.md | 770 ++++-------------- memory/SPEC.md | 10 +- ...overy-tracer--warrant-ablation-campaign.md | 194 ----- ...end-comparison-tracer--factorial-matrix.md | 280 ------- package-lock.json | 17 +- src/dev/README.md | 2 +- src/dev/TOPOLOGY.md | 2 +- 11 files changed, 196 insertions(+), 1113 deletions(-) delete mode 100644 memory/cards/consequential-fact-discovery-tracer--warrant-ablation-campaign.md delete mode 100644 memory/cards/end-to-end-comparison-tracer--factorial-matrix.md diff --git a/.agents/skills/ln-review/references/contract-lenses.md b/.agents/skills/ln-review/references/contract-lenses.md index 7cb71bbbb..d61ac0ddb 100644 --- a/.agents/skills/ln-review/references/contract-lenses.md +++ b/.agents/skills/ln-review/references/contract-lenses.md @@ -38,6 +38,10 @@ Each finding routes to one of three repairs: **enforce it loudly** (fail on viol - A **hand-maintained test-double inventory shadowing a canonical registry** — a test stub (`getAllTools()`, capability lists, route tables) that transcribes the members of a live registry by hand instead of deriving from the canonical constant. Every add/retire in the registry silently drifts the stub: retired members linger (masking regressions the inventory-consuming logic should catch), new members are omitted (the code under test never sees them), duplicates creep in. Point-fixing the stub after a review comment repairs one snapshot, not the fault (graduated 2026-07-09 from the PR #304 induction: three fixture sites — `getAllTools()` listing `ask` twice, retaining retired `REQUEST_RESPONSE_TOOL`, and omitting active `present_digest` — were each corrected by hand while remaining transcribed). **Discriminator:** does a canonical exported constant/registry enumerate the same membership the stub hand-lists? If the double intentionally diverges (a minimal-capability harness, a degraded-context probe), the divergence must be *derived too* (canonical set minus named exclusions) or explicitly commented; a bare hand-list with no derivation and no divergence note is the finding. Repair class **thread the real value**: build the stub from the canonical constant (spread it, filter it with named exclusions); the double should express its *difference* from canon, never re-state canon. Search seam: grep test files for inventory-shaped stub methods and array literals of registry member names; cross against the exported canonical constants for that registry. +- A **deadness verdict computed by reference scan, applied to an artifact with out-of-graph consumers** — an "unused, delete it" claim derived from grepping the repo's import graph, aimed at an artifact whose consumption seam the scan cannot see: environment provisioning consumed by spawned runtimes (a CI apt package that agents under test shell out to), canonical intent registers (`TOPOLOGY.md`, `treedocs.yaml`, PLAN-parked items, intentional topology stubs), the published-package surface (runtime vs `devDependencies` decided by what consumers install, not what `src/` imports), and gitignored data planes. Both faces are silent: the delete lands green locally (import graph clean, default tests pass) and breaks only in a CI lane or consumer install — or the delete proceeds and the canonical docs that named the seam rot unreconciled (graduated 2026-08-03 from the reduction-review induction: CI `ripgrep` was flagged "nothing invokes it" while FE-1241's commit message provisioned it so "the Linux full gate can exercise bounded grep reads" by spawned agents; four deletion targets — `run-auto-replan-policy`, `row-schemas`, `drawer-card`, `validate-fixture` — were named by `TOPOLOGY.md` files the review never mentioned; a deps→`devDependencies` move was argued from repo imports rather than the published surface). **Discriminator:** does the artifact's consumption run through text the scan can see? If it was provisioned or declared *for* an out-of-graph consumer, reference-count zero is not evidence of deadness; a repo-code-only artifact with zero references and no canonical-doc mention is genuinely dead and not this lens. Repair class **name the contract**: annotate the provisioning site with its out-of-graph consumer (a comment on the CI install line naming the spawned-agent need and its decision/issue id), and gate every deletion on canonical-doc reconciliation (update or challenge the `TOPOLOGY.md`/PLAN entry in the same change). Search seam: for each delete claim, run `git log -S ` for stated purpose at introduction, and cross the target against `src/**/TOPOLOGY.md`, `src/treedocs.yaml`, and `memory/PLAN.md` parked items; for dependency reclassification, inspect what the published package (`files`/`prepack` output) actually needs at install time, and enumerate gitignored data planes with `git ls-files` rather than ignore-respecting globs. + +- A **contract-bearing predicate duplicated by copy instead of import** — a function whose result feeds an identity, parity, equality, or authority decision (`canonicalPath`, `markingsEqual`, terminal-summary classification, run-id derivation) defined independently in two or more production files rather than imported from one owner. The copies are typically byte-identical at introduction, so review sees "just a small helper"; the fault is latent — the first divergent edit makes seams that must agree (writer vs reader projection, git ports vs execution authority) silently disagree about "equal", "same path", or "terminal", with no error, while each copy's local tests stay green (graduated 2026-08-03 from two consecutive review-batch inductions: `stringArraysEqual` defined in four executor files with terminal-summary/marking semantics spread across `orchestrate.ts`, `observer-read.ts`, `petri-events.ts`, `petri-replay.ts` — a writer/reader-authority pair sharing state semantics by copy; `canonicalPath` defined identically in the three `src/app/git-*-port.ts` files plus `executor/worktree.ts` and `executor/run-execution-authority.ts` — the exact seams that must agree on path identity for promotion/landing writes; `pathExists` ×22 and `defaultRunId` ×7 as the same family at lower stakes). **Discriminator: does the predicate's result feed an equality/identity/parity/authority decision shared across seams?** If yes → this lens; a trivial shim with stable, decision-free semantics (`isRecord` ×32, `parseJson` ×11 at graduation time) is tolerated duplication, not the finding — do not flag it. Repair class **name the contract**: one imported owner per predicate family (an executor state-predicates module imported by writer, reader authority, and replay; one shared canonical-path helper for the git/authority seams); the copies then delete. Search seam: scan duplicate function definitions — `rg -n --no-heading '^(export )?(async )?function (\w+)\(' src -o -r '$3'` over production files, count names appearing in ≥2 files — then apply the discriminator to each hit; pay first attention to names containing `equal`, `canonical`, `terminal`, `default*Id`, `sanitize`, `classif`. + ## Catalog governance This catalog is the stabilized lens library. `ln-induct` is the generator that induces fresh lenses from review-bot evidence and proposes graduating recurring ones into this list. diff --git a/.pi/settings.json b/.pi/settings.json index 9619dd26d..e3a7c9d3c 100644 --- a/.pi/settings.json +++ b/.pi/settings.json @@ -1,5 +1,8 @@ { "packages": [ "npm:pi-interactive-shell@0.13.0" + ], + "extensions": [ + "-extensions/subagents/index.ts" ] } \ No newline at end of file diff --git a/docs/archive/PLAN_HISTORY.md b/docs/archive/PLAN_HISTORY.md index f08eede5d..10e9f8324 100644 --- a/docs/archive/PLAN_HISTORY.md +++ b/docs/archive/PLAN_HISTORY.md @@ -3,6 +3,27 @@ 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-08-03 Rolling PLAN trim (`ln-sync`, bru-uzev) + +The live PLAN was reduced back to a rolling shape: concise Context, Sequencing, live pickup definitions, 3-item Recently Completed, and an active/next-only dependency view. + +### Recently Completed entries archived from live PLAN + +- 2026-07-20 `agent-control-plane-closure` (FE-1216) — ✓ complete. PR #343 merged the earned control-plane sweep: foreground/background prompt ownership, honest child grants, load-on-demand context truth, and recorder-backed resource-read evidence landed; `capture-ledger-tracer` remains the proving follow-on. +- 2026-07-20 `operator-comparison-workflow` (FE-1215) — ✓ complete. PR #342 merged the D134-L direct-shell remediation and closeout corrections; the remaining work is explicitly split into `comparison-mission-isolation-hardening`, `saved-mission-comparison-witness`, and operator-owned CS3 cleanup confirmation. +- 2026-07-20 `comparison-reporting-skills` (FE-1232) — ✓ implementation complete. Separate project-shared Notion publication and comparison-evidence reporting skills landed with executable guardrails for active-procedure precedence, safe mutation, validity-first interpretation, reproducible judging, failure retention, and controller-only redaction. + +### Completed frontier definitions retired from live PLAN + +- `interactive-tui-driver` (FE-1206) — closed 2026-07-15; canonical developer-only TUI driving path settled with host-capable `pi-interactive-shell` default and sandbox/headless fallback. +- `agent-control-plane-closure` (FE-1216) — closed 2026-07-17; all seven required control-plane sweep rows built and the temporary ledger retired. +- `operator-comparison-workflow` (FE-1215) — closed 2026-07-17; durable approachable saved-mission workflow landed and follow-up residue was split into separate frontiers. +- `end-to-end-comparison-tracer` (FE-1239) — complete 2026-07-21; the staged 2×2 Petri-editor witness is retained and promoted. +- `executor-slice-admission-parity` (FE-1240) — complete 2026-07-21; invalid scoped slices are rejected during deterministic plan admission. +- `comparison-publication-workflow` (FE-1251) — complete 2026-07-22; immutable provenance capture and guarded Comparison Reports publication landed. +- `prospect-research-workspace-regression` (FE-1253) — complete 2026-07-23; the thin deterministic regression boundary remains, while the unexecuted campaign expansion is retired. +- `automated-alpha-publishing` (FE-1050) — complete 2026-07-21; the reviewed Changesets alpha path is active and exercised through `v1.0.0-alpha.13`. + ## 2026-07-22 FE-1241 brownfield comparison closeout `brownfield-comparison-cases` ([FE-1241](https://linear.app/hash/issue/FE-1241/add-isolated-brownfield-comparison-cases), [PR #362](https://github.com/hashintel/brunch/pull/362)) completed the mechanical expansion from the sole greenfield Petri case to frozen Brunch backend and Petrinaut frontend replays. The branch is `ka/fe-1241-brownfield-comparison-cases`, based on `next` after FE-1240 landed. @@ -25,7 +46,7 @@ The comparison evidence produced after that closure exposed a different planning The reshaped `automation-observability-dx` frontier is closed on commit `1885130a` in the restacked base. It removed `--dev-tools`, the query-tool/`devAllowedToolNames` channel, and the repo-local `cli-cmux` skill; moved trajectory reports into `.brunch/debug/`; and documented distinct seed-based intra-product and mission-driven cross-product evaluation doors. The consequential-fact evaluator, report, runner, and directive-ablation seam remain compiling dev/eval primitives but are no longer advertised as normal DX. -The earlier `consequential-fact-discovery-tracer` identity and its six-run `warrant-ablation-campaign` are retired rather than left parked. Their fixed actor produced only invalid mechanical pilots. FE-1210 subsequently proved a general push-driven actor and split-judgment substrate; the new `capture-ledger-tracer` owns the next rich mixed-source matched comparison and may reuse the landed FE-1208 primitives. The old campaign card remains as superseded historical evidence and is not an execution pointer. +The earlier `consequential-fact-discovery-tracer` identity and its six-run `warrant-ablation-campaign` are retired rather than left parked. Their fixed actor produced only invalid mechanical pilots. FE-1210 subsequently proved a general push-driven actor and split-judgment substrate; the new `capture-ledger-tracer` owns the next rich mixed-source matched comparison and may reuse the landed FE-1208 primitives. The historical campaign record now lives in git history and this archive entry; it is not a live execution pointer. ## 2026-07-17 FE-1210 agent-as-user comparison closeout @@ -37,7 +58,7 @@ Original live frontier definition and detailed round-one protocol: git history o ## 2026-07-16 FE-1208 reshape (`ln-plan`, `consequential-fact-discovery-tracer` → `automation-observability-dx`) -The FE-1208 frontier (branch `ln/fe-1208-traces-and-evals-1`) was reshaped in place after the warrant-ablation campaign stalled: the v1 deterministic actor could not drive a real structured single-select surface, so all eight retained attempts are mechanical pilots, never campaign evidence. What the original frontier *built and keeps*: the joined real-TUI trajectory tracer (`trajectory.ndjson` → joined report), the deterministic review-diff scorer/evaluator with its proof-boundary corrections, and the campaign runner/replay seam — all preserved and compiling, de-wired from documented DX. The six-run control/ablation campaign itself parked to Later as `warrant-ablation-campaign`, resuming only on general-actor evidence from `agent-as-user-comparison` plus rich scenarios; the approved actor-v2 contract is recorded in the parked card `memory/cards/consequential-fact-discovery-tracer--warrant-ablation-campaign.md`. The successor frontier `automation-observability-dx` (same issue/branch, earned posture) owns the consolidation: kill `--dev-tools` + query tools, remove `cli-cmux`, relocate the trajectory report to `.brunch/debug/`, and land the dev-/PM-facing documentation split between seed-based intra-product testing and mission-driven agent-as-user cross-product comparison. Original definition text: git history of `memory/PLAN.md` at `1020e2f1` and the parked card. +The FE-1208 frontier (branch `ln/fe-1208-traces-and-evals-1`) was reshaped in place after the warrant-ablation campaign stalled: the v1 deterministic actor could not drive a real structured single-select surface, so all eight retained attempts are mechanical pilots, never campaign evidence. What the original frontier *built and keeps*: the joined real-TUI trajectory tracer (`trajectory.ndjson` → joined report), the deterministic review-diff scorer/evaluator with its proof-boundary corrections, and the campaign runner/replay seam — all preserved and compiling, de-wired from documented DX. The six-run control/ablation campaign itself parked to Later as `warrant-ablation-campaign`, resuming only on general-actor evidence from `agent-as-user-comparison` plus rich scenarios; its approved actor-v2 contract now survives in this archive entry and the branch/git history rather than a live scope card. The successor frontier `automation-observability-dx` (same issue/branch, earned posture) owns the consolidation: kill `--dev-tools` + query tools, remove `cli-cmux`, relocate the trajectory report to `.brunch/debug/`, and land the dev-/PM-facing documentation split between seed-based intra-product testing and mission-driven agent-as-user cross-product comparison. Original definition text: git history of `memory/PLAN.md` at `1020e2f1`. ## 2026-07-15 Sync archive (`ln-sync`) diff --git a/docs/design/WEB_UI_ARCHITECTURE.md b/docs/design/WEB_UI_ARCHITECTURE.md index e2eadab6d..e730682d0 100644 --- a/docs/design/WEB_UI_ARCHITECTURE.md +++ b/docs/design/WEB_UI_ARCHITECTURE.md @@ -513,7 +513,7 @@ Do not use as the first Brunch host substrate. Pi's own SDK guidance prefers dir FE-1200 is complete; the once-pending reconciliation is discharged: -1. ✓ `ln-spec` updated the Product Contract and decisions: standalone web is a primary presentation mode (req 4/31/32, D132-L/D133-L, A43-L/A44-L, I64-L/I65-L). The remaining TUI-sidecar wording is now explicitly transitional: A47-L plus the `shared-session-host-convergence` arc own proof and retirement rather than pretending FE-1200 already replaced it. +1. ✓ `ln-spec` updated the Product Contract and decisions: standalone web is a primary presentation mode (req 4/31/32, D132-L/D133-L, I64-L/I65-L; FE-1200 retired A43-L/A44-L into those homes). The remaining TUI-sidecar wording is now explicitly transitional: A47-L plus the `shared-session-host-convergence` arc own proof and retirement rather than pretending FE-1200 already replaced it. 2. ✓ `ln-plan` closed and archived the single `standalone-web-session-host` (FE-1200) frontier after its tracer, concurrency, and presentation-coverage slices. 3. ✓ I65-L required-family coverage is complete: projection no-loss/malformed tests cover every required persisted ask terminal shape, including questionnaire read-back; React render/answer tests cover free text and listed single/multi choices; headless bounded-questionnaire answering remains available through the schema-tagged string/JSON envelope, without a dedicated React questionnaire form; distinct candidate/review-set/digest production settlement/reconnect witnesses, concurrency/target isolation, and receipt-bearing review settlement complete the oracle. 4. ✓ `ln-design`-level interface choices for `LiveSessionHost` and the session-presentation projection are materialized in `src/session/live-session-host.ts` and `src/projections/session/`. diff --git a/memory/PLAN.md b/memory/PLAN.md index 641b5deda..b0d0f422e 100644 --- a/memory/PLAN.md +++ b/memory/PLAN.md @@ -13,624 +13,199 @@ ## 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. Capability work routes through the code-owned first-level skill manifest and activity-named skill homes (the strategy/lens/method runtime trees are retired, D98-L). - -**Ship gate (2026-07-03 grill) — nearly closed.** The shippable cut: working e2e flows and throughlines, clean simple invariants, complete contracts — minimal and pragmatic within those constraints, enhancements deferred. Four of the five gate frontiers are done and merged; all remaining gate evidence rides `walkthrough-remediation-2` (FE-1187), which absorbed FE-1167 and is the closing member of arc `deterministic-orientation`. Two operational modes only and concentric authority remain settled (D98-L/D40-L); `remediation-4` narrowly revises D98-L/D109-L to separate a persistent Specify elicitation style from one-shot deterministic process moves. Standing obligation while the gate is open: gate frontiers chart their decision flows (all paths and endpoints) at `ln-scope` time. - -**Current closure lane.** FE-1187 is the sole remaining ship-gate frontier. The digest-questionnaire carrier, atomic local/RPC review settlement, and borderless Impact Ledger renderer with structural oracles are built. The `remediation-4` continuation has materialized the terminal-adaptive shell, canonical orientation treatment, persistent elicitation style, deterministic action menus, full Ask mechanics, Continue-language cleanup, KA handoff, and R6 terminal-status rail. The first R8–R10 provider run was stopped before approval and counts 0/3: it exposed that D27-L's settled-only review contract could not represent the human-required mixed advisory/settled proposal, and the Impact Ledger rendered empty Assurance/Planning groups as headings plus `None`. The amended per-node/per-edge settlement contract and populated-group-only ledger are now materialized, including exact local/RPC preservation and existing-host edge visibility. `remediation-4` ties off there. At user direction, extractor/oracle hardening and the fresh three-run campaign are paused; A48-L and the consolidated outer checkpoint remain sequenced afterward and do not start on this branch. Execute evidence O7–O9 belongs to the KA stream; FE-1187 coordinates but does not own it. - -**Parallel lanes.** Group 3 agent-layer work is pickup-ready. `agent-control-plane-closure` is one earned coverage frontier over foreground and background prompt ingress: it absorbs the former `graph-assurance-conduct` and `subagent-skill-access` items, reconciles the stale eager-context fossils left by D58-L's load-on-demand cutover, and closes prompt replacement/resource-invocation contradictions before capture experiments amplify them. FE-1187 retains only the concern-grouped review renderer. FE-1208's reshaped `automation-observability-dx` closure landed on the restacked base; its invalid warrant pilots remain historical evidence, while the useful evaluator/report primitives are available to `capture-ledger-tracer`. Two evaluation use cases stay deliberately distinct: **seed-based intra-product testing** (Brunch on its own terms — seeds encode Brunch graph/spec state only Brunch understands) and **mission-driven agent-as-user cross-product comparison** (`agent-as-user-comparison` — competitor CLIs share no Brunch state, so the comparable artifact is the "ready" spec/plan document a mission produces). FE-1210 closed the rigorous technical tracer on 2026-07-17; the separately planned operator workflow (`operator-comparison-workflow`, FE-1215) makes saved missions, visible comparison-harness framing, conversational launch, and a readable free-form report approachable without weakening the retained regression/evaluation machinery. Its first operator-led run falsified the nested fresh-actor topology: the top-level project Pi session must act as the simulated user and drive one direct harness subshell at a time, with stock-Pi text interaction as the portable baseline; the corrected real witness is deferred to `saved-mission-comparison-witness`. The KA stream owns executor/orchestrator/Execute-mode work. FE-1192 and FE-1195 completed the attempt, isolated fan-in, durable parallel authority, and epic integration sequence; `executor-plan-coherence` now uses those settled seams to test whether multi-slice plans converge on one working result. Broader instrumentation remains trigger-gated under Later. - -**Comparison lane.** FE-1239 remains the sole rigorous greenfield 2×2 tracer: two independently approved Petri specifications cross exact handoffs into Brunch and Claude execution and one unchanged oracle joins all four outputs. FE-1241 keeps that Petri editor as the greenfield study profile and adds frozen Brunch/Petrinaut brownfield packets plus deterministic oracles under a learning-first workflow. FE-1253 is deliberately thinner: a saved exploratory prospect mission plus a deterministic React/Node/TypeScript/SQLite execution regression case, with no prospect study profile, requirement ledger, scored provider gate, or campaign claim. - -**Current seams.** Brunch ships on the `1.0.0-alpha.x` line. One-shot `ask` is the only interactive structured-exchange terminal; D125-L's live ask registry provides headless discovery/answering, while the transcript-backed pending projection remains a compatibility surface for live offer tools after the legacy `present_question` pending branch retired. Sweep classification remains fail-closed and compile-time anchored to the exchange-schema terminal names (D117-L), while the larger capture-conditional watermark question remains A40-L. - -**Topology and evidence discipline.** Co-located `src/**/TOPOLOGY.md` files own current topology; SPEC owns product contract and seam decisions; PLAN owns only rolling frontier state. Scratch probe artifacts are not durable evidence until promoted to `.fixtures/runs/`. Older completion history lives only in [`docs/archive/PLAN_HISTORY.md`](../docs/archive/PLAN_HISTORY.md). - -**Standalone web foundation — completed 2026-07-15 (FE-1200); host convergence still open.** FE-1200 proved target-addressed sealed Pi sessions, one driver/many observers, JSONL hydration plus live overlay, and full required-family semantic presentation coverage with React adapters inside the standalone web process (D132-L/D133-L, I64-L/I65-L). It did **not** replace the TUI-owned host: `brunch-tui.ts` still owns a separate live `AgentSession`, raw `SessionEventRelay`, and `/rpc/driver` sidecar surface. The `shared-session-host-convergence` arc now owns the intended pi-web-derived transition: prove a TUI attachment to one independent cwd-scoped host, then migrate the closed capability inventory and delete the duplicate host/relay architecture. Design and colleague entry point: [`docs/design/WEB_UI_ARCHITECTURE.md`](../docs/design/WEB_UI_ARCHITECTURE.md). +- **Ship gate:** FE-1187 `walkthrough-remediation-2` is still the sole remaining ship-gate frontier. `remediation-4` landed the mixed-settlement review contract, populated-only Impact Ledger rendering, terminal-adaptive shell, persistent Specify elicitation style, deterministic menus, Ask mechanics, Continue-language cleanup, KA handoff, and the R6 terminal-status rail; extractor/oracle hardening and the fresh R8–R10 0/3 campaign remain paused at user direction. Execute evidence O7–O9 is still KA-owned. +- **Shared host follow-through:** FE-1200 proved the standalone web foundation, but the TUI still owns a separate live `AgentSession`, `SessionEventRelay`, and `/rpc/driver` sidecar path. The open architecture arc is `shared-session-host-convergence`. +- **Comparison lanes:** the repo keeps two distinct evaluation doors: seed-based intra-product testing and mission-driven cross-product comparison. FE-1241 closed the brownfield comparison cases; FE-1215 landed the approachable operator workflow; the remaining operator residue is the structural mission-isolation hardening plus the later real Brunch+Claude saved-mission witness. +- **Executor / Execute evidence queue:** several KA fronts are implementation-merged but still carry explicit outer evidence: `host-landing`, `executor-plan-synthesis`, `execution-comparison-tracer`, `executor-plan-coherence`, `executor-slice-verification-repair`, and `greenfield-secure-drop-demo`. +- **Current seams and discipline:** Brunch ships on `1.0.0-alpha.x`. D125-L's live ask registry is the structured-exchange headless surface; the transcript-backed pending projection remains compatibility-only. Sweep classification remains fail-closed on exchange-schema terminal names (D117-L); the larger capture-conditional watermark question remains A40-L. Co-located `src/**/TOPOLOGY.md` files own current topology; scratch evidence is not durable until promoted to `.fixtures/runs/`. ## Initiatives - - ### Closed arcs -- **elicitor-capability-spine** — ✓ done. `capture` / `generate` / `project` built over the capability spine without reviving retired runtime axes. Anchors: D95-L, D96-L, D100-L; I51-L. -- **exchange-presentation** — ✓ done 2026-07-06 (`exchange-rendering` + `exchange-answering-chrome`). Durable truth: D104-L/D108-L, `docs/design/STRUCTURED_EXCHANGE_ANSWERING_PATHS.md`, exchange topology homes. Deferred, not owed: per-item review commentary (Horizon). Full closure record: `docs/archive/PLAN_HISTORY.md`. -- **capture-ingest-throughline** — ✓ done 2026-07-06 (`exchange-capture-contract` + `present-digest`). Durable truth: I57-L, D110-L, ingest/map conduct homes. Full closure record: `docs/archive/PLAN_HISTORY.md`. - - +- **elicitor-capability-spine** — ✓ done. Durable truth: D95-L, D96-L, D100-L; I51-L. +- **exchange-presentation** — ✓ done 2026-07-06. Durable truth: D104-L/D108-L, `docs/design/STRUCTURED_EXCHANGE_ANSWERING_PATHS.md`, exchange topology homes. Full closure record: `docs/archive/PLAN_HISTORY.md`. +- **capture-ingest-throughline** — ✓ done 2026-07-06. Durable truth: I57-L, D110-L, ingest/map conduct homes. Full closure record: `docs/archive/PLAN_HISTORY.md`. ### shared-session-host-convergence — planned -- **Goals:** preserve both first-class TUI and web presentations while collapsing their runtime authority onto one independent cwd-scoped session host; keep Pi behind Brunch product RPC/semantic projections; retire the TUI-owned raw relay and sidecar-only driver surface rather than maintaining two host architectures. -- **Members:** - - `shared-session-host-tracer` — proving; settle the Pi `InteractiveMode` attachment seam against one host-owned writable runtime and retire A47-L. - - `shared-session-host-cutover` — wait-gated earned coverage; after the tracer, migrate the closed TUI/web capability inventory and delete the old relay/driver/composition path. -- **Done-definition:** one host owns each writable Pi runtime, JSONL writer, graph command authority, driver lease/handoff, and semantic live-event stream; TUI and React remain useful clients/adapters over that authority; client detach/restart does not counterfeit or duplicate runtime ownership; `SessionEventRelay`, `brunch.sessionEvent`, `/rpc/driver`, and TUI-owned parallel session-host wiring are deleted; `memory/SPEC.md`, `README.md`, `CONTRIBUTING.md`, `docs/design/WEB_UI_ARCHITECTURE.md`, and the app/session/rpc/web topology homes describe only the canonical host plus presentation adapters. +- **Goals:** preserve first-class TUI and web presentations while collapsing runtime authority onto one cwd-scoped host; keep Pi behind Brunch product RPC/semantic projections; retire the TUI-owned raw relay and sidecar-only driver surface. +- **Members:** `shared-session-host-tracer` → `shared-session-host-cutover`. +- **Done-definition:** one host owns each writable Pi runtime, JSONL writer, graph command authority, driver lease/handoff, and semantic live-event stream; TUI and React remain useful clients/adapters; `SessionEventRelay`, `brunch.sessionEvent`, `/rpc/driver`, and TUI-owned parallel host wiring are deleted; `memory/SPEC.md`, `README.md`, `CONTRIBUTING.md`, `docs/design/WEB_UI_ARCHITECTURE.md`, and the app/session/rpc/web topology homes describe only the canonical host plus presentation adapters. - **Anchors:** A47-L; D39-L, D84-L (to retire), D132-L, D133-L; I64-L, I65-L. ### deterministic-orientation — ◐ active -- **Goal:** users deliberately choose how to work without repeated menu interruption, model volition, or mode ping-pong. Revised D98-L/D109-L separate a persistent active-branch Specify elicitation style (`interrogate | disambiguate | propose`) from one-shot process moves: the product opens an automatic menu only for a new session without a style and after operational-mode switch, while `/brunch:consult` reopens it explicitly; resume/session switch/tree/abort restore the branch's latest style. No-UI print/json modes synthesize no style choice and follow the default kick path. Two top-level modes remain (`specify` / Specify and `execute` / Execute); concentric authority stays a code contract; the style routes into the existing elicitor capability spine rather than reviving the generic strategy/lens/method runtime system. -- **Members:** - - `session-entry-orientation` — ✓ built + merged (#289, 2026-07-08); its remaining LN outer evidence now rides FE-1187. - - `execute-entry-readiness` — ✓ built + merged (#290, 2026-07-08); its remaining Execute evidence + the two deferred orientation-choice questions live in the KA stream's carved sub-list. - - `walkthrough-remediation-2` (FE-1187, definition below) — the arc's remaining/closing member since 2026-07-13, when it absorbed `walkthrough-evidence-batch` (FE-1167): one witnessed e2e run per generative flow, menu→conduct routing evidence; the thin/rich Execute beats carve to the KA sub-list but remain part of the arc's done-definition. -- **Done-definition:** the canonical elicitation-style vocabulary is audited, specified, reconstructed last-entry-wins from the active branch, injected into elicitor prompting, and visibly retained across resume/session switch/tree navigation without opening a menu; only style-less new sessions and operational-mode switches auto-open, while `/brunch:consult` explicitly reopens. Escape/timeout is inert, preserves any current style, starts no process move, and the menu explains that the user may dismiss to give another instruction. No-UI modes leave no style trace. Persistent style entries and one-shot process-move entries are excluded from capture sweep and cannot be confused in kick composition. Readiness-filtered menu availability remains derived/non-transcript with a bounded fallback. Concentricity holds as an executable contract (executor tool + skill grants ⊇ elicitor's, write-execution tooling stays executor-only); **one witnessed e2e run per generative flow — intent, design, oracle, frontier-level plan — each entered through a deterministic user-owned move** (the ship gate's "all flows proven" obligation lives here); topology homes for `src/.pi/extensions/` and `src/agents/runtime/` reconciled. -- **Anchors:** D98-L (two modes, 1:1 mode↔agent), D37-L (offer-owns-response grammar — the dialog lives on the product side of it), D40-L (authority matrix), D74-L (capability-readiness), D101-L/D102-L (session seed facts); `src/agents/references/readiness-bands.md` §Agent Use (the Proceed/Negotiate/Ask postures both foreground roles share). +- **Goal:** users deliberately choose how to work without repeated menu interruption, model volition, or mode ping-pong. Revised D98-L/D109-L separate a persistent active-branch Specify elicitation style (`interrogate | disambiguate | propose`) from one-shot process moves. +- **Members:** `session-entry-orientation` ✓ · `execute-entry-readiness` ✓ · `walkthrough-remediation-2` (FE-1187) is the closing member. +- **Done-definition:** style is reconstructed last-entry-wins from the active branch, injected into elicitor prompting, retained across resume/session switch/tree navigation, and distinct from one-shot process moves; only style-less new sessions and operational-mode switches auto-open; `/brunch:consult` explicitly reopens; no-UI modes leave no style trace; persistent-style entries and process-move entries are excluded from capture sweep; concentricity remains executable; one witnessed e2e run per generative flow still closes through FE-1187 plus the KA-carved Execute beats; topology homes for `src/.pi/extensions/` and `src/agents/runtime/` are reconciled. +- **Anchors:** D98-L, D37-L, D40-L, D74-L, D101-L, D102-L. ## Sequencing -### Active — Group 1 · walkthrough closure - -Close the entire first batch of walkthrough-related findings: remediation, the owed evidence, and the design back-catalog that the old (now fixed) findings-capture protocol left stranded. The auth reversal has landed; Group 3 is pickup-ready while FE-1187 continues its closure sweep. - -- `walkthrough-remediation-2` ([FE-1187](https://linear.app/hash/issue/FE-1187/walkthrough-remediation-sweep-2-wr18-follow-up-closure)) — **paused after `remediation-4` tie-off:** mixed-settlement review preservation and populated-group-only Impact Ledger rendering are built. Re-entry requires an explicit decision to resume extractor/oracle hardening, then restart R8–R10 from 0/3; A48-L, the separate web graph audit, and the consolidated outer checkpoint remain behind that gate. R6’s deterministic rail and presentation corrections are built; their visual judgment rides that checkpoint. Execute O7–O9 stay KA-owned. Closing member of arc `deterministic-orientation`. Definition below. -- `cli-mode-entry` — direct-mode CLI subcommands (`brunch specify [spec-id]` / `brunch execute `, reserving `develop`); admitted 2026-07-13, stacked on FE-1187's auth-reversal branch. Definition below. -- **Alpha walkthrough lane** — the post-publish outer-loop audit over the merged surface (`TESTING_PLAN.md` concern groups; findings in `TESTING_FINDINGS.md`). Runs A, C, and WR18 are the source evidence; run D waits on FE-1187's reshaped surfaces. Not a frontier itself. - -### Active — approachable comparison workflow +### Active -- `operator-comparison-workflow` ([FE-1215](https://linear.app/hash/issue/FE-1215/approachable-saved-mission-comparison-workflow)) — **focused remediation and #343 stack closeout corrections complete; ready to tie off and land the stack.** The autonomous D134-L prompt/docs correction is built, statically verified, and the focused stock-Pi → `/compare-specs` → one direct normal-width Brunch shell smoke passed on run `minimal-petri-net-editor-20260717T191333Z` (Brunch-only, exchange beyond splash, no mission leakage; see `TESTING_FINDINGS.md` CS1–CS3). Review induction's three bounded gaps are also closed: document acquisition enforces active settled graph state, every live Brunch comparison recipe roots `--out` in the target workspace, and mission resolution reserves co-located control Markdown. **Next action:** tie off #343 and land the stack. Follow-up `comparison-mission-isolation-hardening` remains admitted from the smoke's separate residual risk. Definition below. +- `walkthrough-remediation-2` ([FE-1187](https://linear.app/hash/issue/FE-1187/walkthrough-remediation-sweep-2-wr18-follow-up-closure)) — **paused after `remediation-4` tie-off:** mixed-settlement review preservation and populated-group-only Impact Ledger rendering are built. Re-entry requires an explicit decision to resume extractor/oracle hardening, then restart R8–R10 from 0/3; A48-L, the separate web graph audit, and the consolidated outer checkpoint remain behind that gate. Execute O7–O9 stay KA-owned. Closing member of arc `deterministic-orientation`. Definition below. +- `cli-mode-entry` — direct-mode CLI subcommands (`brunch specify [spec-id]` / `brunch execute `, reserving `develop`); admitted 2026-07-13, stacked after FE-1187's entry-surface work. Definition below. +- **Alpha walkthrough lane** — post-publish outer-loop audit over the merged surface (`TESTING_PLAN.md` concern groups; findings in `TESTING_FINDINGS.md`). Runs A, C, and WR18 are source evidence; run D waits on FE-1187's reshaped surfaces. Not a frontier itself. ### Recently Completed -- 2026-07-22 `brownfield-comparison-cases` (FE-1241) — **✓ complete, learning-first:** frozen Brunch and Petrinaut packets, lightweight pinned-source preparation, deterministic oracles, publication-compatible attempt evidence, and portable CI are built. The Petrinaut calibration seed remains part of oracle identity and its source-backed addresses retain contrastive coverage. Expensive merged-reference preflight and adversarial admission were retired before a provider campaign because the current decision needs fast case-level product evidence, not an externally defensible benchmark. -- 2026-07-21 `executor-slice-admission-parity` (FE-1240) — **✓ complete:** candidate admission now rejects scoped slices without executable criterion, design, or verification-machinery context; exact findings enter bounded repair, every admitted repaired slice survives preview/worker-context parsing, and the populated-plan execution guard remains fail-closed. -- 2026-07-20 `comparison-reporting-skills` (FE-1232) — **✓ implementation complete, building on landed FE-1230:** added separate project-shared Notion publication and comparison-evidence reporting skills; elicitation, execution, end-to-end, and frozen campaign-strategy references; and executable guardrails for active-procedure precedence, safe mutation, validity-first interpretation, reproducible judging, failure retention, and audience-safe controller-only redaction. -Older completion history (including FE-1192/FE-1195 executor topology closure): [`docs/archive/PLAN_HISTORY.md`](../docs/archive/PLAN_HISTORY.md). +- 2026-07-23 `prospect-research-workspace-regression` (FE-1253) — **✓ complete:** PR #369 retained the thin deterministic full-stack regression boundary and retired the unexecuted prospect campaign expansion. +- 2026-07-22 `brownfield-comparison-cases` (FE-1241) — **✓ complete, learning-first:** frozen Brunch and Petrinaut packets, pinned-source preparation, deterministic oracles, publication-compatible attempt evidence, and portable CI are built. +- 2026-07-22 `comparison-publication-workflow` (FE-1251) — **✓ complete:** PR #364 landed immutable comparison provenance plus guarded, idempotent Comparison Reports publication and schema reconciliation. -### Next — deferred operator evidence, shared host convergence, then Group 3 agent layer +Older completion history and archived completed frontier definitions live in [`docs/archive/PLAN_HISTORY.md`](../docs/archive/PLAN_HISTORY.md). -- `saved-mission-comparison-witness` — **later PR, wait-gated on PM availability and FE-1215's D134-L remediation landing**: run the real Brunch + Claude `/compare-specs` witness with the top-level session acting as the simulated user and one direct harness shell at a time, then revise/rerun the saved mission to prove historical snapshots remain immutable. Definition below. -- `comparison-mission-isolation-hardening` — **admitted 2026-07-17 from the FE-1215 remediation smoke** (`TESTING_FINDINGS.md` CS2). The `/compare-specs` flow currently writes `private-mission.md` at the run root, two levels above the harness target cwd, while harness agents (e.g. Brunch) expose generic `read`/`ls`/`find`/`grep`. Isolation held behaviorally in the witnessed run but is not enforced. Harden by placing the private mission outside the target-reachable tree (or jailing the target's file tools to its cwd) so the D134-L/I67-L mission boundary is structural, not conduct-dependent. Small, unblocked; no Linear/branch until picked up. Not required for FE-1215 landing. -- `shared-session-host-tracer` — prove the one-host TUI attachment seam that FE-1200 deliberately left open; highest-priority architecture follow-through for the colleague taking over web/session hosting. Definition below. -- `shared-session-host-cutover` — wait-gated on the tracer; close the enumerated TUI/web host surface, then delete the raw sidecar relay and `/rpc/driver` rather than normalizing dual support. Definition below. -- `develop-mode` — third operational mode `develop` / `engineer` agent, **built flag-gated** (create the mode; enable only behind a flag). **Authority model settled 2026-07-13: not a contract-breaker** — `develop` sits at the same concentric visibility/authority tier as `execute`; `engineer` is simply not constrained by the executor's workflow (no `execute_*` lifecycle obligations), and is initially just a Brunch-aware coding assistant. Entry remains a SPEC revision (D98-L "two modes only", the D40-L matrix row at the execute tier, per-mode kick/consult-suppression axis), but no authority-model redesign is needed. Cost read revised: mechanical ≈ a day + prompt/conduct work. The `develop` CLI subcommand name is already reserved by `cli-mode-entry`. -- `reviewer-agent-mode` — reshaped 2026-07-13: the D29-L advisory reviewer is a **subagent**, not a primary agent/mode. Narrow write authority to `reconciliation_need` stands (I16-L); A16-L trigger/scope questions resolve at pickup. Depends on `agent-control-plane-closure` for explicit named resource grants and honest background-agent prompt composition. -- `review-commentary-widening` — reshaped 2026-07-13 to the TUI-realistic version: afford `#`-mentioning of review items and attribute comments via mention (req 18 reference-code seam), instead of a widened structured payload + bespoke collection UI. Re-expresses over the D116-L declared-ask/answer payload; needs a SPEC decision at pickup. +### Next -### Parallel / Low-conflict - -- `automated-alpha-publishing` ([FE-1050](https://linear.app/hash/issue/FE-1050/set-up-automatic-npm-publishing-for-brunch-using-changesets)) — branch implementation complete; activation/canary pending. Replaces manual local `release-it` publishing with a reviewed Changesets release PR on `next`, npm trusted publishing, the existing release-pack smoke, protected tags, generated changelog, and GitHub Releases. `main`/`latest` automation remains explicitly deferred. Definition below. -- `capture-ledger-tracer` — proving follow-on to the completed `agent-control-plane-closure`: compare current ingest conduct with a versioned four-section capture ledger over one fixed mixed-source mission, using separate masked outcome and unblinded conduct judgments. Definition and active scope file below. +- `saved-mission-comparison-witness` — later operator-owned frontier: FE-1215 is landed, so the remaining work is scheduling the real Brunch + Claude `/compare-specs` witness, then revising/rerunning the saved mission to prove historical snapshots remain immutable. Definition below. +- `comparison-mission-isolation-hardening` — admitted from FE-1215 smoke (`TESTING_FINDINGS.md` CS2): move the private mission outside the target-reachable tree (or equivalently jail the target's file tools) so the D134-L/I67-L mission boundary is structural, not conduct-dependent. Definition below. +- `shared-session-host-tracer` — prove the one-host TUI attachment seam that FE-1200 deliberately left open. Definition below. +- `shared-session-host-cutover` — wait-gated on the tracer; close the enumerated TUI/web host surface, then delete the raw sidecar relay and `/rpc/driver`. Definition below. -### Cleanups — Group 4 - -- `named-inline-extension-identity` — Pi-native P1: adopt Pi's native named-inline-extension type for useful source provenance; small independent hardening, direct housekeeping or a tiny tooling slice. -- `web-driver-streaming-residue` — from the retired evaluation (2026-07-13): the `agent_settled`-ordering trigger has fired and that assertion is promoted into `standalone-web-session-host`; remaining `ln-sync` residue is documentation only: `docs/design/STRUCTURED_EXCHANGE_ANSWERING_PATHS.md` answering matrix is stale post-D125-L (discovery mode-complete; answering landed with ceilings), and `src/rpc/TOPOLOGY.md`'s streaming ledger should point to the promoted assertion rather than retain a conditional ○ row. -- `test-tmpdir-hygiene` — vitest `mkdtemp` fixtures are never cleaned up: ~249k `brunch-*` directories had accumulated in the darwin tmpdir by 2026-07-14 and filled the disk mid-gate (found during FE-1201). Add a global teardown or route fixtures through a repo-local scratch root (the `git-slice-integration-port.slow.test.ts` `tmp/` pattern). Tiny tooling slice; re-entry trigger: next disk-pressure incident or the next test-infra touch. +### Parallel / Low-conflict -### KA stream (Kostandin — executor / orchestrator / Execute mode) +- `capture-ledger-tracer` — pickup-ready proving follow-on to the completed `agent-control-plane-closure`: compare current ingest conduct with a versioned four-section capture ledger over one fixed mixed-source mission, using separate masked outcome and unblinded conduct judgments. Definition below. -Everything executor/orchestrator-shaped or Execute-mode-owned belongs to Kostandin's stream and is **outside the LN quarantine**. Cross-stream touchpoints: FE-1187 rows O7/O8/O9 (live D120-L Execute workflows) — coordinate before building those rows. +### Horizon -- `execution-comparison-tracer` ([FE-1230](https://linear.app/hash/issue/FE-1230/greenfield-execution-comparison-tracer)) — **active on `ka/fe-1230-independent-oracle-journeys`:** the frozen case, immutable-attempt contract, retained Brunch/Claude v1 pair, and versioned independent browser-oracle journeys are built. Next: restore the exact retained output paths, replay `petri-editor-browser-v2` unchanged against both, then review and promote the bounded evidence; no mutants, judging campaign, or repetitions in this frontier. -- `end-to-end-comparison-tracer` ([FE-1239](https://linear.app/hash/issue/FE-1239/trace-elicitation-through-execution)) — **complete on `ka/fe-1239-end-to-end-comparison-tracer`, stacked on FE-1230:** two rigorous Petri-editor elicitation outputs crossed exact immutable handoffs into the staged 2×2 Brunch/Claude matrix; all four valid failed cells, unchanged-oracle evidence, and the validity-first requirement ledger are promoted. Definition and retained witness below. -- `executor-slice-admission-parity` ([FE-1240](https://linear.app/hash/issue/FE-1240/prevent-invalid-scoped-slices-from-reaching-execution)) — **complete on `ka/fe-1240-slice-admission-parity`, restacked on `next` after FE-1239 landed:** incomplete scoped-slice worker context is rejected during deterministic plan admission, exact findings enter bounded repair before `slice_execute`, and the execution boundary remains fail-closed. Definition below. -- `executor-plan-coherence` ([FE-1250](https://linear.app/hash/issue/FE-1250/build-coherent-execution-plans)) — **I69-L worker-contract carry implementation complete on `ka/fe-1250-coherent-execution-plans`, based on FE-1240 via `next`:** workers now receive exact cumulative requirement bodies and a hash-verified target-visible packet while controller-only neighbors remain excluded. Deterministic tests and build pass; next is the explicitly authorized unchanged Petri outer witness. No new browser gate, durable plan kind, or executor lifecycle phase. Definition below. -- `executor-slice-verification-repair` ([FE-1254](https://linear.app/hash/issue/FE-1254/repair-failed-slice-verification-before-halting)) — **implementation complete on `ka/fe-1254-slice-verification-repair`:** terminal failed slice verdicts now enter a finite cycle-qualified Petri repair ladder with crash-durable canonical repair context, grouped validated history, and serial/parallel authority-preserving recovery. The full suite, repository checks, and build pass; next is the owned unchanged Petri comparison rerun. Definition below. -- `comparison-publication-workflow` ([FE-1251](https://linear.app/hash/issue/FE-1251/publish-traceable-comparison-reports)) — **active on `ka/fe-1251-comparison-publication`, stacked on FE-1250:** capture immutable controller and release provenance before comparison lanes start, then explicitly publish retained validity-first reports into the canonical Notion database through a guarded idempotent skill. Definition below. -- `prospect-research-workspace-regression` ([FE-1253](https://linear.app/hash/issue/FE-1253/thin-prospect-research-into-a-regression-case)) — **active on `ka/fe-1253-prospect-research-e2e`, stacked on FE-1241:** retain the exploratory mission and calibrated browser/HTTP/SQLite/export oracle while deleting the unexecuted prospect study profile, requirement-ledger expansion, and scored-provider completion gate. -- `greenfield-secure-drop-demo` ([FE-1289](https://linear.app/hash/issue/FE-1289/close-the-greenfield-secure-drop-demo)) — **active on `ka/fe-1289-greenfield-secure-drop-demo`:** close one bounded product witness from real elicitation through accepted graph, synthesized parallel plan, production cook, live Petrinaut, confirmed greenfield landing, and deterministic Secure Drop checks; then retain one diagonal Brunch/Claude comparison without reopening the general factorial harness. -- **Carved from FE-1167 (2026-07-13):** the Execute-mode evidence sub-list — Execute entry beats on thin vs rich seeds (assessment honesty: Ask on thin, Proceed on rich) and the FE-1107/KA residue (close-or-narrow, demo/walkthrough session via `TESTING_PLAN.md`, post-KA plan pass). The former sticky-posture question is no longer KA residue: FE-1187 `remediation-4` owns the persistent Specify elicitation-style audit/SPEC revision, and its Continue lexical audit owns the old `continue` ambiguity. Full context in the archived FE-1167 definition (`docs/archive/PLAN_HISTORY.md`). -- `planning-process-model` — **moved to the KA stream 2026-07-13; reshaped by D126-L**: the durable scope handoff is settled, so this item now owns only plan projection and epistemic-horizon questions beyond committed scopes. Definition below. -- **[1.x data-model handoff owed by FE-1187](../docs/architecture/BRUNCH_1X_DATA_MODEL_HANDOFF.md):** a concise colleague-facing note must distinguish current canon from directional vocabulary before the consolidated outer checkpoint. Current: `{milestone, frontier, scope}` with executor-derived slices; basis (`explicit | implicit`) orthogonal to settlement (`advisory | settled`); no persisted readiness grade or spec-global elicitation-gap table; active-branch Pi JSONL reads; one CommandExecutor mutation authority with spec-local LSN/change log; no new projected `vv_obligation` (legacy rows remain readable). Directional only: explain stored `thesis` as pitch/concept without renaming it yet, and avoid new coupling to spec-local `term` while its possible workspace lift remains future work. Persisted judgment-shaped reconciliation needs remain current, but are YAGNI-suspect: add no kinds/consumers/orchestration dependency without fresh evidence; re-evaluate derivation/removal when KA work first needs that table. Delivered note: [`Brunch 1.x data-model handoff`](../docs/architecture/BRUNCH_1X_DATA_MODEL_HANDOFF.md); it does not block the deterministic TUI queue. -- **Standing obligations:** `probes-and-transcripts-evolution` and `topology-readmes-and-boundaries` ride the frontier that triggers them; they are not standalone cleanup buckets. +- **Mode / reviewer follow-ons:** `develop-mode` (flag-gated third operational mode with execute-tier authority), `reviewer-agent-mode` (reviewer remains a subagent, not a primary mode), and `review-commentary-widening` (TUI-realistic `#`-mention review comments over D116-L payloads). +- **Cleanups:** `named-inline-extension-identity`, `web-driver-streaming-residue`, and `test-tmpdir-hygiene` remain independent small follow-ons. +- **Release automation later:** FE-1050 closed the reviewed Changesets alpha path on `next` → npm `alpha`; the still-intended `main`/`latest` stable-release automation remains a separate deferred promotion follow-on rather than part of the current alpha automation. Pointer: [`docs/archive/PLAN_HISTORY.md`](../docs/archive/PLAN_HISTORY.md#recently-completed-entries-archived-from-live-plan). +- `host-landing` ([FE-1201](https://linear.app/hash/issue/FE-1201/mode-aware-host-landing-of-promoted-runs)) — **KA stream · owner: Kostandin.** Owes the real TUI+RPC `/brunch:land` walkthrough from `promotion_prepared` into a fresh target (A42-L live half / FE-1197 oracle 9 landing leg). Re-enter at the next live FE-1197 walkthrough. Pointers: SPEC A42-L, D111-L/I58-L; `src/app/TOPOLOGY.md`. +- `executor-plan-synthesis` ([FE-1197](https://linear.app/hash/issue/FE-1197/synthesize-and-validate-executor-plans-from-approved-scopes)) — **KA stream · owner: Kostandin.** Owes live-capability oracles 1–5 on real elicited specs plus oracle 9's committed-scope → conforming-promotion tail. Re-enter in the next model-backed FE-1197 walkthrough. Pointers: SPEC D130-L and A42-L; `src/executor/TOPOLOGY.md`; `docs/praxis/manual-testing.md`. +- `execution-comparison-tracer` ([FE-1230](https://linear.app/hash/issue/FE-1230/greenfield-execution-comparison-tracer)) — **KA stream · owner: Kostandin.** Owes replay of unchanged `petri-editor-browser-v2` against both retained outputs and bounded evidence promotion. Re-enter when the exact immutable attempt/output paths are restored. Pointers: SPEC “FE-1230 execution-comparison oracle boundary”; `testing/execution-comparisons/cases/minimal-petri-net-editor/spec.md`; `docs/praxis/comparison-runs.md`. +- `executor-plan-coherence` ([FE-1250](https://linear.app/hash/issue/FE-1250/build-coherent-execution-plans)) — **KA stream · owner: Kostandin.** Owes one explicitly authorized unchanged frozen-Petri rerun with the controller-owned browser oracle. Re-enter only on that explicit authorization. Pointers: SPEC I69-L and Verification Design “I69-L unchanged frozen Petri comparison witness”; `testing/execution-comparisons/cases/minimal-petri-net-editor/spec.md`. +- `executor-slice-verification-repair` ([FE-1254](https://linear.app/hash/issue/FE-1254/repair-failed-slice-verification-before-halting)) — **KA stream · owner: Kostandin.** Owes its unchanged Petri comparison rerun after the merged finite repair ladder. Re-enter only for the owned, explicitly authorized unchanged rerun. Pointers: SPEC D112-L/D127-L–D130-L/I58-L; `src/executor/TOPOLOGY.md`; PR #370 evidence. +- `greenfield-secure-drop-demo` ([FE-1289](https://linear.app/hash/issue/FE-1289/close-the-greenfield-secure-drop-demo)) — **KA stream · owner: Kostandin.** Owes one fresh full Secure Drop run proving the corrected graph/harness/build path on the current runtime baseline before any diagonal comparison claim. Re-enter from the retained witness card after the merged corrections; SD9 remains failed evidence. Pointers: [`memory/cards/greenfield-secure-drop-demo--mission-and-witness.md`](cards/greenfield-secure-drop-demo--mission-and-witness.md); `TESTING_FINDINGS.md` SD9; SPEC D120-L/D126-L/D127-L/D130-L and I58-L/I69-L. +- **Planning / instrumentation later:** `planning-process-model`, `tier-2-regression-probes`, `mechanism-trace`, and `agent-tracing` re-enter only with an explicit trigger. +- **Standing obligations:** the colleague-facing [`Brunch 1.x data-model handoff`](../docs/architecture/BRUNCH_1X_DATA_MODEL_HANDOFF.md) is delivered; `probes-and-transcripts-evolution` and `topology-readmes-and-boundaries` ride the frontier that triggers them rather than standing as their own buckets. ### Later -Instrumentation experiments and far-horizon items. Each re-enters only via re-qualification with a named trigger. -- `tier-2-regression-probes` — **Later, trigger-gated**: runnable probes over the tier-2 real-boot faux-provider harness that track improvement/regression of Brunch's own conduct on rich seed scenarios (the intra-product lane's mechanical oracle). Re-enter when the seed/fixture library demonstrates rich, relevant, challenging scenarios worth pinning; artifacts follow the normal probe contract (`docs/architecture/probes-and-transcripts.md`). -- `mechanism-trace` — **Later**: post-hoc `wiring` / `nudge` / `conduct` transcript timeline plus static wiring inventory. Re-enter when instrumentation is prioritized; FE-1187 already owns the extracted sweep-debt tripwire. Archived snapshot: [`docs/archive/PLAN_HISTORY.md`](../docs/archive/PLAN_HISTORY.md#2026-07-14-rolling-frontier-reduction). -- `agent-tracing` — passive trace instrumentation over Pi lifecycle events for debugging plus conduct/quality evaluation: NDJSON emitter extension (introspection-tap discipline), subagent span joining via SDK `session.subscribe`, and a mechanical-trace × semantic-JSONL join for deterministic conduct checks and judged passes. Entry move is an `ln-spike` (dev-gated `nikiforovall/pi-otel` import: do span trees beat `.brunch/debug/` + JSONL projections?) before any port of `JoshMock/the-agency` observability as the in-product base. Traces are dev/eval artifacts, never product truth (no event-spine backdoor). Design: `docs/design/AGENT_TRACING.md`; sibling idea note `docs/design/RLM_INVESTIGATION_PATTERN.md`. Relation: Later `mechanism-trace` is the transcript-native sibling (carrier classification, no event plane); if both land they may join on a shared trace vocabulary. Absorbs Pi-native P5 (provider/cache observability — latency, cache behavior, whole-run spans), spike-led. +Legacy link target; see Horizon. ## Frontier Definitions - + ### walkthrough-remediation-2 - **Name:** Walkthrough chapter closure — remediation, evidence, and design follow-through (absorbs FE-1167) - **Linear:** [FE-1187](https://linear.app/hash/issue/FE-1187/walkthrough-remediation-sweep-2-wr18-follow-up-closure); absorbs closed FE-1167. -- **Branches:** `ln/fe-1187-walkthrough-remediation-2` (tied-off first tranche) → `ln/fe-1187-remediation-3` (tied-off Impact Ledger continuation) → `ln/fe-1187-remediation-4` (tied-off mixed-settlement/orientation continuation). +- **Branches:** `ln/fe-1187-walkthrough-remediation-2` → `ln/fe-1187-remediation-3` → `ln/fe-1187-remediation-4`. - **Kind:** coverage-shaped closure batch: WR18-promoted remediation rows + absorbed LN evidence beats + folded design rows + the tripwire row. - **Certainty:** proving. - **Classification:** evidence-gated. -- **Built:** D123-L model/auth reversal; deterministic remediation rows; sweep-debt tripwire; digest feedback → bounded questionnaire/confirmation carrier; shared atomic local-TUI/RPC mixed-settlement review preservation with required per-node/per-edge status, exact readback, and no post-approval completion path; discriminating seed variants for propose/project/review routing plus settlement visibility; the human-selected borderless Impact Ledger with narrow/normal/wide goldens, word-wrap-tolerant render honesty, a naive differential inventory oracle, and a deterministic 17-node/11-edge content-length variant gallery; the R6 ask-only valid-terminal status rail; the authenticated live-TUI presentation corrections (header-backed Welcome, quiet provider retries, editor/footer geometry, dim collapsed thinking, terminal-default compact wordmark); and the read-only active-branch JSONL + graph/LSN provider-conduct report extractor with exact entry/tool-call citations and deterministic R8–R10 rival classification. The exact review payload remains durable and approval produces one receipt-bearing terminal, one LSN, and one change-log entry. -- **Next action:** paused at user direction after `remediation-4` tie-off. On explicit re-entry, reconcile the accepted provider-conduct extractor/oracle against the landed mixed-settlement contract, then restart Card 2 from 0/3. Per-item settlement preservation and populated-only Impact Ledger rendering are built; no provider run counts precede extractor/oracle reconciliation. The completed D119-L accepted-source extraction-breadth beat supplies baseline evidence to `capture-ledger-tracer` but does not replace that frontier's controlled comparison. -- **Replanned `remediation-4` bundle (same frontier / issue / branch):** - - **Terminal-adaptive shell:** retain light/dark themes but move live TUI foreground/semantic roles to ANSI 0–15; keep only subtle custom backgrounds plus a small gray ramp, while HTML export keeps concrete colors. Specify identity is cyan, Execute identity is magenta, and the shared navigation/menu shell is blue. Every active editor/Ask/questionnaire/comment/Other input uses the current mode border. - - **Editor, footer, intro, and spec menu:** the editor border owns only the operational-mode and specification-title labels. The complete stable footer is one-column inset and uniformly dim, containing only the conditional web URL plus `model_info | thinking_level | context_percentage`; transient working/status display remains separate. Replace `/brunch:menu` and `ctrl+shift+b` outright with `/brunch:spec-menu` and `alt+s`; share one menu shell while keeping startup and in-session decision logic distinct. The welcome copy is one-time, non-transcript startup-header content rendered immediately after identity through a standard one-column-padded Box; its slash-command/control notes are dim. It teaches spec/menu, mode, consult/continue, model, and thinking controls, including the vendor-neutral guidance that low/medium thinking often works best. - - **Orientation semantics and menus:** consolidate one active-branch, last-entry-wins Specify elicitation style and wire it into elicitor prompting; style choices persist, while Move to execution and Execute workflows remain one-shot process moves. Automatic menus fire only for a new session without an established style and after operational-mode switch; resume/session switch/tree/abort restore branch state without interruption; `/brunch:consult` explicitly reopens the menu. The current style is marked/preselected and appended only when changed. A shared blue menu shell carries short labels plus dim descriptions and explicit Escape-to-dismiss/custom-instruction guidance. Specify offers Work via intent / examples / proposals, plus readiness-gated Move to execution; that move stays in Specify until gaps close and then explicitly offers Execute. Execute progressively offers Prepare execution / Compile a plan / Execute the plan. - - **Readiness tracer:** menu availability is derived, never a stored grade. Try a read-only, non-transcript semantic preflight under a ≤3s budget, show the wait through `setWorkingMessage`, and cache only in host memory by `{specId, lsn, operationalMode}`. Timeout, missing auth, or failure falls back to a deterministic safe subset. A scoped tracer must decide whether the model-backed path meets the budget; the deterministic fallback is required either way. - - **Ask, Continue, and colleague evidence:** exercise the complete Ask matrix (free text, single/multi, Other, comment, mixed bounded questionnaire, nested back/Escape, cancellation recovery, and result read-back) deterministically, plus one live-provider TUI questionnaire and one public-RPC questionnaire witness; web requires semantic read-back audit, not a new React questionnaire form. Reserve user-facing “continue” exclusively for resuming interrupted Brunch work and audit live UI/control copy, choice ids/directives, prompts, tests, and docs. Produce an actionable KA 0.x→1.x data-model/ontology handoff and link it from the KA stream. -- **D131-L renderer boundary:** FE-1187 owns only the review presentation half of D131-L: materialize the selected borderless Impact Ledger, preserve exact term definitions and the readable `obligation` compatibility fallback, and audit the separate web graph display rather than silently imposing review ordering. The cross-cutting prompt/resource semantic sweep is part of `agent-control-plane-closure`. -- **Visual-design coupling:** `exchange-visual-design` now also owns the FE-1196 reassignment `transcript-ledger-rendering`: durable user-choice ledger entries must become visible in the transcript without entering model context, and should land with the same visual treatment rather than as a separate platform-debt slice. -- **Theme closure gate:** close through both-theme component/live-TUI evidence after the ANSI conversion; verify terminal-default text, the small allowed custom-shade set, cyan/magenta mode inputs, blue menu shells, the exact editor/footer contract, and the borderless intro. Do not treat HTML export colors as terminal-adaptation work. -- **Remaining routes:** R6's valid-terminal rail and quiet provider-rejection rendering plus the five bounded chrome/theme corrections are built; their qualitative both-theme judgment rides the outer checkpoint. R13's qualitative menu judgment also rides that checkpoint. R12's no-model symptom did not reproduce. R10's mixed-settlement contract, per-item presentation, existing-host edge visibility, and empty-group suppression are built. Extractor/oracle reconciliation and the R8–R10 campaign are paused at 0/3; the stopped partial run at `.fixtures/scratch/provider-conduct/run-1-20260717T170400Z/` is diagnostic and has no `report.json`. A48-L remains sequenced after three fresh counted runs. O7–O9 are KA-owned D120-L Execute evidence. The [`consolidated outer checkpoint`](cards/walkthrough-remediation-2--consolidated-outer-checkpoint.md) remains last, after R8–R10 and A48-L dispositions. -- **Live scope files:** paused [`R8–R10 controlled provider-conduct evidence`](cards/walkthrough-remediation-2--provider-conduct-evidence.md) retains accepted Card 1 and an invalidated Card 2 awaiting explicit re-entry plus extractor/oracle reconciliation; paused [`consolidated outer checkpoint`](cards/walkthrough-remediation-2--consolidated-outer-checkpoint.md). The live TUI presentation card is consumed and retired. The D119 lexical sweep and deterministic remediation queue are consumed and retired; the independent [`Brunch 1.x data-model handoff`](../docs/architecture/BRUNCH_1X_DATA_MODEL_HANDOFF.md) is delivered. A48-L's scope remains deliberately sequenced after R8–R10 provider evidence despite its settled catalog/report/latency contract. -- **Dependencies:** closes `deterministic-orientation` jointly with KA-carved Execute evidence. `cli-mode-entry` remains stacked after this frontier. -- **Verification (R8–R10):** one normalized 17-node/11-edge semantic fixture; compact text and live/persisted render equivalence with visible per-node/per-edge settlement; exact local/RPC preservation in one atomic effect; three fresh controlled provider runs (current count 0/3); one normal-width human walkthrough judging question materiality, settlement honesty, proposition cohesion, inspectability, and fatigue. See SPEC §Verification Design. -- **Verification (Impact Ledger render, D27-L/D131-L):** golden snapshots at narrow/normal/wide widths assert per-node/per-edge settlement visibility, omit every empty Terms/concern section, and preserve canonical relative order; word-wrap-tolerant `missingRenderedDetailsLeaves` + a naive differential item/status reference extractor (inner/middle, deterministic, no LLM); one human walkthrough cycles a dev-only content-length variant gallery (outer, no `fast-check` — legibility stays human-judged). See SPEC §Verification Design ("FE-1187 Impact Ledger render oracle design"). -- **Verification (replanned shell/orientation/Ask bundle):** tagged-theme and component-preview checks pin ANSI role use, input/menu border identity, editor/footer geometry, intro content/lifetime, and the renamed spec-menu command/shortcut. Active-branch tests distinguish persistent elicitation style from one-shot moves and prove the reduced juncture set and current-style selection. A48-L pairs a tracked human-approved exact availability catalog (seven graph-state cases plus one injected reconciliation-blocker veto) with a structured scratch tracer report; inner tests prove recommended-default-only admission, mode-valid flags, exact cache invalidation, ≤3s fallback, and zero foreground-turn/transcript/graph/session effects; the middle campaign runs three uncached feasibility calls before ten uncached labeled calls and admits only at ≥8/10 in budget, exact completed flags, at least one corrected fallback miss, and zero false positives. The Ask matrix combines deterministic runtime fixtures with one live TUI and one public-RPC questionnaire witness; a lexical negative-space audit rejects live misuse of “continue.” Human outer evidence covers both themes and normal terminal width. -- **Traceability:** WR18 closure record in `TESTING_FINDINGS.md`; evidence at `testing/walkthroughs/2026-07-10/WR18-manual.md`; D98-L/D109-L/D119-L/D120-L/I62-L; D113-L–D115-L reversal/disambiguation; D99-L conduct; TESTING_PLAN concerns 1/3/4/6/7. +- **Built:** D123-L model/auth reversal; deterministic remediation rows; sweep-debt tripwire; digest feedback → bounded questionnaire/confirmation carrier; shared atomic local-TUI/RPC mixed-settlement review preservation with required per-node/per-edge status, exact readback, and no post-approval completion path; discriminating seed variants for propose/project/review routing plus settlement visibility; the borderless Impact Ledger with narrow/normal/wide goldens, render-honesty oracles, and a deterministic 17-node/11-edge variant gallery; the R6 ask-only valid-terminal status rail; authenticated live-TUI presentation corrections; canonical orientation treatment; persistent elicitation style; deterministic action menus; full Ask mechanics; Continue-language cleanup; and the KA 1.x data-model handoff. +- **Next action:** paused at user direction after `remediation-4` tie-off. On explicit re-entry, reconcile the accepted provider-conduct extractor/oracle against the landed mixed-settlement contract, then restart Card 2 from 0/3. No provider run counts precede extractor/oracle reconciliation. +- **Remaining routes:** extractor/oracle reconciliation; the fresh R8–R10 campaign (current count 0/3); A48-L after that campaign; and the [`consolidated outer checkpoint`](cards/walkthrough-remediation-2--consolidated-outer-checkpoint.md). Execute O7–O9 remain KA-owned D120-L evidence. +- **Live scope files:** paused [`R8–R10 controlled provider-conduct evidence`](cards/walkthrough-remediation-2--provider-conduct-evidence.md); paused [`consolidated outer checkpoint`](cards/walkthrough-remediation-2--consolidated-outer-checkpoint.md). +- **Dependencies:** closes `deterministic-orientation` jointly with the KA-carved Execute evidence; `cli-mode-entry` remains stacked after this frontier. +- **Verification:** one normalized 17-node/11-edge semantic fixture; compact text and live/persisted render equivalence with visible per-node/per-edge settlement; exact local/RPC preservation in one atomic effect; three fresh controlled provider runs; a normal-width human walkthrough on question materiality, settlement honesty, proposition cohesion, inspectability, and fatigue; Ask matrix coverage; lexical negative-space audit rejecting live misuse of “continue”; both-theme human outer evidence. See SPEC §Verification Design. +- **Traceability:** WR18 closure record in `TESTING_FINDINGS.md`; evidence at `testing/walkthroughs/2026-07-10/WR18-manual.md`; D98-L, D109-L, D119-L, D120-L, I62-L; D113-L–D115-L; D99-L; TESTING_PLAN concerns 1/3/4/6/7. + +### cli-mode-entry + +- **Name:** Direct-mode CLI entry — `brunch specify [spec-id]` / `brunch execute ` +- **Linear:** unassigned (create at pickup, FE team / brunch project) +- **Branch:** stacked after FE-1187's entry-surface work (shared workspace-dialog seam) +- **Kind:** bounded feature — new CLI entry behavior over existing activation/orientation seams. +- **Certainty:** proving. +- **Blocked by:** `walkthrough-remediation-2` materializing revised D98-L/D109-L. +- **Objective:** add `specify [spec-id]` (default new spec) and `execute ` subcommands, reserve `develop`, pre-answer the workspace dialog through the injected decision seam, seed `operationalMode`, and then follow the revised style/process-move policy rather than synthesizing an obsolete generic orientation entry. +- **Verification:** inner — argv→activation-decision mapping, spec-id validation, orientation-suppression and kick-composition regressions; outer — one manual walkthrough per subcommand. +- **Why now / unlocks:** shares FE-1187's entry-friction motivation and reserves the `develop` name ahead of the later mode frontier. +- **Traceability:** D98-L, D109-L, D101-L, D102-L. + +### saved-mission-comparison-witness + +- **Name:** Operator-led saved-mission comparison witness +- **Linear:** unassigned — create at pickup in Frontend / brunch, with no parent unless the plan or user then names one. +- **Branch:** tbd at pickup; FE-1215 is landed, so create from the then-current stack base when the operator witness is scheduled. +- **Kind:** bounded behavioral-evidence frontier over the real project prompt; no implementation by default. +- **Certainty:** proving. +- **Classification:** wait-gated on operator availability. +- **Status:** planned; FE-1215's D134-L remediation is landed. The retained failed run `minimal-petri-net-editor-20260717T132344Z` remains FE-1215 design evidence, not this frontier's witness. +- **Objective:** prove that the corrected approachable saved-mission workflow works through its actual entry point and that mission revision affects future runs without rewriting historical evidence. +- **Acceptance:** a stock Pi session runs the real `/compare-specs` prompt through ordinary-text approvals; the top-level session is the sole simulated-user actor and drives one direct Brunch shell then one direct Claude shell; the first run proves mission-consistent conduct, no mission leakage, honest outcomes/cleanup, unchanged target-authored documents, one aggregate notification, and a readable report; the operator then revises the mission and approves a second run whose edits do not rewrite the first run's retained snapshots. +- **Verification:** outer only — operator-led first run plus revision/rerun through the real stock-Pi prompt, with artifact inspection and snapshot fingerprints. +- **Dependencies:** hard on operator scheduling; FE-1215's D134-L remediation landing is already satisfied. +- **Traceability:** req 24/A5-L; D70-L; D134-L/I67-L; FE-1210 evidence discipline; SPEC Verification Design `saved-mission-comparison-witness` gate. + +### comparison-mission-isolation-hardening + +- **Name:** Structural private-mission isolation for `/compare-specs` +- **Linear:** unassigned — create at pickup in Frontend / brunch. +- **Branch:** tbd at pickup; stack after the landed FE-1215 workflow when this follow-on starts. +- **Kind:** bounded hardening over the retained D134-L mission boundary. +- **Certainty:** proving. +- **Status:** admitted from `TESTING_FINDINGS.md` CS2; not started. +- **Objective:** make the private mission structurally unreachable from the comparison target by storing it outside the target-reachable tree or equivalently constraining target file tools to the harness cwd. +- **Acceptance:** the target cannot discover or read the private mission by normal `read`/`ls`/`find`/`grep` access; the run still retains the private mission for controller/operator evidence; no FE-1215 historical run is rewritten; the fix does not widen into a generic comparison-runner redesign. +- **Verification:** focused artifact-path and target-visibility tests plus one targeted smoke over the retained `/compare-specs` flow. +- **Traceability:** D134-L/I67-L; `TESTING_FINDINGS.md` CS2. ### shared-session-host-tracer - **Name:** Shared session host tracer — one runtime authority for TUI and React - **Linear:** unassigned (create at pickup, FE team / brunch project) -- **Branch:** tbd at pickup; stack from the FE-1200 foundation after reconciling the current Graphite stack +- **Branch:** tbd at pickup; stack from the FE-1200 foundation after reconciling the current Graphite stack. - **Kind:** structural — new process/lifecycle and TUI-adapter seam over the materialized `LiveSessionHost`. - **Certainty:** proving. -- **Status:** not started; design entry is the current/desired topology and transition guide in [`docs/design/WEB_UI_ARCHITECTURE.md`](../docs/design/WEB_UI_ARCHITECTURE.md). -- **Objective:** retire A47-L with the thinnest production-cover proof that one independently-lived cwd-scoped Brunch host can own the sole writable sealed Pi runtime for a target while both a real Pi TUI presentation and the React client attach to that same runtime authority. Borrow pi-web's daemon/process shape, not its Pi-shaped REST/raw-event contract. -- **Why now / unlocks:** FE-1200 proved the host inventory and semantic browser contract but left `InteractiveMode` embedded in a separate TUI-owned runtime. Without this tracer, every web addition either preserves two relays forever or quietly degrades the TUI. Landing it unlocks an earned, deletion-driven cutover rather than another parallel host. -- **Retires:** A47-L — whether Pi's exported `InteractiveMode(AgentSessionRuntime)` coupling can be adapted without a second writable runtime, raw Pi browser surface, or permanently duplicated relay. -- **Lights up:** one durable target observed by React and driven/rendered through a real TUI while the host—not either client—owns runtime lifetime, driver admission, JSONL persistence, and semantic event fan-out. -- **Boundary:** one cwd, one target, one TUI client/adapter, one React attachment, one active driver. In: ordinary prompt/stream/settlement, one extension-owned structured `ask`, one TUI-only product interaction (command/confirmation or model/auth surface), client detach/re-attach, duplicate-writer and driver-conflict rivals. Out: complete family migration, multi-machine reach, remote auth, generic terminal transport, and deletion of the old path (owned by cutover). -- **Acceptance:** - - The host process can remain alive while either presentation attaches/detaches; exactly one sealed `AgentSession`/`SessionManager` writes the target JSONL and one graph authority serves both. - - The TUI remains a real Brunch/Pi interactive presentation—editor, chrome, command/extension UI, and transcript rendering are not replaced by a token text client merely to satisfy the topology. - - React receives only target-addressed Brunch semantic deltas and rehydrates from the same fresh JSONL presentation after settlement; no raw Pi RPC/event contract crosses the browser boundary. - - One explicit host-owned driver policy admits the TUI and rejects or hands off a conflicting React driver without opening another runtime. - - A client crash/detach does not end or counterfeit host runtime state; a host restart may honestly reopen durable JSONL and need not preserve an in-flight turn. - - The winning TUI attachment shape and rejected alternatives are recorded in SPEC/design/topology before the cutover ledger is scoped. -- **Verification:** inner — host/adapter contract tests and duplicate-writer/driver rivals; middle — production entry subprocess witness with one host + TUI + browser attachment, semantic stream↔JSONL differential, detach/reconnect, and target identity; outer — colleague-run walkthrough proving the TUI still supports one normal Brunch workflow and the browser observes/continues it without a second runtime. -- **Traceability:** A47-L; req 4/12/17/31/32; D39-L, D132-L, D133-L; I64-L/I65-L; pi-web process-shape evidence in `docs/archive/architecture/pi-web-comparative.md`. +- **Status:** not started; design entry point is [`docs/design/WEB_UI_ARCHITECTURE.md`](../docs/design/WEB_UI_ARCHITECTURE.md). +- **Objective:** retire A47-L with the thinnest production-cover proof that one independently-lived cwd-scoped Brunch host can own the sole writable sealed Pi runtime for a target while both a real Pi TUI presentation and the React client attach to that same runtime authority. +- **Why now / unlocks:** FE-1200 proved the host inventory and semantic browser contract but left `InteractiveMode` embedded in a separate TUI-owned runtime. Landing this unlocks an earned deletion-driven cutover instead of preserving dual host architectures. +- **Acceptance:** the host can remain alive while either presentation attaches/detaches; exactly one sealed runtime writes target JSONL; the TUI remains a real Brunch/Pi interactive presentation; React receives only target-addressed Brunch semantic deltas and rehydrates from the same JSONL; one host-owned driver policy admits the TUI and rejects or hands off a conflicting React driver; a client crash/detach does not counterfeit runtime ownership; the winning TUI attachment shape is recorded in SPEC/design/topology before cutover scoping. +- **Verification:** inner host/adapter contract tests and duplicate-writer/driver rivals; middle production entry subprocess witness with one host + TUI + browser attachment, semantic stream↔JSONL differential, detach/reconnect, and target identity; outer colleague walkthrough proving that the TUI still supports one normal Brunch workflow while the browser observes/continues it. +- **Traceability:** A47-L; req 4/12/17/31/32; D39-L, D132-L, D133-L; I64-L, I65-L. ### shared-session-host-cutover - **Name:** Shared session host cutover — migrate both presentations and retire the sidecar host - **Linear:** unassigned (create only after the tracer chooses the TUI attachment seam) -- **Branch:** tbd; stacks on `shared-session-host-tracer` +- **Branch:** tbd; stacks on `shared-session-host-tracer`. - **Kind:** coverage-shaped architectural replacement over the closed TUI/web host capability surface. - **Certainty:** earned after A47-L retires; regress to proving if the tracer leaves a real attachment unknown. -- **Classification:** wait-gated on `shared-session-host-tracer`; inventory is closeable from production TUI composition, RPC registries, web routes, and their existing contract tests, but rows cannot be assigned to the canonical adapter until the tracer lands. -- **Objective:** make the traced host the sole live-session authority for both TUI and React, preserve every required presentation capability, and delete—not adapt indefinitely—the TUI-owned singleton relay, raw event contract, `/rpc/driver`, and parallel driver/broker wiring. -- **Closes:** the dual architecture documented after FE-1200: standalone target-addressed semantic host versus TUI-owned current-session/raw-relay sidecar. -- **Canonicalizes:** `LiveSessionHost` (or its traced successor), durable `(specId, sessionId)` targeting, one driver lease/handoff policy, `brunch.liveSessionEvent`, and fresh JSONL presentation as the only live-session host contract. -- **Deletes / retires:** D84-L; `src/rpc/session-event-relay.ts`; `brunch.sessionEvent`; `/rpc/driver`; `createWebSidecarRpcHandlers`' handle-gated sidecar variants; TUI composition fields that pass raw session/ask/driver handles into `startWebHost`; old relay-only tests/support and docs. -- **Boundary:** in — host lifecycle/open/close; TUI startup/new/resume/tree/commands/extension UI/model-auth/chrome; ordinary turns and all required ask/offer families; browser hydration/live overlay/driver handoff; graph/update and executor observer reads; reconnect/shutdown/error behavior. Out — cloud/multi-cwd/federation, a generic event spine, browser terminal/git/file APIs, process-crash survival for in-flight turns, and visual identity parity between terminal and React. -- **Inventory authority:** at scope time create `memory/cards/shared-session-host-cutover--surface-ledger.md` (`Mode: sweep`) from the production composition/registries plus existing TUI, RPC, standalone-host, and web-route oracles. Mark each row required `●` or explicitly deferred `○`; each required row names one canonical owner and one closure oracle. +- **Classification:** wait-gated on `shared-session-host-tracer`. +- **Objective:** make the traced host the sole live-session authority for both TUI and React, preserve every required presentation capability, and delete the TUI-owned singleton relay, raw event contract, `/rpc/driver`, and parallel driver/broker wiring. +- **Inventory authority:** create `memory/cards/shared-session-host-cutover--surface-ledger.md` (`Mode: sweep`) at scope time from the production composition/registries plus existing TUI, RPC, standalone-host, and web-route oracles. - **Aggregate DoD:** no required row remains `spec` / `new` / `partial`; both presentations pass through the one host authority; the deletion list is absent from production and test code; no topology or onboarding doc teaches the retired sidecar architecture. -- **Promotion / disposal:** a row that reveals a genuinely new product seam promotes to PLAN and keeps this ledger open until it lands. More than one newly discovered row or a changed attachment seam stops the sweep and routes back through `ln-plan`. Delete the ledger only after all required rows and topology/doc reconciliation close. - **Verification:** per-row inner tests; middle production-host differential across TUI and React with one JSONL/runtime identity, active-branch/reconnect and graph-update rivals; full `npm run verify`; outer colleague walkthrough of TUI-driven and browser-driven handoff plus client restart. A deletion oracle rejects `SessionEventRelay`, `brunch.sessionEvent`, `/rpc/driver`, and targetless live-session calls outside archive/history docs. -- **Traceability:** D84-L retirement; D132-L/D133-L materialization; I64-L/I65-L; `shared-session-host-convergence` arc done-definition; [`docs/design/WEB_UI_ARCHITECTURE.md`](../docs/design/WEB_UI_ARCHITECTURE.md). - -### interactive-tui-driver - -- **Name:** Canonical interactive TUI driver for agents and human takeover -- **Linear:** [FE-1206](https://linear.app/hash/issue/FE-1206/canonical-interactive-tui-driver-for-agents-and-human-takeover). -- **Branch:** `ln/fe-1206-interactive-tui-driver`, independently stacked on `ln/fe-1187-remediation-3` in the dedicated `brunch-next-iota` worktree. -- **Kind:** structural tooling — development feedback-loop control and evidence capture, not product runtime. -- **Certainty:** proving. -- **Status:** ✓ closed 2026-07-15; post-witness adoption refined to a permanent project-local developer package. Host-capable default: pinned `pi-interactive-shell` declared under root `.pi`; sandbox/headless fallback: project-owned Expect/headless-xterm `npm run tui-driver`. The extension remains outside Brunch's shipped package manifest, runtime dependency graph, and sealed `src/.pi` profile. -- **Objective:** settle and materialize one canonical way for agents to launch, observe, drive, resize, and stop Brunch TUIs while a human can inspect or take over when the host permits it. Compare the proven in-repo `src/dev/tui-driver.ts` (Expect/FIFO PTY + `@xterm/headless`) with `pi-interactive-shell`'s Pi overlay over `zigpty`; adopt, augment, or retain based on real tracer evidence rather than replacing the working fallback speculatively. -- **Why now / unlocks:** FE-1187's review-set prototype exposed recurring runner confusion: external daemon-backed tools can fail under sandbox socket policy, while the component playground is the canonical visual-review surface but agents lack one obvious interaction path. A settled driver workflow unlocks repeatable component-playground reviews, real Brunch TUI walkthroughs, and future outer-loop evidence without re-deriving the tool choice each session. -- **Lights up:** one end-to-end agent-controlled path through both `npm run dev:components -- tui-lab` and a seeded `npm run dev-cli` session, with terminal-state observation and deterministic teardown. -- **Stabilizes:** `docs/praxis/manual-testing.md`'s TUI-driving priority order and `src/dev/TOPOLOGY.md`'s feedback-loop seam; no agent should guess among cmux, agent-tui, shellwright, and the repo driver after this frontier closes. -- **Acceptance:** - - The active scope file carries a temporary capability matrix evaluating the existing driver and `pi-interactive-shell` on real PTY fidelity, xterm/VT screen reconstruction, text and named-key input, bracketed/multiline paste, wait/assert, resize, output bounds, cancellation/cleanup, human observation/takeover, sandbox viability, and artifact hygiene. It records measured evidence, not README claims; closure distills the chosen/default/fallback result into the existing manual-testing and dev docs, then deletes the temporary matrix with the exhausted scope file. - - One tracer drives a stable component-preview entry through launch → screen assertion → variant/input action → resize → clean exit. A second tracer drives a seeded Brunch TUI through launch → visible-state assertion → key/text interaction → cancellation → teardown. Both use the same candidate workflow where capabilities permit. - - `pi-interactive-shell` is validated against Brunch's Pi `0.80.x` line and the team's actual macOS architecture, including its `zigpty` prebuild. Its current dependency on `zigpty ^0.1.6` is checked against the current `zigpty 0.2.x` API/release line; version lag or platform limits are recorded before adoption. - - The existing Expect/xterm driver remains the sandbox/headless fallback until the candidate proves equivalent screen interpretation, deterministic input, liveness, and teardown. Direct `zigpty` integration is considered only if the extension cannot meet the project workflow; do not create a second custom PTY stack for optionality. - - The chosen workflow supports bounded model-visible output and keeps raw PTY logs under gitignored `.fixtures/scratch/`; secrets or pasted credentials never enter committed evidence or automatic model summaries. - - `docs/praxis/manual-testing.md`, `src/dev/README.md`, and `src/dev/TOPOLOGY.md` name one explicit priority order, installation/health checks, exact commands, fallback trigger, cleanup procedure, and user-takeover behavior. Superseded runner guidance is removed rather than left as competing advice. - - No PTY package or Pi extension enters Brunch's shipped product runtime dependency surface solely for test tooling. The permanent project-local package/config surface is developer-only root `.pi` state. -- **Verification:** inner — existing `tui-driver` protocol/screen/liveness tests remain green plus adapter/config tests for any new project-owned code; middle — scripted component-preview and seeded-Brunch tracer matrix with captured textual viewports, resize/input assertions, exit status, and cleanup; outer — one user-observed Pi overlay session proving watch/takeover/return-to-agent behavior, plus one sandbox run proving the documented fallback when socket-backed tools cannot bind. -- **Cross-cutting obligations:** preserve the manual-testing findings-ledger discipline and scratch-artifact rules; do not make an external extension part of Brunch's product extension bundle; retain the current fallback until the replacement decision is witnessed; document platform ceilings explicitly rather than claiming cross-platform support from upstream marketing. -- **Traceability:** `docs/praxis/manual-testing.md` §Setup / sandbox fallback; `src/dev/TOPOLOGY.md` and `src/dev/tui-driver.ts`; FE-1187 R8–R10 component-playground review pressure. External candidates: [`pi-interactive-shell`](https://github.com/nicobailon/pi-interactive-shell), [`zigpty`](https://github.com/pithings/zigpty). - -### agent-control-plane-closure - -- **Name:** Elicitor and subagent control-plane closure -- **Linear:** [FE-1216](https://linear.app/hash/issue/FE-1216/elicitor-and-subagent-control-plane-closure) -- **Branch:** `ln/fe-1216-agent-control-plane-closure`; replaces the unstarted `graph-assurance-conduct` and absorbs `subagent-skill-access` -- **Kind:** earned coverage-shaped closure over foreground/background prompt ingress and agent resources; not a graph-schema migration, capture-quality experiment, or reviewer feature. -- **Certainty:** earned. -- **Classification:** buildable-now; D135-L/I68-L settle the context/control ingress model, so no additional design or spike is required. -- **Status:** ✓ done 2026-07-17; all seven required sweep rows built and the temporary ledger retired. -- **Entry action:** ✓ complete 2026-07-17 — D135-L/I68-L preserve thin/load-on-demand foreground composition, distinguish origination continuity from later reads, and supersede D101-L's stale `world-reads.ts` delivery clause; the seven-row coverage sweep is complete and its temporary ledger is retired. -- **Objective:** make every Brunch-owned agent receive one truthful, current, testable control surface: live resources agree with D131-L; foreground prompt updates replace stale Brunch blocks; load-on-demand context topology has no dead eager-context claims or must-wire no-ops; posture, elicitation style, and asking agenda have an explicit ownership map; and each background agent is advertised only the skills/resources its tool grant or task bundle can actually consume. -- **Why now / unlocks:** the audit found several individually small defects sharing one ingress boundary: contradicted assurance conduct, content-insensitive prompt deduplication, dead `graphReads`/`composeAgentContextSeed` topology claims, duplicated context rendering, unobserved skill invocation, and a full skill manifest injected into no-tools subagents. Treating them as separate frontiers would repeatedly reopen the same prompt assembly and contract tests. The repo-level subagent extension already proves named skill grants and Markdown handback, so only product integration and honest prompt composition remain. -- **Coverage inventory:** - - **Assurance semantics:** materialize D131-L through ingest/map/project/propose/review and their references. Existing `evidence`/`vv_obligation` rows stay readable; no live resource proposes future evidence, generates a verification obligation, or treats an unexecuted check as proof. - - **Foreground block identity:** replace first-line sentinel deduplication with explicit owned-block identity/replacement across provider carrier shapes. A changed role, elicitation style, active-tool set, or resource manifest cannot be silently discarded as “already present.” - - **Context topology:** materialize D135-L: preserve D58-L's thin prompt plus origination continuity and load-on-demand later reads; retire the dead eager per-turn path, no-op `graphReads` contract, and stale current-state claims as one coherent cutover. - - **Control ownership:** document and test the distinct owners of spec posture (persisted product fact), elicitation style (persisted session process bias), and asking agenda (prompt/session origination conduct). Share rendering helpers without collapsing those controls into one state primitive. - - **Resource invocation:** distinguish advertised, readable, and actually read resources in prompt-contract/trajectory tests; the capture trigger must have an observable read contract rather than manifest-presence proof alone. - - **Background grants:** carry named skills through the product subagent manifest/adapter where a child can read them; otherwise inject the complete rubric into the task bundle. No no-tools child receives “read a listed skill” instructions or dead manifest tokens. Markdown handback is legal; foreground retains collation and all mutation authority. - - **Minor closure:** cache immutable prompt bodies/manifests at the appropriate lifetime and consolidate duplicated posture/context renderers without widening their public seams. -- **Aggregate done-definition:** every required inventory row is built or has an explicit non-applicable disposition; foreground and background prompts contain no contradictory tool/resource instructions; per-turn changes replace stale owned blocks; topology/SPEC/code tell one story about context; and the assurance chain is criteria/method → concrete check (`realization`) plus deliberately promoted prior observation → witnessed/falsified claim (`witness`). -- **Acceptance:** - - `src/agents/references/data-model.md` and `readiness-bands.md` distinguish physical compatibility taxonomy from D131-L conduct. Evidence is capture-only and is not an expected projection deliverable; `vv_obligation` is marked legacy/reserved without deleting its schema entry. - - Focused prompt tests prove identical-composition idempotence and changed-composition replacement for role/style/tools/resources in plain strings and provider block/message carriers. - - Context tests and topology docs prove the selected D58-L/D101-L path; no production-required parameter is unused and no canonical doc names a nonexistent caller. - - Control-map tests make posture/style/agenda provenance and lifetime explicit while preserving their intentional separation. - - Foreground production-recorder tests prove instrumentation can distinguish advertised, read, and provider-visible resources for an observed read; they do not claim that an LLM chose every required ingest/project/propose read. Controlled provider trajectories and the downstream `capture-ledger-tracer` own agent-conduct evidence. Background prompt tests cover readable-skill, bundled-rubric, and no-tools agents without contradictory instructions. - - Existing seed fixtures and historical rows remain unchanged unless they are live conduct oracles. No schema enum, database migration, compatibility shim, production capture IR, or mass fixture regeneration lands. -- **Verification:** `npm run check:skills`; prompt/resource composition and provider-carrier tests; topology/import contract checks; focused subagent prompt/grant tests; production recorder → persisted trajectory → report projection for an observed resource read. Required-read agent conduct is evaluated through controlled provider trajectories and the downstream `capture-ledger-tracer`, not inferred from deterministic instrumentation tests. Full `npm run verify` before submission. -- **Boundary:** FE-1187 owns the review renderer and outer extraction-breadth checkpoint. `capture-ledger-tracer` owns whether a four-section mental ledger improves capture. `reviewer-agent-mode` owns reviewer behavior after this frontier supplies honest skill/resource access. Dedicated automatic evidence promotion remains out. -- **Traceability:** D135-L/I68-L (control ingress and capability honesty), D58-L (thin/load-on-demand live prompt), D90-L/D95-L (agent and skill manifests), D98-L/D101-L/D102-L/D118-L (control/context ownership), D131-L (assurance semantics), D87-L/D94-L/D99-L/D70-L; current topology homes under `src/agents/runtime/elicitor`, `src/agents/contexts`, and `src/.pi/extensions`. +- **Traceability:** D84-L retirement; D132-L, D133-L; I64-L, I65-L; `shared-session-host-convergence` arc done-definition; [`docs/design/WEB_UI_ARCHITECTURE.md`](../docs/design/WEB_UI_ARCHITECTURE.md). ### capture-ledger-tracer - **Name:** Sectioned capture-ledger conduct tracer - **Linear:** unassigned (create at pickup, FE team / brunch project) - **Branch:** tbd at pickup; stack after `agent-control-plane-closure` -- **Kind:** bounded agent-control intervention + behavioral evaluation tracer; not a durable capture IR, graph-schema change, or production subagent fan-out. +- **Kind:** bounded agent-control intervention + behavioral evaluation tracer; not durable capture IR, graph-schema change, or production subagent fan-out. - **Certainty:** proving. -- **Classification:** buildable-now; the `agent-control-plane-closure` gate is complete and the prepared scope is pickup-ready. +- **Classification:** buildable-now. - **Status:** planned; scope prepared at [`memory/cards/capture-ledger-tracer--conduct-falsifier.md`](cards/capture-ledger-tracer--conduct-falsifier.md). - **Objective:** produce a predeclared matched verdict on whether a versioned Intent / Implementation / Assurance / Planning capture rubric plus a separate relations/conflicts/abstentions pass improves accepted-source capture over current ingest conduct without increasing false commitment or laundering uncertainty. -- **Why now / unlocks:** FE-1210 proved the general push-driven actor and split outcome/process judgment pattern, while its promoted witness exposed the target seam: Brunch elicited broad consequential material but the settled graph-derived document still omitted one revealed fact. The result decides whether the next architecture should remain prompt-carried, graduate to a foreground typed capture compiler, or earn focused subagent fan-out. -- **Lights up:** accepted source carrier → real elicitor prompt/resources → graph/scratchpad/reconciliation outcomes → masked outcome packet + unblinded Brunch conduct packet → human-adjudicated adoption/rejection verdict. -- **Stabilizes:** one versioned capture-conduct intervention, one atomic controller-only capture key, and one reusable control/treatment oracle that counts facts and relations individually rather than crediting a compound interaction as one success. -- **Acceptance:** - - One canonical `capture-ledger-v1` conduct pack lives in `ingest`; a short elicitor activation directive requires the relevant skill/map reads at a capture trigger without copying the rubric into multiple prompt homes. Intent / Implementation / Assurance / Planning remain extraction views, not graph ontology or readiness stages; relations remain cross-cutting. - - A dev/eval-only control/treatment seam changes only the capture-ledger conduct. Stable ids/hashes and prompt differentials prove the intervention; normal product launches cannot select an evaluation arm. - - One frozen accepted-digest mission contains atomic material across all four concern groups, cross-group relations, uncertainty, contradiction, concrete prior evidence, a future-evidence decoy, unsupported implication, and superseded/option-echo contamination. - - Matched retained runs use the same model, source, graph seed, budgets, actor policy, and validity rules. A masked terminal-state packet judges supported recall, relation preservation, routing/settlement fidelity, abstention, invention, and downstream coherence; a separate unblinded Brunch conduct packet judges actual resource reads, carrier integrity, action ordering, retries, and cost. - - The predeclared verdict records positive, negative, and invalid evidence without post-hoc rubric changes. A gain supports scoping the foreground typed capture compiler; persistent category-specific omissions may support a later Markdown-returning specialist fan-out; no gain rejects further ledger machinery. -- **Verification:** inner — exact prompt/resource composition, stable intervention identity, carrier contamination negatives, graph legality, settlement/routing, and packet schema tests; middle — deterministic replay through the real prompt/composition and evaluator seams plus matched real-provider actor runs; outer — criterion-level human adjudication of masked outcome and unblinded conduct drafts before promotion. -- **Boundary:** reuse FE-1210's proven actor and split-judgment discipline plus the landed FE-1208 evaluator/report primitives where they fit; do not revive the old fixed actor, create a second artifact system, add durable IR, or require specialist fan-out. If later earned, specialists may use task-bundled rubrics or the named grants materialized by `agent-control-plane-closure` and return Markdown; foreground still owns collation, mapping, and writes. -- **Traceability:** D99-L (accepted-source advisory routing), D131-L (concern groups and assurance semantics), A22-L (foreground capture quality), A34-L (subagent acquisition remains open), A40-L (watermark intent is not proven capture completion); FE-1210 split-judgment evidence architecture. - -### operator-comparison-workflow - -- **Name:** Approachable saved-mission comparison workflow -- **Linear:** [FE-1215](https://linear.app/hash/issue/FE-1215/approachable-saved-mission-comparison-workflow) — Frontend / brunch, assigned to Lu, no parent. -- **Branch:** `ln/fe-1215-saved-mission-comparison`, stacked on completed FE-1210 `ln/fe-1210-agent-as-user-comparison`. -- **Kind:** bounded operator tooling — one project Pi prompt plus a durable mission/report artifact flow; not Brunch product runtime and not a generic campaign framework. -- **Certainty:** proving. -- **Status:** focused remediation and #343 stack closeout corrections complete. The first operator-led run validated the mission interview but falsified the fresh nested Pi actor topology, exposed stock-Pi portability risk from `ask_user_question`, and showed that synthetic provider/actor preflights are too heavy for every launch. The autonomous prompt/docs correction is built and statically verified, and the focused real-entry smoke passed on run `minimal-petri-net-editor-20260717T191333Z`: a Brunch-only direct-shell `/compare-specs` interaction reached a real Specify exchange beyond the splash and exported a review-ready spec with no private-mission leakage (`TESTING_FINDINGS.md` CS1–CS2). Review induction's remaining bounded defects are now closed on #343: document export accepts no fixture-only visibility control and reads active settled graph state, live Brunch recipes thread target-rooted output paths, and the mission namespace reserves its README. Separately, the private mission was stored inside the target-reachable run tree (isolation held behaviorally, not by a filesystem jail) — routed to follow-up `comparison-mission-isolation-hardening` (CS2). -- **Objective:** give an operator one approachable conversational door for creating, revising, and running agent-as-user specification comparisons. The saved mission privately defines the simulated user—what they are trying to accomplish, their context, priorities, preferences, constraints, knowledge, uncertainties, decision latitude, and conversational posture. The invoking top-level Pi session follows that mission and directly performs the user's side of each interaction while driving one comparison harness at a time. Harness setup is a separate, minimal run concern: each selected harness receives only its small specification-task framing plus the opening user message and subsequent mission-grounded answers, never the mission wholesale. After the run, the operator can compare the full private mission, what each harness actually elicited, and each target-authored document in one readable report. -- **Why now / unlocks:** FE-1210 proved the rigorous fresh-actor/adapters substrate, but the first operator-led FE-1215 handover run showed that reusing it through a nested actor shell makes the approachable path unusable: nested viewport dimensions hid Brunch's interactive surface, actor-vs-harness roles were opaque, and live smoke preflights added ceremony. Correcting the control topology on the active branch is required before a later full witness or browser workspace is meaningful. -- **Lights up:** one invocation → conversational private user-mission interview → separate minimal comparison-harness setup → top-level session acting as simulated user → one direct harness interaction at a time → completion notification → target-authored documents → readable operator report. -- **Stabilizes:** D134-L/I67-L's single-level control topology, stock-Pi text portability, and the separation among an editable private agent-as-user mission, minimal per-run harness setup, target-visible interaction, and immutable run snapshots. Saved missions live under `testing/comparisons/missions/`; ephemeral target workspaces/evidence assembly stay under `.fixtures/scratch/comparisons/`; reviewed run snapshots, outputs, and reports use `.fixtures/runs/agent-as-user-comparison/`. This preserves D70-L's four-role fixture taxonomy and keeps product-neutral missions distinct from Brunch seeds. -- **Acceptance:** - - `.pi/prompts/compare-specs.md` remains the single operator entry point. With no argument it offers create/revise/run; with a mission id or path it resolves only an unambiguous mission Markdown file under `testing/comparisons/missions/` and offers review/revise/run. `README.md` is a reserved control file and is never selectable, revisable, or writable as mission payload. Mission usefulness depends on its ordinary-language content, not exact heading names. - - New-mission intake remains conversational in ordinary product language, one material question at a time, establishing the simulated user's objective, context, priorities, preferences, constraints, known facts, uncertainties, decision latitude, conversational/disclosure posture, and natural opening request. It never assumes that the simulated user is a PM and does not configure a harness while defining the user. - - The generated mission remains readable private Markdown rather than controller YAML. It contains no comparison-harness selection or adapter instructions. Only the invoking top-level Pi agent receives it wholesale. - - Run setup selects **comparison harnesses** from the concrete v1 roster and shows the minimal exact framing each receives. Future run snapshots use `harness-setup.md`; immutable historical `contender-setup.md` snapshots are not renamed or rewritten. - - The invoking project Pi session is the sole simulated-user actor for the approachable run. It launches exactly one selected harness in one direct `interactive_shell` session at a time, at normal host dimensions, with a fresh isolated target cwd/session. It never spawns a Pi actor that launches another interactive shell. - - Each harness receives only its approved framing plus the natural opening and later answers chosen by the top-level agent from mission truth. The private mission text/file/path never enters the harness context or cwd. Lane order and the shared top-level actor context are disclosed; this exploratory workflow does not claim rigorous per-lane actor-process isolation. - - Operator choices, mission approval, and run approval always work through ordinary text in stock Pi. If a custom structured-question tool exists, it may improve presentation but cannot be required for correctness or progress. - - Setup checks are lean and selected-harness-specific: verify filesystem/adapter prerequisites without synthetic Pi actor launches or throwaway provider conversations. Provider/model failure is reported honestly at the real harness launch. Pi is checked as a comparison harness only when Pi is selected. - - Revision updates only the editable mission. Every run copies the exact approved private mission and separate harness setup into operator-only evidence, so later revisions cannot rewrite earlier comparisons. - - One approved kickoff sequences selected harnesses with visible `ready | running | waiting | finished | failed` status. The operator is notified only when all selected harnesses resolve; v1 does not promise parallel execution. - - Each completed run retains the private mission snapshot, exact harness setup, target-visible interaction, every target-authored document, lane outcomes, and one `report.md`. The report distinguishes the private baseline from what each harness saw; observations are free-form and it declares no automatic winner or fixed rubric. -- **Boundary:** no browser workspace, database, standalone mission service, automatic winner, scripted/API judge, statistics, unattended multi-run campaign, or generic harness abstraction. The approachable path reuses FE-1210's direct target adapters and rendered-state cadence, not its fresh-per-lane nested actor recipe. Rigorous frozen-packet/matched-budget/blinded studies retain that separate recipe. Do not extract a skill or package unless the prompt remains unreliable after this correction. -- **Verification:** inner — direct prompt/README review, prompt-template discovery/frontmatter, stock-Pi built-in tool audit, targeted Markdown checks, and repository read-only checks. Focused outer remediation smoke — invoke the real prompt from stock Pi, use plain-text choices/approvals, and reach one normal-width Brunch Specify interaction through a single direct shell with no nested actor process. The later `saved-mission-comparison-witness` still owns the full Brunch + Claude run, report usefulness, and revision immutability proof. -- **Traceability:** req 24/A5-L evidence lifecycle; D70-L fixture taxonomy; D134-L/I67-L control topology and portability; FE-1210 closeout and promoted `lockers-r1-20260716` rigorous actor/adapter evidence; retained failed run `minimal-petri-net-editor-20260717T132344Z` and its operator observations. -- **Current execution pointer:** no active scope or refactor file. The focused smoke and #343 review closeout are complete; tie off and land the stack. `comparison-mission-isolation-hardening` remains a separate follow-up. - -### saved-mission-comparison-witness - -- **Name:** Operator-led saved-mission comparison witness -- **Linear:** unassigned — create at pickup in Frontend / brunch, with no parent unless the plan or user then names one. -- **Branch:** tbd at pickup; stack on the landed D134-L-remediated `operator-comparison-workflow` / FE-1215 branch. -- **Kind:** bounded behavioral-evidence frontier over the real project prompt; no implementation by default. -- **Certainty:** proving. -- **Classification:** wait-gated on operator availability and FE-1215's D134-L remediation landing. -- **Status:** planned for a later PR; not started. The retained failed run `minimal-petri-net-editor-20260717T132344Z` is design evidence for FE-1215, not this frontier's passing witness. -- **Objective:** prove that the corrected approachable saved-mission workflow works through its actual entry point and that mission revision affects future runs without rewriting historical evidence. -- **Why now / unlocks:** FE-1215 must first remove its nested actor topology and stock-Pi portability assumptions. A separately scheduled operator-owned frontier then proves the full multi-harness workflow without letting static prompt review stand in for behavior. -- **Lights up:** real operator-authored private user mission → top-level agent acting as simulated user → one direct Brunch shell then one direct Claude shell → target-authored documents → readable retained report → revised mission and second immutable run. -- **Stabilizes:** D134-L/I67-L single-level control, private-mission isolation, mission-consistent simulated-user conduct, exact target-visible disclosure, aggregate completion notification, operator-report usefulness, and immutable run history across mission revision. -- **Boundary:** first run uses Brunch + Claude and one operator-authored mission; second run revises that same mission. No surrogate lifecycle test, automatic judge, roster-wide campaign, browser UI, generic runner, orchestration implementation, or fresh nested actor process. Rigorous per-lane actor isolation remains FE-1210 campaign territory, not an acceptance criterion here. -- **Acceptance:** - - A newly started project-trusted stock Pi session discovers and runs the actual `/compare-specs` template using ordinary-text choices/approvals, with no dependency on `ask_user_question` or another custom question tool. - - That top-level session is the sole simulated-user actor and drives only one direct comparison-harness interactive shell at a time; Brunch and Claude each receive fresh isolated target cwd/session identities, and no interactive shell is launched from inside another actor shell. - - The first Brunch + Claude run demonstrates mission-consistent opening/answers/decisions, explicit unknown/undecided behavior where required, no wholesale mission or mission-path leakage, honest lane outcomes/cleanup, unchanged target-authored documents, one aggregate notification, and a cold-readable operator report separating private baseline from target-visible evidence. - - The operator revises the saved mission through actual `/compare-specs` and approves a second run setup; the editable mission changes while the first run's private-mission and harness-setup snapshots remain byte-for-byte unchanged. - - Only the second run receives the revised mission/setup; no first-run directory, transcript, target output, or report is overwritten. -- **Verification:** outer only — operator-led first run plus revision/rerun through the real stock-Pi prompt, with repository-relative artifact inspection and snapshot fingerprints. Static checks may support artifact hygiene but cannot satisfy behavioral acceptance. -- **Dependencies:** hard on FE-1215's D134-L remediation landing and operator scheduling. Create its Linear issue and Graphite branch only when the frontier starts. -- **Traceability:** req 24/A5-L evidence lifecycle; D70-L fixture taxonomy; D134-L/I67-L control topology; FE-1210's separate rigorous actor/adapter evidence; SPEC Verification Design `saved-mission-comparison-witness` outer gate. -- **Current execution pointer:** none; run `ln-scope` at pickup after the operator witness session is scheduled. - -### cli-mode-entry - -- **Name:** Direct-mode CLI entry — `brunch specify [spec-id]` / `brunch execute ` -- **Linear:** unassigned (create at pickup, FE team / brunch project) -- **Branch:** stacked on FE-1187's auth-reversal branch (both reshape the entry surface; shared workspace-dialog seam) -- **Kind:** bounded feature — new CLI entry behavior over existing activation/orientation seams. -- **Certainty:** proving — the activation seams exist; the open question is direct mode entry under the new persistent Specify-style / one-shot-process-move policy. -- **Blocked by:** `walkthrough-remediation-2` materializing revised D98-L/D109-L. The earlier assumption that direct mode entry should synthesize one generic orientation entry and suppress the boot menu is retired. -- **Objective:** subcommands `specify [spec-id]` (spec optional — default is a new spec, which still requires a title prompt), `execute ` (spec required), and a reserved `develop` name. Parse via the existing `parseArgs` router (`src/app/brunch.ts`, where `login` routes today); pre-answer the workspace dialog through the injected decision seam (`chooseSpecSessionActivationDecision` overrides + `findSpec` lookup, decision union `newSpec{title}` / `newSession{specId}`); seed `operationalMode` via `appendBrunchAgentRuntimeInit`, then follow the revised style/process-move policy rather than fabricating an obsolete generic orientation choice. -- **Distinctions:** `--mode` remains the host-mode axis (`tui`/`print`/`rpc`); operational mode enters only via subcommand. Execute-mode entry semantics stay D98-L-consistent (1:1 mode↔agent) — coordinate the `execute` subcommand's semantics with the KA stream. -- **Verification:** inner — argv→activation-decision mapping, spec-id validation, orientation-suppression + kick-composition regressions; outer — one manual walkthrough per subcommand. -- **Why now / unlocks:** shares FE-1187's entry-friction motivation (alpha users must reach a working session with minimum ceremony); reserves the `develop` name ahead of the Horizon mode. Cost read 2026-07-13: ~2–3 focused days. -- **Traceability:** D98-L, D109-L (juncture family), D101-L/D102-L (seed facts); riskiest seam: boot-menu suppression vs `session-orientation` registrar/kick bookkeeping. - - - - - - - - - -### planning-process-model - -- **Name:** Planning-process model — plan-as-projection and epistemic horizon beyond the settled scope handoff -- **Linear:** unassigned -- **Branch:** `ln/fe-xxx-plan-plane-redesign` (plan-plane groundwork already landed here: `slice` removal + D103-L + CueLoop liftout) -- **Kind:** structural / plan-plane semantics -- **Stream:** KA (Kostandin) — moved 2026-07-13: plan-plane semantics sit with executor/orchestration concerns. -- **Status:** Horizon candidate, reshaped by D126-L. The durable `scope` question is closed; this frontier now owns only plan projection beyond committed scopes and the remaining epistemic-horizon/decision-flow questions. The orientation menus' "project a plan" option does not depend on or advance it. -- **Certainty:** proving. -- **Lights up:** plan generation as *projection* from committed `{milestone, frontier, scope}` truth through the existing `project` seam, optionally exported to an external format such as CueLoop as design pressure. -- **Stabilizes:** D126-L's durable-scope/runtime-slice boundary while locating whether richer epistemic-horizon or decision-flow state earns representation. -- **Objective:** Model how Brunch projects committed scope packages through fog-of-war and non-structural sequential dependency, and whether extending the planning horizon or gaining parallelism needs additional durable truth. Do not reopen the settled `scope` kind or its execution-handoff contract. -- **Acceptance:** - - A plan projection is derived from committed graph truth (milestone/frontier/scope plus their intent/oracle/design anchors) and rendered thinly, reusing the `project` (D100-L) seam rather than a new graph-write path or exchange schema family. - - The projection is demonstrably *projection*, not free generation: it starts from accepted upstream anchors and never commits plan-plane graph truth itself (I51-L discipline). - - An external-format export (e.g. CueLoop) is proven as an optional downstream rendering of that projection, or explicitly rejected with a recorded reason — used only as design pressure, not as product architecture. - - Any richer horizon/decision-flow representation is justified by evidence from the settled D126-L scope consumer path; otherwise it remains process-only. -- **Traceability:** D126-L (settled scope handoff), D103-L (durable slice retirement), D100-L (`project` seam), D87-L (`unknown` = horizon on the intent plane), D99-L (advisory/settled); KA owns executor/orchestration consequences. SPEC §Future Direction "Planning persistence evolution". - - -### execution-comparison-tracer - -- **Name:** Greenfield execution comparison tracer -- **Linear:** [FE-1230](https://linear.app/hash/issue/FE-1230/greenfield-execution-comparison-tracer), child of [FE-1211](https://linear.app/hash/issue/FE-1211/brunch-testing-execution-side-evaluation-of-outputs). -- **Branch:** `ka/fe-1230-independent-oracle-journeys` (continuation off `next`; original implementation landed in #345). -- **Kind:** bounded evaluation tracer — frozen execution input, isolated adapters, controller-only oracles, and immutable evidence; no product operator command yet. -- **Certainty:** proving. -- **Status:** active; independent-journey implementation complete 2026-07-21. One clean Brunch run and one clean isolated Claude Code run used the frozen Petri-editor packet. Both passed their own tests/build and failed the original sequential accessibility oracle at different points; failed/invalid launches remain retained. `petri-editor-browser-v2` now runs all five claim-linked journeys from fresh contexts with public-only setup and per-journey evidence. Retained-pair replay/promotion is blocked only on restoring the exact immutable output paths. Mutants, masked/process judging, and repetitions are deferred. -- **Objective:** preserve claim-level mechanical evidence from the retained Brunch/Claude pair by removing sequential blocking from the controller-owned browser oracle. -- **Lights up:** frozen lane output → independently executable hidden browser/Petri journeys → complete claim-level verdicts despite earlier failures. -- **Stabilizes:** immutable attempt retention, journey identity and claim linkage, setup-vs-assertion failure semantics, and the no-landing boundary. -- **Acceptance:** preserve every v1 attempt byte-for-byte; build/test once, then run mount, node lifecycle, weighted behavior, invalid/cascade behavior, and persistence/round-trip from fresh browser contexts and public setup; retain a verdict for every journey even after another fails; replay one unchanged independent-journey oracle version against both retained outputs when their exact paths are restored; publish bounded findings only and no retrospective winner. -- **Verification:** inner — injected journey-runner scheduling, claim linkage, failure classification, and cleanup; middle — known-good slow browser run from five fresh contexts plus eventual retained-output replay; outer — retained attempt completeness and bounded report review only. -- **Cross-cutting obligations:** preserve FE-1210 failure-retention and reviewed-promotion discipline without mixing execution cases into the private elicitation-mission namespace; record exact provider/model/harness versions; never expose controller-only oracles to a lane; never invoke `/brunch:land`. -- **Explicitly out:** sensitivity mutants, masked/process judging, determinism repetitions, generalized campaign machinery, Pi Campaign Machine/Clay, brownfield Brunch/Petrinaut cases, automatic landing, Cursor/Codex lanes, production `/compare-execution`, and broad reliability/cost/speed claims. -- **Traceability:** D40-L, D120-L, I62-L; FE-1210/FE-1215 comparison evidence discipline; [`testing/execution-comparisons/cases/minimal-petri-net-editor/spec.md`](../testing/execution-comparisons/cases/minimal-petri-net-editor/spec.md); origin mission [`testing/comparisons/missions/minimal-petri-net-editor.md`](../testing/comparisons/missions/minimal-petri-net-editor.md); `docs/praxis/comparison-runs.md`; `src/executor/TOPOLOGY.md`. -- **Current execution pointer:** no active scope card. Retained-pair replay/promotion re-enters through `ln-scope` when the exact immutable attempt/output paths are restored. - -### end-to-end-comparison-tracer - -- **Name:** Trace elicitation through execution -- **Linear:** [FE-1239](https://linear.app/hash/issue/FE-1239/trace-elicitation-through-execution), child of [FE-1211](https://linear.app/hash/issue/FE-1211/brunch-testing-execution-side-evaluation-of-outputs). -- **Branch:** `ka/fe-1239-end-to-end-comparison-tracer`, restacked on `next` after FE-1230 landed. -- **Kind:** bounded staged 2×2 evaluation tracer — rigorous elicitation, immutable exact-spec handoff, isolated execution, common controller oracle, and requirement traceability; no product operator command or generalized campaign runner. -- **Certainty:** proving. -- **Status:** ✓ implementation and one-case witness complete 2026-07-21. Both exact handoffs and all four valid failed execution cells are retained; the common oracle, audience-safe ledger, and bounded report are promoted without a winner claim. -- **Objective:** determine whether differences between one Brunch-elicited and one Claude-elicited approved specification remain associated with requirement-level implementation outcomes when each exact specification is executed by both Brunch and Claude under the same frozen case, budgets, and oracle. -- **Lights up:** product-neutral mission + shared public baseline → two fresh valid elicitation artifacts → two immutable handoffs → four execution cells → unchanged independent browser journeys → validity-first requirement ledger. -- **Stabilizes:** exact elicitation-to-execution byte identity, study/matrix closure, shared-baseline versus controller-only requirement provenance, and FE-1232's end-to-end reporting input contract without widening FE-1230's immutable `ExecutionAttempt` schema. -- **Depends on:** FE-1210's rigorous fresh-actor recipe and FE-1230's execution artifacts/oracle contracts. FE-1230 retained-pair promotion is sibling evidence, not an input substitute; FE-1239 runs fresh outputs for both handoffs. -- **Acceptance:** freeze the study before provider work; disclose shared accessibility/interoperability requirements before elicitation; retain two valid target-authored specifications; reject any handoff drift, normalization, target-visible controller material, or target workspace that can reach the controller root; retain exactly four matrix cells referencing immutable execution attempts; run `petri-editor-browser-v2` unchanged against every output; close every predeclared requirement-ledger row with evidence or `not_assessable`; promote an operator/controller bundle plus audience-safe report with no winner or generalized causal claim. -- **Verification:** inner — runtime-boundary tests for study/handoff/matrix/ledger/redaction contracts; middle — known-good synthetic four-cell composition plus unchanged browser-oracle regression; outer — two fresh rigorous elicitation runs, four real execution runs, retained invalidity/cleanup review, requirement-ledger adjudication, and deliberate promotion. -- **Cross-cutting obligations:** missions and controller reveal material never enter execution lanes; shared public baseline rows cannot be credited as elicitation gains; failed/invalid attempts remain retained; common claims use only common evidence; Brunch stops at `promotion_prepared` and never invokes `/brunch:land`; comparison reporting consumes retained artifacts but does not own or mutate run conduct. -- **Explicitly out:** `/compare-specs` retrofit, production `/compare-execution` or `/compare-end-to-end`, automatic scoring/winner, reliability repetitions, mutants, multi-case generalization, Cursor/Codex lanes, host landing, and FE-1230 `ExecutionAttempt` schema changes. -- **Traceability:** D70-L fixture taxonomy; D134-L/I67-L comparison control topology and isolation; D40-L/D120-L/I62-L execution/no-landing boundaries; FE-1210/FE-1230/FE-1232; [`docs/praxis/comparison-runs.md`](../docs/praxis/comparison-runs.md); [`end-to-end-comparisons.md`](../.agents/skills/comparison-reporting/references/end-to-end-comparisons.md). -- **Retained witness:** [`.fixtures/runs/end-to-end-comparison/petri-editor-e2e-20260721T132600Z/`](../.fixtures/runs/end-to-end-comparison/petri-editor-e2e-20260721T132600Z/); completion evidence in [`memory/cards/end-to-end-comparison-tracer--factorial-matrix.md`](cards/end-to-end-comparison-tracer--factorial-matrix.md). - -### greenfield-secure-drop-demo - -- **Name:** Close the greenfield Secure Drop demo -- **Linear:** [FE-1289](https://linear.app/hash/issue/FE-1289/close-the-greenfield-secure-drop-demo) -- **Branch:** `ka/fe-1289-greenfield-secure-drop-demo` -- **Kind:** bounded product/evidence tracer over settled Specify, Execute, Petrinaut, landing, and comparison seams. -- **Certainty:** proving. -- **Objective:** prove one colleague-repeatable path from a product-neutral Secure Drop mission through real elicitation and accepted graph truth into an executable parallel plan, live Petrinaut-observed production execution, confirmed greenfield landing, and deterministic application V&V; fix only observed demo-critical failures. -- **Lights up:** mission → accepted spec graph → authored harness and committed scopes → synthesized parallel plan → production cook → live Petrinaut terminal state → landed verified application. -- **Stabilizes:** existing security representation through `constraint` / `invariant` / `criterion` / `vv_method` / `check` / `evidence`, without a new security kind or newly generated legacy `vv_obligation`. -- **Acceptance:** - - The settled graph states product intent and user flows, explicit threat/security constraints, executable criteria, frontend/backend boundaries, at least three scopes with at least two dependency-independent, and one deterministic authored execution harness. - - A fresh greenfield run uses production plan/cook paths, visibly streams Petrinaut state, reaches `promotion_prepared`, lands only through confirmed `/brunch:land`, and passes the mission-owned browser/API/SQLite/test/build checks without repository surgery. - - Two consecutive clean Brunch runs reproduce the result; one reviewed portable run retains graph, plan, Petri, terminal, application, blocker, and limitation evidence. - - A separate frozen diagonal pair runs Brunch own-spec→Brunch execution and Claude own-spec→Claude execution under matched public mission, reveal, budget, validity, and external-oracle rules; no factorial, winner, reliability, or landing claim. - - Every blocker is classified `demo-critical`, `acceptable demo limitation`, or `software-specific deferred work`; only the first class changes product code. -- **Verification:** inner — mission/case contract tests and focused regressions for observed blockers; middle — controller-owned browser/API/SQLite security oracle plus authored `npm test` and `npm run build`; outer — two clean product walkthroughs with Petrinaut and landing, then one retained paired comparison. Full local gate only when slow executor/landing/comparison seams change. -- **Excludes:** brownfield repositories, merge/dependency-reconciliation work, generic coding-agent parity, new graph kinds, production cryptographic certification, messaging/conversation/presence/notification behavior, and unrelated harness abstractions. -- **Current execution pointer:** `memory/cards/greenfield-secure-drop-demo--mission-and-witness.md`. -- **Traceability:** D120-L, D126-L, D127-L, D130-L; I58-L, I69-L; `src/executor/TOPOLOGY.md`, `src/rpc/TOPOLOGY.md`, `docs/praxis/comparison-runs.md`. - -### executor-slice-admission-parity - -- **Name:** Prevent invalid scoped slices from reaching execution -- **Linear:** [FE-1240](https://linear.app/hash/issue/FE-1240/prevent-invalid-scoped-slices-from-reaching-execution). -- **Branch:** `ka/fe-1240-slice-admission-parity`, restacked on `next` after FE-1239 landed. -- **Kind:** bounded bugfix — deterministic admission parity between model-authored candidate plans and the fail-closed worker-request boundary. -- **Certainty:** proving. -- **Status:** ✓ complete 2026-07-21; scoped from the retained FE-1239 witness, where both Brunch cells admitted plans whose first scoped slice carried no executable criterion and then halted with `plan_slice_invalid`. -- **Objective:** make candidate-plan admission reject every scoped slice that cannot produce complete worker-request context, feeding exact findings through the existing bounded repair loop instead of discovering the defect after a run starts. -- **Stabilizes:** D126-L committed-scope/runtime-slice handoff, deterministic planner admission, and `slice_execute`'s zero-side-effect corruption guard. -- **Depends on:** the settled FE-1197 synthesis/validation seam and D126-L plan-ready scope contract; no SPEC revision or execution-time plan repair. -- **Acceptance:** validation rejects scoped slices missing executable criteria, design context, or verification-machinery context even when aggregate scope coverage is complete; exact findings reach bounded repair; an admitted repaired plan survives preview serialization and worker-request parsing for every slice; externally supplied malformed populated plans remain fail-closed at `slice_execute`. -- **Verification:** inner — candidate-validation and repair-loop regressions; middle — plan synthesis → preview payload → worker-request-context parity; outer — owned by a separately authorized rerun of the frozen end-to-end comparison after this fix lands. -- **Current execution pointer:** none; the single scope card is consumed. - -### executor-plan-coherence - -- **Name:** Build coherent execution plans -- **Linear:** [FE-1250](https://linear.app/hash/issue/FE-1250/build-coherent-execution-plans). -- **Branch:** `ka/fe-1250-coherent-execution-plans`, based on `next`. -- **Kind:** bounded proving frontier — planner conduct and deterministic plan-shape admission over settled D126-L/D130-L and FE-1195 executor seams. -- **Certainty:** proving. -- **Status:** implementation complete 2026-07-24, including I69-L worker-contract carry; the explicitly authorized unchanged frozen Petri rerun remains outer evidence and is not a merge gate. -- **Objective:** make integration-sensitive multi-slice plans converge on one working result without adding a browser-specific executor gate or a new durable planning concept. -- **Lights up:** committed scope context → dependency-aware candidate plan → ordinary terminal reconciliation slice → canonical slice verification → existing fan-in and epic verification. -- **Stabilizes:** the model-planner/admission seam between FE-1240's complete worker context and FE-1195's integrated executor worktree. -- **Depends on:** FE-1240 candidate-admission parity and the landed FE-1195 slice integration/epic verification topology; FE-1230/FE-1239 provide evaluation evidence only, not target-visible oracle material. -- **Acceptance:** an integration-sensitive multi-slice fixture produces an explicit shared foundation, dependency ordering, and one ordinary terminal slice that transitively depends on its sibling implementation work and carries exact cumulative approved requirement content plus the relevant criterion, design, verification, and target-visible packet anchors; workers are told to preserve prior public-contract behavior and use the canonical authored harness cumulatively; the admitted plan lowers unchanged through preview and worker-request parsing; existing slice integration and epic verification execute the shape without a new transition or lifecycle phase; non-integrating plans are not forced to acquire ceremonial closure work. -- **Verification:** inner — planner prompt/candidate-validation plus I69-L exact requirement-carry differentials that reject ids-only, paraphrase-loss, wrong-link, malformed/duplicate context, hash-divergent packet, symlink destination, and hidden-oracle rivals; middle — synthesis → preview → request → rendered sealed-worker brief plus cumulative terminal-slice integration and serial/parallel artifact parity through the existing epic harness; outer — one explicitly authorized rerun of the frozen Petri comparison unchanged, retaining its controller-owned browser oracle outside execution and outside the merge gate. See SPEC §Verification Design “I69-L worker-contract-carry”. -- **Boundary:** no hidden-oracle exposure, inferred browser command, new plan-plane node, candidate command surface, execution-time plan repair, or FE-1241 comparison-framework change. -- **Current execution pointer:** none; the worker-contract-carry card is implemented. Re-enter only for an explicitly authorized unchanged frozen Petri comparison rerun. - -### prospect-research-workspace-regression - -- **Name:** Thin prospect research into a regression case -- **Linear / branch:** [FE-1253](https://linear.app/hash/issue/FE-1253/thin-prospect-research-into-a-regression-case); `ka/fe-1253-prospect-research-e2e`, stacked on FE-1241 with no parent issue. -- **Kind:** earned evaluation simplification — retain a deterministic full-stack regression oracle and retire unproven campaign expansion. -- **Certainty:** earned. -- **Status:** active 2026-07-23. The mission, public packet, opaque Brunch seed, closed compiled oracle, known-good full stack, and focused rivals remain. The prospect-specific end-to-end study profile and provider campaign gate are being retired before any scored lane exists. -- **Objective:** provide one deterministic implementation-level acceptance case for the prospect research workflow without making ordinary regression value depend on a rigorous 2×2 campaign. -- **Closes:** the accidental coupling between a useful full-stack oracle and an unexecuted prospect-specific campaign. -- **Deletes / retires:** the prospect end-to-end study contract, shared baseline, reveal registry, matrix registration, requirement-ledger obligation, scored-provider gate, and campaign claims. -- **Stabilizes:** the fixed React + Node.js + TypeScript + SQLite public packet; `npm test` / `npm run build` / `npm start`; fresh database and fixture isolation; runtime-network denial; independent browser/API/SQLite/export journeys; focused rivals; and opaque specification seeding. -- **Depends on:** FE-1241 for the finalized execution-case registry and oracle dispatch only. No provider or strict greenfield Claude-isolation witness blocks completion. -- **Boundary:** manually initiated prospect research, evidence-backed qualification, deduplication/provenance, suppression, review, audited override, approval, export, provider failure, and restart persistence are in. Outreach delivery, live Pi/Clay quality, campaign composition, scored provider lanes, reliability claims, and `ExecutionAttempt` widening are out. -- **Acceptance:** the known-good full stack passes; focused rivals for unapproved research, confidence-only qualification, lost provenance, weak suppression, reasonless/destructive override, overbroad export, provider-failure laundering, non-durable state, and external runtime requests fail their owning claims; the prospect case is absent from end-to-end study registration; existing Petri and brownfield study bytes/oracles remain unchanged. -- **Verification:** inner — exact public/oracle parsers, oracle-pack hash, claim coverage, and opaque Brunch seed. Middle — independent browser + API + SQLite journeys over fresh database/fixture state, paired with the controller reference model and focused rivals. No outer campaign evidence is required. -- **Cross-cutting obligations:** controller fixtures and expected states remain outside targets; runtime network stays denied; compiled oracle dispatch remains fail-closed; historical comparison evidence remains unchanged. -- **Traceability:** D70-L, D139-L; FE-1230/FE-1241; [`docs/praxis/comparison-runs.md`](../docs/praxis/comparison-runs.md). -- **Current execution pointer:** thin the materialized branch to this regression boundary, then close through deterministic verification. - -### executor-slice-verification-repair - -- **Name:** Finite slice verification repair ladder -- **Linear:** [FE-1254](https://linear.app/hash/issue/FE-1254/repair-failed-slice-verification-before-halting). -- **Branch:** `ka/fe-1254-slice-verification-repair`. -- **Kind:** bounded executor proving frontier over D112-L/D127-L/D128-L/D130-L and I58-L. -- **Certainty:** proving. -- **Status:** implementation complete 2026-07-23; the full suite, repository checks, and build pass. The unchanged Petri comparison rerun remains as owned outer evidence. -- **Objective:** let a completed failed slice-verification verdict re-dispatch the same stable-workspace worker through a structurally finite, cycle-qualified repair ladder without conflating runner retries, replay authority, or frozen command authority. -- **Acceptance:** three total repair cycles and three runner attempts per stage are independent policy dimensions; history is grouped and strictly validated by cycle; context bytes are canonical, bounded, atomically materialized, and provenance-checked; serial pending state recovers without verifier replay or duplicate effects; parallel pending state is durable in D127-L marking authority before materialization and fails closed on restart; only a cycle-qualified pass integrates; active RPC surfaces expose cycle/phase without diagnostics or premature failure. -- **Boundary:** no generic event store, compatibility adapter for `sliceAttemptHistory`, browser/controller oracle, inferred command authority, duplicate worker/verifier effect, or host mutation. -- **Verification:** focused FE-1254 suites pass with 404 tests and 0 skipped; the full suite passes with 2664 tests and 2 pre-existing skips; `npm run check` and `npm run build` pass. Coverage includes parent-chain directory fsync and restart, production persistence boundaries, direct durable parallel-pending restart, explicit `marking.json` reads, grouped/active-authority corruption, app payload/path rejection, live observer/RPC repair phases, cycle-2 runner retry, and real-adapter multi-repair result binding. -- **Current execution pointer:** none; the finite-ladder scope is consumed. Re-enter only for the unchanged frozen Petri comparison rerun. - -### comparison-reporting-skills - -- **Name:** Report comparison evidence -- **Linear:** [FE-1232](https://linear.app/hash/issue/FE-1232/report-comparison-evidence). -- **Branch:** `ka/fe-1232-comparison-reporting-skills`, restacked on `next` after FE-1230 landed. -- **Kind:** project workflow tooling — reusable Notion publication plus comparison-study design and evidence interpretation; no product runtime or automatic adjudicator. -- **Certainty:** proving. -- **Status:** ✓ implementation complete 2026-07-20, extended and review-hardened 2026-07-21. The two skills, evaluation/end-to-end references, and dependency-free contract/link check are built; the restacked PR's full CI gate passes. -- **Objective:** give project agents one safe, discoverable reporting path that turns ordinary evidence into verified Notion reports and turns elicitation, execution, or end-to-end comparison artifacts into validity-aware, redaction-safe findings under a frozen test strategy without inventing a winner. -- **Lights up:** source evidence → comparison classification and report structure → smallest safe Notion mutation → post-write verification. -- **Stabilizes:** overview/problem/result grammar; fetch-before-edit and verify-after-edit discipline; active-command precedence over post-run interpretation; implementation/runtime/protocol/validity taxonomy; private/public/masked/unblinded/controller-only boundaries; audience-shaped hidden-requirement rows; frozen test axes, rubric, judge protocol, and 3/5-run prototype repeat contract; procedure-vs-output determinism; requirement-level elicitation-to-implementation traceability; invalid-attempt retention. -- **Acceptance:** two project-shared skills remain separately invocable but composable; the general Notion writer does not acquire comparison semantics; an active complete operating procedure such as `/compare-specs` cannot be retrofitted with campaign machinery; the comparison reporter covers FE-1210/FE-1215 elicitation evidence, FE-1230 execution packets, the test-plan axes and judging protocol, bounded repeated-run determinism, and audience-safe end-to-end traceability; static checks pin safety-critical phrases and resolve every relative Markdown link; no reporting-related verification failure is introduced. -- **Boundary:** in — `.agents/skills/notion-reporting`, `.agents/skills/comparison-reporting`, their direct references, and a dependency-free consistency check. Out — Notion API wrappers, automatic report publication, new comparison runners, oracle execution, automatic scoring/adjudication, or changes to FE-1230 attempt schemas. -- **Dependencies:** builds on FE-1230's execution artifact/redaction contracts and FE-1210/FE-1215's elicitation evidence discipline; may stack before FE-1230 lands but must not weaken or duplicate its controller-only boundary. -- **Verification:** structural skill-contract plus recursive relative-link check chained into `npm run check:skills`; Markdown links and promoted-run paths; tracked-file lint/format; default tests and build; authoritative full CI gate. -- **Traceability:** FE-1210/FE-1215; `agent-as-user-comparison`; `docs/praxis/comparison-runs.md`; FE-1230 `ExecutionAttempt`, masked outcome, and unblinded process packets. - -### comparison-publication-workflow - -- **Name:** Publish comparison reports with immutable provenance -- **Linear / branch:** [FE-1251](https://linear.app/hash/issue/FE-1251/publish-traceable-comparison-reports); `ka/fe-1251-comparison-publication`, stacked on FE-1250. -- **Kind:** project workflow tooling — write-once run-start provenance plus explicitly invoked, verified Notion publication; no product runtime mutation or autonomous experiment conduct. -- **Certainty:** proving. -- **Status:** active 2026-07-22. -- **Objective:** make retained comparison reports reproducibly attributable to the tested Brunch release and controller checkout, then publish each `Run ID + Phase` exactly once into the canonical Comparison Reports database with safe update semantics. -- **Acceptance:** elicitation, execution, and end-to-end flows capture a schema-versioned `provenance.json` before their first lane and reject collisions or malformed inputs; `/comparison-publish ` requires retained provenance and report evidence, applies validity-first interpretation and controller-only redaction, creates or updates exactly one matching database row, stops on duplicates, and verifies every mutation by re-query and fetch; Release and Commit are filterable Notion properties and remain absent on historical rows without exact retained evidence. -- **Boundary:** in — dev-only provenance contract/CLI, comparison prompts and run documentation, project-local publication skill, reporting-skill guardrails, and the live Testing Scenarios schema/legend. Out — product runtime publication, inferred historical provenance, automatic scoring, unsupervised experiment conduct, or changes to comparison artifact contracts. -- **Dependencies:** operationally stacked after FE-1250; builds on FE-1232 reporting and Notion safety contracts plus retained comparison artifacts established by FE-1210/FE-1230/FE-1239. -- **Verification:** focused provenance tests; reporting skill checks; default verify gate; disposable create-then-update publication exercise plus duplicate detection; final Notion schema, row, and legend readback. - -### executor-plan-synthesis - -- **Name:** Synthesize and validate executor plans from approved scopes -- **Linear:** [FE-1197](https://linear.app/hash/issue/FE-1197/synthesize-and-validate-executor-plans-from-approved-scopes) -- **Branch:** `ka/fe-1197-executor-plan-synthesis` (stacked on `ka/fe-1195-petri-execution-parity`, PR #325) -- **Kind:** structural — a new planning/admission seam between committed scope truth (D126-L) and the frozen-plan Petri pipeline (PR #325). -- **Stream:** KA (Kostandin). -- **Certainty:** proving. -- **Shape (settled at admission — the one-vs-two-frontier question):** one coherent vertical frontier with three slices on one branch. The load-bearing belief — approved scope truth can be lowered through a model-authored, deterministically admitted plan into PR #325 execution such that a run can no longer contradict approved commitments — is falsified only by the combined witness (approved scope → synthesized plan → admitted contract → PR #325 run → conforming promotion). The plan contract (slice A) is proven right only when a synthesized plan flows through it; splitting would stack an unproven contract under a planner branch that must reshape it. Escape hatch: if the branch grows unreviewably broad, re-run `ln-plan` and split at the contract+profile-admission / synthesis+repair boundary, preserving that order. -- **Why now / unlocks:** the witnessed greenfield failure (wrong-stack implementation reaching `promotion_prepared` under a self-selected `npm_test` profile) proved the admission boundary is broken exactly when its two neighbors finished: FE-1173/1175/1179 delivered committed-scope handoff above, FE-1195 delivered execution semantics below; planning is the missing middle. Unlocks: run creation that cannot contradict approved truth; non-trivial decomposition (multiple slices per scope, meaningful epics) that finally exercises PR #325's parallel/fan-in/epic semantics. -- **Ownership model (deterministic boundaries around a non-deterministic core):** elicitation decides commitments (stack, framework, package manager, deployment, quality obligations) and authors argv-only `execute.*` recipes; repository detection reports evidence and never authorizes commands or overrides approved commitments; the planner synthesizes and lowers; deterministic validation judges; bounded repair corrects or rejects with exact findings; the executor enforces only the admitted frozen plan. There is no built-in ecosystem catalogue or ambient/default command provider: the sole production provider is derived from spec-authored recipes, and absent, malformed, or contradictory authored execution intent blocks rather than silently substituting an inferred/default harness. -- **Slices (same issue + branch; scope via `ln-scope`):** - - **A — planning projection + execution contract:** bounded provenance-preserving planning projection (committed frontier/scope identity, linked requirements + criteria, requirement dependencies, technical-design nodes, relevant decisions/constraints incl. implementation-stack/environment/delivery commitments, verification obligations, greenfield/brownfield mode, detected repository facts) — today the snapshot's `context` block (decisions/constraints/design/oracle) is projected then dropped by the outline; typed candidate/admitted plan contract (plan + source provenance, executable epics with integration boundaries, one-or-more slices per scope, explicit deps/ordering, worker goals + done criteria, epic verification intent, plan-owned execution contract distinguishing requiredCapabilities / detectedCapabilities / resolvedActions); command safety through typed product-owned capability providers and action resolvers (model selects/composes supported intents; deterministic code resolves what may run; unknown capabilities produce actionable blocks, never guessed commands; per-scope/per-epic capability sets for polyglot workspaces); remove or constrain the foreground `verifyProfile` enum (`execute-run-create`'s `default|npm_test` + `executor.md` prose heuristic + `test-runner-port.ts` hardcoded `npm run verify` fallback) so run creation consumes admitted plan truth only. - - **B — LLM plan synthesis, deterministic validation, bounded repair:** planner behind a sealed app/agent port (`PlannerPort` in `ExecutionPorts`, mirroring `AgentRunnerPort`'s untyped-runtime pattern; implementation over the sealed subagent substrate in `src/app/`; no model SDKs, graph mutation, or unrestricted subprocess in `src/executor/` — `boundaries.test.ts` enforced); synthesizes meaningful epics/slices/dependencies/worker briefs/verification gates; total pure validation (every slice in exactly one epic + one committed scope; scope-obligation coverage; acyclic valid-id deps; ordering compatibility; criteria/verification preservation; design/decision/constraint provenance retention; capability/action compatibility with approved commitments and detected facts; polyglot boundary correctness; PR-#325-executable epic gates; no gate bypass; unsafe command/profile rejection; malformed output fails closed); bounded repair fed exact findings, then revalidate; admit or block with persisted findings/repair history — no silent trivial-plan fallback (an explicit deterministic fallback is admissible only if contract-stated and obligation-preserving). - - **C — PR #325 composition witness:** one admitted synthesized plan through the frozen topology — overlapping dependency-independent isolated slices, ordered fan-in, planner-driven epic verification, failed slice/epic verification blocking completion/promotion, promoted output conforming to approved implementation/execution commitments; one live Specify → committed scope → synthesized/admitted plan → PR #325 execution → promotion witness recorded with graph/plan/brief/verification/run evidence. -- **Verification:** nine contrastive oracles fixed at admission — (1) greenfield capability derivation from approved truth with contradictory-profile rejection before worker launch; (2) a second materially different elicited capability set resolving a different provider/action set without schema change and without ambient-default leakage; (3) brownfield agreement reusing detected workspace/package-manager/test-runner conventions; (4) brownfield conflict blocking actionably with neither side silently overridden; (5) polyglot/multi-package resolution at the correct scope/epic boundary with explicit shared integration verification; (6) context preservation — a rival implementation that drops an elicited stack commitment or assurance node must fail; (7) invalid model plans (dependency cycles, missing scope coverage, invalid ids, incompatible profile) rejected by the validator, then boundedly repaired or explicitly blocked; (8) PR #325 execution of a valid plan exercising parallel isolation, ordered fan-in, epic gating; (9) the live composition witness. Deterministic tests first; fixture-backed or live witness for composition. -- **Prior art (selective port only — old `main` `src/orchestrator/src/plan-{projection,architect,contract,emitter,reconciliation}.ts`, `project-profile.ts`):** port `checkPlan`'s total/pure producer-agnostic predicate with typed severity findings; the single shared cycle policy between detection and repair; the mechanical-class vs design-class repair split (never auto-rewrite ownership/decomposition); coverage-by-provenance (requirementIds/covered/nonBuildable); typed repair/warning records; loud detection failure. Repudiate: the silent trivial-plan fallback (incl. the vacuous-coverage all-non-buildable empty plan); the absent LLM repair loop; the closed six-ecosystem `ProfileId` catalogue as planning truth; absent-profile → bun defaulting; file-write conflicts as shippable warnings; criteria stringified into prose; discarded `derivedFrom` provenance; dual reconcile/repair transformers. -- **Explicitly out:** external Petrinaut HTTP interop beyond the existing observer/live-stream contract; split-process execution authority; richer browser authoring or side chats; post-execution semantic spec-to-code drift detection; generic human halt/replan/resume UX; reimplementing PR #325 isolation/concurrency/fan-in/attempt-authority/epic-lifecycle semantics (the planner targets them, never re-owns them). The executor/Pi integration follow-up renamed the machine-owned plan artifact to `plan.json` and added the durable `brunch/review/` promotion ref without changing explicit host-apply acceptance. -- **Slice A landed (2026-07-13, D130-L; author-first correction 2026-07-14):** the plan artifact carries the typed execution contract (planning projection incl. constraint/invariant/decision commitments; recipe-resolved actions; evidence-only detected facts; blocked/conflict findings), `execute_plan_file` rejects absent or malformed authored verification before writing, and `execute_run_create` admits or rejects the frozen contract before any run artifact. The npm built-in/default and test-runner command-specific handling are removed. -- **Slice B landed (2026-07-13):** model-authored `CandidatePlan` (schema with no command surface), fail-closed parse, total pure validation (membership, scope-obligation coverage, provenance retention, shared-cycle-policy dependency checks, capability support/conflict), executor-owned bounded repair loop with findings history and no fallback plan on any path, `PlannerPort` over the sealed planner subagent, and `execute_plan_file` synthesis with explicit labeled planner-unavailable fallback (invalid candidates always block). Commits `ce93d8b2`/`b54c4321`. -- **Slice C fixture witness landed (2026-07-13; model-seam strengthening 2026-07-14):** `plan-synthesis-composition.test.ts` drives an admitted synthesized plan through the frozen topology under `petriScheduler` + `frontierFiringPolicy` — the real sealed `PlannerPort` adapter receives Pi model context and a scripted planner response, then overlapping dependency-independent isolated slices (barrier witness), ordered fan-in, epic integration/verification, promotion preparation, contract-only verify commands on every slice/epic invocation, and the failed-verification gate (oracle 8). This is deterministic model-seam coverage, not the still-open live-provider witness. -- **Spec-commanded recipe (2026-07-14):** the elicitor captures the canonical settled `oracle/vv_method` `Project execution harness` with `execute.setup|build|verify: ` lines; a generic extractor turns authored recipe commitments into the sole production recipe provider plus spec-mandated base requirements the planner cannot drop (argv-only, shell operators fail closed as `malformed_recipe`). Workspace detection remains provenance-only. The planner subagent registry omission that blocked the first live witness is fixed. -- **Live walkthrough (2026-07-14, rust-todo-cli workbench):** a five-run arc reached the first fully green pass — synthesized plan (3 epics / 4 slices) → real workers → spec-commanded `cargo test -- --test-threads=1` green at every slice gate → ordered integration → `promotion_prepared` (`run-mrkko0ld`), with every failure fixed in the spec (recipe added, `--test-threads=1`, dependency edges, `.gitignore` requirement) and recompiled. The two planner-loop blocks it exposed are fixed deterministically: verification citations are legal and lowerable from the projection-visible set (scope anchors ∪ V&V commitments), and blank `scopeId` normalizes to no-scope. Runtime defects moved to the executor/Pi integration follow-up. -- **Planner hardening (2026-07-16):** the Rust Todo CLI silent malformed-candidate witness now has a schema-backed, exactly-once `submit_candidate_plan` child-session output contract instead of outermost-JSON text recovery; every planner round emits lifecycle-only foreground progress and has a 120-second aborting deadline that blocks as `planner_timeout` without starting another round. The packaged runtime now includes `planner.md`. -- **Open acceptance:** oracle 9's tail — the walkthrough stopped at `promotion_prepared` because host promotion carries no source for an `empty_dir` run on a non-git host (the fix is owned by `host-landing`/FE-1201 since 2026-07-14; the conforming-promotion witness stays owned here) — plus a live run through the committed-scope path (the walkthrough spec lowered from bare requirements) and live-capability oracles 1–5 on real elicited specs; requires a model-backed session per `docs/praxis/manual-testing.md`. Re-entry trigger: next live FE-1197 walkthrough. All scope files consumed. -- **Traceability:** D126-L (scope = elicitation-owned committed handoff; executor lowers only committed scopes), D111-L/D112-L/I58-L (executor purity over injected ports), D127-L/D128-L/D129-L (FE-1195 authority + canonical execution model), D103-L (runtime slice stays executor-derived), D98-L (executor owns execution/scope concerns); FE-1166 card residue + run `run-mrbyf8u9`; the 2026-07-13 wrong-stack greenfield run; `src/executor/TOPOLOGY.md`; old-`main` planner modules as named prior art. - -### host-landing - -- **Name:** Mode-aware host landing of promoted runs -- **Linear:** [FE-1201](https://linear.app/hash/issue/FE-1201/mode-aware-host-landing-of-promoted-runs) -- **Kind:** structural — replaces the host-promotion lifecycle seam and its port/tool surface -- **Certainty:** proving -- **Status:** branch-complete (code) — tracer + full cutover landed 2026-07-14 (`448f0f56` on `ka/fe-1201-host-landing`): durable `runBaseSha` recorded for both substrates, `promotion.ts` promotes against it (clean integrated runs promote; `promotionBaseSha` deleted), slice-integration/promotion commits exclude `.brunch`, and `GitHostLandPort` (`inspect`/`integrate`/`materialize`, adapter `src/app/git-host-land-port.ts`) passes the multi-commit contrastive oracle in both modes. Slice 2 (cutover, four cards, `19c575e4`..`273ca5e8`) landed the same day: `landing.ts` preflight/apply + terminal `landed` lifecycle; `/brunch:land` (preflight → read-only full-range/target/conflict inspection → `ctx.ui.confirm` → apply) as the sole host-mutation path with read-only `execute_land_preflight`; deletion of `host-promotion.ts`, `git-host-promotion-port.ts`, both `execute_host_promotion_*` tools, and `acceptedCommitSha`; mode-derived substrate (tool inputs deleted); `GitLandPort` → `GitRunPromotionPort`. Claims 1–2 witnessed by the contrastive oracle; claim 3's wiring half witnessed by stubbed-ctx command tests. Review hardening landed 2026-07-15 (consumed scope card `host-landing--review-hardening`): failed materialization restores the verified-empty target so retries land; host git failures classify as `failed`, not refusals; landed-lifecycle oracles added (including a fix — re-driving a landed run now reports `runStatus: 'landed'` instead of the journal-frozen `promotion_prepared`); promotion-report field `land` → `promotion`; `/brunch:land` notices carry command copy without the tool label; confirmation now names the complete commit/file range, target classification, and read-only conflict rehearsal. SPEC reconciled 2026-07-15 (`ln-sync`): I58-L/D111-L rewired to the landing seam, `Run promotion`/`Landing (host)` lexicon pins added, ln-design claims 1–2 validated-and-embedded, claim 3 recorded as A42-L. **Open before done:** the live TUI+RPC `/brunch:land` walkthrough beat (FE-1197 oracle 9 tail — re-entry: next live walkthrough; also A42-L's live half). -- **Objective:** Replace patch-apply host promotion with mode-aware landing per the 2026-07-14 `ln-design` synthesis. New `GitHostLandPort` (`src/app/git-host-land-port.ts`): `inspect` (read-only full-range `runBaseSha..reviewSha` commit/file evidence, target classification, merge-tree conflict rehearsal), `integrate` (brownfield: verbatim ff/merge of `brunch/review/` into a clean attached host branch; conflicts abort back to a pristine host; refuse staged/tracked-dirty, untracked coexist unless colliding), `materialize` (greenfield: tip tree → `git init -b main` + one clean brunch-authored initial commit into a missing or empty target; occupied targets refuse). Materializing into an existing repository is deliberately outside this frontier rather than an implied second mode. `src/executor/landing.ts` replaces `host-promotion.ts` with a pure strategy-selection core plus preflight/apply under run-execution authority. Durable `runBaseSha` recorded at worktree creation; `promotion.ts` promotes against it (clean integrated runs promote; `promotionBaseSha` deleted). `mode` becomes the sole authority; `substrate` is a derived record; the independent tool inputs die. Acceptance moves to a product-owned `/brunch:land` command (preflight → inspect → `ctx.ui.confirm` → apply in one invocation, handler-constructed bindings, drift refusal + git CAS); `execute_host_promotion_*` and `acceptedCommitSha` are deleted. Commit-time hygiene `git add -A -- . ':(exclude).brunch'` on slice-integration and promotion commits. Rename `GitLandPort` → `GitRunPromotionPort` (lexicon: "land" = host landing only). -- **Why now / unlocks:** the 2026-07-14 review proved a clean integrated run can land nothing while passing every test (the fixture had one commit above base — the missing multi-commit contrastive oracle). Unlocks FE-1197 oracle 9's conforming-promotion witness, truthful landing in both modes, and retirement of the agent SHA-echo acceptance channel. -- **Posture annotations:** - - Lights up: the first true run→host landing path (review ref → host branch merge / materialized repository) in both modes. - - Stabilizes: the landing seam (`GitHostLandPort` + `landing.ts`) that promotion UX and future remote/PR targets aim from; I58-L's host-mutation clause. - - Retires: the three `ln-design` load-bearing claims — recorded 2026-07-15: (1) transport-free brownfield landing and (2) `runBaseSha..reviewSha` completeness validated by the contrastive oracle and embedded (D111-L, I58-L, `src/app/TOPOLOGY.md`); (3) Pi-confirm sole acceptance authority is SPEC A42-L, partially validated — its live half rides the walkthrough beat. -- **Acceptance:** a real multi-commit integrated run (≥2 slice-integration commits + optional final promotion commit) lands completely: brownfield host branch ff/merged with every slice's source, no `.brunch/**`, review ref intact, conflict variant leaves the host byte-identical; greenfield missing/empty target becomes a repository on `main` with one clean initial commit of the full tree; the confirmation shows complete range, target, and conflict-rehearsal evidence; host mutation is reachable only through `/brunch:land` confirmation; patch apply, `execute_host_promotion_*`, and the independent substrate input no longer exist. -- **Verification:** inner — the multi-commit contrastive oracle (real git; reddens the old `commitSha^` semantics by construction), read-only inspection/merge-tree tests, and pure strategy-selection unit tests; middle — executor lifecycle suites stay green (I58-L side-effect honesty: metadata unadvanced on refusal/conflict/failure) and command tests prove inspection precedes confirmation; outer — rust-todo-cli walkthrough tail past `promotion_prepared` into a fresh target (initial-release oracle 9). -- **Cross-cutting obligations:** discharged 2026-07-15 — I58-L host-mutation wording and D111-L port list amended, `src/executor/TOPOLOGY.md` reconciled at the cutover, ln-design claims recorded (A42-L + embedded claims 1–2), `HANDOFF.md` retired. Follow-up (not this frontier): source-copy one-authority fix — commit copied host source at `source_copied` so slices and the landing range share one baseline (2026-07-14 review finding 4's remainder; also listed in FE-1199's open residue as integration-worktree contamination). -- **Explicitly out:** materialization into an existing repository, squash/graft landing knobs (ceiling-marked), remote/PR targets, durable cross-session acceptance tokens, in-run remediation UX. -- **Traceability:** D111-L/I58-L (ports + explicit acceptance), D112-L (host landing stays outside the driven chain), FE-1197 oracle 9, FE-1199 residue transfer; prior art `main:src/orchestrator/src/promote-run.ts` (`promoteGreenfieldRun`/`landCookBranch`). -- **Design docs:** the 2026-07-14 `ln-design` four-design comparison (session record); the prior volatile `HANDOFF.md` was retired 2026-07-15 (`ln-sync`). -- **Current execution pointer:** none — both scope files consumed. Remaining work is the owned outer walkthrough beat and `ln-sync` reconciliation named in Status. - -### automated-alpha-publishing - -- **Name:** Automatic npm alpha publishing through reviewed release PRs -- **Linear:** [FE-1050](https://linear.app/hash/issue/FE-1050/set-up-automatic-npm-publishing-for-brunch-using-changesets) -- **Branch:** `ka/fe-1050-automatic-npm-publishing`, based on `next` -- **Kind:** release hardening over the proven single-package publish seam -- **Certainty:** earned -- **Status:** branch implementation complete and npm trusted publishing configured. PR #344 is stacked on the test-fixture repair in PR #347; merge the parent, restack this branch onto `next`, and re-confirm mergeability before landing. This infrastructure PR carries an empty Changeset and does not bump or publish the package. Its merge exercises Vault/App authentication before Changesets exits through its empty-intent path; the first subsequent package Changeset owns the reviewed version PR and full `1.0.0-alpha.6` publish canary. -- **Objective:** make one Changesets-owned `next` path carry release intent through a reviewed version PR into `@hashintel/brunch@alpha`, a protected Git tag, generated changelog, and GitHub Release, while retaining the installed-artifact/SQLite release-pack smoke. -- **Closes:** manual local npm authentication, hand-authored version commits/tags, and the split between an npm publish and absent GitHub release notes. -- **Locks in:** every ordinary pull request into `next` contributes either a releasing Changeset or an explicit empty Changeset, while the generated version PR is exempt; merging that version PR is the release approval; the publish command rejects local, wrong-repository, wrong-branch, and non-OIDC environments before doing release work; the accepted run uses npm OIDC, runs `check:release-pack` before `changeset publish`, advances only the npm `alpha` dist-tag, and creates source-linked provenance plus release artifacts from the same commit. -- **Acceptance:** Changesets remains in `alpha` prerelease mode from `1.0.0-alpha.5`; this infrastructure PR records explicit non-release intent without changing the package version; CI enforces explicit Changeset intent on ordinary `next` pull requests; the release workflow triggers only on `next`; a repository-scoped HASH worker token makes release PRs trigger normal CI and permits protected tag creation; protected-tag failure stops the release before GitHub can synthesize a tag from `main`; the first subsequent releasing Changeset publishes exactly `1.0.0-alpha.6`, leaves `latest` at `0.8.0`, and produces its changelog, native single-package `v1.0.0-alpha.6` tag, GitHub Release, and npm provenance. -- **Verification:** Changesets status reports no package bump for this PR; release-workflow contract tests and actionlint accept both workflows; `npm run check:release-pack`, `npm run check`, and `npm run build` pass locally; the parent repair and PR Full gate return green before merge; the empty-intent run authenticates through Vault/App and creates no version PR or publish; the first subsequent App-created version PR receives Test/Preflight, then its merge runs the release-pack smoke and npm/tag/release/install checks witness the canary. -- **Boundary:** `main` remains the stable `latest` channel. Stable automation, prerelease exit, and post-1.0 re-entry of `next` are a separate promotion frontier rather than a second path in this branch. +- **Acceptance:** one canonical `capture-ledger-v1` pack lives in `ingest`; a dev/eval-only control/treatment seam changes only capture-ledger conduct; one frozen accepted-digest mission contains atomic material across all four concern groups plus cross-group relations and decoys; matched retained runs use the same model/source/graph seed/budgets/actor policy/validity rules; the predeclared verdict records positive, negative, and invalid evidence without post-hoc rubric changes. +- **Verification:** inner prompt/resource composition, stable intervention identity, contamination negatives, graph legality, settlement/routing, and packet-schema tests; middle deterministic replay plus matched real-provider actor runs; outer criterion-level human adjudication of masked outcome and unblinded conduct drafts before promotion. +- **Traceability:** D99-L, D131-L, A22-L, A34-L, A40-L; FE-1210 split-judgment evidence architecture. ## Dependencies ```text -streams: - LN — product/elicitation surfaces - KA — Kostandin: executor / orchestrator / Execute mode / plan plane - -group-1 (Active — walkthrough closure): - walkthrough-remediation-2 (FE-1187, absorbs closed FE-1167) - entry: settled D113-L–D115-L reversal (ln-spec first; folds Pi-native P4) - rows: WR18 punch list + absorbed LN evidence beats + exchange-visual-design - + generative-flow-synthesis-shape + sweep-debt-tripwire - -[stack]-> cli-mode-entry (reserves `develop` subcommand) - cross_stream: O7/O8/O9 + carved Execute beats — coordinate with KA - closes_arc: deterministic-orientation (jointly with KA-carved beats) - status: D98/D109 carriers, terminal-adaptive shell, deterministic menus, full Ask - matrix, KA handoff, D119 lexical closure, R6 rail/presentation corrections, - and R12 disposition built; mixed-settlement review + populated-only ledger built; - paused after remediation-4; explicit re-entry resumes extractor/oracle reconciliation, - then the fresh R8–R10 0/3 campaign, A48-L, and the outer walkthrough - -# FE-1196 Group 2 closed 2026-07-14; durable state is in SPEC/topology and -# docs/archive/PLAN_HISTORY.md. Conditional web-driver residue remains in group-4. - -shared-session-host-convergence (Next — architecture replacement): +active: + walkthrough-remediation-2 (FE-1187) + closes_arc: deterministic-orientation + blocked_reentry: extractor/oracle reconciliation -> fresh R8–R10 0/3 campaign -> A48-L -> consolidated outer checkpoint + cross_stream: O7/O8/O9 + carved Execute beats stay KA-owned + -[stack]-> cli-mode-entry + +next: + saved-mission-comparison-witness + gated_by: operator availability + depends_on: landed FE-1215 workflow + comparison-mission-isolation-hardening + source: TESTING_FINDINGS.md CS2 from FE-1215 witness + hardens: D134-L/I67-L private-mission boundary shared-session-host-tracer retires: A47-L proves: one host-owned writable runtime + real TUI + React attachment @@ -640,87 +215,30 @@ shared-session-host-convergence (Next — architecture replacement): closes: dual standalone-host / TUI-sidecar topology deletes: SessionEventRelay | brunch.sessionEvent | /rpc/driver | sidecar handle wiring -group-3 (Next — agent layer): - develop-mode (flag-gated; execute-tier authority, no contract break) - agent-control-plane-closure -[hard]-> reviewer-agent-mode (subagent reshape) - review-commentary-widening (mention-based reshape) - -parallel release: - automated-alpha-publishing (FE-1050) - closes: manual local release-it publishing - locks_in: changeset -> reviewed version PR -> pack smoke -> npm alpha + tag + GitHub Release - unconnected: main/latest stable automation (separate promotion frontier) - -parallel evaluation: - agent-control-plane-closure - status: done; earned coverage over foreground/background prompt ingress - absorbs: graph-assurance-conduct | subagent-skill-access - canonicalizes: D131 semantics | owned prompt replacement | load-on-demand context truth - | posture/style/agenda ownership | observable resource reads | honest child grants - excludes: schema migration | review renderer | capture-quality claim | specialist fan-out - -[hard]-> capture-ledger-tracer - status: pickup-ready; proving prompt-level control/treatment falsifier - lights_up: accepted source -> capture conduct -> graph/scratch/reconciliation -> split judgment - excludes: durable IR | production subagent fan-out | graph schema changes +parallel: capture-ledger-tracer + depends_on: completed agent-control-plane-closure reuses: FE-1208 evaluator/report primitives | FE-1210 actor + split judgment - owns: the rich mixed-source scenario and matched-run value - note: FE-1210 human closeout is not a hard dependency - agent-as-user-comparison (FE-1210) - status: closed 2026-07-17; promoted technical tracer (lockers-r1-20260716) - proven: push-driven Pi actor | Brunch document export | Brunch+Claude ready docs | split judgment | portable bundle | Cursor adapter - -[hard]-> operator-comparison-workflow (FE-1215, remediation active after first operator witness) - branch: ln/fe-1215-saved-mission-comparison - lights_up: private agent-as-user mission → minimal comparison-harness setup → top-level simulated-user actor → one direct harness shell at a time - retires: nested Pi actor shell | required custom question tool | per-run synthetic provider preflights | contender/simulated-PM wording - excludes: full multi-harness witness claims | browser UI | automatic winner/judge | multi-run campaign framework - -[hard]-> saved-mission-comparison-witness (next; later operator-owned PR) - status: wait-gated on FE-1215 D134-L remediation landing + operator availability - proves: stock-Pi Brunch+Claude run | single-level actor conduct | report usefulness | revision snapshot immutability - -group-4 (cleanups): rides group-1 stack | named-inline-extension-identity (P1) - -KA stream: - carved FE-1167 Execute beats + FE-1107 residue - planning-process-model (moved 2026-07-13) + +ka_evidence_queue: + host-landing (FE-1201) + oracle: live TUI+RPC /brunch:land -> fresh target (A42-L / FE-1197 oracle 9 landing leg) + reentry: next live FE-1197 walkthrough + executor-plan-synthesis (FE-1197) + oracle: live-capability 1-5 + committed-scope conforming-promotion 9 + reentry: next model-backed FE-1197 walkthrough execution-comparison-tracer (FE-1230) - status: active; approved Opus 4.8 Petri-editor spec ready to freeze as a durable case - reuses: FE-1210 split judgment | failure retention | masked outcome discipline - lights_up: frozen spec -> Brunch/Claude isolated lanes -> hidden browser/Petri oracles -> adjudication - excludes: host landing | product operator command | Cursor/Codex | broad benchmark claims - -[hard]-> end-to-end-comparison-tracer (FE-1239) - status: complete 2026-07-21; promoted staged 2x2 Petri-editor tracer - reuses: FE-1210 fresh actor | FE-1230 attempt/oracle contracts | FE-1232 reporting grammar - lights_up: mission -> exact elicited specs -> four execution cells -> requirement traceability - excludes: winner | repetitions | multi-case causality | product command | ExecutionAttempt schema widening - # FE-1192 and FE-1195 merged; attempt identity, isolated fan-in, - # durable parallel authority, and epic integration are current executor topology. - executor-slice-admission-parity (FE-1240) - status: complete - -[hard]-> executor-plan-coherence (FE-1250) - lights_up: committed scope -> coherent candidate plan -> ordinary reconciliation slice - reuses: canonical harness | isolated integration | epic verification - excludes: browser-specific executor gate | durable plan kind | new lifecycle phase - -[hard]-> brownfield-comparison-cases - status: complete FE-1241 with learning-first pinned snapshots, deterministic case oracles, and publication-compatible execution runs - lights_up: same-base brownfield elicitation -> exact handoff -> crossed execution -> case oracle - cases: minimal-petri-net-editor = FE-1241 greenfield reference | FE-1201-derived brunch backend | PR #9051 petrinaut frontend - excludes: Clay | more greenfields inside FE-1241 | repetitions | aggregate winner | ExecutionAttempt widening - -[hard]-> prospect-research-workspace-regression (FE-1253) - status: active; deterministic full-stack oracle calibrated, campaign expansion retiring - closes: useful regression oracle coupled to an unexecuted 2x2 campaign - excludes: provider lanes | requirement ledger | outreach delivery | reliability claims + oracle: unchanged petri-editor-browser-v2 replay against both retained outputs + reentry: exact immutable attempt/output paths restored + executor-plan-coherence (FE-1250) + oracle: unchanged frozen Petri comparison + controller browser oracle + reentry: explicit authorization + executor-slice-verification-repair (FE-1254) + oracle: owned unchanged Petri comparison rerun after finite repair ladder + reentry: explicit authorization greenfield-secure-drop-demo (FE-1289) - status: active; proving one bounded product witness over settled execution seams - lights_up: secure-drop mission -> accepted graph -> parallel cook -> Petrinaut -> confirmed land -> deterministic checks - reuses: D126-L scopes | D130-L authored harness | FE-1197 execution | FE-1201 landing | existing comparison evidence contracts - excludes: brownfield | factorial matrix | generic parity | new graph kinds | messenger behavior - # executor-run-environment (FE-1166) resolved 2026-07-15: policy merged (PR #302), - # live remainder folded into executor-plan-synthesis (FE-1197), card consumed. - -later: tier-2-regression-probes (trigger: rich seed/fixture scenarios worth pinning) | - mechanism-trace (vocabulary may feed FE-1208-lineage tracing; no parallel artifact system) | - agent-tracing (conditional on a named joined-report observability gap; absorbs P5) + oracle: fresh full corrected Secure Drop graph/harness/build witness + reentry: retained witness card on current runtime baseline rules: candidates never commit graph truth (I51-L) diff --git a/memory/SPEC.md b/memory/SPEC.md index 97cfe7fe9..6f761fcaa 100644 --- a/memory/SPEC.md +++ b/memory/SPEC.md @@ -121,10 +121,10 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c | A40-L | The current `before_agent_start` sweep-watermark advance records intent, not proven capture. A future capture-conditional advance may use Pi's per-turn result signal, but must preserve idempotence across multi-turn runs and compaction. FE-1187 has built the scenario-level sweep-debt tripwire (detection); runtime advance semantics remain deliberately unchanged pending evidence that material is actually stranded. | medium | open | D80-L, D77-L, D116-L | | A42-L | A Pi command plus `ctx.ui.confirm` can carry sole host-mutation acceptance authority for landing (FE-1201 `ln-design` claim 3) across both product surfaces: the TUI and the RPC/web driver. The wiring half is witnessed by stubbed-ctx command tests (confirm-gated apply, decline/no-UI zero-mutation); the live half — a real TUI+RPC `/brunch:land` walkthrough — is unproven. Validation: the FE-1197 oracle 9 tail walkthrough beat (re-entry: next live walkthrough). | medium | partially validated | D111-L; I58-L | -| A43-L | Several sealed Pi `AgentSession`s can run concurrently inside one cwd-scoped Brunch host without module-global extension state, runtime services, ask brokers, event streams, or JSONL writes leaking across session targets. **Validated 2026-07-14 (FE-1200 concurrency slice):** one production `runBrunchWeb` host drove two coordinator-created JSONL sessions through overlapping graph mutations, distinct live asks/answers, target-local contiguous event streams, second-driver/cross-target rivals, isolated failure/recovery, reconnect/fresh presentation, and separate JSONL readback. Session-local semantics stayed isolated while shared graph changes crossed only through canonical `worldUpdate` continuity. | medium | validated | D132-L; req 31; `src/dev/__tests__/standalone-web-session-host.concurrency.test.ts` | -| A44-L | A named JSONL-derived session presentation projection plus session-addressed live-event overlay can hydrate, stream, settle, and reconnect without a chat mirror store or durable replay event spine, while remaining product-shaped rather than exposing raw Pi as the browser contract. **Validated 2026-07-14 (`standalone-web-session-host` automated leaves):** production standalone-web hydration/live/settlement/refetch, malformed-detail rejection, and paired temporary production web/TUI JSONL runs preserve ordered binding/runtime, ordinary message, and current `ask`/answer structures under a normalizer limited to Pi-generated ids and timestamps; a changed-answer rival remains distinguishable. | medium | validated | D133-L; req 12, req 32 | -| A45-L | Splitting standalone semantic `brunch.liveSessionEvent` from the TUI sidecar's raw `brunch.sessionEvent` does not strand a browser raw-event consumer. **Validated 2026-07-15:** session routes consume only the typed semantic subscription; wrong-method coverage proves raw sidecar frames are ignored. | medium | validated | D84-L, D132-L; `src/web/__tests__/session-route.test.tsx` | -| A46-L | A closed Zod schema can represent every `SessionPresentationDelta`, including `OpenAsk` questions with questionnaire questions present or exactly absent. **Validated 2026-07-15:** the contract composes the owned question schemas as exact alternatives and round-trips all delta variants without a cast or restated owner type. | medium | validated | D133-L; `src/rpc/__tests__/standalone-web-session-host.contract.test.ts` | + + + + | A47-L | Pi's valuable `InteractiveMode` TUI behavior can be preserved while one independent cwd-scoped Brunch session host owns the sole writable sealed Pi runtime, JSONL session manager, graph command authority, and semantic live-event fan-out used by both TUI and React clients. The unknown is the TUI attachment seam: Pi exports `InteractiveMode` over an in-process `AgentSessionRuntime`, not a remote TUI client. Validation must prove a real TUI + browser target without a second writable runtime, raw-Pi browser contract, or permanent second relay. Frontier: `shared-session-host-tracer`; retirement/cutover: `shared-session-host-cutover`. | medium | open | D39-L, D132-L, D133-L; I64-L, I65-L | | A48-L | A read-only semantic preflight can improve orientation-menu availability over deterministic graph-fact heuristics while returning within a ≤3-second interaction budget often enough to justify a model-backed path. Admission is limited to the configured soft recommended evaluator model; other foreground selections, missing evaluator auth, timeout, malformed output, or failure use the deterministic safe subset without restricting Pi-native `/model`. The path must consume no foreground turn, write no transcript/graph/session truth, and cache only in process by `{specId, lsn, operationalMode}`. A Brunch-owned reconciliation-blocker reader participates in gating now with an explicit empty implementation; injected non-empty blockers veto availability so future derived/persisted blocker wiring cannot be forgotten. Validation: a tracked human-approved contrastive catalog plus structured scratch tracer report; first run three uncached feasibility calls, then only if plausible run ten uncached labeled cases, requiring ≥8/10 within 3 seconds, exact flags on every completed response, at least one named deterministic-fallback miss corrected, and zero false-positive moves. If the budget or quality gate fails, retire only the model path, not the deterministic fallback. | low | open | D74-L, D109-L, D123-L; `walkthrough-remediation-2` | @@ -304,7 +304,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c | D124-L | Workspace databases use deliberate major-line identity: `.brunch/brunch-v{major}.db` plus a validated SQLite `application_id`. Current-name files that do not prove Brunch lineage fail closed and are never opened, migrated, or deleted; 0.x `brunch.db` has no runtime path and does not influence posture inference. The alpha-only `data.db` predecessor is adopted once, with sidecars, only when the v1 file is absent. | [`src/graph/TOPOLOGY.md`](../src/graph/TOPOLOGY.md); invariant I63-L | active — materialized 2026-07-13 | | D125-L | Headless ask discovery is process-local live state, not transcript scanning or a second event plane. Every no-UI ask mode registers its full D116-L payload in the live ask registry; handle-gated `session.openAsks` discovers it and `session.answerExchange` resolves the unchanged string broker contract, with per-mode decoding in the ask collector. `session.submitExchangeResponse` remains the distinct transcript-mutation path. The transcript-backed pending projection survives only for file/observer compatibility until legacy `present_question` reads retire. | [`src/session/TOPOLOGY.md`](../src/session/TOPOLOGY.md), [`src/rpc/TOPOLOGY.md`](../src/rpc/TOPOLOGY.md) | active — materialized 2026-07-13 | | D132-L | Standalone interactive web uses one cwd-scoped combined Brunch host with a target-addressed inventory of sealed, in-process Pi `AgentSession`s (2026-07-14). The same process serves React assets/WebSocket Brunch RPC and owns coordinator/graph authority; it does not construct `InteractiveMode`, expose raw Pi RPC, spawn one Pi child per session, host multiple projects, or promise in-flight survival across host restart. One durable session target has one driver/many observers and cannot be opened as duplicate writable runtimes; write leases wait for real same-session contention. Hosted-session mutations return the complete `LiveSessionHostResult` discriminated `{status}` union as JSON-RPC success payloads, including domain refusals; only malformed boundary input and thrown host failures use JSON-RPC errors. FE-1200 materialized the one-target path and validated simultaneous target isolation (A43-L). Depends on: D5-L, D10-L, D33-L, D39-L, D84-L; req 4, req 31. Supersedes: D10-L/D72-L read-only-sidecar posture and D84-L singleton/TUI-owned target topology. | [`src/app/TOPOLOGY.md`](../src/app/TOPOLOGY.md), [`src/session/TOPOLOGY.md`](../src/session/TOPOLOGY.md), [`src/rpc/TOPOLOGY.md`](../src/rpc/TOPOLOGY.md), [`src/web/TOPOLOGY.md`](../src/web/TOPOLOGY.md) | active — target-addressed host and concurrent-session isolation materialized 2026-07-14 | -| D133-L | Web and TUI share transport-neutral presentation semantics, not platform components or separately-authored domain decoders (2026-07-14). Validated Brunch `toolResult.details` project to a shared semantic presentation model; LLM-context, TUI, and React adapters render that meaning for their audiences. Web hydrates from a named JSONL-derived product projection and overlays target-addressed live events, then refetches canonical truth at settlement/reconnect. The host emits neither ANSI/TUI strings nor ready-made HTML, and no chat mirror/event store is introduced. FE-1200 materialized the full required persisted family inventory: ordinary text; free-text, choice, choices, and bounded-questionnaire terminal read-back; candidate, review-set, and digest offers/continuations; and receipt-bearing review settlement. Live React controls answer free text and listed single/multi choices; bounded questionnaires remain answerable headlessly through D38-L's schema-tagged string/JSON envelope, without a dedicated React questionnaire form. Depends on: A44-L, D17-L, D19-L, D104-L; req 12, req 17, req 32. | [`src/projections/TOPOLOGY.md`](../src/projections/TOPOLOGY.md), [`src/web/TOPOLOGY.md`](../src/web/TOPOLOGY.md) | active — full required-family coverage materialized 2026-07-15 | +| D133-L | Web and TUI share transport-neutral presentation semantics, not platform components or separately-authored domain decoders (2026-07-14). Validated Brunch `toolResult.details` project to a shared semantic presentation model; LLM-context, TUI, and React adapters render that meaning for their audiences. Web hydrates from a named JSONL-derived product projection and overlays target-addressed live events, then refetches canonical truth at settlement/reconnect. The host emits neither ANSI/TUI strings nor ready-made HTML, and no chat mirror/event store is introduced. FE-1200 materialized the full required persisted family inventory: ordinary text; free-text, choice, choices, and bounded-questionnaire terminal read-back; candidate, review-set, and digest offers/continuations; and receipt-bearing review settlement. Live React controls answer free text and listed single/multi choices; bounded questionnaires remain answerable headlessly through D38-L's schema-tagged string/JSON envelope, without a dedicated React questionnaire form. Depends on: D17-L, D19-L, D104-L; req 12, req 17, req 32. | [`src/projections/TOPOLOGY.md`](../src/projections/TOPOLOGY.md), [`src/web/TOPOLOGY.md`](../src/web/TOPOLOGY.md) | active — full required-family coverage materialized 2026-07-15 | | D134-L | The approachable `/compare-specs` control topology is one top-level project Pi session acting as the simulated user and driving exactly one comparison-harness interactive subshell at a time. It does not spawn a Pi actor that then opens a nested interactive shell. The top-level agent alone receives the private mission; each harness receives only its approved minimal framing and the user's natural messages. Shared top-level context and lane order are acceptable and disclosed for this exploratory workflow; isolation-sensitive studies continue to use FE-1210's separate rigorous campaign recipe. Ordinary text interaction is the stock-Pi baseline for choices and approvals; a custom structured-question tool may enhance presentation but is never required. Setup checks are bounded to actual selected-harness prerequisites—no throwaway Pi/Claude provider turns or synthetic actor launches on every run. Supersedes: FE-1215's unmaterialized fresh-nested-actor design note. | [`.pi/prompts/compare-specs.md`](../.pi/prompts/compare-specs.md), [`testing/comparisons/missions/README.md`](../testing/comparisons/missions/README.md); PLAN `operator-comparison-workflow` | active — remediation materialized and focused Brunch smoke witnessed 2026-07-17; full comparison witness deferred | | D136-L | Petrinaut's common mechanical gate uses the full pinned HASH checkout. Before a candidate lane, the controller materializes the parent tree and exact handoff, runs only `corepack yarn install --immutable --mode=skip-build`, and requires tracked source to remain clean. After the lane terminates at `promotion_prepared`, closed focused builds launch the standalone `/optimization` route; a deterministic loopback optimizer grades scenario-first configuration, fixed/optimized bindings, objective direction, request construction, progress/completion/error/cancellation, upstream abort, same-origin secrecy, and source-backed accessibility semantics. Synthetic fixtures prove sensitivity but do not author stronger semantics than the calibrated source behavior. The broad `/processes/draft` host/iframe shell remains non-gating outer evidence. Depends on: D134-L, A49-L retirement. | [`src/dev/TOPOLOGY.md`](../src/dev/TOPOLOGY.md) | active — learning-first gate materialized 2026-07-22 | | D137-L | Historical replay preparation is experimental hygiene for fast product learning, not an adversarial security boundary (revised 2026-07-23). The controller materializes the pinned source tree into a fresh repository with no remote, adds the exact content-addressed packet, runs the one case-owned dependency recipe when required, checks source identity, packet bytes, and tracked cleanliness, then returns a lane-ready Brunch or Claude descriptor. Both lanes disable web/MCP surfaces where supported and bound file tools to the target, but the study reports this limitation rather than probing external services or proving host isolation. Depends on: A49-L retirement, D136-L. | [`src/dev/TOPOLOGY.md`](../src/dev/TOPOLOGY.md) | active — simplified for learning throughput | diff --git a/memory/cards/consequential-fact-discovery-tracer--warrant-ablation-campaign.md b/memory/cards/consequential-fact-discovery-tracer--warrant-ablation-campaign.md deleted file mode 100644 index 9d5912fc9..000000000 --- a/memory/cards/consequential-fact-discovery-tracer--warrant-ablation-campaign.md +++ /dev/null @@ -1,194 +0,0 @@ -# Warrant-before-commit ablation campaign - -Frontier: capture-ledger-tracer (superseded lineage: consequential-fact-discovery-tracer / FE-1208) -Status: superseded (2026-07-17 — FE-1210 proved the general actor; `capture-ledger-tracer` now owns the rich mixed-source mission, matched comparison, and architectural verdict while reusing the landed FE-1208 evaluator/report primitives. This card remains historical evidence; do not resume its fixed scenario or six-run directive-ablation campaign.) -Mode: single -Created: 2026-07-15 - -## Orientation - -- Containing seam: FE-1208's dev/eval-only real-TUI trajectory → consequential-fact evaluator path. Commits `11607e10`, `1e944616`, and `1f36ee18` established canonical active-branch/graph readback plus the calibrated review-diff scorer. -- Frontier: historical FE-1208 proving campaign, superseded by `capture-ledger-tracer`; no active Linear issue or branch is attached to this card. -- Volatile state: no separate handoff survives; this card is the sole historical actor-v2 record. Its corrected scratch trajectory is still diagnostic only; neither that run nor the scorer's hand-authored contrastive fixture counts as provider evidence. -- Main risk: campaign machinery can create a false causal claim by changing more than one prompt feature, relaxing the actor between arms, or promoting only favorable runs. Arm assignment, actor policy, run budget, model configuration, validity rules, and discrimination threshold must be fixed before the first provider run. - -Posture: proving (historical FE-1208 posture; this card is no longer executable). - -## Target Behavior - -A controlled six-run real-TUI campaign produces a promoted, predeclared verdict on whether the warrant-before-commit directive discriminates the calibrated review-diff scenario from its ablated rival. - -## Cold-start reads - -- `memory/SPEC.md` — req 24; A5-L; §Verification Design, especially consequential-fact discovery, combined trajectory/evaluation assessment, controlled warranted-commitment ablation, flywheel design notes, and acknowledged blind spots -- `memory/PLAN.md` — superseding frontier: `capture-ledger-tracer` -- `docs/praxis/manual-testing.md` — TUI priority order, sandbox fallback, evidence capture, cleanup, and findings-ledger discipline -- `src/dev/TOPOLOGY.md` — trajectory/evaluator/tui-driver ownership and scratch boundary -- `src/.pi/extensions/dev-mode/introspection/TOPOLOGY.md` — provider-visible trajectory contract and content-retention ceilings -- `src/agents/runtime/elicitor/TOPOLOGY.md` — real Specify prompt body/composition seam -- `src/.pi/TOPOLOGY.md` and `src/.pi/extensions/TOPOLOGY.md` — sealed profile and product extension composition root -- `src/session/TOPOLOGY.md` — active-branch and review-set settlement authority -- `src/graph/TOPOLOGY.md` — graph/readback and change-log authority - -## Intervention and campaign contract - -### Single intervention - -- **Control arm:** the current provider-visible elicitor body includes the exact warrant-before-commit paragraph beginning “When a commitment is ready…”. -- **Ablated arm:** one dev/eval-only override removes exactly that paragraph at the real live elicitor composition seam. -- Assign stable directive id `warrant-before-commit` and a content hash to the delimited paragraph. Source delimiters must not become provider-visible text in either arm. -- Product launches, Execute mode, tools, skills, references, graph/session context, and all other elicitor text remain unchanged. The ablation is unavailable unless dev/eval instrumentation is explicitly active. -- The joined trajectory/report must prove the expected directive id/hash is provider-visible in control runs and absent in ablated runs; code-level prompt differential tests prove no other body bytes change. - -### Fixed scenario and actor - -Use the already calibrated review-diff scenario as the sole scenario: - -- public brief: review policy-copy changes and accept a reviewed set atomically -- hidden fact: every accepted policy rewrite retains its source regulator clause identifier verbatim -- forbidden rival: semantic-equivalent text may drop the identifier -- reveal policy: disclose the exact hidden fact only after a compliance/audit/missing-constraint question; otherwise answer from the public brief without leaking it -- approval policy: approve only an exact review set that carries the revealed constraint; request correction when the set omits or contradicts it - -The actor is one versioned deterministic policy over the real TUI surface. A small declared keyword/shape matcher may classify the qualifying question; mark its semantic ceiling and retain every classification in the report for human audit. The policy, response strings, turn budget, timeout behavior, startup/menu gestures, and invalid-run rules are identical across arms. - -### Fixed run configuration - -Before run 1, write one campaign manifest fixing: - -- campaign/scenario/actor/rubric versions -- three run ids per arm and arm order -- workspace seed/setup recipe and fresh-workspace reset per run -- provider, model, thinking level, and any provider-supported seed; record `unsupported` rather than inventing a seed when the provider exposes none -- turn budget, timeout budget, TUI dimensions, actor policy, and artifact paths -- the exact control/ablation directive id/hash pair -- validity rules and discrimination threshold - -Use one provider/model/thinking combination for all six runs. Do not replace or discard a valid run. A mechanically invalid run may be repeated only under its predeclared rule, with the failed attempt retained and named. - -### Predeclared verdict - -For each run, the scorer's six atomic judgments remain visible. Define the primary composite before execution as: - -```text -warranted_commitment = - consequential_fact_completeness == pass - && item_groundedness == pass - && settlement_correctness == pass - && forbidden_rival_absence == pass - && private_leakage_absence == pass - && duplicate_effect_absence == pass -``` - -The campaign **discriminates** only when control has at least `2/3` valid composite passes and ablated has at most `1/3`. Report the exact counts and every atomic reason. If this threshold is not met, the slice still lands the valid promoted no-discrimination evidence, but FE-1208 remains open and `memory/PLAN.md` must record the invalidated discrimination expectation instead of tuning the scorer, changing the actor, or selecting different runs post hoc. - -## Boundary Crossings - -```text -→ fixed campaign manifest + calibrated private scenario -→ dev/eval-only prompt intervention at live elicitor composition -→ product Brunch TUI composition root -→ controlled actor over real PTY/TUI input and visible output -→ provider requests + Pi active-branch transcript + graph settlement -→ joined trajectory + consequential-fact evaluator -→ aggregate predeclared verdict -→ human audit -→ deliberate scratch-to-runs promotion -``` - -## Risks and Assumptions - -- RISK: the override leaks into normal product behavior → MITIGATION: make the option programmatic/dev-eval-only, fail closed outside active instrumentation, and pin product/control prompt equivalence. -- RISK: the two arms differ in more than the directive → MITIGATION: exact body differential test plus first-provider-request directive id/hash evidence for every run. -- RISK: semantic question matching makes the deterministic actor selectively cooperative → MITIGATION: one frozen matcher/policy for both arms, code-adjacent `ceiling:` marker, retained classification evidence, and human audit of all six classifications. -- RISK: provider or TUI failures are laundered as behavioral failures → MITIGATION: predeclare mechanical validity separately from scorer verdicts; retain failed attempts and permit replacement only for named mechanical invalidity. -- RISK: promotion captures secrets or workstation paths → MITIGATION: retain bounded secret-filtered trajectory content, copy only the required JSONL/report/readback/viewport artifacts, normalize paths, and run `check:promoted-run-paths`. -- ASSUMPTION: removing the one warrant directive changes enough conduct for the predeclared 2/3-versus-1/3 rule to discriminate. - → IMPACT IF FALSE: the evaluator remains calibrated but this intervention does not validate its usefulness on real provider behavior; FE-1208 needs plan revision rather than broader tracing. - → VALIDATE: execute and retain all six fixed runs, then compute the aggregate verdict without post-hoc rubric/actor changes. - → `memory/SPEC.md` §Acknowledged Blind Spots: warrant-directive ablation is an intentionally weak rival - -## Posture check - -- **Lights up:** the complete real TUI → controlled actor → joined trajectory → evaluator → aggregate verdict → promoted regression path. -- **Stabilizes:** a dev/eval-only single-directive intervention, fixed campaign manifest, and scratch→audit→promotion contract. -- **Uncertainty retired by landing:** whether the calibrated evaluator and landed legibility envelope discriminate the real provider's conduct under the selected single intervention. -- A positive result closes the synthetic A/B portion of FE-1208. A negative result is still information gain but triggers `ln-plan`; it must not be repaired by expanding the evaluator, adopting OTel, or changing campaign conditions in this slice. - -## Acceptance Criteria - -- ✓ `src/agents/runtime/elicitor/__tests__/compose-live-prompt.test.ts` — control output preserves the current provider-visible elicitor body, ablated output removes only stable directive `warrant-before-commit`, source delimiters are absent in both, and the directive hash is stable. -- ✓ `src/.pi/extensions/__tests__/agent-runtime-system-prompts.test.ts` plus the real app composition test — product launches cannot select ablation; explicit dev/eval launches wire the chosen arm through `before_agent_start` and `before_provider_request` without changing active tools, skills, references, runtime control, or Execute prompting. -- ✓ joined trajectory tests — every run report validates the directive id/hash and expected arm state at the provider boundary; mismatched arm evidence fails before scoring. -- ✓ campaign actor/state-machine tests — legal TUI traces obey one frozen reveal/approval policy and turn budget; hidden facts never appear before a qualifying question; omitted/contradictory review sets receive the predeclared correction response; unknown states/timeouts fail mechanically rather than improvising. -- ✓ campaign manifest/report tests — arm order, three run ids per arm, fixed provider/model/thinking/setup/actor/budget, validity rules, artifact inventory, atomic scorer reasons, and the 2/3-versus-1/3 rule are runtime-validated and byte-stably reprojected. -- ✓ campaign integration test — a deterministic fake-provider or replay fixture drives the same production TUI composition, actor, joined-report, evaluator, and aggregate entry points end to end; the harness does not inject prompt wiring or graph outcomes unavailable to the real command. -- ✓ six real-provider run bundles under `.fixtures/scratch/` — three valid control and three valid ablated runs use fresh workspaces and the fixed manifest; each retains run config, source `session.jsonl`, joined `trajectory.json`/report, bounded viewport, graph readback, evaluator verdict/reasons, and cleanup status. -- ✓ human calibration record — the user/coordinator audits all six reveal-policy classifications and at least one full atomic-reason chain per arm, recording agreement/disagreement without editing run outputs; any material disagreement blocks promotion and routes through `ln-oracles`. -- ✓ promoted campaign bundle under `.fixtures/runs/consequential-fact-ablation//` — contains the immutable campaign manifest, all six reviewed run bundles, aggregate JSON/Markdown verdict, calibration record, and portable artifact references; no scratch-only or credential material is copied. -- ✓ `npm run check:promoted-run-paths` and `npm run verify` — promotion is portable and the full project gate passes with no unexplained skipped-test increase. - -## Invariants preserved - -- Normal Brunch and Execute prompts remain unchanged unless explicit dev/eval instrumentation selects the ablation — guarded by: prompt differential, app composition, and Execute prompt tests. -- One intervention changes per campaign; directive presence/precedence supports causality only inside this controlled comparison — guarded by: fixed manifest validation and bounded-claim report text. -- Pi active branch and Brunch spec-scoped graph readers remain evidence authority — guarded by: campaign integration and per-run evaluator reports. -- Review-set approval remains the only atomic settled-batch commit path — guarded by: existing I15-L settlement suites plus per-run single-effect scorer judgment. -- Hidden facts never enter provider input through the campaign harness before actor reveal — guarded by: actor policy tests, provider-boundary trajectory evidence, and human calibration. -- Scratch artifacts are non-evidence until reviewed and promoted deliberately — guarded by: promotion command/check plus manifest artifact-state validation. - -## Verification Approach - -- Inner: prompt differential, runtime boundary schemas, actor state-machine, aggregate verdict, artifact hygiene, and deterministic replay tests. -- Middle: deterministic production-entry campaign replay plus six real-provider TUI runs scored from canonical session/graph/trajectory artifacts. -- Outer: user/coordinator audit of all reveal classifications and sampled atomic reasons before promotion; the audit is owned by this card and is not deferred. - -## Cross-cutting obligations - -- Use the real TUI/product composition root; test-only prompt injection or direct graph seeding of expected outcomes cannot satisfy the campaign integration or real-run leaves. -- Keep traces and campaign artifacts dev/eval-only and non-authoritative; no product event spine or runtime scoring behavior. -- Deterministic checks own structure and negative space; human labels calibrate only residual semantic classification. -- Preserve product-neutral scenario/run/verdict fields while keeping Brunch directive/trajectory enrichment diagnostic. -- Retain and restate the bounded claim: this ablation validates evaluator discrimination only, not broad Brunch quality, practical usefulness, or competitor superiority. -- Do not add OTel, broad subagent spans, provider matrices, competitor execution, generic scorecards, interaction-quality scoring, or a second artifact system. -- After a positive campaign, FE-1208 still owes one mined real walkthrough failure before practical-quality claims; scope that separately rather than pulling it into this build. - -## Expected touched paths (tentative) - -```text -src/agents/prompts/elicitor.md ~ -src/agents/runtime/ -├── foreground-policy.ts ~ -└── elicitor/ - ├── compose-live-prompt.ts ~ - ├── __tests__/compose-live-prompt.test.ts ~ - └── __snapshots__/live-elicitor-prompt.md ? -src/.pi/extensions/ -├── agent-runtime/system-prompts/index.ts ~ -├── dev-mode/introspection/trajectory.ts ~ -├── dev-mode/introspection/TOPOLOGY.md ~ -├── __tests__/agent-runtime-system-prompts.test.ts ~ -└── __tests__/dev-mode-introspection.test.ts ~ -src/app/ -├── brunch.ts ~ -├── brunch-tui.ts ~ -├── pi-extensions.ts ~ -├── TOPOLOGY.md ? -└── __tests__/brunch-tui.test.ts ~ -src/dev/ -├── consequential-fact-evaluator.ts ~ -├── consequential-fact-campaign.ts + -├── consequential-fact-evaluator/ -│ ├── actor.ts + -│ ├── campaign.ts + -│ └── review-diff-scenario.json + -├── dev-cli.ts ~ -├── TOPOLOGY.md ~ -└── __tests__/ - ├── consequential-fact-evaluator.test.ts ~ - ├── consequential-fact-campaign.test.ts + - ├── dev-cli.test.ts ~ - └── fixtures/consequential-fact-review-diff.json - -.fixtures/runs/consequential-fact-ablation// + -memory/PLAN.md ~ -``` diff --git a/memory/cards/end-to-end-comparison-tracer--factorial-matrix.md b/memory/cards/end-to-end-comparison-tracer--factorial-matrix.md deleted file mode 100644 index f54d5531b..000000000 --- a/memory/cards/end-to-end-comparison-tracer--factorial-matrix.md +++ /dev/null @@ -1,280 +0,0 @@ -# End-to-end Petri-editor factorial matrix - -Frontier: end-to-end-comparison-tracer -Status: done -Mode: slices -Created: 2026-07-21 - -## Orientation - -- Containing seam: controller-owned dev/evaluation composition over the rigorous FE-1210 elicitation recipe, FE-1230 execution artifacts/oracles, and FE-1232 reporting grammar; no product runtime command is added. -- Frontier: `end-to-end-comparison-tracer` (FE-1239), stacked on FE-1230 and parented under FE-1211. -- Volatile state: FE-1230's independent browser journeys are built on the parent branch; its old retained pair remains separate sibling evidence. This frontier must run fresh elicitation-derived outputs. -- Main risk: the existing execution public contract exposes product behavior. Shared interoperability requirements must therefore be disclosed before elicitation and marked as controlled baseline, while exact lane-authored specification bytes cross the handoff unchanged. - -Posture: proving (inherited from `end-to-end-comparison-tracer`). - -Cross-cutting obligations: - -- preserve mission/reveal/controller isolation and FE-1210 failure retention; -- preserve FE-1230 `ExecutionAttempt`, controller-oracle, and no-landing contracts; -- let comparison-reporting consume retained evidence without changing run conduct; -- never credit shared public-baseline requirements as elicitation gains. - -## Card 1 — Freeze the study and exact handoff - -Status: done - -### Target Behavior - -A frozen study accepts only byte-identical approved elicitation artifacts and describes one closed two-specification-by-two-executor matrix with complete requirement provenance. - -### Cold-start reads - -- `memory/SPEC.md` — D70-L, D134-L, I67-L, D40-L, D120-L, I62-L -- `memory/PLAN.md` — frontier: `end-to-end-comparison-tracer` -- `docs/praxis/comparison-runs.md` and `comparison-runs/mission-packet.md` — rigorous actor, validity, retention, and controller isolation -- `.agents/skills/comparison-reporting/references/end-to-end-comparisons.md` — validity chain and traceability row shape -- `src/dev/TOPOLOGY.md` — dev/evaluation ownership -- `src/dev/execution-comparison/artifact-contract.ts` and `oracle-pack.ts` — immutable attempt/oracle identities to reference, not widen - -### Boundary Crossings - -```text -frozen case references - → runtime-boundary study parser - → approved elicitation artifact + byte hash - → immutable handoff record - → closed matrix + requirement registry -``` - -### Risks and Assumptions - -- RISK: a path points to controller material or escapes the retained run → MITIGATION: canonical containment checks plus disjoint controller/target roots at parse and materialization boundaries. -- RISK: a handoff helper "helps" by reformatting free-form Markdown → MITIGATION: hash the source bytes and write/copy only those bytes with exclusive creation. -- ASSUMPTION: FE-1230's `ExecutionAttempt` is sufficient as the execution-cell leaf. - → IMPACT IF FALSE: widening that schema would couple sibling evidence to E2E provenance. - → VALIDATE: matrix tests reference attempts by path/hash and prove the complete join without altering `ExecutionAttempt`. - -### Posture check - -- Proof of life: establishes the previously missing elicitation → execution identity seam. -- Invariant: makes "unchanged approved specification" executable rather than report prose. -- Uncertainty: locates whether a separate E2E artifact can compose FE-1230 without schema widening. - -### Acceptance Criteria - -- ✓ `study-contract.test.ts` — rejects mutable/unknown versions, incomplete lane sets, duplicate matrix cells, non-SHA identities, and controller roots reachable from target roots. -- ✓ `handoff-contract.test.ts` — materializes exact approved bytes once, rejects source/hash drift and destination overwrite, and records elicitation provenance without normalization. -- ✓ `matrix-contract.test.ts` — accepts exactly `{brunch_spec, claude_spec} × {brunch, claude_code}` and validates referenced `ExecutionAttempt` bytes/hashes. -- ✓ `traceability-contract.test.ts` — requires every predeclared row to name origin, both elicitation dispositions, both handoffs, all four implementation/verification dispositions, evidence, and assessment. -- ✓ `redaction.test.ts` — audience-safe rows retain opaque ids/public concern categories and remove controller-only wording, fixtures, expected states, and reveal policy. - -### Invariants preserved - -- FE-1230 `ExecutionAttempt` schema remains unchanged — guarded by: existing `artifact-contract.test.ts` plus matrix composition tests. -- Controller-only material never enters a target path — guarded by: study/handoff containment negatives. -- Invalid/failed evidence remains referenceable — guarded by: matrix fixtures containing valid and invalid attempts. - -### Verification Approach - -- Inner: runtime-boundary unit tests for every untrusted JSON/path/artifact entry. -- Middle: synthetic retained-run fixture closes all four cells and every ledger row. -- Outer: none for this card; Card 3 owns provider evidence and reviewed promotion. - -### Expected touched paths (tentative) - -```text -src/dev/ -├── end-to-end-comparison.ts + -└── end-to-end-comparison/ - ├── study-contract.ts + - ├── handoff-contract.ts + - ├── matrix-contract.ts + - ├── traceability-contract.ts + - ├── redaction.ts + - └── __tests__/ + -testing/end-to-end-comparisons/ -└── cases/minimal-petri-net-editor/ - ├── study-contract.json + - └── requirement-registry.json + -``` - -### Completion evidence - -| Leaf | Outcome | Evidence | -| --- | --- | --- | -| Frozen study contract | met | `study-contract.test.ts`; tracked case hash load | -| Exact immutable handoff | met | `handoff-contract.test.ts`; byte equality, drift/escape/overwrite negatives | -| Closed four-cell matrix | met | `matrix-contract.test.ts`; four parsed immutable `ExecutionAttempt` leaves | -| Complete traceability rows | met | `traceability-contract.test.ts`; tracked AC14–AC26 registry | -| Audience-safe redaction | met | `traceability-contract.test.ts`; controller fields/private evidence removed | - -Skipped-test-count delta vs parent: 0. - -## Card 2 — Compose exact-spec execution cells - -Status: done - -### Target Behavior - -Each frozen handoff launches through either executor from an isolated target workspace and produces an immutable FE-1230 execution attempt without exposing controller material or landing Brunch output. - -### Cold-start reads - -- `memory/PLAN.md` — frontier: `end-to-end-comparison-tracer` -- Card 1 public exports — frozen study/handoff/matrix contracts -- `src/dev/execution-comparison/brunch-lane.ts` — coded-spec adapter to preserve beside the new opaque-spec path -- `src/dev/execution-comparison-brunch.ts` — pinned Brunch execution entry -- `src/dev/execution-comparison/browser-oracle.ts` — unchanged common output oracle -- `src/executor/TOPOLOGY.md` — `empty_dir`, promotion, and no-landing boundaries - -### Boundary Crossings - -```text -immutable handoff - → isolated target packet - → Brunch or Claude execution adapter - → output repository + process ledger - → unchanged browser oracle - → immutable ExecutionAttempt -``` - -### Risks and Assumptions - -- RISK: opaque Markdown loses intent when seeded into Brunch graph state → MITIGATION: preserve it as one settled approved-spec artifact plus separately predeclared shared delivery/interface nodes; do not infer missing requirements. -- RISK: Claude execution becomes an ad hoc shell recipe that cannot prove cleanup → MITIGATION: one adapter contract owns launch, fixed prompt, process/status capture, git evidence, and deterministic teardown. -- ASSUMPTION: the existing browser oracle can assess all four outputs from the shared baseline. - → IMPACT IF FALSE: a target may be behaviorally correct but unaddressable, invalidating common comparison evidence. - → VALIDATE: run the known-good implementation through both adapter packet shapes before provider execution. - -### Posture check - -- Proof of life: lights the exact handoff through both executor boundaries. -- Invariant: stabilizes target/controller isolation and no-landing behavior across a crossed matrix. -- Uncertainty: tests whether Brunch can execute an opaque third-party specification without format repair. - -### Acceptance Criteria - -- ✓ `brunch-adapter.test.ts` — exact arbitrary Markdown survives workspace preparation byte-for-byte, the legacy coded-spec FE-1230 path stays green, and only shared baseline material is added separately. -- ✓ `claude-adapter.test.ts` — prepares a fresh git target containing only exact spec/shared baseline, validates fixed launch inputs, records output/cleanup, and rejects controller paths. -- ✓ `execution-cell.test.ts` — both adapters emit parseable immutable `ExecutionAttempt` artifacts linked by matrix cell without changing `ExecutionAttempt`. -- ✓ existing `browser-oracle.slow.test.ts` — unchanged `petri-editor-browser-v2` still passes against the known-good application. -- ✓ existing execution suites — `promotion_prepared` remains the Brunch terminal and `landed` remains invalid. - -### Invariants preserved - -- FE-1230 coded-spec execution remains available unchanged — guarded by: `brunch-lane.test.ts`. -- Browser journeys and controller pack remain byte-identical on this branch — guarded by: case/oracle contract tests and git diff review. -- Brunch host landing remains impossible inside the adapter — guarded by: terminal parser and launch-command negative assertions. - -### Verification Approach - -- Inner: adapter contract tests with injected process runners and temporary git repositories. -- Middle: known-good app through both packet/collection paths plus unchanged slow browser suite. -- Outer: Card 3 owns real provider runs, cleanup review, and promotion. - -### Expected touched paths (tentative) - -```text -src/dev/ -├── execution-comparison/brunch-lane.ts ~ -├── execution-comparison/__tests__/brunch-lane.test.ts ~ -└── end-to-end-comparison/ - ├── brunch-adapter.ts + - ├── claude-adapter.ts + - ├── execution-cell.ts + - └── __tests__/ ~ -``` - -## Card 3 — Run and promote the factorial witness - -Status: done - -### Target Behavior - -One reviewed retained bundle proves the full validity chain from two fresh rigorous elicitation lanes through four execution cells to a closed requirement traceability report. - -### Cold-start reads - -- `memory/PLAN.md` — frontier: `end-to-end-comparison-tracer` -- Cards 1–2 public contracts and verification results -- `.agents/skills/agent-as-user-comparison/SKILL.md` — fresh actor recipe -- `.agents/skills/comparison-reporting/SKILL.md` and `references/end-to-end-comparisons.md` — evidence order and report grammar -- `docs/praxis/manual-testing.md` — outer-loop capture, cleanup, and findings disposition - -### Boundary Crossings - -```text -two fresh elicitation lanes - → operator approval + immutable handoffs - → four real execution cells - → unchanged independent journeys - → complete requirement ledger - → controller + audience-safe reports - → reviewed promoted bundle -``` - -### Risks and Assumptions - -- RISK: provider/runtime invalidity exhausts the first launch → MITIGATION: retain every attempt and replace only under the frozen replacement rule. -- RISK: poor output is mislabeled invalid and rerun → MITIGATION: validity and quality stay orthogonal; poor valid output remains the result. -- RISK: a polished report overclaims the one-case matrix → MITIGATION: no aggregate winner; report only cell validity, requirement outcomes, within-executor/spec contrasts, and limitations. - -### Posture check - -- Proof of life: first valid end-to-end comparison path. -- Invariant: proves exact frozen handoff identity survives real actors and executors. -- Uncertainty: determines whether elicitation differences remain visible after crossing executor identity. - -### Acceptance Criteria - -- ✓ retained elicitation manifests — one valid Brunch and one valid Claude target-authored specification under matched frozen actor policy, with complete cleanup. -- ✓ handoff validator — both approved source hashes equal execution input hashes byte-for-byte. -- ✓ matrix validator — exactly four retained execution cells exist; invalid attempts are retained and replacements cite the frozen rule. -- ✓ browser reports — every cell retains a verdict for all five independent journeys even when another journey fails. -- ✓ traceability validator — every registry row closes with exact evidence or `not_assessable`; shared-baseline rows are never credited as elicitation gains. -- ✓ comparison-reporting review — controller report presents validity before outcomes and makes no winner/reliability/cross-case causal claim. -- ✓ `npm run check:promoted-run-paths` — promoted bundle contains no scratch, controller-root, session-private, or absolute host path. -- ✓ `npm run verify:full` — full repository gate passes. - -### Invariants preserved - -- Private reveal keys are never promoted — guarded by: promoted-path/content checks and manual bundle review. -- Failed and invalid attempts are not erased — guarded by: manifest inventory and immutable directories. -- Common comparison claims use only common evidence — guarded by: traceability schema and report review. - -### Verification Approach - -- Inner: validators over the assembled retained bundle. -- Middle: unchanged mechanical oracle over every execution cell. -- Outer: named operator/controller review of elicitation validity, cleanup, traceability dispositions, redaction, and bounded report before promotion. - -### Expected touched paths (tentative) - -```text -.fixtures/runs/end-to-end-comparison// + -docs/praxis/comparison-runs.md ~ -src/dev/TOPOLOGY.md ~ -memory/PLAN.md ~ -memory/cards/end-to-end-comparison-tracer--factorial-matrix.md ~ -.changeset/*.md + -``` - -### Completion evidence - -| Leaf | Outcome | Evidence | -| --- | --- | --- | -| Two exact elicitation handoffs | met | promoted `handoffs/`; both study/spec hashes validate | -| Closed real execution matrix | met | promoted `matrix-manifest.json`; four immutable valid failed attempts | -| Unchanged common oracle | met | five portable journey dispositions under every cell's `evidence/` directory | -| Requirement closure and redaction | met | controller ledger retained in scratch; promoted `requirement-ledger.public.json` | -| Bounded comparison report | met | promoted `report.md`; validity precedes outcomes and no winner/causal claim is made | -| Portable promotion | met | manual untracked-bundle scan plus `check:promoted-run-paths` recipe; no host/scratch/controller paths | - -Promoted witness: -`.fixtures/runs/end-to-end-comparison/petri-editor-e2e-20260721T132600Z/`. - -Observed result: all four final cells were valid failures. Both Brunch cells halted at -`plan_slice_invalid` before implementation; both Claude Code outputs passed their own gates and failed -the common browser oracle. Poor valid outputs were retained and not rerun. diff --git a/package-lock.json b/package-lock.json index 1481bd601..02c89c564 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@hashintel/brunch", - "version": "1.0.0-alpha.12", + "version": "1.0.0-alpha.13", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@hashintel/brunch", - "version": "1.0.0-alpha.12", + "version": "1.0.0-alpha.13", "license": "Apache-2.0", "dependencies": { "@earendil-works/pi-ai": "0.83.0", @@ -1157,7 +1157,6 @@ "version": "0.83.0", "resolved": "https://registry.npmjs.org/@earendil-works/pi-coding-agent/-/pi-coding-agent-0.83.0.tgz", "integrity": "sha512-uYhF+FsZxogoSX/AxBcUdiY+ZklubwaXyAoEGA2eQwsHcyEAhUYIKh/WLXe/a8+k8eTCmxb+ZN2Zo9mzQtzbWw==", - "hasShrinkwrap": true, "license": "MIT", "dependencies": { "@earendil-works/pi-agent-core": "^0.83.0", @@ -6949,6 +6948,7 @@ "version": "5.6.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", + "dev": true, "license": "MIT", "engines": { "node": "^12.17.0 || ^14.13 || >=16.0.0" @@ -7059,6 +7059,7 @@ "version": "7.0.6", "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, "license": "MIT", "dependencies": { "path-key": "^3.1.0", @@ -8612,6 +8613,7 @@ "version": "4.2.11", "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true, "license": "ISC" }, "node_modules/hosted-git-info": { @@ -8915,6 +8917,7 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, "license": "ISC" }, "node_modules/jackspeak": { @@ -8937,6 +8940,7 @@ "version": "2.7.0", "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz", "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==", + "dev": true, "license": "MIT", "bin": { "jiti": "lib/jiti-cli.mjs" @@ -9511,6 +9515,7 @@ "version": "11.5.0", "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.0.tgz", "integrity": "sha512-5YgH9UJd7wVb9hIouI2adWpgqrrICkt070Dnj8EUY1+B4B2P9eRLPAkAAo6NICA7CEhOIeBHl46u9zSNpNu7zA==", + "dev": true, "license": "BlueOak-1.0.0", "engines": { "node": "20 || >=22" @@ -10216,6 +10221,7 @@ "version": "7.1.3", "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz", "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==", + "dev": true, "license": "BlueOak-1.0.0", "engines": { "node": ">=16 || 14 >=14.17" @@ -10788,6 +10794,7 @@ "version": "3.1.1", "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, "license": "MIT", "engines": { "node": ">=8" @@ -11502,6 +11509,7 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, "license": "MIT", "dependencies": { "shebang-regex": "^3.0.0" @@ -11514,6 +11522,7 @@ "version": "3.0.0", "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, "license": "MIT", "engines": { "node": ">=8" @@ -12861,6 +12870,7 @@ "version": "2.0.2", "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, "license": "ISC", "dependencies": { "isexe": "^2.0.0" @@ -13071,6 +13081,7 @@ "version": "2.9.0", "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", + "dev": true, "license": "ISC", "bin": { "yaml": "bin.mjs" diff --git a/src/dev/README.md b/src/dev/README.md index 44665215c..1e98b855f 100644 --- a/src/dev/README.md +++ b/src/dev/README.md @@ -60,7 +60,7 @@ npm run dev-cli -- mutate --workspace .fixtures/workbenches/workspace-alpha-grou npm run dev-cli -- export --workspace .fixtures/workbenches/workspace-alpha-grounding --spec-id 1 --out .fixtures/seeds/custom/example.json ``` -The consequential-fact evaluator and campaign remain functional but are parked and intentionally not part of the active DX; see [`memory/PLAN.md` §Later](../../memory/PLAN.md#later), `warrant-ablation-campaign`. +The consequential-fact evaluator, report, runner, and directive-ablation seam remain functional dev/eval primitives, but the earlier consequential-fact / `warrant-ablation-campaign` line is retired rather than parked; see the FE-1208 reshape and closeout entries in [`docs/archive/PLAN_HISTORY.md`](../../docs/archive/PLAN_HISTORY.md#2026-07-16-fe-1208-reshape-ln-plan-consequential-fact-discovery-tracer--automation-observability-dx). `capture-ledger-tracer` is the live successor for rich mixed-source matched comparison. Rules: diff --git a/src/dev/TOPOLOGY.md b/src/dev/TOPOLOGY.md index 7ee93fe86..c9c949520 100644 --- a/src/dev/TOPOLOGY.md +++ b/src/dev/TOPOLOGY.md @@ -49,7 +49,7 @@ D139-L admits `prospect-research-workspace-v1` as a deterministic greenfield exe - Seeding is always explicit: the launcher only seeds when `--seed / --reset` is present or chosen in the prompt flow. - `rpc`, `mutate`, `export`, and `document-export` are explicit subcommands for scripted reads, graph curation, fixture export, and read-only spec Markdown rendering from active settled graph state. Fixture export alone accepts `--show all|active`; document export has no visibility override. - `trajectory` joins one workspace's normalized debug events to Pi's canonical active session branch and an optional bounded viewport. It requires explicit workspace/session/run inputs and replaces `/.brunch/debug/trajectory.json` plus `trajectory-report.md` on each run (latest-wins); the report is diagnostic attribution, not product truth or a causality claim. -- The consequential-fact evaluator and campaign remain functional but are parked and intentionally absent from the active DX surface; see [`memory/PLAN.md` §Later](../../memory/PLAN.md#later), `warrant-ablation-campaign`. +- The consequential-fact evaluator, report, runner, and directive-ablation seam remain functional dev/eval primitives, but the earlier consequential-fact / `warrant-ablation-campaign` line is retired rather than parked; see the FE-1208 reshape and closeout entries in [`docs/archive/PLAN_HISTORY.md`](../../docs/archive/PLAN_HISTORY.md#2026-07-16-fe-1208-reshape-ln-plan-consequential-fact-discovery-tracer--automation-observability-dx). `capture-ledger-tracer` is the live successor for rich mixed-source matched comparison. Current subcommands: From 20f96c61c1c88139d9bdacd08c9b88d68e7f3a0e Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 18:05:21 +0200 Subject: [PATCH 02/35] Record deadness-oracle blind spot and host-convergence confirmation SPEC gains the "No deadness oracle in the gate" Acknowledged Blind Spot (episodic sweeps only, false positives on out-of-graph consumers per FE-1241 ripgrep evidence; knip.jsonc/konsistent unwired). PLAN's shared-session-host-convergence arc records the independent architecture-review confirmation and folds the coordinator decomposition into the arc. Co-Authored-By: Claude Fable 5 --- memory/PLAN.md | 1 + memory/SPEC.md | 1 + 2 files changed, 2 insertions(+) diff --git a/memory/PLAN.md b/memory/PLAN.md index b0d0f422e..e38173e61 100644 --- a/memory/PLAN.md +++ b/memory/PLAN.md @@ -33,6 +33,7 @@ - **Members:** `shared-session-host-tracer` → `shared-session-host-cutover`. - **Done-definition:** one host owns each writable Pi runtime, JSONL writer, graph command authority, driver lease/handoff, and semantic live-event stream; TUI and React remain useful clients/adapters; `SessionEventRelay`, `brunch.sessionEvent`, `/rpc/driver`, and TUI-owned parallel host wiring are deleted; `memory/SPEC.md`, `README.md`, `CONTRIBUTING.md`, `docs/design/WEB_UI_ARCHITECTURE.md`, and the app/session/rpc/web topology homes describe only the canonical host plus presentation adapters. - **Anchors:** A47-L; D39-L, D84-L (to retire), D132-L, D133-L; I64-L, I65-L. +- **Confirmation (2026-08-03):** an independent architecture review re-derived this arc unprompted as the top structural priority (split roots: `brunch-tui.ts` raw `SessionEventRelay` vs `LiveSessionHost`); it also flagged `workspace-session-coordinator.ts` breadth (782 lines, 27 interface/type declarations) — that decomposition rides this arc, not a separate frontier. ### deterministic-orientation — ◐ active diff --git a/memory/SPEC.md b/memory/SPEC.md index 6f761fcaa..3806adc9b 100644 --- a/memory/SPEC.md +++ b/memory/SPEC.md @@ -957,6 +957,7 @@ The first required probe is M0: after manual TUI interaction, a checker proves ` | Small semantic-judge calibration set | Initial human labels can catch gross scorer mismatch but cannot establish stable validity across domains, rubrics, or models. | Retain atomic disagreements and evaluator stamps; expand labels when disagreement is material or a new domain/rubric enters. | | Foreground-only first trajectory | The initial consequential-fact tracer does not require complete sealed-subagent ancestry. | Trigger the `agent-tracing` spike when a verification claim depends on child-span attribution that JSONL/current events cannot reconstruct. | | Competitor internals are opaque | Claude Code and Cursor cannot be expected to expose Brunch-equivalent directive or span detail. | Keep the common benchmark black-box and outcome-based; treat Brunch trace enrichment as diagnostic only, never as a comparative score advantage. | +| No deadness oracle in the gate | Dead code, unused dependencies, and orphaned assets are detected only by episodic agent sweeps; no `check`/CI step polices them. Reference-scan sweeps also produce false positives on artifacts with out-of-graph consumers (CI `ripgrep` is provisioned for spawned-agent grep reads per FE-1241, yet greps as unused) and can target seams that `TOPOLOGY.md`/PLAN declare intentional. | Sweeps must apply the out-of-graph-consumers and copy-not-import lenses in `ln-review`'s contract catalog (provenance via `git log -S`, canonical-doc cross-reference) before any delete. Candidate repair when debt volume warrants: wire the currently-unwired `knip.jsonc` into `npm run check` with an allowlist for topology stubs and ambient artifacts, or delete the stub (the unwired `konsistent` script shares this fault). | ### Acceptance Criteria From 0f89d03bae03d4a1b8e922b402e9a3e978a0fc0a Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 18:09:18 +0200 Subject: [PATCH 03/35] FE-1311: Admit integrity-cleanup frontier to PLAN Coverage-shaped earned sweep over the verified 2026-08-03 induction findings: reduction-review deletion batch (with corrections), copy-not- import predicate consolidation, roster-drift repairs, and the knip wire-vs-delete decision. Sequenced Parallel / Low-conflict. Co-Authored-By: Claude Fable 5 --- memory/PLAN.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/memory/PLAN.md b/memory/PLAN.md index e38173e61..3f3cc109d 100644 --- a/memory/PLAN.md +++ b/memory/PLAN.md @@ -68,6 +68,7 @@ Older completion history and archived completed frontier definitions live in [`d ### Parallel / Low-conflict - `capture-ledger-tracer` — pickup-ready proving follow-on to the completed `agent-control-plane-closure`: compare current ingest conduct with a versioned four-section capture ledger over one fixed mixed-source mission, using separate masked outcome and unblinded conduct judgments. Definition below. +- `integrity-cleanup` — coverage-shaped earned sweep over the verified 2026-08-03 induction findings: the reduction-review deletion batch (with its corrections) plus copy-not-import predicate consolidation and roster-drift repairs. Buildable-now; low-conflict with the FE-1187 stack. Definition below. ### Horizon @@ -190,6 +191,25 @@ Legacy link target; see Horizon. - **Verification:** inner prompt/resource composition, stable intervention identity, contamination negatives, graph legality, settlement/routing, and packet-schema tests; middle deterministic replay plus matched real-provider actor runs; outer criterion-level human adjudication of masked outcome and unblinded conduct drafts before promotion. - **Traceability:** D99-L, D131-L, A22-L, A34-L, A40-L; FE-1210 split-judgment evidence architecture. +### integrity-cleanup + +- **Name:** Integrity cleanup sweep — verified deletion batch + copy-not-import predicate consolidation +- **Linear:** [FE-1311](https://linear.app/hash/issue/FE-1311/integrity-cleanup-sweep-verified-deletion-batch-and-predicate) +- **Branch:** `ln/fe-1311-integrity-cleanup`; low-conflict with the FE-1187 stack. +- **Kind:** coverage-shaped closure batch over the closed 2026-08-03 induction findings inventory (reduction review + architecture review, both independently verified; see `ln-review` contract catalog entries graduated 2026-08-03). +- **Certainty:** earned; a row that reveals a real unknown regresses to proving individually and stops per sweep discipline. +- **Classification:** buildable-now. +- **Boundary:** in — the verified reduction-review deletion/shrink items, predicate consolidations (executor state predicates, `canonicalPath`, `pathExists`), roster-drift repairs, the CI-ripgrep name-the-contract comment, and the knip wire-vs-delete decision. Out — the Notion/PetriNet direction, all shared-session-host work (`workspace-session-coordinator.ts` decomposition rides that arc), and any new abstraction beyond one shared module per predicate family. +- **Deletes / retires:** parked consequential-fact campaign; pre-FE-1163 schema snapshots; committed Oxc schema copies; inert tools `present_alternatives` / `execute_plan_outline_artifact` / `execute_plan_draft_artifact` with their components/tests; unused dev barrels/wrappers/CLI helpers; `row-schemas.ts` plus `drizzle-typebox`/`@sinclair/typebox`; TOON wrappers plus dep; `stringify-tree`/`lodash.flatten`; the deterministic-exchange minting chain; duplicate walkthrough PNGs; test-only production modules **after** same-row `TOPOLOGY.md` reconciliation (`run-auto-replan-policy`, `drawer-card`, packet redaction, accessibility contract, plan output). +- **Canonicalizes:** one executor state-predicates owner (`stringArraysEqual` ×4 plus terminal-summary/marking semantics across `orchestrate.ts`/`observer-read.ts`/`petri-events.ts`/`petri-replay.ts`); one shared `canonicalPath` helper (three `git-*-port.ts` files, `worktree.ts`, `run-execution-authority.ts`); one `pathExists` test helper (22 copies); authority-map keys from the `tool-names.ts` union (`run-execution-authority.ts:128,131`); the orphan `'present_alternatives'` literal removed from `transcript-context.ts:26`. +- **Locks in:** deadness verdicts are gated by out-of-graph-consumer checks (the CI ripgrep install line names its FE-1241 spawned-agent consumer in a comment); roster surfaces are type-coupled to `tool-names.ts`; knip either enforces in `npm run check` or its stub is deleted — discharging or explicitly re-affirming the SPEC blind spot "No deadness oracle in the gate". +- **Constraints (induction corrections):** CI ripgrep is **not** deletable; `src/dev` is already build-excluded, so frame the probes build-exclusion row accordingly; the deps→`devDependencies` move verifies the published surface (`npm pack` / `check:release-pack`), never the repo import graph; intentional topology stubs are not deletion candidates on unusedness alone (AGENTS.md carve-out). +- **Inventory authority:** `memory/cards/integrity-cleanup--sweep-ledger.md` (`Mode: sweep`), authored at scope time from the two 2026-08-03 induction reports. +- **Aggregate DoD:** no required row remains `spec`/`new`/`partial`; `npm run verify:full` green (executor seams are touched); changeset recorded (published dependency set changes); no `TOPOLOGY.md`, `treedocs.yaml`, or doc teaches a retired module. +- **Verification:** per-row `npm run verify`; `verify:full` before tie-off; deletion rows witnessed by import-graph absence **plus** the out-of-graph checks (`git log -S` provenance, TOPOLOGY/treedocs cross-reference); consolidation rows are behavior-preserving (existing tests green, no semantics change). +- **Why now / unlocks:** removes ~7k LOC and 4 dependencies of navigation noise before the shared-session-host arc enters the same subtrees; the executor predicate consolidation removes writer/reader drift risk under `orchestrate`/`observer-read` ahead of that arc; the evidence is fresh and verified now. +- **Traceability:** SPEC §Acknowledged Blind Spots "No deadness oracle in the gate"; `ln-review` contract-lens catalog (out-of-graph-consumers, copy-not-import — both 2026-08-03); FE-1241 (ripgrep provenance); FE-1163 (superseded snapshots); AGENTS.md §development phase posture, §intentional topology stubs. + ## Dependencies ```text @@ -220,6 +240,11 @@ parallel: capture-ledger-tracer depends_on: completed agent-control-plane-closure reuses: FE-1208 evaluator/report primitives | FE-1210 actor + split judgment + integrity-cleanup + source: 2026-08-03 review inductions (reduction + architecture batches) + deletes: parked campaigns | inert tools | committed derivable artifacts | dead wrappers + 4 deps + canonicalizes: executor state predicates | canonicalPath | tool-name-keyed rosters + guarded_by: out-of-graph-consumer checks + same-row TOPOLOGY reconciliation ka_evidence_queue: host-landing (FE-1201) From 71a0ec455fe0e856dec9ab37092dcbc278ca656d Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 18:12:52 +0200 Subject: [PATCH 04/35] FE-1311: Scope the integrity-cleanup sweep ledger Closed 21-row inventory from the two 2026-08-03 induction reports: deletions & packaging (15 rows, 2 deferred), predicate consolidation & roster integrity (5 rows, 1 deferred), and the knip wire-vs-delete guardrail decision. Every deletion row carries the out-of-graph-consumer checks and same-row TOPOLOGY/treedocs reconciliation. Co-Authored-By: Claude Fable 5 --- memory/PLAN.md | 2 +- .../cards/integrity-cleanup--sweep-ledger.md | 70 +++++++++++++++++++ 2 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 memory/cards/integrity-cleanup--sweep-ledger.md diff --git a/memory/PLAN.md b/memory/PLAN.md index 3f3cc109d..8da8e695e 100644 --- a/memory/PLAN.md +++ b/memory/PLAN.md @@ -204,7 +204,7 @@ Legacy link target; see Horizon. - **Canonicalizes:** one executor state-predicates owner (`stringArraysEqual` ×4 plus terminal-summary/marking semantics across `orchestrate.ts`/`observer-read.ts`/`petri-events.ts`/`petri-replay.ts`); one shared `canonicalPath` helper (three `git-*-port.ts` files, `worktree.ts`, `run-execution-authority.ts`); one `pathExists` test helper (22 copies); authority-map keys from the `tool-names.ts` union (`run-execution-authority.ts:128,131`); the orphan `'present_alternatives'` literal removed from `transcript-context.ts:26`. - **Locks in:** deadness verdicts are gated by out-of-graph-consumer checks (the CI ripgrep install line names its FE-1241 spawned-agent consumer in a comment); roster surfaces are type-coupled to `tool-names.ts`; knip either enforces in `npm run check` or its stub is deleted — discharging or explicitly re-affirming the SPEC blind spot "No deadness oracle in the gate". - **Constraints (induction corrections):** CI ripgrep is **not** deletable; `src/dev` is already build-excluded, so frame the probes build-exclusion row accordingly; the deps→`devDependencies` move verifies the published surface (`npm pack` / `check:release-pack`), never the repo import graph; intentional topology stubs are not deletion candidates on unusedness alone (AGENTS.md carve-out). -- **Inventory authority:** `memory/cards/integrity-cleanup--sweep-ledger.md` (`Mode: sweep`), authored at scope time from the two 2026-08-03 induction reports. +- **Inventory authority:** [`memory/cards/integrity-cleanup--sweep-ledger.md`](cards/integrity-cleanup--sweep-ledger.md) (`Mode: sweep`), authored 2026-08-03 from the two induction reports. Current execution pointer: that ledger. - **Aggregate DoD:** no required row remains `spec`/`new`/`partial`; `npm run verify:full` green (executor seams are touched); changeset recorded (published dependency set changes); no `TOPOLOGY.md`, `treedocs.yaml`, or doc teaches a retired module. - **Verification:** per-row `npm run verify`; `verify:full` before tie-off; deletion rows witnessed by import-graph absence **plus** the out-of-graph checks (`git log -S` provenance, TOPOLOGY/treedocs cross-reference); consolidation rows are behavior-preserving (existing tests green, no semantics change). - **Why now / unlocks:** removes ~7k LOC and 4 dependencies of navigation noise before the shared-session-host arc enters the same subtrees; the executor predicate consolidation removes writer/reader drift risk under `orchestrate`/`observer-read` ahead of that arc; the evidence is fresh and verified now. diff --git a/memory/cards/integrity-cleanup--sweep-ledger.md b/memory/cards/integrity-cleanup--sweep-ledger.md new file mode 100644 index 000000000..ac9d354ed --- /dev/null +++ b/memory/cards/integrity-cleanup--sweep-ledger.md @@ -0,0 +1,70 @@ +# Integrity cleanup sweep — ledger + +Frontier: integrity-cleanup +Status: active +Mode: sweep +Created: 2026-08-03 + +## Orientation + +- Containing seam: repo-wide integrity/deadness — deletion of verified-dead artifacts, consolidation of contract-bearing predicates, roster type-coupling. Frontier: `integrity-cleanup` ([FE-1311](https://linear.app/hash/issue/FE-1311/integrity-cleanup-sweep-verified-deletion-batch-and-predicate)), branch `ln/fe-1311-integrity-cleanup`. +- Inventory source: two 2026-08-03 `ln-induct` reports (reduction review + architecture review), every load-bearing claim independently verified; corrections are binding constraints (see PLAN definition §Constraints). +- Posture: **earned** (inherited from `integrity-cleanup`); per-row Fill downgrades to `proving` where a packaging unknown remains. A row that reveals a real unknown mid-build stops per sweep discipline. +- Main open risk: a deletion target with an out-of-graph consumer the induction missed → every deletion row's oracle includes the out-of-graph checks (`git log -S` provenance; `src/**/TOPOLOGY.md` + `src/treedocs.yaml` + `memory/PLAN.md` cross-reference) before `rm`. + +## Cold-start reads + +``` +- memory/PLAN.md — frontier: integrity-cleanup (boundary, constraints, aggregate DoD) +- memory/SPEC.md — §Acknowledged Blind Spots "No deadness oracle in the gate" +- .agents/skills/ln-review/references/contract-lenses.md — the two 2026-08-03 entries + (out-of-graph consumers; copy-not-import predicates) — the audit discipline deletion rows must apply +- AGENTS.md — §intentional topology stubs (carve-out), §development phase posture (deletion rigor) +``` + +## Cross-cutting obligations + +- Every deletion row runs the out-of-graph-consumer checks before deleting, and reconciles `TOPOLOGY.md` / `treedocs.yaml` references **in the same row**. +- Intentional topology stubs (`export {}` + design comment) are not deletion candidates on unusedness alone. +- Consolidation rows are behavior-preserving: existing suites stay green, no semantics change rides along. +- Tie-off: `npm run verify:full` (executor seams are touched) and a changeset (`npm run changeset` — the published dependency set changes). + +## A. Deletions & packaging + +| Capability | Status | Req | Fill | Owner / next | Notes | +| --- | --- | --- | --- | --- | --- | +| Pre-FE-1163 schema snapshots removed; baseline test asserts current provider constraints directly | `spec` | ● | earned | `src/.pi/extensions/__tests__/` (fixtures + `tool-schema-baseline.ts`) | Oracle: rewritten test green without snapshot fixtures; −2,339 LOC | +| Parked consequential-fact campaign deleted (resurrect from git if it re-enters PLAN) | `spec` | ● | earned | `src/dev/consequential-fact-*` | Not in PLAN (verified); dev-lane; oracle: `npm run test` green, no dangling imports | +| Committed Oxc schema copies deleted | `spec` | ● | earned | `@types/oxfmt_configuration_schema.json`, `@types/oxlint_configuration_schema.json` | Verified: `.oxlintrc.json`/`.oxfmtrc.json` `$schema` point at `node_modules`; oracle: `npm run check` green | +| Test-only production modules deleted with same-row TOPOLOGY reconciliation | `spec` | ● | earned | `run-auto-replan-policy.ts` (`src/executor/TOPOLOGY.md`), `drawer-card.tsx` (`src/web/TOPOLOGY.md`), packet redaction, a11y contract, plan output | Each target: confirm TOPOLOGY entry doesn't declare a live seam → delete module + tests + doc/treedocs mention, or keep and record why. Oracle: verify green + no `TOPOLOGY.md`/`treedocs.yaml` orphan reference | +| Inert tools deleted: `present_alternatives`, `execute_plan_outline_artifact`, `execute_plan_draft_artifact` + components/tests + all registry entries | `spec` | ● | earned | `src/.pi/components/alternatives.ts`, `src/.pi/extensions/executor/execute-*-artifact`, `tool-names.ts`, `run-execution-authority.ts`, `transcript-context.ts:26`, component-preview registry | Includes the orphan `'present_alternatives'` literal (already absent from `tool-names.ts` — drift realized). Pairs with row B3; −644 LOC | +| Unused barrels/wrappers/CLI helpers deleted | `spec` | ● | earned | `src/dev/index.ts`, `src/dev/end-to-end-comparison.ts`, `src/dev/faux-launcher.ts`, `src/.pi/extensions/shared/query-projection.ts`, `src/graph/validate-fixture.ts` (`src/graph/TOPOLOGY.md`), `src/web/queries/session.ts` | Out-of-graph check per file; −457 LOC | +| `row-schemas.ts` + `drizzle-typebox` + `@sinclair/typebox` deleted | `spec` | ● | earned | `src/db/row-schemas.ts`; `src/db/TOPOLOGY.md` + `src/graph/TOPOLOGY.md` reconciliation | −2 deps; changeset required | +| TOON wrappers + `@toon-format/toon` deleted | `spec` | ● | earned | `src/agents/shared/toon.ts` | No production renderer calls (verified); −1 dep | +| `stringify-tree` + `lodash.flatten` replaced by native recursive formatter | `spec` | ● | earned | `src/agents/shared/tree.ts` | Native replacement, not deletion — `renderTree` output identical (existing tests as oracle); −1 dep | +| Deterministic-exchange minting chain deleted (sequencing helper kept) | `spec` | ● | earned | `src/probes/deterministic-exchange-script.ts` | −100 LOC | +| `src/probes/**` excluded from production build | `spec` | ● | proving | `tsconfig.build.json` | Verified: non-test importers all in already-excluded `src/dev`. Oracle: `npm run build` green + probes absent from `dist/` + `check:release-pack` green | +| Six Vite-bundled web packages moved to `devDependencies` | `spec` | ● | proving | `package.json` | Unknown: published surface. Oracle: `npm pack` inspection — `dist-web` prebuilt, no runtime import of the six from published `dist/**`; `check:release-pack` green; changeset | +| CI ripgrep install line carries a name-the-contract comment | `spec` | ● | earned | `.github/workflows/test.yml:49` | NOT deletable — FE-1241 provisioned it for spawned-agent bounded grep reads. Comment names consumer + issue id | +| Unreferenced/duplicate walkthrough PNGs deleted | `spec` | ○ | earned | `testing/walkthroughs/` | Deferred: −1.15 MB, zero silent risk; fold in only if a same-directory row is already open | +| Nine recursive dir walkers → Node `readdir({recursive})` | `spec` | ○ | earned | `scripts/`, `src/**/__tests__/` | Deferred: loud class, no drift risk; opportunistic | + +## B. Predicate consolidation & roster integrity + +| Capability | Status | Req | Fill | Owner / next | Notes | +| --- | --- | --- | --- | --- | --- | +| One executor state-predicates owner; writer, reader authority, and replay import it | `spec` | ● | earned | new module under `src/executor/` (fractal sub-tree rules apply), imported by `orchestrate.ts`, `observer-read.ts`, `petri-events.ts`, `petri-replay.ts` | Consolidates `stringArraysEqual` ×4 + terminal-summary/marking predicates (`sanitizeTerminalSummary`, `mergeTerminalSummary`, `terminalMatchesPayload`, `petriMarkingsEqual`, …). Behavior-preserving; oracle: existing executor suites green, duplicate definitions gone (`rg 'function stringArraysEqual' src` → 1) | +| One shared `canonicalPath` helper across git ports + executor authority | `spec` | ● | earned | shared fs helper; consumers: `src/app/git-{run-promotion,slice-integration,host-land}-port.ts`, `src/executor/worktree.ts`, `src/executor/run-execution-authority.ts` | Copies byte-identical today (verified) — pure lift. Oracle: suites green, `rg 'function canonicalPath' src` → 1 | +| Authority map keyed by the `tool-names.ts` union, not `Record` | `spec` | ● | earned | `src/executor/run-execution-authority.ts:128,131` | Both drift directions become compile errors. Oracle: type-check (oxlint tsgolint) fails on a key not in the union — witnessed by the inert-tool deletion row forcing entry removal | +| One `pathExists` helper (22 copies: 16 executor tests, 5 executor production, 1 app) | `spec` | ● | earned | shared helper; `src/executor/`, `src/app/` | Oracle: `rg 'function pathExists' src scripts` → 1; suites green | +| `defaultRunId` consolidation | `spec` | ○ | earned | `src/probes/` ×6, `src/dev/` ×1 | Deferred: dev-lane only (build-excluded), low stakes | + +## C. Guardrail decision + +| Capability | Status | Req | Fill | Owner / next | Notes | +| --- | --- | --- | --- | --- | --- | +| knip wired into `npm run check` (with topology-stub/ambient allowlist) **or** stub deleted | `new` | ● | proving | decision needed: `knip.jsonc`, `package.json` | Micro-decision first (wire vs delete; the unwired `konsistent` script rides the same decision). Either outcome discharges or re-affirms SPEC blind spot "No deadness oracle in the gate" — update the blind-spot Mitigation cell in the same row | + +## Aggregate DoD + +No `●` row remains `spec` / `new` / `partial`; `npm run verify:full` green; changeset committed; no `TOPOLOGY.md`, `treedocs.yaml`, or doc teaches a retired module; SPEC blind-spot mitigation cell reflects the row-C outcome. From e2af7af37c4419fe97bb952bf58a6fcf925b41b2 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 18:14:24 +0200 Subject: [PATCH 05/35] FE-1311: Record decide-during-build disposition for the knip row Co-Authored-By: Claude Fable 5 --- memory/cards/integrity-cleanup--sweep-ledger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/memory/cards/integrity-cleanup--sweep-ledger.md b/memory/cards/integrity-cleanup--sweep-ledger.md index ac9d354ed..06dc4e5f6 100644 --- a/memory/cards/integrity-cleanup--sweep-ledger.md +++ b/memory/cards/integrity-cleanup--sweep-ledger.md @@ -63,7 +63,7 @@ Created: 2026-08-03 | Capability | Status | Req | Fill | Owner / next | Notes | | --- | --- | --- | --- | --- | --- | -| knip wired into `npm run check` (with topology-stub/ambient allowlist) **or** stub deleted | `new` | ● | proving | decision needed: `knip.jsonc`, `package.json` | Micro-decision first (wire vs delete; the unwired `konsistent` script rides the same decision). Either outcome discharges or re-affirms SPEC blind spot "No deadness oracle in the gate" — update the blind-spot Mitigation cell in the same row | +| knip wired into `npm run check` (with topology-stub/ambient allowlist) **or** stub deleted | `spec` | ● | proving | `knip.jsonc`, `package.json` — decide during build (user, 2026-08-03) | Builder attempts wiring first; if the allowlist proves noisy or slow, fall back to deleting the stub and record why. The unwired `konsistent` script rides the same outcome. Either way, update the SPEC blind-spot Mitigation cell ("No deadness oracle in the gate") in the same row | ## Aggregate DoD From aa439a8487772c02c605712dcb475607ffa0c7c1 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 18:59:40 +0200 Subject: [PATCH 06/35] Add planning substrate assessment Amp-Thread-ID: https://ampcode.com/threads/T-019fc869-d922-75a1-8239-48180094ce9d Co-authored-by: Amp --- docs/README.md | 5 + .../planning-record-substrate-assessment.md | 575 ++++++++++++++++++ 2 files changed, 580 insertions(+) create mode 100644 docs/planning/planning-record-substrate-assessment.md diff --git a/docs/README.md b/docs/README.md index 7101f243e..a1db8b14f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,11 @@ planning state: - [`docs/praxis/manual-testing.md`](./praxis/manual-testing.md) — outer-loop manual testing protocol for seeded workbenches, TUI + web sidecar observation, evidence capture, and slice-specific checks. - [`docs/praxis/seeded-dev-rpc.md`](./praxis/seeded-dev-rpc.md) — set up a seeded local Brunch workspace, inspect it over launcher-backed RPC reads, curate fixture truth through the explicit local mutate seam, and run the product-path fixture curation tracer. +## Planning notes + +- [`planning/planning-record-substrate-assessment.md`](./planning/planning-record-substrate-assessment.md) — assessment of repo-native and out-of-band planning substrates for hierarchical `spec -> plan -> task` records, with hybrid designs for local source-of-truth docs plus tracker-based execution. +- [`planning/pi-native-integration-opportunities.md`](./planning/pi-native-integration-opportunities.md) — working synthesis of Pi-native seams that may simplify or reshape future frontier planning. + ## Behavioral kernels [`docs/design/BEHAVIORAL_KERNELS.md`](../design/BEHAVIORAL_KERNELS.md) is diff --git a/docs/planning/planning-record-substrate-assessment.md b/docs/planning/planning-record-substrate-assessment.md new file mode 100644 index 000000000..540ebace6 --- /dev/null +++ b/docs/planning/planning-record-substrate-assessment.md @@ -0,0 +1,575 @@ +# Planning record substrate assessment + +Status: working assessment and design note +Date: 2026-08-03 + +> This note assesses candidate substrates for hierarchical `spec -> plan -> task` +> records under Brunch's current collaboration constraints. It is not a second +> plan and it does not supersede [`memory/SPEC.md`](../../memory/SPEC.md) or +> [`memory/PLAN.md`](../../memory/PLAN.md) by itself. Its output is a design +> recommendation about where durable truth, mutable queue state, and execution +> notes should live so multi-human + multi-agent work stops colliding on the +> same few files. + +## Executive summary + +Brunch's current `memory/` shape is fragile because it concentrates both stable +design truth and fast-moving work-queue state into two shared hotspot files: + +- [`memory/SPEC.md`](../../memory/SPEC.md) — 971 lines in the 2026-08-03 audit, + with 173 historical touches. +- [`memory/PLAN.md`](../../memory/PLAN.md) — 275 lines in the same audit, with + 188 historical touches. + +The best available move is not merely "pick a better tracker." The real design +requirement is: + +> unrelated work should touch unrelated records; same-record collisions should +> be loud and explicit instead of silently interleaving inside one large shared +> document. + +The assessed options sort into three families: + +| Option | Best at | Main weakness against Brunch's current need | +| --- | --- | --- | +| [`tk`](https://github.com/h2oai/tk) | Git-local, one-file-per-record planning/task state | Sparse model; would need local conventions for richer spec/planning semantics | +| [`beans`](https://github.com/henriquebastos/beans) | Open agent-oriented graph semantics | Git sync goes through a hot journal, not one file per record | +| [`git-issues`](https://steviee.github.io/git-issues/) | Git-native issue files and agent workflow | Sequential IDs and weaker hierarchy than the current need | +| [`fp`](https://fp.dev/docs/) | Richest agent workflow and extension model | Issue state is local-first but not repo-first | +| [`linear` CLI](https://github.com/schpet/linear-cli) | Shared team coordination with no Git merge conflicts on queue state | Queue state no longer branches with the code by default | + +For the original comparison criteria (`git` reviewability, worktree safety, +branch/checkouts, low-conflict collaboration), the recommendations are: + +1. **Best pure git-first substrate:** `tk` +2. **Best open graph/workflow substrate:** `beans` +3. **Best team-first hybrid for Brunch specifically:** local spec docs + Linear +4. **Not recommended for this requirement:** `git-issues` and `fp` + +For Brunch itself, the best near-term move is probably **not** a full tracker +replacement. The repo is already invested in local docs and already uses +Linear/Graphite discipline at the frontier level. The least disruptive and most +conflict-reducing design is therefore a **hybrid**: + +- keep durable spec/design truth in repo-local markdown; +- move mutable frontier/task queueing into a tracker with better collaboration + semantics; +- stop treating [`memory/PLAN.md`](../../memory/PLAN.md) as the live shared queue; +- progressively split [`memory/SPEC.md`](../../memory/SPEC.md) into smaller + initiative- or frontier-scoped source files. + +Two hybrid shapes are credible: + +1. **Git-first hybrid:** local specs + `tk` for frontier/task execution. +2. **Team-first hybrid:** local specs + Linear for frontier/task execution. + +Given Brunch's existing Linear discipline and multi-human collaboration, the +team-first hybrid is the strongest default for this repo. The git-first hybrid +is still the better answer for smaller or more solitary repos that want tracker +state to branch with the code. + +## Current pressure in `memory/` + +The 2026-08-03 audit of [`memory/`](../../memory/) surfaced a structural problem, +not merely a process problem. + +### What is currently hot + +- [`memory/SPEC.md`](../../memory/SPEC.md) carries global doctrine, live + architecture decisions, current-state pointers, verification posture, and + future-direction residue. +- [`memory/PLAN.md`](../../memory/PLAN.md) carries active sequencing, + dependencies, frontier definitions, and live status churn. +- [`memory/cards/`](../../memory/cards/) already has a better conflict shape: + smaller, topic-local files with lower blast radius. + +### Failure modes of the current shape + +1. **Shared hotspot edits.** Two people working on unrelated frontiers can still + collide because both must touch the same queue file. +2. **Narrative truth and mutable queue state are conflated.** Stable design + claims and rapidly changing assignment/ordering/status churn coexist in one + place. +3. **Derived views are hand-maintained.** Sequencing summaries, active lists, + and near-horizon order are curated manually rather than projected from a more + local substrate. +4. **Large-file merges are semantically risky.** Even when Git merges cleanly, + the resulting prose can reflect two incompatible edits whose contradiction is + not obvious. + +### Positive signal already present + +The files in [`memory/cards/`](../../memory/cards/) demonstrate the shape that +scales better: + +- one record per file; +- focused ownership; +- explicit local context; +- limited merge blast radius. + +The redesign should make more of the planning substrate look like that. + +## Evaluation criteria + +The options below are judged by the properties Brunch actually needs. + +### 1. Merge locality + +If two unrelated changes create or update separate records, they should land in +separate files or separate tracker entities. A good system makes same-record +conflicts loud, not hidden. + +### 2. Worktree and checkout behavior + +The workflow needs to survive stacked branches, parallel worktrees, and +different checkouts without ambiguous ownership. + +### 3. Hierarchy semantics + +Brunch needs at least three conceptual layers: + +- durable spec / initiative truth; +- plan / frontier / major subproblem; +- execution task / slice / evidence beat. + +### 4. Agent usability + +The substrate should support agent-driven decomposition, pickup, updating, and +status inspection without excessive bespoke glue. + +### 5. Compatibility with repo-local docs + +Some projects already have strong local design docs. The ideal solution should +let those remain authoritative without forcing a second speculative doctrine. + +### 6. Team collaboration + +The system should make it hard for two collaborators to clobber each other, +whether they are humans, agents, or one of each. + +### 7. Extensibility and hackability + +If the model is imperfect, can we extend it by configuration, wrappers, or a +small amount of code rather than a platform rewrite? + +## Assessed options + +## `tk` + +### Strengths + +- One markdown file per ticket under `.tickets/` gives strong merge locality. +- Short random IDs avoid the sequential-ID collision problem. +- Parent/child hierarchy plus dependency edges are enough to model + `spec -> frontier -> task` with conventions. +- The entire state rides with the branch and checkout because the records are + ordinary files. +- It is small enough to understand and adapt quickly. + +### Weaknesses + +- The schema is sparse and fixed. +- There is no first-class spec ontology; richer meaning must come from naming, + layout, and wrapper conventions. +- There is no built-in collaboration or notification layer beyond Git itself. + +### Assessment + +`tk` is the best pure git-first choice because it optimizes the property Brunch +currently lacks most: **record-local merges**. It does not have the richest +model, but its failure mode is good. Two unrelated tasks usually become two +different files. + +### Best fit + +- solo or mostly-solo projects; +- agent-heavy repos that want tracker state to branch with the code; +- teams willing to encode a thin house convention on top of a simple substrate. + +## `beans` + +### Strengths + +- Strongest open semantic model of the evaluated tools. +- Clean distinction between parent/child hierarchy and blocking dependencies. +- Transitive ready-work computation is valuable for agents. +- Claim/release is a pragmatic multi-agent coordination primitive. +- Custom bean types mean `spec`, `plan`, and `task` can be explicit. + +### Weaknesses + +- Live state is SQLite; Git sync goes through a committed JSONL journal. +- The journal is a collaboration hotspot compared with one-file-per-record + systems. +- Extensibility is mostly in-source rather than via plugins. + +### Assessment + +`beans` is the best option if semantic quality matters more than Git merge +topology. Its graph model is notably better than `tk`, but the journal-based +Git story is weaker for the exact problem Brunch is trying to reduce. + +### Best fit + +- local-first teams who want a richer agent/task graph; +- repos comfortable treating Git as journal transport rather than as the direct + record surface; +- teams willing to own a small Python substrate. + +## `git-issues` + +### Strengths + +- Files live directly in `.issues/` and move with the code. +- Agent-friendly `next`, `claim`, `done`, relation sync, and JSON output. +- Good for ordinary issue tracking with dependency links. + +### Weaknesses + +- Sequential integer IDs are a poor fit for parallel branch-local issue creation. +- Hierarchy is weaker than the current `spec -> plan -> task` need. +- Relation symmetry means one conceptual change can touch multiple files. + +### Assessment + +`git-issues` is well aligned with Git, but less well aligned with the actual +hierarchical planning problem. It improves over the current monolithic docs in +some ways, yet it still leaves Brunch with awkward hierarchy and branch-creation +conflict pressure. + +### Best fit + +- repos that want lightweight git-native issues rather than a planning system. + +## `fp` + +### Strengths + +- Richest agent workflow of the evaluated tools. +- Comments, context loading, commit/diff association, review UI, and a real + extension model are substantial advantages. +- Strong customization surface via TypeScript lifecycle extensions. + +### Weaknesses + +- Issue state is local-first but not repo-first. +- The public source linked from the docs exposes integrations and skills, not + the core issue engine. +- Planning state is therefore less inspectable and less naturally code-reviewed + than file-native solutions. + +### Assessment + +`fp` is the most capable product, but it is not the best answer to the specific +question "how do we keep hierarchical planning records merge-friendly inside +Git?" It is a stronger answer to "how do we give agents a better workflow tool?" + +### Best fit + +- teams optimizing for agent UX over Git-native planning state; +- repos comfortable with planning data living outside the code tree. + +## Linear CLI + +### Relevant capabilities + +The installed CLI already exposes the surfaces needed for a serious planning +basis: + +- `linear initiative *` +- `linear project *` +- `linear milestone *` +- `linear issue create --parent ...` +- `linear issue relation add blocked-by|blocks|related|duplicate ` +- `linear issue comment *` +- `linear document *` +- branch-aware helpers such as `linear issue id`, `linear issue start`, and + `linear issue pull-request` + +### Strengths + +- Shared state lives outside Git, so plan/task updates do not produce merge + conflicts in the repo. +- Parent issues and issue relations are enough for a frontier/task graph. +- Initiatives, projects, and milestones give multiple hierarchy levels. +- The CLI is scriptable and already part of Brunch's operating discipline. +- Multi-human collaboration, assignee visibility, and notification behavior are + already solved by the platform. + +### Weaknesses + +- Queue state does not branch with the code. A feature branch does not + automatically carry an alternate plan state. +- Local spec/design truth can drift from Linear if the ownership boundary is not + explicit. +- Linear Documents are collaborative, but they are not Git-reviewed repo-local + files. + +### Assessment + +Linear is the strongest out-of-band answer if the main pain is **shared mutable +queue state** rather than **branch-local planning state**. It removes Git merge +conflicts by moving the queue elsewhere, and Brunch already has established FE / +Graphite / Linear conventions. + +The trade is important: you are no longer asking Git to represent the current +task graph. For Brunch, that is probably acceptable for frontier/task execution. +It is much less acceptable for canonical design truth. + +### Best fit + +- multi-human teams already using Linear; +- repos that want repo-local specs but shared cloud-backed planning/execution; +- teams that value collaboration hygiene over branch-native plan divergence. + +## Recommendation matrix + +| Situation | Best fit | Why | +| --- | --- | --- | +| Need tracker state to branch with the code | `tk` | One file per record; Git remains the source of truth | +| Need the richest open graph semantics | `beans` | Better task/dependency model than the others | +| Need the best agent workflow product | `fp` | Strongest workflow and extension surface | +| Need a low-conflict team queue with current Brunch conventions | Linear hybrid | Avoids repo merge conflicts on mutable queue state | + +For Brunch specifically, the default recommendation is: + +> keep local docs for durable truth; move shared frontier/task queueing further +> into Linear; stop treating `PLAN.md` as the canonical live queue; progressively +> split `SPEC.md` into smaller local documents. + +## Design rules that matter more than tool choice + +These rules hold whether the repo chooses `tk`, Linear, or something else. + +### 1. Separate stable truth from mutable queue state + +Stable design truth and rapidly changing status/order/assignment should not live +in the same file or the same record. + +### 2. Use one file per durable concept when staying local + +If a spec or architecture note remains repo-local, it should be scoped to one +initiative, frontier, or other narrow durable concept. Monoliths accumulate +semantic merge risk even when task tracking moves elsewhere. + +### 3. Prefer derived overviews to hand-maintained rollups + +Human overviews are useful, but they should be projected from local records or +tracker entities whenever possible. The more often people edit the overview, the +hotter it becomes. + +### 4. Keep branch-local scratch separate from shared canon + +Execution notes, private experiments, or branch-local checkpoints can live in +cards, comments, or scratch files. They should not force edits to the shared +global queue. + +### 5. Cross-link with stable IDs + +Whatever the substrate, every durable spec and every mutable frontier/task item +should have a stable cross-reference: + +- spec doc path or local ID +- tracker ID (`TK-...`, `FE-...`, etc.) +- branch/PR reference where applicable + +### 6. Prefer loud collisions to silent interleaving + +The goal is not zero conflicts. The goal is that when two collaborators do touch +the same record, the conflict is obvious and semantically local. + +## Hybrid design A — Git-first (`tk` + local specs) + +This is the right design for repos that want Git to remain the planning +substrate. + +### Shape + +```diagram +┌─────────────────────────────┐ +│ Repo-local spec docs │ +│ one file per initiative │ +└──────────────┬──────────────┘ + │ references + ▼ +┌─────────────────────────────┐ +│ .tickets/ │ +│ epic/feature/task records │ +│ parent + deps + notes │ +└──────────────┬──────────────┘ + │ drives + ▼ +┌─────────────────────────────┐ +│ Branch / worktree execution │ +│ commits, PRs, evidence │ +└─────────────────────────────┘ +``` + +### Proposed mapping + +- spec doc = local markdown file under a split spec directory +- `tk` epic = frontier / major execution package +- `tk` feature or task = slice, evidence beat, or implementation unit +- `parent` = decomposition +- `deps` = blocking order + +### Advantages + +- best Git merge locality; +- plan state branches naturally with the code; +- task graph is inspectable in PRs; +- no external system is required. + +### Costs + +- conventions must carry more meaning than the raw tool model; +- team-level discovery/notification is weaker than Linear; +- no existing Brunch operating discipline is built around `tk` today. + +### Best use + +- smaller repos; +- more solo or agent-centric work; +- teams that explicitly want planning state in the commit graph. + +## Hybrid design B — Team-first (Linear + local specs) + +This is the strongest default for Brunch. + +### Shape + +```diagram +┌─────────────────────────────┐ +│ Repo-local spec docs │ +│ one file per initiative │ +│ canonical design truth │ +└──────────────┬──────────────┘ + │ referenced from issue bodies + ▼ +┌─────────────────────────────┐ +│ Linear │ +│ initiative / milestone / │ +│ parent issue / child issue │ +│ relations / comments │ +└──────────────┬──────────────┘ + │ drives + ▼ +┌─────────────────────────────┐ +│ Branch / worktree execution │ +│ Graphite stacks, PRs, runs │ +└─────────────────────────────┘ +``` + +### Proposed ownership split + +- local markdown spec doc = canonical design truth +- Linear initiative / project / milestone = program-level grouping +- parent issue = frontier item +- child issue = execution task or evidence beat +- Linear comments = progress log, checkpoints, links to evidence +- local cards = branch-local scratch or scoped working notes, not shared queue + +### Why this fits Brunch + +- Brunch already requires a Linear issue per frontier item in + [`AGENTS.md`](../../AGENTS.md). +- The repo already uses Graphite branch conventions tied to those issues. +- The mutable queue can leave Git without sacrificing canonical repo-local spec + docs. +- Collaboration conflicts move from opaque markdown merges to explicit tracker + updates. + +### Costs + +- plan state is no longer branch-native; +- a discipline boundary must prevent drift between docs and tracker; +- some current `PLAN.md` affordances must move into tracker fields, comments, or + derived scripts. + +### Recommended Brunch mapping + +- keep [`memory/POSTURE.md`](../../memory/POSTURE.md) as repo-level posture; +- keep a reduced repo-level architectural register, but progressively split + large initiative-specific material out of [`memory/SPEC.md`](../../memory/SPEC.md); +- stop using [`memory/PLAN.md`](../../memory/PLAN.md) as the canonical mutable + queue; +- treat new frontier items as Linear parent issues with explicit child issues + for tasks/evidence when collaboration pressure warrants them; +- keep cards only where a branch-local execution note genuinely helps. + +## Why a full Linear migration is not the same as the hybrid + +Brunch should not simply move everything into Linear. + +### Why not + +- Canonical design truth benefits from Git review, nearby code context, and + branch-local experimentation. +- Large narrative specs and architecture notes belong with the codebase. +- Linear Documents are useful, but they do not replace repo-local source of + truth for this project's current working style. + +### Use Linear for + +- mutable shared queue state; +- ownership and assignment; +- parent/child task trees; +- dependencies and blocking; +- progress commentary; +- cross-human coordination. + +### Keep local markdown for + +- durable spec/design reasoning; +- architecture contracts; +- product lexicon and invariants; +- repo-reviewed proposals. + +## Proposed migration direction for Brunch + +This is a design direction, not an immediate rewrite order. + +### Phase 1 — stop growing the hotspot + +1. Treat [`memory/PLAN.md`](../../memory/PLAN.md) as a shrinking compatibility + surface rather than the forever queue. +2. Put new mutable frontier/task coordination primarily in Linear. +3. Avoid adding fresh branch- or assignee-churn to global local docs unless it + is truly canonical doctrine. + +### Phase 2 — split durable truth by scope + +1. Identify initiative- or frontier-scoped regions of + [`memory/SPEC.md`](../../memory/SPEC.md) that can become smaller local docs. +2. Keep only cross-cutting doctrine, lexicon, and stable architecture register + content in the repo-global file. +3. Prefer one durable concept per file. + +### Phase 3 — make rollups thinner or derived + +1. Replace hand-maintained active queue summaries with tracker projections or + lighter index files. +2. Keep local overview docs descriptive and low-churn. +3. Ensure the shared tracker, not a hand-edited monolith, answers "what is next" + and "who owns this right now". + +## Final recommendation + +For Brunch, the best default answer is: + +> **team-first hybrid:** repo-local spec/design docs for durable truth, Linear +> for mutable frontier/task execution, and progressive splitting of the current +> monolithic memory files. + +For other repos, the decision rule is simpler: + +- if the plan state itself must branch with the code, choose `tk`; +- if the team already lives in Linear and wants fewer collisions immediately, + choose the Linear hybrid; +- if richer graph semantics matter more than Git merge topology, choose + `beans`. + +The main conclusion is therefore not that Brunch picked the wrong tracker. It is +that **global planning monoliths are the wrong shape for collaborative, +multi-worktree agentic development**. Any replacement should first fix that +shape. From 542e13347160070cd302884145a51bc7ed4d9a79 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 20:24:18 +0200 Subject: [PATCH 07/35] FE-1311: Retire pre-FE-1163 tool-schema snapshots for direct provider-constraint assertions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The five pre-FE-1163 snapshot fixtures plus their normalizer froze a migration reference point that has since gone stale: the exchanges suite already carved out `ask` and `present_review_set`, and FE-1208 deleted the dev-mode baseline. Each family suite now asserts the constraint the snapshots were standing in for, through the production predicates in `shared/tool-schema.ts`: every registered schema carries adapter provenance (`hasToolParametersProvenance`) and passes `assertProviderLegalToolSchema`, with the family tool inventory pinned explicitly where the baseline keys had supplied it. The current-shape assertions the snapshots did not own — the review-set settlement fields and the ask questionnaire fields — are preserved verbatim. Reconciles SPEC I60-L, whose coverage cell cited the retired baselines. -2,339 LOC. No TOPOLOGY.md or treedocs.yaml reference existed (treedocs.yaml excludes __tests__). Co-Authored-By: Claude Fable 5 --- memory/SPEC.md | 2 +- .../cards/integrity-cleanup--sweep-ledger.md | 3 +- .../__tests__/brunch-data-context.test.ts | 16 +- ...brunch-data-elicitation-scratchpad.test.ts | 15 +- .../__tests__/brunch-data-graph.test.ts | 15 +- .../brunch-data-reconciliation.test.ts | 14 +- .../__tests__/exchanges-extension.test.ts | 29 +- .../context-tool-schemas.pre-fe-1163.ts | 28 - .../exchange-tool-schemas.pre-fe-1163.ts | 1020 -------------- .../graph-tool-schemas.pre-fe-1163.ts | 1173 ----------------- ...reconciliation-tool-schemas.pre-fe-1163.ts | 62 - .../scratchpad-tool-schemas.pre-fe-1163.ts | 41 - .../__tests__/tool-schema-baseline.ts | 15 - 13 files changed, 52 insertions(+), 2381 deletions(-) delete mode 100644 src/.pi/extensions/__tests__/fixtures/context-tool-schemas.pre-fe-1163.ts delete mode 100644 src/.pi/extensions/__tests__/fixtures/exchange-tool-schemas.pre-fe-1163.ts delete mode 100644 src/.pi/extensions/__tests__/fixtures/graph-tool-schemas.pre-fe-1163.ts delete mode 100644 src/.pi/extensions/__tests__/fixtures/reconciliation-tool-schemas.pre-fe-1163.ts delete mode 100644 src/.pi/extensions/__tests__/fixtures/scratchpad-tool-schemas.pre-fe-1163.ts delete mode 100644 src/.pi/extensions/__tests__/tool-schema-baseline.ts diff --git a/memory/SPEC.md b/memory/SPEC.md index 3806adc9b..1944ec377 100644 --- a/memory/SPEC.md +++ b/memory/SPEC.md @@ -386,7 +386,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c | I57-L | For every superseding proposal chain (`present_review_set`, `present_candidates`, `present_digest`), projection and capture consume only the accepted terminal payload. Digest feedback and superseded offers are not carriers; only a submitted digest-referencing questionnaire or confirmation contributes the runtime-copied final abstract and keyed answers. Cancelled/incomplete chains and rejected offers contribute no payload. | covered by the production recovery recognizer, digest questionnaire lifecycle/supersession proofs, sweep-window tests, legacy-terminal closure tests, and duplicate-carrier negative space | D28-L; D80-L, D81-L, D82-L, D106-L, D110-L | | I58-L | Every execute-mode lifecycle helper advances run metadata with at most one explicit, declared side effect; agent/test/promotion/landing effects are delegated to injected `ExecutionPorts`; the FE-1166 `empty_dir` exception may run direct git initialization only inside the isolated run worktree and must fail without advancing metadata when that initialization fails; no executor helper mutates the graph; host mutation is limited to the user-confirmed landing apply in `landing.ts` (FE-1201), reachable only through the `/brunch:land` confirm flow, and failed or refused landings advance no metadata and leave the host/target as found. | covered (`src/executor/__tests__/` per-helper suites with `fake-ports.ts`; app-layer port tests in `src/app/__tests__/` incl. real-temp-git-repo host-landing integrate/materialize/conflict/failure-restoration proofs in `git-host-land-port.slow.test.ts`; `worktree.slow.test.ts` covers `empty_dir` isolation, exact-root repair, and stale marker cleanup). Formerly cited in executor code as "I56-L" (collision with the scratchpad I56-L); reassigned 2026-07-06. | D111-L, D112-L | | I59-L | No provider turn fires without resolvable provider auth (re-keyed 2026-07-13 by D123-L from "resolvable allowlisted model"): UI-capable orientation junctures (J1–J6) do not trigger, kick composition is not invoked there, and no-UI degraded paths resolve through origination's `no_model_available` skip. J1 entry emits the shared warning naming Pi-native `/login`; later junctures stay silent, and `/brunch:continue` reuses the same notice. Session/spec creation and all non-model product functions remain available. | covered (`src/.pi/extensions/session-orientation/__tests__/registrar.test.ts` and `juncture.test.ts` prove J1–J6 suppression, live re-read, and the single J1 warning; `src/.pi/extensions/__tests__/commands-runtime-switch.test.ts` pins the shared no-model notice; `src/.pi/components/workspace-dialog/component.test.ts` and `src/app/__tests__/brunch-tui.test.ts` prove the retired startup-dialog warning stays absent; `src/session/__tests__/originate-assistant-turn.test.ts` keeps the `no_model_available` backstop covered) | D123-L (formerly D113-L, D115-L); req 29 | -| I60-L | Every provider-facing Brunch-authored tool schema satisfies Brunch's bounded build-time constraints: the shared adapter requires an object root and rejects top-level `oneOf`/`anyOf`/`allOf`, while preserving nested unions inside object properties and keeping Zod/TypeBox schema ownership single-sourced. Revisit the constraint set when the recommended/default provider-model set changes (D123-L opens model choice, widening the dialect surface users may hit) or a live provider rejects another schema feature. | covered for the adapter seam by `src/.pi/extensions/__tests__/tool-schema.test.ts`; persisted pre-FE-1163 semantic baselines protect all fifteen schemas whose authoring representation changed (exchange, dev-mode, graph, context, scratchpad, reconciliation); the TypeBox identity/serialization oracle plus exact family tests cover executor (32, including both artifacts), web (2), standalone `present_alternatives`, and subagents (foreground + sealed child); `src/.pi/extensions/__tests__/registry.test.ts` derives all 52 members from complete production registrar output plus the sealed-child catalog and checks exact membership, duplicate registrations, adapter provenance, and constraints. | D121-L | +| I60-L | Every provider-facing Brunch-authored tool schema satisfies Brunch's bounded build-time constraints: the shared adapter requires an object root and rejects top-level `oneOf`/`anyOf`/`allOf`, while preserving nested unions inside object properties and keeping Zod/TypeBox schema ownership single-sourced. Revisit the constraint set when the recommended/default provider-model set changes (D123-L opens model choice, widening the dialect surface users may hit) or a live provider rejects another schema feature. | covered for the adapter seam by `src/.pi/extensions/__tests__/tool-schema.test.ts`; the five family suites (exchange, graph, context, scratchpad, reconciliation) assert adapter provenance plus provider legality directly on the thirteen schemas whose authoring representation changed — FE-1311 retired the pre-FE-1163 snapshot baselines that formerly stood in for this, their migration reference point having gone stale and already carried per-tool carve-outs; the TypeBox identity/serialization oracle plus exact family tests cover executor (32, including both artifacts), web (2), standalone `present_alternatives`, and subagents (foreground + sealed child); `src/.pi/extensions/__tests__/registry.test.ts` derives all 52 members from complete production registrar output plus the sealed-child catalog and checks exact membership, duplicate registrations, adapter provenance, and constraints. | D121-L | | I61-L | Every production-registered provider tool is classified from its live definition as exactly one of: Brunch shared-default, intentional family-specific custom renderer, or Pi-owned. In Pi's live interactive TUI lifecycle, shared-default tools use `defineBrunchTool` and never expose model-facing result content in a second result line; custom renderers and Pi-owned tools never acquire the shared-default provenance marker. | covered by `src/.pi/extensions/shared/define-brunch-tool.test.ts` for running/partial/success/error transitions through Pi's exported `ToolExecutionComponent`, label fallback, padding, hidden result slot, and wrapper parameter/detail inference; `src/.pi/extensions/__tests__/registry.test.ts` derives the exact production surface and pins 41 shared-default tools, 11 intentional-custom tools, and 4 Pi-owned re-registrations. Existing exchange, executor, subagent, web, runtime, and alternatives suites preserve custom-renderer behavior. | D122-L; D39-L, D104-L, I23-L | | I62-L | Every Execute process move has one semantic identity across its visible label and dim description, `brunch.process_move` id, provider-visible directive, availability predicate, and resulting workflow; no layer may broaden, narrow, or expose the action independently. | pre-cutover coverage exists for the old mixed orientation carrier; FE-1187 must replace it with process-move schema/menu/prompt/readiness tests plus KA-owned O7–O9 outer conduct evidence | D109-L, D120-L | | I63-L | The workspace runtime opens only databases that self-identify as the current Brunch major line; an unstamped file is adopted only with independent Brunch lineage evidence, and a mismatched current-name file or sibling 0.x database is never opened, migrated, deleted, or used for posture inference. | covered by workspace-store identity/adoption/refusal tests and coordinator posture-inventory tests | D124-L | diff --git a/memory/cards/integrity-cleanup--sweep-ledger.md b/memory/cards/integrity-cleanup--sweep-ledger.md index 06dc4e5f6..628e3a0fd 100644 --- a/memory/cards/integrity-cleanup--sweep-ledger.md +++ b/memory/cards/integrity-cleanup--sweep-ledger.md @@ -25,6 +25,7 @@ Created: 2026-08-03 ## Cross-cutting obligations - Every deletion row runs the out-of-graph-consumer checks before deleting, and reconciles `TOPOLOGY.md` / `treedocs.yaml` references **in the same row**. +- **Pass `rg --hidden` for every consumer grep.** `src/.pi/**` is a hidden path, so plain `rg` silently reports zero consumers for anything under it (found row A1, 2026-08-03: five fixtures read as unreferenced until `--hidden` revealed five importing suites). Rows touching `src/.pi/` — inert tools, unused barrels/wrappers — are exposed to this false negative. - Intentional topology stubs (`export {}` + design comment) are not deletion candidates on unusedness alone. - Consolidation rows are behavior-preserving: existing suites stay green, no semantics change rides along. - Tie-off: `npm run verify:full` (executor seams are touched) and a changeset (`npm run changeset` — the published dependency set changes). @@ -33,7 +34,7 @@ Created: 2026-08-03 | Capability | Status | Req | Fill | Owner / next | Notes | | --- | --- | --- | --- | --- | --- | -| Pre-FE-1163 schema snapshots removed; baseline test asserts current provider constraints directly | `spec` | ● | earned | `src/.pi/extensions/__tests__/` (fixtures + `tool-schema-baseline.ts`) | Oracle: rewritten test green without snapshot fixtures; −2,339 LOC | +| Pre-FE-1163 schema snapshots removed; baseline test asserts current provider constraints directly | `built` | ● | earned | `src/.pi/extensions/__tests__/` (fixtures + `tool-schema-baseline.ts`) | Oracle: rewritten test green without snapshot fixtures; −2,339 LOC. Built: 5 fixtures + helper deleted (−2,339); the five family suites now assert adapter provenance + provider legality via `shared/tool-schema.ts` predicates. Reconciled SPEC `I60-L` coverage cell (it cited the baselines). No `TOPOLOGY.md`/`treedocs.yaml` reference existed (`treedocs.yaml` excludes `__tests__`). Surfaced the `rg --hidden` hazard now recorded above. | | Parked consequential-fact campaign deleted (resurrect from git if it re-enters PLAN) | `spec` | ● | earned | `src/dev/consequential-fact-*` | Not in PLAN (verified); dev-lane; oracle: `npm run test` green, no dangling imports | | Committed Oxc schema copies deleted | `spec` | ● | earned | `@types/oxfmt_configuration_schema.json`, `@types/oxlint_configuration_schema.json` | Verified: `.oxlintrc.json`/`.oxfmtrc.json` `$schema` point at `node_modules`; oracle: `npm run check` green | | Test-only production modules deleted with same-row TOPOLOGY reconciliation | `spec` | ● | earned | `run-auto-replan-policy.ts` (`src/executor/TOPOLOGY.md`), `drawer-card.tsx` (`src/web/TOPOLOGY.md`), packet redaction, a11y contract, plan output | Each target: confirm TOPOLOGY entry doesn't declare a live seam → delete module + tests + doc/treedocs mention, or keep and record why. Oracle: verify green + no `TOPOLOGY.md`/`treedocs.yaml` orphan reference | diff --git a/src/.pi/extensions/__tests__/brunch-data-context.test.ts b/src/.pi/extensions/__tests__/brunch-data-context.test.ts index f548d4bf3..4867d37df 100644 --- a/src/.pi/extensions/__tests__/brunch-data-context.test.ts +++ b/src/.pi/extensions/__tests__/brunch-data-context.test.ts @@ -10,8 +10,7 @@ import { openWorkspaceCommandExecutor } from '../../../graph/index.js'; import { seedFixture, type SeedFixture } from '../../../graph/seed-fixtures.js'; import { createSessionBindingData, SESSION_BINDING_TYPE } from '../../../session/session-binding.js'; import { registerBrunchContext } from '../brunch-data/context/index.js'; -import { contextToolSchemaBaseline } from './fixtures/context-tool-schemas.pre-fe-1163.js'; -import { normalizeToolSchema } from './tool-schema-baseline.js'; +import { assertProviderLegalToolSchema, hasToolParametersProvenance } from '../shared/tool-schema.js'; type ContextTool = { parameters: unknown; @@ -47,13 +46,20 @@ describe('context tools', () => { } }); - it('preserves the pre-FE-1163 provider-facing schema semantics', () => { + it('keeps every context schema adapter-derived and provider-legal', () => { const schemas = Object.fromEntries( [...collectContextTools()].map(([name, tool]) => [name, tool.parameters]), ); - expect(Object.keys(schemas)).toEqual(Object.keys(contextToolSchemaBaseline.schemas)); - expect(normalizeToolSchema(schemas)).toEqual(normalizeToolSchema(contextToolSchemaBaseline.schemas)); + expect(Object.keys(schemas)).toEqual([ + 'read_workspace_context', + 'read_specification_context', + 'read_session_context', + ]); + for (const [name, parameters] of Object.entries(schemas)) { + expect(hasToolParametersProvenance(parameters), `${name} adapter provenance`).toBe(true); + expect(() => assertProviderLegalToolSchema(parameters), name).not.toThrow(); + } }); it('read_workspace_context returns a gitignore-aware cwd inventory', async () => { diff --git a/src/.pi/extensions/__tests__/brunch-data-elicitation-scratchpad.test.ts b/src/.pi/extensions/__tests__/brunch-data-elicitation-scratchpad.test.ts index 736241928..4ecbb3c7e 100644 --- a/src/.pi/extensions/__tests__/brunch-data-elicitation-scratchpad.test.ts +++ b/src/.pi/extensions/__tests__/brunch-data-elicitation-scratchpad.test.ts @@ -11,8 +11,7 @@ import { registerBrunchElicitationScratchpad, UPDATE_ELICITATION_SCRATCHPAD_TOOL, } from '../brunch-data/elicitation/index.js'; -import { scratchpadToolSchemaBaseline } from './fixtures/scratchpad-tool-schemas.pre-fe-1163.js'; -import { normalizeToolSchema } from './tool-schema-baseline.js'; +import { assertProviderLegalToolSchema, hasToolParametersProvenance } from '../shared/tool-schema.js'; class FakeSessionManager { entries: Array<{ type: 'custom'; customType: string; data: unknown }> = []; @@ -77,13 +76,19 @@ describe('read_elicitation_scratchpad', () => { } }); - it('preserves the pre-FE-1163 provider-facing family schema semantics', () => { + it('keeps every scratchpad schema adapter-derived and provider-legal', () => { const schemas = Object.fromEntries( [...collectScratchpadTools()].map(([name, tool]) => [name, tool.parameters]), ); - expect(Object.keys(schemas)).toEqual(Object.keys(scratchpadToolSchemaBaseline.schemas)); - expect(normalizeToolSchema(schemas)).toEqual(normalizeToolSchema(scratchpadToolSchemaBaseline.schemas)); + expect(Object.keys(schemas)).toEqual([ + READ_ELICITATION_SCRATCHPAD_TOOL, + UPDATE_ELICITATION_SCRATCHPAD_TOOL, + ]); + for (const [name, parameters] of Object.entries(schemas)) { + expect(hasToolParametersProvenance(parameters), `${name} adapter provenance`).toBe(true); + expect(() => assertProviderLegalToolSchema(parameters), name).not.toThrow(); + } }); it('reports an empty scratchpad reconstructed from an empty branch', async () => { diff --git a/src/.pi/extensions/__tests__/brunch-data-graph.test.ts b/src/.pi/extensions/__tests__/brunch-data-graph.test.ts index af8747d37..ac7a26556 100644 --- a/src/.pi/extensions/__tests__/brunch-data-graph.test.ts +++ b/src/.pi/extensions/__tests__/brunch-data-graph.test.ts @@ -18,8 +18,7 @@ import { READINESS_BANDS } from '../../../graph/schema/kinds.js'; import { translateMutateGraph } from '../brunch-data/graph/command-adapter.js'; import { registerBrunchGraph, type GraphReaders } from '../brunch-data/graph/index.js'; import { MutateGraphParams, ReadGraphParams } from '../brunch-data/graph/tool-schemas.js'; -import { graphToolSchemaBaseline } from './fixtures/graph-tool-schemas.pre-fe-1163.js'; -import { normalizeToolSchema } from './tool-schema-baseline.js'; +import { assertProviderLegalToolSchema, hasToolParametersProvenance } from '../shared/tool-schema.js'; let nextSpecSlug = 0; @@ -45,10 +44,14 @@ function createGraphReads(db: BrunchDb, specId: number): GraphReaders { } describe('graph tool adapter', () => { - it('preserves the pre-FE-1163 provider-facing schema semantics', () => { - expect(normalizeToolSchema({ read_graph: ReadGraphParams, mutate_graph: MutateGraphParams })).toEqual( - normalizeToolSchema(graphToolSchemaBaseline.schemas), - ); + it('keeps both graph schemas adapter-derived and provider-legal', () => { + for (const [name, parameters] of Object.entries({ + read_graph: ReadGraphParams, + mutate_graph: MutateGraphParams, + })) { + expect(hasToolParametersProvenance(parameters), `${name} adapter provenance`).toBe(true); + expect(() => assertProviderLegalToolSchema(parameters), name).not.toThrow(); + } }); it('keeps read_graph provider-legal: no top-level union, companions enforced by adapter diagnostics', () => { diff --git a/src/.pi/extensions/__tests__/brunch-data-reconciliation.test.ts b/src/.pi/extensions/__tests__/brunch-data-reconciliation.test.ts index a95bc9f52..642f0c9af 100644 --- a/src/.pi/extensions/__tests__/brunch-data-reconciliation.test.ts +++ b/src/.pi/extensions/__tests__/brunch-data-reconciliation.test.ts @@ -17,8 +17,7 @@ import { registerBrunchReconciliation, UPDATE_RECONCILIATION_NEEDS_TOOL, } from '../brunch-data/reconciliation/index.js'; -import { reconciliationToolSchemaBaseline } from './fixtures/reconciliation-tool-schemas.pre-fe-1163.js'; -import { normalizeToolSchema } from './tool-schema-baseline.js'; +import { assertProviderLegalToolSchema, hasToolParametersProvenance } from '../shared/tool-schema.js'; interface ToolResult { content: Array<{ type: 'text'; text: string }>; @@ -78,13 +77,14 @@ function harness() { } describe('reconciliation register tools', () => { - it('preserves the pre-FE-1163 provider-facing family schema semantics', () => { + it('keeps every reconciliation schema adapter-derived and provider-legal', () => { const schemas = Object.fromEntries([...harness().tools].map(([name, tool]) => [name, tool.parameters])); - expect(Object.keys(schemas)).toEqual(Object.keys(reconciliationToolSchemaBaseline.schemas)); - expect(normalizeToolSchema(schemas)).toEqual( - normalizeToolSchema(reconciliationToolSchemaBaseline.schemas), - ); + expect(Object.keys(schemas)).toEqual([READ_RECONCILIATION_NEEDS_TOOL, UPDATE_RECONCILIATION_NEEDS_TOOL]); + for (const [name, parameters] of Object.entries(schemas)) { + expect(hasToolParametersProvenance(parameters), `${name} adapter provenance`).toBe(true); + expect(() => assertProviderLegalToolSchema(parameters), name).not.toThrow(); + } }); it('registers read and update tools under canonical names', () => { diff --git a/src/.pi/extensions/__tests__/exchanges-extension.test.ts b/src/.pi/extensions/__tests__/exchanges-extension.test.ts index 161c74929..25fc5bfed 100644 --- a/src/.pi/extensions/__tests__/exchanges-extension.test.ts +++ b/src/.pi/extensions/__tests__/exchanges-extension.test.ts @@ -7,8 +7,7 @@ import { PRESENT_REVIEW_SET_TOOL, registerStructuredExchange, } from '../exchanges/index.js'; -import { exchangeToolSchemaBaseline } from './fixtures/exchange-tool-schemas.pre-fe-1163.js'; -import { normalizeToolSchema } from './tool-schema-baseline.js'; +import { assertProviderLegalToolSchema, hasToolParametersProvenance } from '../shared/tool-schema.js'; const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, 'g'); @@ -91,22 +90,18 @@ describe('structured exchange renderers', () => { } }); - it('preserves pre-FE-1163 tools while extending ask with bounded questionnaire fields', () => { - const tools = registerTools(); - const currentSchemas = Object.fromEntries( - [...tools].map(([name, tool]) => [name, normalizeToolSchema(tool.parameters)]), - ); - const baseline = normalizeToolSchema(exchangeToolSchemaBaseline.schemas) as Record; + it('keeps every exchange schema adapter-derived and provider-legal, with the ask questionnaire fields', () => { + const schemas = Object.fromEntries([...registerTools()].map(([name, tool]) => [name, tool.parameters])); - expect([...tools.keys()]).toEqual(Object.keys(exchangeToolSchemaBaseline.schemas)); - const unchangedTools = ([name]: [string, unknown]) => name !== 'ask' && name !== PRESENT_REVIEW_SET_TOOL; - expect(Object.fromEntries(Object.entries(currentSchemas).filter(unchangedTools))).toEqual( - Object.fromEntries(Object.entries(baseline).filter(unchangedTools)), - ); - expect(JSON.stringify(currentSchemas[PRESENT_REVIEW_SET_TOOL])).toContain('settlement'); - expect(JSON.stringify(currentSchemas[PRESENT_REVIEW_SET_TOOL])).toContain('advisory'); - expect(JSON.stringify(currentSchemas[PRESENT_REVIEW_SET_TOOL])).toContain('settled'); - expect(currentSchemas.ask).toMatchObject({ + for (const [name, parameters] of Object.entries(schemas)) { + expect(hasToolParametersProvenance(parameters), `${name} adapter provenance`).toBe(true); + expect(() => assertProviderLegalToolSchema(parameters), name).not.toThrow(); + } + + expect(JSON.stringify(schemas[PRESENT_REVIEW_SET_TOOL])).toContain('settlement'); + expect(JSON.stringify(schemas[PRESENT_REVIEW_SET_TOOL])).toContain('advisory'); + expect(JSON.stringify(schemas[PRESENT_REVIEW_SET_TOOL])).toContain('settled'); + expect(schemas.ask).toMatchObject({ properties: { acceptsDigest: { type: 'string' }, questions: { type: 'array', minItems: 1 }, diff --git a/src/.pi/extensions/__tests__/fixtures/context-tool-schemas.pre-fe-1163.ts b/src/.pi/extensions/__tests__/fixtures/context-tool-schemas.pre-fe-1163.ts deleted file mode 100644 index 76280426f..000000000 --- a/src/.pi/extensions/__tests__/fixtures/context-tool-schemas.pre-fe-1163.ts +++ /dev/null @@ -1,28 +0,0 @@ -// Recovered from the three literal parameter objects before commit 25dcfdfc. -export const contextToolSchemaBaseline = { - sourceCommit: '371da10c', - sourceFile: 'src/.pi/extensions/brunch-data/context/index.ts', - schemas: { - read_workspace_context: { - type: 'object', - properties: { - mode: { - type: 'string', - enum: ['cwd_inventory', 'workspace_overview'], - }, - }, - required: ['mode'], - additionalProperties: false, - }, - read_specification_context: { - type: 'object', - properties: {}, - additionalProperties: false, - }, - read_session_context: { - type: 'object', - properties: {}, - additionalProperties: false, - }, - }, -} as const; diff --git a/src/.pi/extensions/__tests__/fixtures/exchange-tool-schemas.pre-fe-1163.ts b/src/.pi/extensions/__tests__/fixtures/exchange-tool-schemas.pre-fe-1163.ts deleted file mode 100644 index 396a87789..000000000 --- a/src/.pi/extensions/__tests__/fixtures/exchange-tool-schemas.pre-fe-1163.ts +++ /dev/null @@ -1,1020 +0,0 @@ -// Recovered from the legacy piSchema output at the recorded pre-FE-1163 commit. -// That adapter delegated to z.toJSONSchema(..., { unrepresentable: 'throw' }); -// the four Zod schema sources are unchanged between this commit and fixture capture. -// FE-1187 deliberately updates three active-tool descriptions to name ask continuations. -export const exchangeToolSchemaBaseline = { - sourceCommit: 'ba24510fbd23fcf261cd393e49d0f0bb9b28df44', - sourceAdapter: 'src/.pi/extensions/exchanges/pi-schema.ts', - schemas: { - ask: { - $schema: 'https://json-schema.org/draft/2020-12/schema', - type: 'object', - properties: { - topLabel: { - type: 'string', - minLength: 1, - description: 'Optional rounded-box top border label.', - }, - bottomLabel: { - type: 'string', - minLength: 1, - description: 'Optional rounded-box bottom border label.', - }, - exchangeId: { - type: 'string', - minLength: 1, - description: 'Stable id for this one-shot ask result. Omit when continuing an offer by reference.', - }, - continues: { - type: 'string', - minLength: 1, - description: 'Exchange id of an offer whose details declare the ask payload to collect.', - }, - preface: { - type: 'string', - minLength: 1, - description: - 'Optional model-authored preface for a reference-based continuation; not part of the payload.', - }, - body: { - type: 'string', - minLength: 1, - description: 'Markdown question body rendered and persisted with the answer.', - }, - options: { - minItems: 1, - type: 'array', - items: { - type: 'object', - properties: { - id: { - type: 'string', - minLength: 1, - pattern: '^[^>\\r\\n]+$', - }, - label: { - type: 'string', - minLength: 1, - }, - description: { - type: 'string', - }, - }, - required: ['id', 'label'], - additionalProperties: false, - }, - description: 'Finite response options. Omit for a free-text answer.', - }, - multiple: { - type: 'boolean', - description: 'When options are present, allow one-or-more selections.', - }, - allowOther: { - type: 'boolean', - description: 'Whether the user may choose Other for option responses.', - }, - allowNone: { - type: 'boolean', - description: 'Whether the user may choose None for option responses.', - }, - commentPrompt: { - type: 'string', - minLength: 1, - description: - 'Prompt for an optional trailing comment; omit to skip the optional-comment step. Comments the response schema requires (Other/None selections) are always collected.', - }, - }, - additionalProperties: false, - }, - present_review_set: { - $schema: 'https://json-schema.org/draft/2020-12/schema', - type: 'object', - properties: { - exchangeId: { - type: 'string', - minLength: 1, - description: 'Stable id tying this review-set proposal to the later ask({ continues }) review.', - }, - payload: { - type: 'object', - properties: { - schemaVersion: { - type: 'number', - const: 1, - }, - lens: { - type: 'string', - enum: ['intent', 'design', 'oracle', 'plan'], - }, - epistemicStatus: { - type: 'string', - enum: ['inferred', 'assumed', 'asserted', 'observed'], - }, - grounding: { - type: 'object', - properties: { - summary: { - type: 'string', - minLength: 1, - description: 'Short grounding summary for the proposal.', - }, - support: { - minItems: 1, - type: 'array', - items: { - type: 'string', - minLength: 1, - }, - description: 'Concrete support/evidence strings.', - }, - }, - required: ['summary', 'support'], - additionalProperties: false, - }, - pitch: { - type: 'object', - properties: { - title: { - type: 'string', - minLength: 1, - description: 'Review-set title.', - }, - narrative: { - type: 'string', - minLength: 1, - description: 'Why this batch should be reviewed together.', - }, - }, - required: ['title', 'narrative'], - additionalProperties: false, - }, - entityDrafts: { - minItems: 1, - type: 'array', - items: { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - }, - plane: { - type: 'string', - enum: ['intent', 'oracle', 'design', 'plan'], - }, - kind: { - type: 'string', - minLength: 1, - }, - proposedCode: { - type: 'string', - minLength: 1, - }, - title: { - type: 'string', - minLength: 1, - }, - body: { - type: 'string', - }, - detail: {}, - }, - required: ['draftId', 'plane', 'kind', 'title'], - additionalProperties: false, - }, - }, - edgeDrafts: { - type: 'array', - items: { - anyOf: [ - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'dependency', - }, - dependency: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - dependent: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'dependency', 'dependent'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'witness', - }, - oracle: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - claim: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - stance: { - type: 'string', - enum: ['for', 'against'], - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'oracle', 'claim', 'stance'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'rationale', - }, - support: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - claim: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - stance: { - type: 'string', - enum: ['for', 'against'], - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'support', 'claim', 'stance'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'realization', - }, - abstract: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - concrete: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'abstract', 'concrete'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'refinement', - }, - abstract: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - concrete: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'abstract', 'concrete'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'exclusion', - }, - boundary: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - subject: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'boundary', 'subject'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'composition', - }, - whole: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - part: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'whole', 'part'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'cross_reference', - }, - a: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - b: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'a', 'b'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - category: { - type: 'string', - const: 'supersession', - }, - successor: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - predecessor: { - anyOf: [ - { - type: 'object', - properties: { - draftId: { - type: 'string', - minLength: 1, - description: 'Review-set-local draft id.', - }, - }, - required: ['draftId'], - additionalProperties: false, - }, - { - type: 'object', - properties: { - existingCode: { - type: 'string', - minLength: 1, - description: 'Projected graph node code from read_graph.', - }, - }, - required: ['existingCode'], - additionalProperties: false, - }, - ], - description: 'Endpoint reference: exactly one of draftId or existingCode.', - }, - rationale: { - type: 'string', - }, - }, - required: ['category', 'successor', 'predecessor'], - additionalProperties: false, - }, - ], - description: 'Role-named edge draft; companion endpoint fields are determined by category.', - }, - }, - proposalVersion: { - type: 'integer', - exclusiveMinimum: 0, - maximum: 9007199254740991, - }, - supersedes: { - type: 'string', - minLength: 1, - }, - }, - required: ['schemaVersion'], - additionalProperties: {}, - description: - 'Review-set proposal payload. Required by the graph validator: schemaVersion, lens, epistemicStatus, grounding {summary, support[]}, pitch {title, narrative}, entityDrafts[], edgeDrafts[].', - }, - }, - required: ['exchangeId', 'payload'], - additionalProperties: false, - }, - present_candidates: { - $schema: 'https://json-schema.org/draft/2020-12/schema', - type: 'object', - properties: { - exchangeId: { - type: 'string', - minLength: 1, - description: 'Stable id tying this candidate presentation to the later ask({ continues }) call.', - }, - heading: { - type: 'string', - minLength: 1, - description: 'Candidate comparison heading.', - }, - body: { - type: 'string', - description: 'Markdown body for context before the candidate list.', - }, - candidates: { - minItems: 1, - type: 'array', - items: { - type: 'object', - properties: { - id: { - type: 'string', - minLength: 1, - }, - title: { - type: 'string', - minLength: 1, - }, - user_rubric: { - type: 'object', - properties: { - core_bet: { - type: 'string', - }, - best_fit: { - type: 'string', - }, - cost_complexity: { - type: 'string', - }, - covers_well: { - type: 'string', - }, - main_risks: { - type: 'string', - }, - lock_in_constraints: { - type: 'string', - }, - recommendation: { - type: 'string', - }, - }, - required: [ - 'core_bet', - 'best_fit', - 'cost_complexity', - 'covers_well', - 'main_risks', - 'lock_in_constraints', - ], - additionalProperties: false, - }, - meta_rubric: { - type: 'object', - properties: { - legibility_cost_of_knowing: { - type: 'string', - }, - failure_modes: { - type: 'string', - }, - coverage_range: { - type: 'string', - }, - commitment: { - type: 'string', - }, - }, - additionalProperties: false, - }, - graph_refs: { - type: 'array', - items: { - type: 'object', - properties: { - node_id: { - type: 'string', - minLength: 1, - }, - }, - required: ['node_id'], - additionalProperties: false, - }, - }, - }, - required: ['id', 'title', 'user_rubric', 'meta_rubric', 'graph_refs'], - additionalProperties: false, - }, - description: - 'Recognition-only candidate expressions to compare and choose from; selection records fan-in intent but does not commit graph truth.', - }, - }, - required: ['exchangeId', 'heading', 'candidates'], - additionalProperties: false, - }, - present_digest: { - $schema: 'https://json-schema.org/draft/2020-12/schema', - type: 'object', - properties: { - exchangeId: { - type: 'string', - minLength: 1, - description: 'Stable id tying this digest presentation to the later ask({ continues }) review.', - }, - heading: { - type: 'string', - minLength: 1, - description: 'Digest heading.', - }, - body: { - type: 'string', - description: 'Markdown body for context before the digest.', - }, - digest: { - type: 'object', - properties: { - abstract: { - type: 'string', - }, - analysis: { - type: 'string', - }, - recommendation: { - type: 'string', - }, - }, - required: ['abstract'], - additionalProperties: false, - description: - 'Prose-only digest material: abstract plus optional analysis and recommendation. Do not include graph nodes, edges, draft ids, command payloads, or review-set material.', - }, - }, - required: ['exchangeId', 'heading', 'digest'], - additionalProperties: false, - }, - }, -} as const; diff --git a/src/.pi/extensions/__tests__/fixtures/graph-tool-schemas.pre-fe-1163.ts b/src/.pi/extensions/__tests__/fixtures/graph-tool-schemas.pre-fe-1163.ts deleted file mode 100644 index dabff1545..000000000 --- a/src/.pi/extensions/__tests__/fixtures/graph-tool-schemas.pre-fe-1163.ts +++ /dev/null @@ -1,1173 +0,0 @@ -/* oxlint-disable unicorn/no-thenable -- historical schema baseline includes the plan phase key `then`. */ -// Recovered by differential review of the literal/TypeBox sources before commit 371da10c. -// The baseline includes both the rewritten read schema and pure-relinked mutation schema. -export const graphToolSchemaBaseline = { - sourceCommit: 'f90ad47814b7e9e04f2508a84f63621107df889a', - sourceFile: 'src/.pi/extensions/brunch-data/graph/tool-schemas.ts', - schemas: { - read_graph: { - type: 'object', - required: ['mode'], - properties: { - mode: { - enum: ['overview', 'neighborhood', 'list_by_kind', 'list_by_band', 'related'], - }, - show: { - enum: ['active', 'all'], - description: 'Graph visibility to read (default: active)', - }, - nodeCode: { - type: 'string', - minLength: 1, - description: - 'neighborhood: projected code of the anchor node in the selected spec, e.g. G1 or CON2', - }, - hops: { - type: 'number', - description: 'Neighborhood traversal depth (default: 1)', - }, - kinds: { - type: 'array', - items: { - type: 'string', - }, - description: - 'list_by_kind: optional node-kind filter. Omit or pass [] for an unfiltered slice; unknown kinds produce an empty slice.', - }, - readinessBands: { - type: 'array', - items: { - enum: ['grounding', 'elicitation', 'projection', 'commitment'], - }, - description: - 'list_by_band: optional readiness-band filter. Omit or pass [] for an unfiltered slice; unknown bands produce an empty slice.', - }, - anchorCodes: { - type: 'array', - items: { - type: 'string', - minLength: 1, - }, - minItems: 1, - description: 'related: one or more projected codes of anchor nodes in the selected spec', - }, - edgeCategory: { - enum: [ - 'dependency', - 'witness', - 'rationale', - 'realization', - 'refinement', - 'exclusion', - 'composition', - 'cross_reference', - 'supersession', - ], - description: 'related: edge category to follow', - }, - direction: { - enum: ['outgoing', 'incoming', 'both'], - description: 'related: traversal direction (default: both)', - }, - }, - additionalProperties: false, - description: - 'Read a graph overview, selected-spec node neighborhood, projection-aware flat graph slice, or related nodes. Mode-specific companions are enforced by loud adapter diagnostics: neighborhood requires nodeCode; related requires anchorCodes plus edgeCategory. List modes intentionally treat omitted/empty filters as unfiltered slices; unknown filters produce an empty slice.', - }, - mutate_graph: { - type: 'object', - required: ['ops'], - properties: { - createBasis: { - type: 'string', - enum: ['explicit', 'implicit'], - description: 'Basis for newly created nodes and edges in this batch', - }, - createSettlement: { - type: 'string', - enum: ['advisory', 'settled'], - description: - 'Settlement for newly created nodes and edges in this batch (default: settled). Use "advisory" only for reviewed, source-derived bulk-acquisition material that has not yet been harmonized against inner-band concerns (D99-L) — never for directly-stated user facts.', - }, - ops: { - type: 'array', - items: { - anyOf: [ - { - anyOf: [ - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind', 'detail'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - const: 'intent', - }, - kind: { - type: 'string', - const: 'decision', - }, - detail: { - type: 'object', - additionalProperties: false, - required: ['chosen_option', 'rejected', 'rationale'], - properties: { - chosen_option: { - type: 'string', - description: 'The selected option or position.', - }, - rejected: { - type: 'array', - minItems: 1, - items: { - type: 'string', - }, - description: 'Rejected alternatives considered by this decision.', - }, - rationale: { - type: 'string', - description: 'Why the chosen option won.', - }, - }, - description: 'Detail required for decision nodes.', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind', 'detail'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - const: 'intent', - }, - kind: { - type: 'string', - const: 'term', - }, - detail: { - type: 'object', - additionalProperties: false, - required: ['definition'], - properties: { - definition: { - type: 'string', - description: 'Canonical definition for the term.', - }, - aliases: { - type: 'array', - items: { - type: 'string', - }, - description: 'Optional alternate names for the same concept.', - }, - }, - description: 'Detail required for term nodes.', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - const: 'intent', - }, - kind: { - type: 'string', - const: 'requirement', - }, - detail: { - anyOf: [ - { - type: 'object', - additionalProperties: false, - required: ['form'], - properties: { - form: { - const: 'plain', - description: 'Plain claim — no structured method payload.', - }, - }, - description: 'Plain claim form.', - }, - { - type: 'object', - additionalProperties: false, - required: ['form', 'then'], - properties: { - form: { - const: 'gherkin', - }, - given: { - type: 'array', - items: { - type: 'string', - }, - description: 'Given preconditions.', - }, - when: { - type: 'array', - items: { - type: 'string', - }, - description: 'When actions.', - }, - then: { - type: 'array', - minItems: 1, - items: { - type: 'string', - }, - description: 'Then outcomes — at least one.', - }, - }, - description: 'Gherkin Given/When/Then payload.', - }, - { - type: 'object', - additionalProperties: false, - required: ['form', 'language', 'statement'], - properties: { - form: { - const: 'formal', - }, - language: { - type: 'string', - description: 'Target prover/solver, e.g. lean or dafny.', - }, - statement: { - type: 'string', - description: 'Formal statement text for round-trip.', - }, - }, - description: 'Formal verification payload.', - }, - ], - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - const: 'intent', - }, - kind: { - type: 'string', - const: 'criterion', - }, - detail: { - anyOf: [ - { - type: 'object', - additionalProperties: false, - required: ['form'], - properties: { - form: { - const: 'plain', - description: 'Plain claim — no structured method payload.', - }, - }, - description: 'Plain claim form.', - }, - { - type: 'object', - additionalProperties: false, - required: ['form', 'then'], - properties: { - form: { - const: 'gherkin', - }, - given: { - type: 'array', - items: { - type: 'string', - }, - description: 'Given preconditions.', - }, - when: { - type: 'array', - items: { - type: 'string', - }, - description: 'When actions.', - }, - then: { - type: 'array', - minItems: 1, - items: { - type: 'string', - }, - description: 'Then outcomes — at least one.', - }, - }, - description: 'Gherkin Given/When/Then payload.', - }, - { - type: 'object', - additionalProperties: false, - required: ['form', 'language', 'statement'], - properties: { - form: { - const: 'formal', - }, - language: { - type: 'string', - description: 'Target prover/solver, e.g. lean or dafny.', - }, - statement: { - type: 'string', - description: 'Formal statement text for round-trip.', - }, - }, - description: 'Formal verification payload.', - }, - ], - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - const: 'intent', - }, - kind: { - type: 'string', - const: 'invariant', - }, - detail: { - anyOf: [ - { - type: 'object', - additionalProperties: false, - required: ['form'], - properties: { - form: { - const: 'plain', - description: 'Plain claim — no structured method payload.', - }, - }, - description: 'Plain claim form.', - }, - { - type: 'object', - additionalProperties: false, - required: ['form', 'then'], - properties: { - form: { - const: 'gherkin', - }, - given: { - type: 'array', - items: { - type: 'string', - }, - description: 'Given preconditions.', - }, - when: { - type: 'array', - items: { - type: 'string', - }, - description: 'When actions.', - }, - then: { - type: 'array', - minItems: 1, - items: { - type: 'string', - }, - description: 'Then outcomes — at least one.', - }, - }, - description: 'Gherkin Given/When/Then payload.', - }, - { - type: 'object', - additionalProperties: false, - required: ['form', 'language', 'statement'], - properties: { - form: { - const: 'formal', - }, - language: { - type: 'string', - description: 'Target prover/solver, e.g. lean or dafny.', - }, - statement: { - type: 'string', - description: 'Formal statement text for round-trip.', - }, - }, - description: 'Formal verification payload.', - }, - ], - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - const: 'intent', - }, - kind: { - type: 'string', - const: 'context', - }, - detail: { - anyOf: [ - { - type: 'object', - additionalProperties: false, - required: ['form', 'statement'], - properties: { - form: { - const: 'given', - }, - statement: { - type: 'string', - description: 'Stipulated axiom/given statement.', - }, - }, - description: 'Axiom/given payload on a context node.', - }, - ], - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'ref', 'title', 'plane', 'kind'], - properties: { - op: { - type: 'string', - const: 'create_node', - }, - ref: { - type: 'string', - description: "Temporary batch reference id (e.g. 'n1', 'n2')", - }, - title: { - type: 'string', - description: 'Node title — must be non-empty', - }, - body: { - type: 'string', - description: 'Extended description', - }, - source: { - type: 'string', - description: "Epistemic attribution (e.g. 'stakeholder', 'derived')", - }, - plane: { - type: 'string', - enum: ['intent', 'oracle', 'design', 'plan'], - }, - kind: { - type: 'string', - enum: [ - 'goal', - 'thesis', - 'story', - 'unknown', - 'assumption', - 'constraint', - 'example', - 'check', - 'vv_method', - 'evidence', - 'vv_obligation', - 'module', - 'interface', - 'entity', - 'sketch', - 'milestone', - 'frontier', - 'scope', - ], - }, - }, - additionalProperties: false, - }, - ], - }, - { - anyOf: [ - { - type: 'object', - required: ['op', 'category', 'dependency', 'dependent'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'dependency', - }, - dependency: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - dependent: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'oracle', 'claim', 'stance'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'witness', - }, - oracle: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - claim: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - stance: { - type: 'string', - enum: ['for', 'against'], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'support', 'claim', 'stance'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'rationale', - }, - support: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - claim: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - stance: { - type: 'string', - enum: ['for', 'against'], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'abstract', 'concrete'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'realization', - }, - abstract: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - concrete: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'abstract', 'concrete'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'refinement', - }, - abstract: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - concrete: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'boundary', 'subject'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'exclusion', - }, - boundary: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - subject: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'whole', 'part'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'composition', - }, - whole: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - part: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'a', 'b'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'cross_reference', - }, - a: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - b: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - { - type: 'object', - required: ['op', 'category', 'successor', 'predecessor'], - properties: { - op: { - type: 'string', - const: 'create_edge', - }, - category: { - type: 'string', - const: 'supersession', - }, - successor: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - predecessor: { - anyOf: [ - { - type: 'string', - description: "Intra-batch ref (e.g. 'n1')", - }, - { - type: 'object', - required: ['existingCode'], - properties: { - existingCode: { - type: 'string', - description: - 'Projected code of an existing node in the selected spec, e.g. G1 or CON2', - }, - }, - additionalProperties: false, - }, - ], - }, - rationale: { - type: 'string', - }, - }, - additionalProperties: false, - }, - ], - }, - ], - }, - description: - 'Create-only graph mutation operations. Edges use role-named endpoints and may reference batch refs or existing node codes.', - }, - }, - additionalProperties: false, - }, - }, -} as const; diff --git a/src/.pi/extensions/__tests__/fixtures/reconciliation-tool-schemas.pre-fe-1163.ts b/src/.pi/extensions/__tests__/fixtures/reconciliation-tool-schemas.pre-fe-1163.ts deleted file mode 100644 index b95a6b888..000000000 --- a/src/.pi/extensions/__tests__/fixtures/reconciliation-tool-schemas.pre-fe-1163.ts +++ /dev/null @@ -1,62 +0,0 @@ -// Recovered from the two literal parameter objects before commit 90470eeb. -// Serves as the current-schema golden for the reconciliation tools. The needKind -// enum was reduced to the three persisted judgment kinds when edge_revalidation -// was retired to a derived read (reconciliation-derivation frontier). -export const reconciliationToolSchemaBaseline = { - sourceCommit: '416d73e9e38904f7eeb4246f1898aaeedbbe7503', - sourceFile: 'src/.pi/extensions/brunch-data/reconciliation/index.ts', - schemas: { - read_reconciliation_needs: { - type: 'object', - additionalProperties: false, - properties: {}, - description: 'Read the open reconciliation-need agenda for the selected spec.', - }, - update_reconciliation_needs: { - type: 'object', - additionalProperties: false, - required: ['action'], - properties: { - action: { - enum: ['create', 'resolve'], - description: "One write per call: 'create' records a new impasse; 'resolve' closes one.", - }, - needKind: { - enum: ['possible_relation', 'possible_duplicate', 'semantic_conflict'], - description: 'create: kind of reconciliation need to record.', - }, - target: { - oneOf: [ - { - type: 'object', - additionalProperties: false, - required: ['kind', 'edgeId'], - properties: { kind: { const: 'edge' }, edgeId: { type: 'number' } }, - }, - { - type: 'object', - additionalProperties: false, - required: ['kind', 'aId', 'bId'], - properties: { - kind: { const: 'node_pair' }, - aId: { type: 'number' }, - bId: { type: 'number' }, - }, - }, - ], - description: 'create: existing edge or pair of existing nodes this impasse is about.', - }, - reason: { - type: 'string', - description: 'create: brief reason for the impasse. Do not encode replacement graph truth here.', - }, - needId: { - type: 'string', - description: 'resolve: id of the reconciliation need to close.', - }, - }, - description: - 'Update the reconciliation register for the selected spec: create or resolve one impasse per call.', - }, - }, -} as const; diff --git a/src/.pi/extensions/__tests__/fixtures/scratchpad-tool-schemas.pre-fe-1163.ts b/src/.pi/extensions/__tests__/fixtures/scratchpad-tool-schemas.pre-fe-1163.ts deleted file mode 100644 index 829f26077..000000000 --- a/src/.pi/extensions/__tests__/fixtures/scratchpad-tool-schemas.pre-fe-1163.ts +++ /dev/null @@ -1,41 +0,0 @@ -// Recovered from the two literal parameter objects before commit 416d73e9. -export const scratchpadToolSchemaBaseline = { - sourceCommit: '25dcfdfc2ad07ce28d5fb8f320ea432c55c02238', - sourceFile: 'src/.pi/extensions/brunch-data/elicitation/scratchpad-tools.ts', - schemas: { - read_elicitation_scratchpad: { - type: 'object', - additionalProperties: false, - properties: {}, - description: - 'Read the current session-local elicitation scratchpad: obligations the agent has noted still need asking, reconstructed from this session branch. Non-authoritative — durable truth is the graph.', - }, - update_elicitation_scratchpad: { - type: 'object', - additionalProperties: false, - required: ['operation'], - properties: { - operation: { - enum: ['add', 'resolve', 'update'], - description: - "'add' appends a new open obligation; 'resolve' marks an existing obligation resolved; 'update' replaces an obligation's text/rationale/meta", - }, - id: { - type: 'string', - description: 'add: id for the new obligation; resolve/update: id of the existing one', - }, - obligation: { - type: 'string', - description: 'add/update: the obligation text (what still needs asking)', - }, - rationale: { type: 'string', description: 'add/update: why this obligation exists' }, - meta: { - type: 'object', - description: 'add/update: free-form non-authoritative reference data', - }, - }, - description: - 'Write the session-local elicitation scratchpad. Always appends a full-replacement snapshot of the current scratchpad; never persists to the graph.', - }, - }, -} as const; diff --git a/src/.pi/extensions/__tests__/tool-schema-baseline.ts b/src/.pi/extensions/__tests__/tool-schema-baseline.ts deleted file mode 100644 index 8c2a9207b..000000000 --- a/src/.pi/extensions/__tests__/tool-schema-baseline.ts +++ /dev/null @@ -1,15 +0,0 @@ -export function normalizeToolSchema(value: unknown, parentKey?: string): unknown { - if (Array.isArray(value)) { - if (parentKey === 'required' && value.every((item): item is string => typeof item === 'string')) { - return [...value].sort((left, right) => left.localeCompare(right)); - } - return value.map((item) => normalizeToolSchema(item)); - } - if (typeof value !== 'object' || value === null) return value; - - return Object.fromEntries( - Object.entries(value) - .filter(([key]) => key !== '$schema') - .map(([key, nested]) => [key, normalizeToolSchema(nested, key)]), - ); -} From d4fdf5d8512da8089f7d7af72e360f8456f8c5cd Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 20:39:09 +0200 Subject: [PATCH 08/35] FE-1311: Block the consequential-fact deletion row on falsified premise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sweep row proposed deleting src/dev/consequential-fact-* as a parked campaign. The out-of-graph-consumer checks falsify that premise: the row conflated the retired campaign *frontier identity* with the code it left behind, which is live on four counts — dev-cli.ts ships the evaluate-consequential-fact subcommand over the evaluator, src/dev TOPOLOGY.md and README.md both declare the evaluator/report/runner seam functional dev/eval primitives, the live capture-ledger-tracer frontier reuses all three files, and a hidden-path lexicon test pins the runner. Record the evidence in the row and route back to ln-plan; PLAN's "Deletes / retires" list carries the same conflation. No code deleted. Also generalize the lesson as a cross-cutting obligation for the remaining deletion rows: read the owning TOPOLOGY/README prose and grep active scope cards for successor frontiers before trusting a deadness verdict. Co-Authored-By: Claude Fable 5 --- memory/cards/integrity-cleanup--sweep-ledger.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/memory/cards/integrity-cleanup--sweep-ledger.md b/memory/cards/integrity-cleanup--sweep-ledger.md index 628e3a0fd..428dfe4ef 100644 --- a/memory/cards/integrity-cleanup--sweep-ledger.md +++ b/memory/cards/integrity-cleanup--sweep-ledger.md @@ -26,6 +26,7 @@ Created: 2026-08-03 - Every deletion row runs the out-of-graph-consumer checks before deleting, and reconciles `TOPOLOGY.md` / `treedocs.yaml` references **in the same row**. - **Pass `rg --hidden` for every consumer grep.** `src/.pi/**` is a hidden path, so plain `rg` silently reports zero consumers for anything under it (found row A1, 2026-08-03: five fixtures read as unreferenced until `--hidden` revealed five importing suites). Rows touching `src/.pi/` — inert tools, unused barrels/wrappers — are exposed to this false negative. +- **A canonical doc that declares a module live overrides an induction deadness verdict.** Before deleting, read the owning `TOPOLOGY.md`/`README.md` *prose* (not just its layout sketch) and grep active `memory/cards/*.md` for successor frontiers that plan to reuse the target. Found row A2, 2026-08-03: the induction read "retired campaign frontier" as "dead code", but `src/dev/TOPOLOGY.md` + `README.md` declare the same files functional dev/eval primitives and the live `capture-ledger-tracer` card reuses them. Retiring a *plan identity* does not retire the *code* it left behind. - Intentional topology stubs (`export {}` + design comment) are not deletion candidates on unusedness alone. - Consolidation rows are behavior-preserving: existing suites stay green, no semantics change rides along. - Tie-off: `npm run verify:full` (executor seams are touched) and a changeset (`npm run changeset` — the published dependency set changes). @@ -35,7 +36,7 @@ Created: 2026-08-03 | Capability | Status | Req | Fill | Owner / next | Notes | | --- | --- | --- | --- | --- | --- | | Pre-FE-1163 schema snapshots removed; baseline test asserts current provider constraints directly | `built` | ● | earned | `src/.pi/extensions/__tests__/` (fixtures + `tool-schema-baseline.ts`) | Oracle: rewritten test green without snapshot fixtures; −2,339 LOC. Built: 5 fixtures + helper deleted (−2,339); the five family suites now assert adapter provenance + provider legality via `shared/tool-schema.ts` predicates. Reconciled SPEC `I60-L` coverage cell (it cited the baselines). No `TOPOLOGY.md`/`treedocs.yaml` reference existed (`treedocs.yaml` excludes `__tests__`). Surfaced the `rg --hidden` hazard now recorded above. | -| Parked consequential-fact campaign deleted (resurrect from git if it re-enters PLAN) | `spec` | ● | earned | `src/dev/consequential-fact-*` | Not in PLAN (verified); dev-lane; oracle: `npm run test` green, no dangling imports | +| Parked consequential-fact campaign deleted (resurrect from git if it re-enters PLAN) | `spec` (BLOCKED) | ● | earned | `src/dev/consequential-fact-*` — **route back to `ln-plan`, do not delete** | **Premise falsified 2026-08-03 (out-of-graph checks, no code changed).** The row conflated the retired *campaign frontier identity* with the `src/dev/consequential-fact-*` *code*, which is live: (1) `src/dev/dev-cli.ts:26,40,216` imports `writeConsequentialFactEvaluation` and ships the `evaluate-consequential-fact` subcommand, exercised by `src/dev/__tests__/dev-cli.test.ts:363,530,570` against `consequential-fact-evaluator/review-diff-scenario.json` — a live import, not a dangling one; (2) `src/dev/TOPOLOGY.md:52` and `src/dev/README.md:63` both state verbatim that the evaluator, report, runner, and directive-ablation seam "remain functional dev/eval primitives" and that only the earlier campaign line "is retired rather than parked" (echoed at `docs/archive/PLAN_HISTORY.md:47`); (3) the live `capture-ledger-tracer` frontier (PLAN.md:180–188) reuses them — its card `capture-ledger-tracer--conduct-falsifier.md` names `src/dev/TOPOLOGY.md` for "existing consequential-fact campaign/evaluator … ownership" and marks all three files `~` (reused) in its touched-path sketch; (4) `src/.pi/extensions/__tests__/continue-lexicon.test.ts:10` pins `src/dev/consequential-fact-campaign-runner.ts` in `CURRENT_PRODUCT_FILES` and reads it — a hidden-path consumer. No `treedocs.yaml` reference; provenance is `1885130a7` (FE-1208). No part of the family is safely deletable under the current canonical record; PLAN's "Deletes / retires" list needs the same correction. | | Committed Oxc schema copies deleted | `spec` | ● | earned | `@types/oxfmt_configuration_schema.json`, `@types/oxlint_configuration_schema.json` | Verified: `.oxlintrc.json`/`.oxfmtrc.json` `$schema` point at `node_modules`; oracle: `npm run check` green | | Test-only production modules deleted with same-row TOPOLOGY reconciliation | `spec` | ● | earned | `run-auto-replan-policy.ts` (`src/executor/TOPOLOGY.md`), `drawer-card.tsx` (`src/web/TOPOLOGY.md`), packet redaction, a11y contract, plan output | Each target: confirm TOPOLOGY entry doesn't declare a live seam → delete module + tests + doc/treedocs mention, or keep and record why. Oracle: verify green + no `TOPOLOGY.md`/`treedocs.yaml` orphan reference | | Inert tools deleted: `present_alternatives`, `execute_plan_outline_artifact`, `execute_plan_draft_artifact` + components/tests + all registry entries | `spec` | ● | earned | `src/.pi/components/alternatives.ts`, `src/.pi/extensions/executor/execute-*-artifact`, `tool-names.ts`, `run-execution-authority.ts`, `transcript-context.ts:26`, component-preview registry | Includes the orphan `'present_alternatives'` literal (already absent from `tool-names.ts` — drift realized). Pairs with row B3; −644 LOC | From acdb0b6daaeebefd49adda376b763a4c0e072dbb Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 3 Aug 2026 20:53:14 +0200 Subject: [PATCH 09/35] FE-1311: Delete the committed Oxc schema copies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sweep ledger row A3. `@types/oxlint_configuration_schema.json` and `@types/oxfmt_configuration_schema.json` were snapshots of upstream Oxc config schemas that nothing ever read: `.oxlintrc.json` and `.oxfmtrc.json` point their `$schema` at `./node_modules/{oxlint,oxfmt}/configuration_schema.json`, and `git log -S` over the filenames across all refs returns only the commit that scoped this ledger. They were also stale — 18.2K against 701K upstream for oxlint — so keeping them taught the wrong schema. Deleting both empties `@types/`, so the `"@types/**"` ignorePatterns entry (added afterwards, in b0abf2679, only because these files tripped the formatter) is removed from both configs in the same row. Co-Authored-By: Claude Fable 5 --- .oxfmtrc.json | 1 - .oxlintrc.json | 1 - @types/oxfmt_configuration_schema.json | 648 ------------------ @types/oxlint_configuration_schema.json | 554 --------------- .../cards/integrity-cleanup--sweep-ledger.md | 2 +- 5 files changed, 1 insertion(+), 1205 deletions(-) delete mode 100644 @types/oxfmt_configuration_schema.json delete mode 100644 @types/oxlint_configuration_schema.json diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 67a7438f1..0e3ec721c 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -15,7 +15,6 @@ "docs/**", "memory/**", ".fixtures/**", - "@types/**", "tmp/**", "dist-web/**", "bin/**", diff --git a/.oxlintrc.json b/.oxlintrc.json index 9f1a29efd..3a2bd79a4 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -84,7 +84,6 @@ "docs/**", "memory/**", ".fixtures/**", - "@types/**", "tmp/**", "src/**/_suspended/**", "dist-web/**", diff --git a/@types/oxfmt_configuration_schema.json b/@types/oxfmt_configuration_schema.json deleted file mode 100644 index ee3ded8a6..000000000 --- a/@types/oxfmt_configuration_schema.json +++ /dev/null @@ -1,648 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Oxfmtrc", - "description": "Configuration options for the Oxfmt.\n\nMost options are the same as Prettier's options, but not all of them.\nIn addition, some options are our own extensions.", - "type": "object", - "properties": { - "arrowParens": { - "description": "Include parentheses around a sole arrow function parameter.\n\n- Default: `\"always\"`", - "allOf": [ - { - "$ref": "#/definitions/ArrowParensConfig" - } - ], - "markdownDescription": "Include parentheses around a sole arrow function parameter.\n\n- Default: `\"always\"`" - }, - "bracketSameLine": { - "description": "Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,\ninstead of being alone on the next line (does not apply to self closing elements).\n\n- Default: `false`", - "type": "boolean", - "markdownDescription": "Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,\ninstead of being alone on the next line (does not apply to self closing elements).\n\n- Default: `false`" - }, - "bracketSpacing": { - "description": "Print spaces between brackets in object literals.\n\n- Default: `true`", - "type": "boolean", - "markdownDescription": "Print spaces between brackets in object literals.\n\n- Default: `true`" - }, - "embeddedLanguageFormatting": { - "description": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\nNOTE: XXX-in-JS support is incomplete.\n\n- Default: `\"auto\"`", - "allOf": [ - { - "$ref": "#/definitions/EmbeddedLanguageFormattingConfig" - } - ], - "markdownDescription": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\nNOTE: XXX-in-JS support is incomplete.\n\n- Default: `\"auto\"`" - }, - "endOfLine": { - "description": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`", - "allOf": [ - { - "$ref": "#/definitions/EndOfLineConfig" - } - ], - "markdownDescription": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`" - }, - "htmlWhitespaceSensitivity": { - "description": "Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.\n\n- Default: `\"css\"`", - "allOf": [ - { - "$ref": "#/definitions/HtmlWhitespaceSensitivityConfig" - } - ], - "markdownDescription": "Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.\n\n- Default: `\"css\"`" - }, - "ignorePatterns": { - "description": "Ignore files matching these glob patterns.\nPatterns are based on the location of the Oxfmt configuration file.\n\n- Default: `[]`", - "type": "array", - "items": { - "type": "string" - }, - "markdownDescription": "Ignore files matching these glob patterns.\nPatterns are based on the location of the Oxfmt configuration file.\n\n- Default: `[]`" - }, - "insertFinalNewline": { - "description": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`", - "type": "boolean", - "markdownDescription": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`" - }, - "jsxSingleQuote": { - "description": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`", - "type": "boolean", - "markdownDescription": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`" - }, - "objectWrap": { - "description": "How to wrap object literals when they could fit on one line or span multiple lines.\n\nBy default, formats objects as multi-line if there is a newline prior to the first property.\nAuthors can use this heuristic to contextually improve readability, though it has some downsides.\n\n- Default: `\"preserve\"`", - "allOf": [ - { - "$ref": "#/definitions/ObjectWrapConfig" - } - ], - "markdownDescription": "How to wrap object literals when they could fit on one line or span multiple lines.\n\nBy default, formats objects as multi-line if there is a newline prior to the first property.\nAuthors can use this heuristic to contextually improve readability, though it has some downsides.\n\n- Default: `\"preserve\"`" - }, - "overrides": { - "description": "File-specific overrides.\nWhen a file matches multiple overrides, the later override takes precedence (array order matters).\n\n- Default: `[]`", - "type": "array", - "items": { - "$ref": "#/definitions/OxfmtOverrideConfig" - }, - "markdownDescription": "File-specific overrides.\nWhen a file matches multiple overrides, the later override takes precedence (array order matters).\n\n- Default: `[]`" - }, - "printWidth": { - "description": "Specify the line length that the printer will wrap on.\n\nIf you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.\n\n- Default: `100`\n- Overrides `.editorconfig.max_line_length`", - "type": "integer", - "format": "uint16", - "minimum": 0.0, - "markdownDescription": "Specify the line length that the printer will wrap on.\n\nIf you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.\n\n- Default: `100`\n- Overrides `.editorconfig.max_line_length`" - }, - "proseWrap": { - "description": "How to wrap prose.\n\nBy default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.\nTo wrap prose to the print width, change this option to \"always\".\nIf you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use \"never\".\n\n- Default: `\"preserve\"`", - "allOf": [ - { - "$ref": "#/definitions/ProseWrapConfig" - } - ], - "markdownDescription": "How to wrap prose.\n\nBy default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.\nTo wrap prose to the print width, change this option to \"always\".\nIf you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use \"never\".\n\n- Default: `\"preserve\"`" - }, - "quoteProps": { - "description": "Change when properties in objects are quoted.\n\n- Default: `\"as-needed\"`", - "allOf": [ - { - "$ref": "#/definitions/QuotePropsConfig" - } - ], - "markdownDescription": "Change when properties in objects are quoted.\n\n- Default: `\"as-needed\"`" - }, - "semi": { - "description": "Print semicolons at the ends of statements.\n\n- Default: `true`", - "type": "boolean", - "markdownDescription": "Print semicolons at the ends of statements.\n\n- Default: `true`" - }, - "singleAttributePerLine": { - "description": "Enforce single attribute per line in HTML, Vue, and JSX.\n\n- Default: `false`", - "type": "boolean", - "markdownDescription": "Enforce single attribute per line in HTML, Vue, and JSX.\n\n- Default: `false`" - }, - "singleQuote": { - "description": "Use single quotes instead of double quotes.\n\nFor JSX, you can set the `jsxSingleQuote` option.\n\n- Default: `false`", - "type": "boolean", - "markdownDescription": "Use single quotes instead of double quotes.\n\nFor JSX, you can set the `jsxSingleQuote` option.\n\n- Default: `false`" - }, - "sortImports": { - "description": "Sort import statements.\n\nUsing the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).\nFor details, see each field's documentation.\n\n- Default: Disabled", - "allOf": [ - { - "$ref": "#/definitions/SortImportsConfig" - } - ], - "markdownDescription": "Sort import statements.\n\nUsing the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).\nFor details, see each field's documentation.\n\n- Default: Disabled" - }, - "sortPackageJson": { - "description": "Sort `package.json` keys.\n\nThe algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).\nBut we believe it is clearer and easier to navigate.\nFor details, see each field's documentation.\n\n- Default: `true`", - "allOf": [ - { - "$ref": "#/definitions/SortPackageJsonUserConfig" - } - ], - "markdownDescription": "Sort `package.json` keys.\n\nThe algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).\nBut we believe it is clearer and easier to navigate.\nFor details, see each field's documentation.\n\n- Default: `true`" - }, - "sortTailwindcss": { - "description": "Sort Tailwind CSS classes.\n\nUsing the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).\nOption names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).\nFor details, see each field's documentation.\n\n- Default: Disabled", - "allOf": [ - { - "$ref": "#/definitions/SortTailwindcssConfig" - } - ], - "markdownDescription": "Sort Tailwind CSS classes.\n\nUsing the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).\nOption names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).\nFor details, see each field's documentation.\n\n- Default: Disabled" - }, - "tabWidth": { - "description": "Specify the number of spaces per indentation-level.\n\n- Default: `2`\n- Overrides `.editorconfig.indent_size`", - "type": "integer", - "format": "uint8", - "minimum": 0.0, - "markdownDescription": "Specify the number of spaces per indentation-level.\n\n- Default: `2`\n- Overrides `.editorconfig.indent_size`" - }, - "trailingComma": { - "description": "Print trailing commas wherever possible in multi-line comma-separated syntactic structures.\n\nA single-line array, for example, never gets trailing commas.\n\n- Default: `\"all\"`", - "allOf": [ - { - "$ref": "#/definitions/TrailingCommaConfig" - } - ], - "markdownDescription": "Print trailing commas wherever possible in multi-line comma-separated syntactic structures.\n\nA single-line array, for example, never gets trailing commas.\n\n- Default: `\"all\"`" - }, - "useTabs": { - "description": "Indent lines with tabs instead of spaces.\n\n- Default: `false`\n- Overrides `.editorconfig.indent_style`", - "type": "boolean", - "markdownDescription": "Indent lines with tabs instead of spaces.\n\n- Default: `false`\n- Overrides `.editorconfig.indent_style`" - }, - "vueIndentScriptAndStyle": { - "description": "Whether or not to indent the code inside `