* feat(#2995): extend fragment emission to agents/ across every read point
Epic #1671 Phase 6.4. `composeWorkflow` stripped `<!-- gsd:section -->` markers
only for `gsd-core/workflows/`, so a marked agent shipped its markers verbatim
into every runtime — and agent text is loaded into a subagent's context on every
dispatch.
The issue proposed widening the `copyWithPathReplacement` guard. That is a no-op
for agents: agents never traverse that function. Agent content is read for
emission at five independent points, and the obvious chokepoint
`stageAgentsForProfile` short-circuits on the DEFAULT `full` profile
(`skills === '*'` returns the real unstaged directory), so a hook placed there is
dead code on most installs.
Composition now happens at two call sites instead of five parallel surfaces:
`stageAgentsForRuntimeWithConverter` (with `agentsKind` and `kimiAgentsKind`
routed through it via an identity converter) and the inline agent loop in
bin/install.js. Both compose BEFORE any path rewrite, so a `.claude/` ->
`.windsurf/` regex can never reach inside a marker attribute — the ordering
#2930 established for workflows.
`installCodexConfig` was the fifth read point: Codex embeds each agent's prompt
into a per-agent `.toml` via its own readFileSync. Call-graph analysis missed it;
the exhaustive per-runtime emission sweep found it. That is why the new guard is
behavioral rather than structural — a sixth read point fails the sweep without
anyone remembering to extend a list.
tests/agent-fragments-emission.install.test.cjs spawns a real installer for every
runtime at every agent-bearing scope, derived from RUNTIME_META and the
capability registry at run time so a new runtime cannot be silently
under-covered. It asserts markers are absent AND the `when="always"` body is
retained, so marker-absence cannot be satisfied by dropping content. An
identity-composer negative control proves the assertion can fail.
Verified: 0 install failures, 0 marker leaks, body retained on 27 runtime/scope
paths; red before the wiring on claude(global+local), zcode(global+local),
kimi, codex and opencode.
Refs #2995
* chore(#2995): give the tightest agents headroom and correct the design lock
Epic #1671 Phase 6.4, second half.
`agents/gsd-verifier.md` had 12 bytes of headroom under its 49,152-byte LARGE
cap and `agents/gsd-debugger.md` had 147 under its 57,344-byte XL cap. Both now
extract reference material to `gsd-core/references/` behind an @-reference — the
documented DEFECT.AGENT-FILE-SIZE-CAP-BREACH remedy:
gsd-verifier 49,140 -> 46,371 B headroom 12 -> 2,781
gsd-debugger 57,197 -> 48,851 B headroom 147 -> 8,493
Byte accounting proves no content was lost: the combined agent+reference delta
is exactly the new files' headers plus the agents' slim replacement blocks. Each
agent keeps its routing table and a one-line summary per entry, so it degrades
gracefully on a runtime that does not inline @-references.
`agents/gsd-planner.md` is untouched and still passes both char guards
(49,130 < 49,152); it needed no change, so it took none.
The other nine LARGE/XL agents carry NO gsd:section markers, and that is
deliberate, not deferred. `when=` selection is read from
gsd-core/workflows/section-manifest.json, which gen-section-manifest.cjs derives
from gsd-core/workflows/*.md only — shape `{workflows: ...}`, no per-agent key,
no per-agent init entry point. An agent atom therefore fails admission gate (2)
("a fact the init seam demonstrably computes at a real entry point") and would
evaluate false forever while looking like working gating. Marking agents would
manufacture exactly the silent-inertness rot the frozen vocabulary exists to
prevent.
ADR-1671 gains three amendments, two of which close gaps /adr-phase-coverage
found against what actually merged:
- The 19 -> 29 vocabulary widening shipped in #2994 with no coordinated ADR
amendment, which that bullet's own rule forbids. Recorded now.
- `flag:--verify-only` was one of six atoms #2992 withheld and deferred to
"the LARGE/XL rollout phase". Five shipped; this one is permanently
rejected, and that disposition lived only in a merged PR body.
- Phase 6.4's own finding: emission extends to agents/, gating does not.
CONTEXT.md's glossary was stale on both seams — Workflow Fragments Module still
listed the original 4-atom vocabulary and described when= as "not yet acted on",
and Section Manifest Module still described InvocationFacts as
{waveFlag, phaseNumber, hasPriorPhases}. Both now match the shipped contract.
Inventory manifest regenerated AFTER build:lib per the documented ordering
landmine; 19 install-tree fixtures pick up the two new references.
Refs #2995
* chore(#2995): correct the compose-site count and mark the raw stager
Self-review found two comment defects in the prior commit. The agentsKind
comment claimed composition lands at TWO call sites; it is three, since
installCodexConfig's per-agent .toml writer was added after that comment was
written. And stageAgentsForProfile is now production-dead — both callers route
through the composing stager — while staying exported and unit-tested, which
makes it a trap: it does a raw copyFileSync and short-circuits to the unstaged
source directory under the default profile, so a future caller would silently
reintroduce the marker-shipping path. Its JSDoc now says so.
* test(#2995): guard the marker-documenting-doc class for agents
Widening the composer's scope to agents/ makes reachable the exact class #2930
narrowed scope to avoid: a file that DOCUMENTS the marker syntax with an
unfenced example is indistinguishable from a real marker, so the composer drops
that line from the emitted artifact.
Three rows. A fenced example must compose byte-identically. No shipped agent may
carry a marker outside a fence — asserted by parsing every real agent and
requiring zero explicit sections, which is what makes the fence protection
load-bearing rather than decorative. And a non-vacuity row asserts an UNFENCED
marker IS parsed as a real marker, so if that ever stops being true the second
row is guarding nothing.
Also applies two review findings: stageAgentsForProfile's new JSDoc claimed it
had no production caller, which is false — bin/install.js's _stageAgents still
calls it, and its consumers compose before writing. Corrected to state the
invariant instead. And a let/const nit in the emission sweep.
* fix(#2995): keep verifier status vocabulary in the agent, fix a wrong fixture
The first remote run came back red with three failures. Both root causes were
mine.
1. tests/agent-frontmatter.test.cjs requires agents/gsd-verifier.md to literally
contain HOLLOW and DISCONNECTED. The Step 4b extraction moved that status
vocabulary into gsd-core/references/verifier-wiring-patterns.md, so the agent
no longer had it.
Byte accounting said no content was lost, and byte-wise that was true — but a
contract required those tokens to live IN THE AGENT. That is ADR-1671:66's
flexReserve floor stated concretely: a load-bearing fragment must not be
trimmed out of its host, and "the bytes still exist somewhere" is not the
test. The two status tables are restored to the agent and deliberately
mirrored in the reference with a note saying so, so the procedure there still
reads standalone. gsd-verifier lands at 47,069 B — headroom 12 -> 2,083,
rather than the 2,781 the first attempt claimed.
2. Row 12b of the new marker-documentation guard asserted that an unfenced
marker example parses as a real marker, and threw instead:
"unmatched /gsd:section close marker". The grammar is WHOLE-LINE only. The
fixture had put the OPEN marker inline mid-sentence, so it was correctly not
recognised as an open while the close, on its own line, was.
That is a real refinement of the hazard this guard exists for: only a marker
on its OWN line is mis-parsed — which is exactly how a documentation example
is normally written. Row 12b now uses a whole-line marker, and a new row 12c
pins the inline case as explicitly NOT a marker.
No test was weakened to accommodate the change; the change was corrected to
satisfy the tests.
Refs #2995
* chore(#2995): backfill changeset pr number to 3058
---------
Co-authored-by: sim <sim@local>
ed360cd99f