* enhance(#4139): Phase 7 — the agent-skill seam picks the payload in code
ADR-4139 stream 2. The non-Claude `#2454` persona fallback in cmdAgentSkills
(src/init.cts) now selects between a canonical agents/<name>.md and a
token-minimized agents/<name>.compact.md sibling based on
workflow.compact_content, resolved in code (a real function call with a real
exit code) rather than a prose config-get gate — the same precedent stream 1's
spine/detail split established for a load-bearing seam, applied here because
this seam already runs through TypeScript instead of an eager @-include.
A missing compact sibling falls back to the canonical persona and discloses
the fallback in the served payload itself (a leading HTML-comment provenance
line), so the Done-when contract — compact when on, canonical when off, never
silent or empty — holds even for an agent nobody has compacted yet.
Authored a .compact.md sibling for all 35 shipped agents (agents/gsd-*.md),
each an independent, complete rewrite (not an extraction — nothing is "moved"
the way spine/detail moves text) that preserves frontmatter, every @-include,
every output-format contract, and every guardrail verbatim while cutting
restatement and verbose framing. Verified mechanically: every pair registers
(a canonical sibling exists), every compact file is strictly smaller, and the
full @-include set matches canonical's — including which references are
standalone eager-load lines versus inline prose mentions, since demoting one
to inline changes what the host actually substitutes.
Traced the install path before writing any code (.gsd/phase/.../40-design.md):
stageAgentsForRuntimeWithConverter glob-copies every agents/*.md file with no
stem filtering under the default full profile, so the new .compact.md files
install for free with zero installer changes — matching issue #4407's stated
scope. A tiered agent profile that doesn't stage a compact sibling degrades
through the same fallback-with-provenance path already required for an
unauthored one, so no installer change is needed there either.
Extends tests/helpers/compact-content-variant.cjs with an AGENTS_ROOT export
(deliberately not folded into DEFAULT_VARIANT_ROOTS, since agent variants are
reached by a generic code construction rather than a literal path in prose,
and checkReachability's markdown-search shape has nothing to find there).
Reachability is instead proven behaviorally: tests/agent-skills.test.cjs's new
"#4407 compact payload selection" describe block spawns gsd_run agent-skills
against real compact/canonical fixture pairs and asserts on the served
payload, which can only pass if the seam genuinely wires through.
Fixed a pre-existing test whose agents/*.md glob incidentally matched the new
.compact.md siblings (tests/agent-skills.test.cjs's Skill-frontmatter drift
guard) and added the 35 new agents/*.compact.md entries to docs/INVENTORY.md's
roster, both real, unrelated-to-content defects the new files' mere existence
surfaced.
Regenerated: install-tree fixtures (19 runtimes now ship 35 more agent files
under the full profile), INVENTORY-MANIFEST.json, and the variant-swap token
benchmark baseline (npm run benchmark:compact-content-variants --write).
Closes#4407.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(#4407): apply orthogonal review findings from the compact-payload seam
Standards axis of /code-review: extracted readNonEmptyFileOrNull(filePath)
to collapse the duplicated read-and-empty-check shape between the compact
and canonical branches in cmdAgentSkills, and updated the adjacent comment
enumerating flat JSON extras to name agent_payload_variant alongside
source/degraded (added by the prior commit, comment left stale).
Security review and the Spec axis found no defects requiring a code change;
their non-blocking observations (a pre-existing, unmodified path-construction
pattern; the reasoned, documented substitution of a behavioral test for the
literal reachability check) are recorded in
.gsd/phase/enhance-4407-agent-skill-seam/60-review.json.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(#4407): repo-wide roster/cap fixes surfaced by shipping .compact.md agents
Root-caused via a real gsd-test run (93 failures) rather than guessing which
tests glob agents/ naively. Two classes of defect, both genuine:
1. Identity-roster confusion (11 files/areas): many tests and one production
script derive "the set of GSD agents" from `readdirSync(agentsDir).filter(f
=> f.endsWith('.md'))`, which incidentally matched the new .compact.md
variant siblings too — a compact file is a rendering of an EXISTING agent
identity, not a new one. Fixed at the shared root
(tests/helpers/agent-roster.cjs's listAgentFiles, which several tests
already consolidated on) and at each independent glob that didn't use it:
agent-size-budget.test.cjs (tier-cap lookup now strips the .compact suffix
before checking XL/LARGE membership, so a compact file inherits its
canonical sibling's tier instead of silently falling through to DEFAULT),
agent-skills-bootstrap.test.cjs, check-contract-drift.test.cjs (the actual
script, not just its test), codex-config.test.cjs (confirmed directly
against generateCodexAgentToml that a compact role's derived sandbox_mode
is byte-identical to its canonical sibling's before excluding it — not
assumed), and copilot-install.test.cjs (two counts that legitimately DO
need both files — an installed-file count and a full-conversion smoke test
— fixed to expect 70, not stay pinned to 35).
no-bare-gsd-tools-command-position.test.cjs needed the opposite kind of fix:
two compact files reproduce descriptive prose already allowlisted at their
canonical file's line number; added matching entries at the compact files'
own line numbers rather than excluding them from the scan (a genuine bare
gsd-tools command-position bug in a compact file would be as real a defect
as in canonical).
2. A hard, non-ackable cap (found via emitted-attribution.test.cjs's real-tree
run): six agents' compact renditions (gsd-debugger, gsd-executor,
gsd-phase-researcher, gsd-plan-checker, gsd-planner, gsd-verifier) exceed
the 32,768-byte NEW_FILE_CAP (ADR-1610) even after aggressive compaction —
confirmed structural, not a compaction-quality gap: each is dominated by
content this phase's own rules require verbatim (the ~2.6 KB gsd_run
bootstrap preamble runtime-launcher-parity.test.cjs requires inlined in
every agent that calls gsd_run, output-format contracts, guardrails).
ADR-4139's prescribed remedy (spine + lazily-read parts) has no landing
spot in cmdAgentSkills's single-file synchronous read. Removed these 6
compact files rather than ship an over-cap file or invent a multi-part
read mechanism out of scope for this phase; recorded by name with the
reason in .gsd/phase/enhance-4407-agent-skill-seam/40-design.md and
50-test-matrix.md, per #4407's own "or explicitly recorded as not worth
covering" allowance. Their canonical personas are served correctly today
via the fallback-with-disclosed-provenance path this phase's own Done-when
#2 already requires — 29 of 35 agents now have a compact variant.
Also fixes an unrelated, genuinely pre-existing defect this gsd-test run
surfaced: gsd-core/workflows/execute-plan.md sat 21 bytes over its own
DEFAULT-tier hard cap (40,960 bytes) at the branch point, before any change in
this PR touched it — confirmed via `git show <merge-base>:...execute-plan.md
| wc -c`. Per CLAUDE.md's no-deferral rule, fixed inline rather than filed:
two meaning-preserving trims in the <success_criteria> block (a repeated
parenthetical replaced with a same-exception reference; one redundant
qualifier dropped) bring it to 40,940 bytes.
Regenerated install-tree fixtures, INVENTORY-MANIFEST.json, and the variant
benchmark baseline to reflect the 6 removed files. Docs/INVENTORY.md's 6
now-orphaned roster rows removed alongside them.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(#4407): make .compact.md-aware roster checks resilient to partial coverage
Round 2 of the gsd-test-driven roster fixes: two checks assumed every agent
has a compact sibling (true for 29 of 35 after the NEW_FILE_CAP exception),
breaking once 6 stems legitimately have none.
- tests/agent-classification-parity.test.cjs: the INVENTORY.md parser was
picking up the "### Compact Payload Variants" subsection's rows as
phantom/uncounted entries in the primary/advanced/inventory-only
classification this test validates — a compact row documents an existing
agent's alternate rendition and never gets its own AGENTS.md heading, so it
was never meant to participate in that classification. Excluded at the
parser, not per-assertion.
- tests/copilot-install.test.cjs: the derived expected-file-list generator
assumed every listAgentFiles() stem has a .compact.md source sibling;
checks disk per stem now instead.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs(#4407): backfill changeset PR number
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: sim <sim@local>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
37b965c0d1