FE-1091: Renderer golden coverage and prompt assembly lock, Part 1

.agents/skills/ln-review/SKILL.md

@@ -65,6 +65,8 @@ If `memory/SPEC.md` §Oracle Strategy by Loop Tier exists, check whether recent
 
 Collect gaps as numbered findings (category: `oracle-coverage`).
 
+**Test-oracle hygiene for topology/prose sentinels.** Source/doc/resource substring tests are suspicious unless they either cross the production consumer that uses the resource (loader, prompt composition, package asset build, public API) or name a live topology contract from SPEC / a co-located README. Brunch intentionally materializes architecture into topology, so do not ban topology tests; distinguish named architecture sentinels from arbitrary path/prose locks. Route repairs to consumer-level tests, named boundary sentinels with decision citations, or deletion of completed-migration residue.
+
 **Notation aid.** Map test artifacts against acceptance leaves with `pseudo matrix` (coverage variant): rows = obligation leaves from a `pseudo tree` decomposition of the frontier acceptance, columns = test artifacts. Gaps surface as `.` cells; partial coverage as `~`. Compact, scannable, and the matrix itself becomes a coverage artifact reviewers can re-run.
 
 ### Load-bearing layer coverage (category: `coverage-candidacy`)

.agents/skills/ln-review/references/contract-lenses.md

