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

packages/agents/content/_partials/README.md

@@ -4,6 +4,23 @@ Partials are reusable Markdown fragments shared across skills, subagents, and pl
 
 This README is the canonical reference for the partial system. The expander is implemented in `packages/agents/src/lib/directive-expander.ts`.
 
+## Choosing a bucket
+
+Shared Markdown lives in one of two buckets. The choice is not stylistic — it decides whether the agent reliably sees the content.
+
+- **`_partials/` — content the agent must reproduce.** Output blocks, option menus, render formats, checklists it works through. Inlined at install time, so it is in context the moment the agent generates output.
+- **`_data/` — content the agent consults conditionally.** Resolution tables, classification rubrics, doctrine references. Reached by a runtime Markdown link and read only when the situation calls for it.
+
+A runtime link is an optional read. Where the model already holds a strong prior for what the content looks like — and it does, for anything resembling a standard option menu or output block — it generates from that prior instead of taking the hop. Emphasis is not a remedy: a `<HARD-GATE>` reading "follow its options and output format exactly; do not improvise" sat over one such link, and the block was improvised anyway. Never put must-reproduce content behind a runtime link.
+
+Inlining is not free — a partial's cost is paid by every consumer — so content the agent needs only sometimes stays in `_data/`. A spec that is partly must-reproduce and partly reference splits along that seam: the render contract becomes a partial, and the doctrine stays in `_data/` and includes the partial, so there is still one source of truth.
+
+Inline a spec **once per skill, as a section**, and point every use site at it with an in-file anchor (`[option format](#option-format)`). Anchor-only links pass through the link rewriter untouched. A skill with two use sites would otherwise carry the block twice, and a reference from inside a numbered procedure cannot absorb a long block inline. An in-file anchor costs nothing, because the content is already in context — the filesystem hop is the defect, not the pointer.
+
+### Skill-local pointers are load-bearing
+
+Several skill bodies — `collaborate`, `design-and-plan`, and `refine-plan` among them — carry a pointer to the option-format rules at their question-asking steps, duplicating the universal rule in `AGENTS.md`. That duplication is intentional: agents follow a behavioural rule more reliably when the directive sits near the action it governs. Do not remove these pointers during DRY-driven refactors — the redundancy is load-bearing.
+
 ## Directive grammar
 
 Three include shapes are recognized. Each must occupy a full line, with optional leading and trailing whitespace. Inline directives inside prose or code spans are not expanded.

packages/agents/content/skills/_data/recommendation-gradient.md

@@ -1,9 +1,11 @@
 # Recommendation gradient
 
-> **Note for maintainers:** Several skill bodies — including `collaborate/SKILL.md`, `design-and-plan/SKILL.md`, and `refine-plan/SKILL.md` — contain pointers back to this file at their question-asking steps. Those pointers duplicate the universal rule in `AGENTS.md` _intentionally_: Agents follow behavioural rules more reliably when the directive sits near the action it governs. Do not remove these pointers during DRY-driven refactors — the redundancy is load-bearing.
-
 For numbered option-style questions with 2 or more choices, mark each option with a strength gradient and a brief rationale. The gradient applies to every list with substantive tradeoffs, including templated next-steps menus and substantive binary choices.
 
+The render contract comes first; the doctrine behind it follows. Skills that ask option-style questions carry the render contract inlined, so what they consult here is the doctrine.
+
+<!-- include: ../_partials/option-format.md / -->
+
 ## Confirmation prompts vs. substantive binaries
 
 Reserve `👍🏼👎🏼` for confirmation prompts, where the agent has proposed a single action and the user's response is approve-or-redirect. "No" means "let's adjust or discuss," not a concrete alternative agent action.
@@ -31,46 +33,11 @@ Same surface phrasing, two correct renderings:
 
 Both "yes" (extract) and "no" (inline) are concrete agent actions with their own tradeoffs.
 
-## Markers
-
-| Marker | Label                | When to use                                                                              |
-| ------ | -------------------- | ---------------------------------------------------------------------------------------- |
-| ■■■    | strongly recommended | You'd actively push back if the developer picked otherwise. Reserve for clear-cut cases. |
-| ■■□    | recommended          | Your lean. Default level when you have a preference.                                     |
-| ■□□    | weakly recommended   | A slight edge; mostly preference.                                                        |
-| □□□    | not recommended      | Clear drawbacks; included for completeness or to rule out explicitly.                    |
-
-If you have no preference (pure taste call), omit markers from every option. Don't explain the omission — the absence is the signal.
-
-Render markers as plain text, never inside backticks — backticks shrink the glyphs and hurt readability.
-
 ## Ranking criteria
 
 Rank options on correctness — behavior, API quality, architectural soundness, testability, maintainability — and treat convenience considerations (effort, blast radius, consistency with existing code) as secondary. See [design priorities](./design-priorities.md) for the full rule and a before/after example.
 
-## Format
-
-Marker, then option title and colon. Each pro (`➕`) and con (`➖`) goes on its own line, prefixed with 3 non-breaking-space characters (NBSP, U+00A0) for visual indent — regular ASCII spaces are commonly stripped or normalized in model output, so a visible character is needed to make the indent reliable. Apply this even when an option has only one pro or con. Lead with the strongest argument. Use semicolons between items and a period on the last.
-
-## Question identifiers
-
-When a single response contains 2+ option-style questions, prefix each question with an identifier so the user can reference answers unambiguously (e.g., "Q1: Option 2"). Default to `Q1`, `Q2`, etc. When the skill's underlying data already carries stable identifiers — for example, `refine-plan` presents questions tied to plan-review findings like `C1`, `X2` — use those identifiers in place of `Q1/Q2` so the cross-skill mapping is preserved. For a single option-style question, omit the identifier.
-
-## Examples
-
-Single question with markers:
-
-```
-Want me to:
-1. ■□□ Use a single config file:
-   ➕ minimal surface area;
-   ➖ couples concerns.
-2. ■■■ Split into two configs:
-   ➕ separates lifecycle and runtime concerns;
-   ➕ matches existing repo pattern.
-3. □□□ Use three configs:
-   ➖ over-decomposed for current scope.
-```
+## Further examples
 
 Single question without markers (pure taste call):
 
