#971 Inline output-shaping specs so skills cannot improvise them

[williamthorsen]

What

Addresses malformed next-steps menus and option-style questions: dropped numbering, a recommendation that didn't match the top-rated option, and menus that never appeared at all. Skills presenting these blocks are now instructed to build them from formatting rules the skill states directly. A companion rule directs that any shared instruction an agent must reproduce be stated in the skill that uses it, while material it only consults stays in a linked reference.

Why

Agents were producing next-steps menus and option lists that looked plausible but were wrong, and on one harness produced nothing at all. Stronger wording had already been tried and had not held — a hard gate demanding the options be followed exactly, and not improvised, sat directly over the defect and did not change the outcome. The fix had to be structural rather than another round of emphasis.

Details

🐛 Bug fixes

• The option-format contract and the two next-steps menus are inlined into the ten skills that render them, once per skill, with every point of use reaching the block by an in-file anchor. A skill with two menu sites therefore carries one copy, and a reference from inside a numbered procedure does not have to absorb the block inline.
• plan, save-plan, and review-branch gain the option-format rules outright; they render gradient options but previously reached the rules only indirectly.
• The rule that the per-line pro/con indent applies even to an option carrying a single pro or con is restored, having been dropped when the contract was distilled.
• The wider doctrine behind the format — when a confirmation prompt fits better than a numbered list, how to rank options against one another — stays a linked reference and includes the inlined contract, so it still reads whole and there is one source of truth.

🧪 Tests

• A build-time guard fails on a Markdown link whose file target is missing, or whose anchor names no heading or two. Links are resolved the way the install pipeline resolves them — after include expansion, against the host file's directory — so a link authored in a shared fragment is checked in each context it renders into. Fenced code blocks are excluded from both link and heading scanning, since a fence illustrates output rather than declaring it.
• A second guard asserts each consuming skill carries each spec exactly once, and pins the individual rules that must survive distillation.

📚 Documentation

• The partials reference states the rule deciding where a shared fragment belongs, and names the failure mode it prevents: a runtime link is an optional read, and where the model holds a prior for the content it generates from that prior instead of fetching. The maintainer-directed note explaining why the skill-local pointers are deliberate moves out of the shipped tree and into that reference.

Closes #971

[github-actions]

Dependency audit

Production dependency audit passed.