@@ -19,6 +19,8 @@ Each finding routes to one of three repairs: **enforce it loudly** (fail on viol
 - A **tagged-union arm that is representable and boundary-accepted but has no semantics anywhere downstream** (validation checks kind membership only; derivation hits a default/zero branch) → a "dark variant" persists as permanently-inert data, silently (graduated 2026-06-11: `field`/`coverage` gap predicates were creatable but derived coverage 0 forever and could not be hand-answered). Repair: one exhaustive `never`-checked owner of per-arm semantics that both validation and derivation ride — every accepted arm gets an implementation or loud rejection at the boundary, and adding an arm without deciding its semantics fails to compile.
 - A **provider-visible string composed outside the ledgered render planes** (`content:` fields, custom entry copy, toolResult text built inline rather than in `renderers/` or the compose path) that restates behavior or decisions maintained elsewhere → the string is a duplicated behavioral claim with no wording oracle and no decision traceability, so decision revisions sweep the surrounding *comments* (reviewed) but not the *payload* (un-oracled), and the model acts on stale instructions (graduated 2026-06-12: `kickTurnMessage` still instructed the model that "a structured exchange offer was just presented" after revised D78-L retired the canned offer — the same module's docstring had been updated; elicitor gap guidance was similarly ad-hoc rather than source-of-truthed). Repair: name the contract — give the surface a ledger row (renderer ledger entry-copy rows) with a wording oracle (golden) or derive it from the source of truth; at minimum tag it with the decision ID it restates so revisions sweep it. Project-scoped lens: it is operative here because the provider-visible channel is enumerable and the golden/ledger discipline exists, and the stakes are high because these strings are control surfaces, not cosmetic copy. (Universal kernel, for calibration only: any string restating a contract maintained elsewhere drifts silently — but at that altitude it stops being searchable.)
 
+- A **topology/prose sentinel test without a product-entrypoint or named-contract oracle** (`readFile` / `access` / `readdir` plus hardcoded `src/...`, README phrases, retired path checks, or arbitrary prompt-resource `toContain` needles) → the test freezes representation or completed-migration residue rather than the behavior a user/runtime observes. It can pass while the production consumer is unwired, or fail during a harmless topology refactor. **Discriminator:** if the assertion crosses the real consumer (loader, prompt composition, package asset build, public API) or explicitly names a live SPEC / topology README contract that cannot be cheaply expressed elsewhere, it is legitimate architecture coverage; otherwise it is a prose/path lock. Repair class **name or relocate the oracle**: move to a consumer-level test, keep a narrow named boundary sentinel with decision citation, or delete the residue once the migration is closed. Do not generalize to "no topology tests" — Brunch deliberately materializes architecture into topology.
+
 - A **capability-readiness / permission gate whose required precondition can only be produced by the capability it gates** — a *circular-precondition gate* (bootstrap-deadlock smell). The gate reads as ordinary defensive readiness ("don't allow X until the frame for X exists"), but the only path to the required state runs *through* X, so a fresh/empty subject can never satisfy it and the gate never opens — silently, with no error, presenting as "the tool just isn't available" (graduated 2026-06-22: `mutate_graph` was gated on `propose-graph` readiness, which required `context`/`thesis`/`goal`/`constraint` nodes that only `mutate_graph` can create — a fresh or foundation-light spec could never establish its own frame; D86-L floored the write tools). **Discriminator (mechanical, clears false positives): does the gated action *produce* the gated-on state?** If yes → circular, floor it. If the gated action only *consumes* state it doesn't write (audit gated on graph truth; a downstream/generative lens gated on a grounded frame it defers creating elsewhere), the gate is legitimate — not every readiness gate is circular. Repair class **floor the bootstrapping capability**: make the state-producing action ungated so the precondition can ever become true; keep readiness *advisory* for it (scale epistemic status / surface an establishment offer) rather than withholding the tool. Search seam: cross the capability→required-state map against the capability→granted-tools/actions map and flag any capability whose granted action writes its own required state.
 
 - An **opaque companion to an enforced discriminant** — a param that carries an enforced discriminant (`kind`/`type`/`action`/`mode` enum) alongside a *companion* (a payload, detail blob, or required-field set) typed `Unknown` / `z.unknown` / `Type.Unknown()` / `z.record(_, z.unknown)` / `looseObject` whose real per-discriminant shape is reconstructed only in a downstream validator. The discriminant is taught and rejected at the boundary; its companion is not — so the author (LLM agent or human) must *know* the per-discriminant shape from outside the schema, guesses it, and burns a turn on a downstream rejection (loud variant), **or** a malformed companion is silently absorbed into an empty/default result and the caller never learns it called wrong (silent variant) (graduated 2026-06-23 from three recurrences: `present_review_set.payload` was `z.unknown()`/`schemaVersion`-only while the nested `grounding`/`pitch`/`epistemicStatus`/`entityDrafts`/`edgeDrafts` shape lived only in `validateReviewSetPayloadShape` (`64fe9a41`, then taught at the boundary); `mutate_graph` create_node `detail: Type.Unknown()` ×2 (agent tool + dev-RPC mirror) while the per-kind `decision`/`term` shape lived only in `command-validation.ts`; the silent face is `read_graph`'s flat-all-optional `mode`↔companion schema returning an empty slice on a malformed call). **Discriminator: is the companion's legal shape a pure function of the discriminant value, and is that mapping enforced only downstream of the boundary?** If yes → opaque companion. (A genuinely free-form blob with no per-discriminant contract is not this lens.) Repair class **name the contract at the boundary**: teach the companion's per-discriminant shape in the boundary schema — structurally (a discriminated union per `create_edge`'s role-named-per-`category` template) or by description — from **one owner the boundary schema and the downstream validator share** (do not fork a second nested model); for the silent variant, make the malformed call unrepresentable (per-`mode` union) or fail loud (`update_elicitation_gaps`-style per-field diagnostics) rather than returning empty. Keep the downstream validator as the diagnostic authority; the boundary only teaches. Search seam: cross each enforced discriminant enum against its companion param's type and flag any companion typed `Unknown`/`unknown`/`record(_, unknown)`/`looseObject` whose real shape is reconstructed in a separate validator. See also `fixture-vs-real-audit` (PLAN) — the same `z.unknown()`/`Type.Unknown()` sites read from the untested-against-real angle.

HANDOFF.md

@@ -0,0 +1,117 @@
+# Handoff
+
+> Generated by `ln-handoff` at 2026-06-26T14:45:15Z. Read this file to resume work.
+> This file is volatile transfer state only. After its contents are reconciled into canonical docs or superseded by a newer handoff, overwrite or delete it.
+
+## Goal
+
+Finish and tie off FE-1091 `renderer-golden-coverage` by ensuring the accepted flat foreground prompt / background subagent topology is implemented, verified, and free of stale `SYSTEM.md` packaging or planning regressions.
+
+## Session State
+
+- **Last completed skill**: `ln-refactor` — produced `memory/REFACTOR.md`; builder implemented all planned commits and deleted the refactor plan.
+- **Current skill**: `ln-handoff` — capturing final volatile review/refactor context.
+- **Flow position**: `grill → spec → plan → [design] → [oracles] → scope → [spike] → build → review → [refactor] → [sync]`; current branch is after review/refactor/build, with no active implementation work remaining.
+- **Handoff trigger**: user requested handoff after builder reported success and a read-only spot check confirmed the judo blockers are closed.
+
+## In-flight work
+
+> CRITICAL: These artifacts exist only in the prior conversation, not on disk.
+> Reproduce them here with full fidelity.
+
+No active scope card or refactor plan remains in flight. `memory/REFACTOR.md` was intentionally deleted after completion. The only remaining volatile state is the review/refactor closure evidence below.
+
+### Completed refactor sequence
+
+The deleted `memory/REFACTOR.md` planned these commits; builder reports they were completed and committed:
+
+1. Make generated agent asset packaging destructive only inside the generated agent-body asset homes, then rebuild those homes from canonical flat foreground and background bodies.
+2. Add packaging/topology characterization that fails if generated or package-bound agent assets contain retired nested prompt-body directories after a build.
+3. Reconcile the active orchestration follow-on scope from the retired orchestrator body to the executor surface and real plan-check target, without implementing that future tool.
+4. Correct prompt/topology prose so current runtime terms and future product vocabulary are not conflated.
+5. Add an executor prompt-composition golden that proves executor prompts do not receive elicitation recommendations or prompt-resource guidance meant only for the elicitor.
+6. Introduce the smallest role boundary in prompt composition so elicitor-only sections are emitted only for elicitor, leaving current elicitor goldens behaviorally unchanged.
+7. Run the full gate and delete the refactor plan once the branch is clean and the topology closure is committed.
+
+### Review findings
+
+> ALL findings from ln-judo-review, not just the one being acted on.
+
+| # | Finding | Status | Implications |
+| --- | --- | --- | --- |
+| 1 | Packaged assets still preserved deleted nested prompt topology because `build:pi-assets` copied into existing `dist/agents/prompts` without cleaning old generated homes. | `addressed` | Commit `86261476` rebuilds generated agent asset homes from flat sources; commit `135f3416` covers generated topology. Spot check showed `dist/agents/prompts` contains only `elicitor.md` and `executor.md`. |
+| 2 | The active `orchestrator-tool-port` scope pointed at retired `src/agents/prompts/orchestrator/SYSTEM.md`, risking resurrection of obsolete topology. | `addressed` | Commit `47ff6748` reconciled the scope to the execute-mode `executor` surface and `cook_plan_check` target. `memory/cards/orchestrator-tool-port--plan-check-tool.md` now reads from `src/agents/prompts/executor.md`. |
+| 3 | SPEC/CODE vocabulary was overclaimed while runtime still exposes `elicit` / `execute`; prompt prose conflated target vocabulary with current runtime state. | `addressed` | Commit `e9d323ab` clarified current execute vocabulary in prompt prose. Do not infer that runtime mode ids have been renamed to SPEC/CODE. |
+| 4 | Prompt composition could leak elicitor-only recommendation / prompt-resource guidance into executor prompts. | `addressed` | Commits `baf1c307` and `054ca69a` locked the executor negative case and gated prompt sections by foreground role. |
+| 5 | `src/.pi/extensions/__tests__/subagents.test.ts` is large (~894 lines) and approaching the 1000-line review threshold. | `deferred` | Not a blocker because this branch did not add new substantive subagent behavior after review. Next subagent feature should consider splitting parser/registry/session/registrar coverage before adding much more. |
+
+### Diagnostic evidence
+
+> Concrete proof points that informed diagnoses or shifted direction.
+> Without these, a new thread inherits conclusions but not reasoning.
+
+- `git status --short --untracked-files=all` returned clean after builder completion: proves no dirty/untracked branch work remained at handoff.
+- `git log --oneline -8` showed the completed refactor stack: `86261476`, `135f3416`, `47ff6748`, `e9d323ab`, `baf1c307`, `054ca69a`, `0809c47d`, preceded by `623fdb39`.
+- `find dist/agents/prompts -maxdepth 3 -type f` showed only `dist/agents/prompts/elicitor.md` and `dist/agents/prompts/executor.md`: proves stale generated nested `SYSTEM.md` bodies are gone from the prompt package asset home.
+- `find dist/agents/subagents -maxdepth 2 -type f` showed `explorer.md`, `projector.md`, `researcher.md`, and `reviewer.md`: proves background subagent assets live in the flat subagent home.
+- `rg` for retired `prompts/<agent>/SYSTEM.md` references found only canonical SPEC/PLAN retirement notes and negative test assertions under `src/agents/prompts/__tests__/prompt-bodies.test.ts`: no active loader/package/reference path was found in the spot check.
+- Builder reported `npm run verify` passed after the final commit: 145 test files passed; 1091 tests passed, 1 skipped, 1 todo; build completed successfully.
+
+## Decisions and assumptions
+
+| Item | Type | Status | Source |
+| --- | --- | --- | --- |
+| Foreground bodies are flat files at `src/agents/prompts/{elicitor,executor}.md`. | `decision` | `persisted` | `memory/SPEC.md`, `memory/PLAN.md`, topology READMEs, code/tests. |
+| Background subagents are flat files at `src/agents/subagents/{explorer,researcher,projector,reviewer}.md`. | `decision` | `persisted` | `memory/SPEC.md`, `memory/PLAN.md`, topology READMEs, code/tests. |
+| Nested `src/agents/prompts/<agent>/SYSTEM.md` is obsolete; no alias/fallback/bridge should be restored. | `decision` | `persisted` | `memory/SPEC.md`, `memory/PLAN.md`, prompt-body tests, build asset topology tests. |
+| Generated package asset homes may be cleaned/rebuilt during build; they are not durable state. | `decision` | `persisted` | Refactor commits and package/build tests. |
+| Runtime mode ids are still current-code `elicit` / `execute`; SPEC/CODE remains target/product vocabulary until a future runtime rename. | `decision` | `persisted` | Prompt/prose clarification commit and current runtime schema. |
+| `orchestrator-tool-port` is next work and should target the execute-mode `executor` surface plus `cook_plan_check`, not a separate orchestrator prompt body. | `decision` | `persisted` | `memory/cards/orchestrator-tool-port--plan-check-tool.md`. |
+| Large subagent test file should be split before substantial future subagent expansion. | `assumption` | `volatile` | Judo review watch item; not yet canonical planning state. |
+
+## Repo state
+
+- **Branch**: `ln/fe-1091-renderer-golden-coverage-and-prompt-assembly-lock`
+- **Recent commits**:
+  - `0809c47d` Flatten agent prompt topology
+  - `054ca69a` Gate prompt sections by foreground role
+  - `baf1c307` Lock executor prompt composition negative case
+  - `e9d323ab` Clarify current execute vocabulary in prompt prose
+  - `47ff6748` Reconcile plan-check scope to executor surface
+  - `135f3416` Cover generated agent asset topology
+  - `86261476` Rebuild agent asset homes from flat sources
+  - `623fdb39` Reopen prompt topology flattening scope
+- **Dirty files**: none at pre-handoff spot check; this `HANDOFF.md` is newly written by `ln-handoff` and should be deleted/overwritten once no longer needed.
+- **Test status**: last known `npm run verify` passed per builder report; not rerun during handoff because no code changed after the builder's full gate.
+
+## Artifact status
+
+| Artifact | Exists | Current vs conversation |
+| --- | --- | --- |
+| `memory/SPEC.md` | yes | current for flat prompt/subagent topology and retired nested prompt-body convention. |
+| `memory/PLAN.md` | yes | current: `renderer-golden-coverage` / context pipeline marked done after topology closure. |
+| `memory/cards/` | one file | `memory/cards/orchestrator-tool-port--plan-check-tool.md` remains live for the next frontier and has been reconciled to the executor surface. The renderer topology scope card was deleted after completion. |
+| `memory/REFACTOR.md` | no | deleted after completed refactor sequence; absence is expected. |
+
+## Next steps
+
+1. If continuing this branch, prepare tie-off/submission: read `docs/praxis/graphite-workflow.md`, inspect the final diff/stack, and use `gt` per project workflow.
+2. If starting the next frontier, use `ln-build` only after confirming the existing active scope `memory/cards/orchestrator-tool-port--plan-check-tool.md` still matches `memory/PLAN.md` and the current executor topology.
+3. Delete `HANDOFF.md` once the next thread has absorbed this volatile state or the branch is submitted.
+
+## Retirement rule
+
+- Delete or overwrite this file once the volatile state above is absorbed into `memory/SPEC.md`, `memory/PLAN.md`, code, or a newer `HANDOFF.md`.
+
+## Open questions
+
+- Should the completed FE-1091 branch be submitted now, or should any additional manual PR review happen first?
+- When the next subagent feature touches `src/.pi/extensions/__tests__/subagents.test.ts`, should that test file be split as preparatory refactor before behavior changes?
+
+## Resume prompt
+
+Paste this into a new session:
+
+> Read `HANDOFF.md` in the workspace root for this work area. It contains the full state of in-progress work.
+> The immediate next step is: prepare tie-off/submission for the completed FE-1091 branch, or start the next `orchestrator-tool-port` scope if the user asks to move on.
+> Start by checking `git status`, reading `docs/praxis/graphite-workflow.md` before any `gt submit`, and confirming `memory/cards/orchestrator-tool-port--plan-check-tool.md` if starting next work.