@@ -97,10 +64,3 @@ Multiple questions in one response (Q1/Q2 identifiers):
 2. ■□□ Place in shared utility module:
    ➕ reusable across packages.
 ```
-
-## Don'ts
-
-- No tiebreaker text for equal-strength options. The developer picks the number.
-- No partial marking. Once any option carries a marker, every option carries one.
-- Cap at ■■□ unless you'd push back. Use ■■■ only when you'd actively object if the developer chose otherwise.
-- No generic pros or cons. Each `➕` and `➖` must speak to the specific decision at hand (this plan, these findings, this design choice). Restatements of an option's inherent properties ("longer wall time", "structured review pass", "ships faster") are noise; the option's name and marker already communicate them. When no context-specific reasoning applies, omit pros and cons entirely — the marker alone is sufficient.

packages/agents/content/skills/_data/next-steps-after-plan.md → packages/agents/content/skills/_partials/next-steps-after-plan.md

@@ -1,8 +1,6 @@
-# Next steps after plan
+## Next-steps options
 
-Standard next-steps block for skills that produce or refine an implementation plan. Skills reference this file to maintain a consistent format and recommendation logic.
-
-## Options
+### Options
 
 | #   | Emoji | Option                                   | Description                                                             |
 | --- | ----- | ---------------------------------------- | ----------------------------------------------------------------------- |
@@ -11,9 +9,9 @@ Standard next-steps block for skills that produce or refine an implementation pl
 | 3   | 🚀🔍  | Implement directly with follow-up review | Implement, then run a single end-of-work review pass as a separate step |
 | 4   | 🚀    | Implement directly                       | Implement without a follow-up review (reserved for trivial work)        |
 
-## Output format
+### Output format
 
-Present all four options as a numbered list in [recommendation-gradient](./recommendation-gradient.md) form. Each option carries a strength marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option earns the strongest marker. Pros and cons are omitted by default — add a `➕` or `➖` line only when the specific plan presents a context-specific tradeoff bearing on which option fits (e.g., "plan introduces a new dependency boundary," "single module with no downstream effects"). Generic option properties ("structured review pass," "longer wall time") are noise and must be omitted; see the [recommendation gradient's don'ts](./recommendation-gradient.md#donts) for the rule. Include all known paths (plan, ticket) in each option line; omit paths that are not available in the current context. Use `~/`-relative paths where possible and absolute paths otherwise.
+Present all four options as a numbered list per [option format](#option-format). Each option carries a strength marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option earns the strongest marker. Pros and cons are omitted by default — add a `➕` or `➖` line only when the specific plan presents a context-specific tradeoff bearing on which option fits (e.g., "plan introduces a new dependency boundary," "single module with no downstream effects"). Generic option properties ("structured review pass," "longer wall time") are noise and must be omitted. Include all known paths (plan, ticket) in each option line; omit paths that are not available in the current context. Use `~/`-relative paths where possible and absolute paths otherwise.
 
 Options that invoke a skill include context-clearing guidance:
 
@@ -45,7 +43,7 @@ Skill names for each option:
 - 🚀🔍 **Implement directly with follow-up review** -> no plan-time skill invocation; implement manually, then run `review-branch` (or `orchestrate-review`) as a separate post-implementation step
 - 🚀 **Implement directly** -> no skill invocation; implement manually or ask the agent to begin
 
-## Recommendation rules
+### Recommendation rules
 
 Select the recommended option by checking these rules in order and stopping at the first match.
 
@@ -66,10 +64,10 @@ Select the recommended option by checking these rules in order and stopping at t
 3. **Implement directly** — recommend instead of rule 2 when the work is trivial enough that a review pass would catch nothing meaningful (e.g., a typo fix, unused-import removal, single-file mechanical rename). Complexity levels 1–2 trivial only.
 4. **Orchestrate** — all other cases (default). Cross-cutting changes, novel patterns, or work whose consequences ripple beyond the immediate change site fall here.
 
-### Marker strengths
+#### Marker strengths
 
-The selected option carries the ■■□ marker in the rendered output. The other three options carry ■□□ by default. Reserve □□□ for an alternative with a clear drawback in the current context. Reserve ■■■ for the selected option only when you would actively push back against any other choice. See [recommendation-gradient markers](./recommendation-gradient.md#markers) for the full marker table and worked examples of the ■■■ and □□□ cases.
+The selected option carries the ■■□ marker in the rendered output. The other three options carry ■□□ by default. Reserve □□□ for an alternative with a clear drawback in the current context. Reserve ■■■ for the selected option only when you would actively push back against any other choice.
 
 Each skill supplies its own recommendation context (e.g., whether the plan was developed interactively, whether a review just completed). Apply these rules using that context.
 
-See [`scope-and-deferral.md`](scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) composes with the recommendation rules above: The rules here pick the next-step _skill_; that reference governs whether work that surfaces alongside the current plan should spawn a new ticket or ship adjacent.
+See [`scope-and-deferral.md`](../_data/scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) composes with the recommendation rules above: The rules here pick the next-step _skill_; that reference governs whether work that surfaces alongside the current plan should spawn a new ticket or ship adjacent.