Decision Record: Planning Carries Only Asked-For Scope

[sameera]

Decision Record: Planning Carries Only Asked-For Scope

Summary

The razor is a rule set with one normative home and one deterministic enforcer: a shared checker in the existing toolkit that counts the limits, verifies asked-citations against a materialized copy of the run's source text, and asserts that no drafting-time token survives into a filed body. Provenance labels live inline beside the items they label in the session-scratch draft and never reach the issue tracker, because filing is done from a derived body whose cleanliness is asserted mechanically rather than remembered. Two gates gain a numbered cut list — the epic approval digest, where whole-story cuts cascade into re-parenting and re-derivation, and a new pre-filing checkpoint in the decision-record stage, where a refuted alternative becomes something the record chose to add rather than a slot it had to fill.

Chosen Approach

One authoring skill states the razor normatively — the two-valued label vocabulary, the citation-normalization rule, the counted limits, the content rules, and the necessity question — and the three drafting stages load it. One toolkit operation implements every check the rules make mechanically decidable, reading a draft plus the run's materialized source text and printing findings; the epic gate invokes it and reports its output rather than counting by eye, and the record and discovery stages invoke the same operation on their own drafts. Each drafting template restates its own limit as a short phrase adjacent to the heading it bounds, because the observed failure showed a heading beating an instruction placed far from it — the restatement is a pointer with a number in it, never the source of truth.

The refuted-alternative rule is the razor's fourth content rule and reaches the decision-record template the same way: the standing slot is removed rather than annotated, and the rule that replaces it is stated once in the skill and restated as a phrase where the architect authors. Because viability is a judgment and not a count, it follows the treatment this epic already fixed for mechanism-naming — prevented at drafting, reported as a non-blocking observation, decided by the reviewer at a gate.

Two facts about the current system drive the decisions below. The epic template is not a separate file but an inline block inside the epic drafting stage, so "stated in the template" resolves to that block. And the decision-record stage has no pre-filing checkpoint at all: its approval gate runs after the sub-issue is already created, and offers only approve-now or leave-open, so there is today no point at which a record body can be reduced before it becomes durable.

Key Decisions

The mechanical checks are one deterministic toolkit operation, not gate-side counting

• Decision: the counted limits, the asked-citation comparison, and the no-token-survives assertion are implemented once as a shared toolkit operation over text; the epic gate, the epic drafting stage, the decision-record stage, and the discovery stage all invoke that one operation and report or act on its findings.
• Why: the same rules must hold identically in four places. Prose-level counting restated four times diverges on the first edit, and the epic's own premise is that a model asked to judge its own additions answers in its own favour — asking that model to count its own list items and eyeball a substring reproduces the failure one layer down. Every mechanical operation in this system already routes through a tested toolkit operation, so this is the existing pattern rather than a new one, and it is what makes the third success metric ("enforced rather than advised") literally true. Story The gate refuses a draft that breaks the rules #287 now carries the checker as well as the gate wiring, and story The other drafting stages apply the same rules #289 reuses it rather than restating the rules.
• Refuted alternative: counting and substring matching inside the gate agent's own prompt. It is genuinely cheaper — no library, no tests, nothing to release — and for a single consumer it would be the right call. It loses because there are four consumers and one of them, the decision-record stage, has no gate agent at all, so the alternative silently means either a second implementation or an unchecked rule for story The other drafting stages apply the same rules #289.

The run's source text is materialized once, beside the draft, before any item is labelled

• Decision: each drafting stage writes the text it was given — the typed capability description in intent mode, the stub issue body in promotion mode, the discovery document plus every resolved ticket in discovery mode — verbatim into a single transient artifact in the same session-scratch working folder as the draft. Every citation check in that run compares against that artifact and nothing else.
• Why: the gate is a separate agent that receives only a draft location, so it cannot see the arguments the lead typed; and typed intent has no durable home anywhere, so there is nothing for the gate to re-fetch. Materializing also makes a resumed draft checkable in a later session, where the original input is gone, and it makes drafting and the gate provably compare against the same bytes rather than two independent readings of "the intent".
• Refuted alternative: have the gate re-derive the source itself by re-reading the stub issue or the discovery folder. This is viable for two of the three modes and avoids an extra artifact, but it fails for intent mode entirely, makes the gate mode-aware, and permits the gate to check against a source that differs from what drafting actually used — a stub body edited between the two steps, for instance.

Citation comparison is normalized substring containment with a minimum fragment length

• Decision: both the quoted fragment and the source text are normalized identically — whitespace runs collapsed, case folded, typographic quote and dash variants mapped to their plain forms — and the check is containment. A fragment shorter than a stated word floor fails as if it were absent.
• Why: the failure mode of an over-strict check is worse than that of an over-loose one. A model re-typing a quote substitutes typographic quotes and trims whitespace routinely; blocking on that trains the lead to reword until the gate relents, which is the same escape valve that makes an unenforced rule worthless. The word floor is what stops the opposite failure: without it, citing a single common word satisfies the rule for every item and the citation means nothing.
• Refuted alternative: exact byte containment. It is simpler and unambiguous, and it is what "string comparison" most literally means. It loses to typographic drift, which is frequent and invisible in rendered prose.
• Refuted alternative: a semantic or fuzzy-similarity judgment of whether the fragment supports the item. It would catch the real gaming case, but it reintroduces exactly the judgment story The gate refuses a draft that breaks the rules #287 exists to remove and makes the gate's verdict irreproducible run to run.

Provenance labels live inline beside their items, and filing is done from a derived body whose cleanliness is asserted

• Decision: each labelled item carries its label — and, when asked, its fragment — immediately adjacent to it in the session-scratch draft. When filing begins, the stage derives a clean body by removing the labels, and the checker runs in an assertion mode over that derived body: any surviving drafting-time token fails the run before an issue is created or updated.
• Why: the labels have three consumers — the human drafting, the gate comparing, and the digest building its cut list — and all three need the label attached to the item it belongs to. Inline adjacency also makes a cut a deletion of the lines the reviewer selected, which is what makes story The reviewer cuts scope in one action #288 cheap. The derived-body assertion converts story Every scope-bearing item says where it came from #285's fourth criterion from an instruction the model must remember into a condition that is checked, at the cost of one extra invocation of a tool that already exists — and it is the same assertion story A refuted alternative is offered, not required #424's final criterion reuses rather than restating.
• Refuted alternative: hold labels in a separate provenance sidecar keyed to items, leaving the draft body clean by construction. This makes leakage impossible rather than merely detected, which is a real advantage. It loses because the key between sidecar and body goes stale the moment an item's wording is edited, and it goes stale silently — the checker would then compare fragments against items that no longer exist, and the cut list would remove the wrong lines.
• Refuted alternative: hidden-comment labels that survive into the filed body but do not render. There is precedent for hidden machine content on epic issues. It loses on story Every scope-bearing item says where it came from #285's fourth criterion as written, and on the decision-record side it would put churning bookkeeping inside the artifact the record digest is taken over.

The razor is one shared skill; the counted limits are additionally restated at the point of authoring

• Decision: a single new authoring skill is the normative statement of the razor and is loaded by all three drafting stages. Each drafting template carries, adjacent to the heading it bounds, a one-phrase restatement of that heading's rule. Where a restatement and the skill disagree, the skill governs and the checker enforces the skill's numbers.
• Why: story The other drafting stages apply the same rules #289's entire value is that three stages apply the same rules, and a single normative source is the only way to guarantee that. But the observed failure was specifically a heading's presence beating a rule stated far from it, so a rule that lived only in a loaded skill would repeat that failure — the restatement exists to sit where the model is actually writing. Bounding the duplication to a phrase, and naming the skill as the tiebreaker, keeps the drift surface small and its resolution stated. The prose style shipped in epic #414: Prose translation agent with a resident density convention #422 is the precedent for the split: the rules an agent can apply to a finished draft live in the nxs-prose agent, and the two rules that need the source material the author holds stay resident in each drafting command. The razor is guidance of the second kind, so it sits where the model writes. It is still the first guidance-only skill in the components tree, which the epic's assumptions now say plainly.
• Refuted alternative: embed the rules once per command and add no skill. Commands here are conventionally self-contained, this avoids a new component entirely, and epic #414: Prose translation agent with a resident density convention #422 did exactly this for the prose style's two resident rules, so the shape now has a precedent. A competent engineer would reasonably choose it. It loses on size. The prose style's resident block is two rules and one fixed procedure, while the razor is a label vocabulary, a citation-normalization rule, the counted limits, the content rules and the necessity question. Three copies of a rule set that large diverge, and the divergence is undetectable: the gate would check against the epic stage's copy while the record stage drafted under its own.
• Refuted alternative: put the razor in a reviewing agent all three stages call. It loses because the razor is authoring guidance that must shape output as it is written; an agent runs in a separate context and can only judge after the fact, which is the review pass the gate already is. epic #414: Prose translation agent with a resident density convention #422 demonstrates the boundary: its translator agent rewrites a drafted file once the draft exists, and it is barred from the two rules it cannot decide without the author's source material, which it reports instead of applying.

The digest's cut list is numbered prose, and the selection is a named list rather than one control per item

• Decision: the digest renders the cut list as stably numbered entries grouped by the story each belongs to. The choice offered is three coarse actions — approve as drafted, approve with cuts, revise — and item selection is given as a list of those numbers. Selecting nothing under "approve with cuts" takes the plain-approval path with no re-derivation and no second confirmation.
• Why: the interactive choice surface is bounded to a handful of options per question, while five stories can easily yield twenty inferred items. Numbered prose plus a typed selection scales to any list length and keeps the cut a single action, which is the story's whole premise: removing scope must be cheaper than accepting it.
• Refuted alternative: paginate the cut list into batches that fit the choice surface. It preserves clicking over typing, which is genuinely lower-friction per item. It loses because it converts one action into several rounds, and a multi-round cut is no longer cheaper than approving as drafted — it re-creates the cost the story exists to remove.

The cut list holds inferred items and, additionally, asked-for stories the necessity answer excludes

• Decision: the cut list offers every inferred item, every entirely-inferred story, and each fully asked-for story that falls outside the minimal usable set named by the necessity answer. An asked-for story offered this way is rendered as such, so the reviewer can see that cutting it removes something they requested rather than something the model added.
• Why: necessity, not provenance alone, is what should make a story cuttable at the digest; a story the lead asked for but which the smallest usable version does not need is exactly the scope worth deferring, and forcing that through a revise-and-re-run costs more than accepting it. This makes story The reviewer cuts scope in one action #288 a general scope-reduction control rather than a razor-only action — a materially larger story than the one originally filed, which the sizing risk below records.
• Refuted alternative: restrict the cut list to inferred items only, leaving an unnecessary but asked-for story visible in the ordering yet not selectable. This keeps The reviewer cuts scope in one action #288 a narrow razor action whose blast radius is exactly the model's own additions, and it was the analysis's recommendation. It lost to the reduction-cost argument above, at this record's approval gate.

A whole-story cut re-parents its dependents rather than dropping their edges

• Decision: removing a story removes it from the implementation sequence and re-parents every surviving story that named it onto that removed story's own blockers. The digest states the cascade — which stories are re-parented onto what — before the lead confirms.
• Why: dropping an edge can let a dependent start before a prerequisite that was only reachable through the removed story, and an under-constrained order breaks work while an over-constrained one merely delays it. Showing the cascade at the moment of choice matches the gate's own design: surface the consequence where the human is already deciding, rather than after filing.
• Refuted alternative: drop the dangling edges and leave the remainder unordered. It is simpler and never invents an edge the lead did not author, which is a real objection. It loses on the asymmetry of the two failure modes.

Complexity, the design-warrant, and the risk banner are all re-derived after cuts

• Decision: after cuts, the epic's complexity is re-derived from the reduced story set by the existing rollup rule; the design-warrant label applied at filing is derived from that new value; and any utilization-risk or scope banner in the epic body that quoted the pre-cut assessment is re-derived or removed.
• Why: the design-warrant follows from complexity at filing, so a cut that drops the epic below the record threshold must also drop the label — otherwise the reduced epic demands a decision record it no longer warrants. The banner is the same class of staleness and is visible to every future reader of the issue, asserting a sizing the epic no longer has.

The personas-table ban is a blocking check; only mechanism-naming stays advisory

• Decision: the presence of a table under the personas heading is a blocking check, because it is a structural presence test and not a judgment. Mechanism-naming remains prevented at drafting time, but the gate reports suspected instances as a non-blocking observation carried into the digest.
• Why: judging whether a phrase names a mechanism is not a count or a comparison, but the presence of a table is. Enforcing the half that is decidable shrinks the unenforced surface to exactly one rule. For that remaining rule, an advisory finding at the digest is what stops it decaying: the fourth success metric is a one-time acceptance check, not a standing guard, and a non-blocking pointer costs nothing while putting the judgment in front of the only party who can make it. This is the precedent every later judgment rule in this epic follows.

The acceptance-criteria limit blocks on the ceiling only, and the overage reason is one stated reason per story

• Decision: the gate blocks only on more than five acceptance criteria with no stated reason. The lower bound of three stays drafting guidance in the skill and is never checked, so no minimum-count finding exists. A story exceeding the ceiling carries a single labelled one-line reason next to its acceptance-criteria heading; the checker tests only that the reason is present, and the digest renders it so the human judges its adequacy.
• Why: a blocking floor is a generation mandate. A story with two genuinely sufficient criteria would be held until a third is manufactured, which produces exactly the padding this epic exists to remove — the rule would work against its own purpose. On the reason: presence is mechanically decidable and adequacy is not, so splitting them keeps the gate free of judgment while still putting the reason in front of the reviewer. A per-criterion reason is bookkeeping without a corresponding gain, since the overage is a property of the story rather than of the sixth criterion in particular.
• Refuted alternative: block below three as well, with its own stated-reason escape, making "three to five" literally enforced and symmetric. It is defensible and was put to the lead explicitly. It lost because the escape hatch would be exercised routinely on small stories, which converts a hard rule into ceremony while still permitting the gate to demand a criterion be invented.

In the decision-record and discovery stages the labels are drafting-time only, and each stage self-checks with the shared checker

• Decision: the record's invariants and risks carry labels while the record is drafted and through its clarification gate; the stage runs the checker before filing and strips the labels from the body it files. In discovery, labels attach to the discovery document's not-yet-specified and out-of-scope entries and to each ticket's question; resolutions are not labelled. Both stages invoke the same checker, and neither gains a gate agent.
• Why: the record body is the artifact its digest is taken over and must carry no churning content, so a label surviving into it would report a design that did not change as changed. A resolution is a decision made in session and is inferred by construction, so labelling it would be uniform noise. Reusing the checker is what makes "the same rules" true rather than asserted, and it honours the epic's assumption that no new agent is created.

The necessity answer is one durable line, and it orders the cut list

• Decision: the epic names the minimal usable story set as a single line in its body, which reaches the filed issue, and the digest renders it beside the story list. Stories outside that set sort first within the cut list.
• Why: the necessity question is the only razor rule whose answer a later reader genuinely consumes — it is scope reasoning, not planning bookkeeping, so unlike the labels it earns a durable home. Ordering the cut list by it turns the answer from a statement into a lever: the reviewer's eye lands first on what the smallest usable version does not need. With asked-for stories cuttable on necessity grounds, this line is also what determines which of them the cut list may offer.

The standing refuted-alternative slot is removed, not annotated, and "offered, not required" becomes a razor content rule

• Decision: the record template stops carrying a refuted-alternative line under every decision. The line is written only where a viable alternative exists, and the template's filling rules no longer instruct the model to replace a placeholder that is not there. The rule that governs it — an alternative is included only where a competent engineer might genuinely have chosen it, and its stated reason for losing must name the trade-off it lost on — is stated normatively in the shared razor skill as a content rule, and restated as a phrase where the architect authors, exactly as the counted limits are.
• Why: this is the epic's own observed failure reproduced in a second template. A fixed slot with permission-to-omit sitting in an adjacent comment is structurally identical to a personas heading with a deviations-only rule beside it, and it produced the same outcome: the slot gets filled. Removing the slot removes the generation pressure at its source rather than asking the model to resist it. Routing the rule through the skill rather than the template keeps the razor's one normative home intact and lets the record and epic stages state the same rule in the same words.
• Refuted alternative: keep the line and soften the filling rule to "replace every placeholder unless its guidance says the line is optional". It is a smaller edit, it keeps every decision entry structurally uniform, and a competent engineer would reasonably prefer not to make a template's shape vary by decision. It loses to the exact mechanism this epic exists to fix — a conditional instruction adjacent to a standing structural slot is what already failed, twice.

Viability is judged by the formatting stage, not the authoring agent, and is advisory

• Decision: when a refuted alternative's stated reason for losing names no trade-off, it is reported as a non-blocking observation and carried to the reviewer at the pre-filing checkpoint. The observation is produced by the stage that formats the record, not by the architect that wrote the alternatives, and it is rendered in the checkpoint only — it is never written into the draft body. It blocks nothing.
• Why: viability is a judgment, not a count, so under this record's existing division it cannot block, and it gets the treatment already fixed for mechanism-naming. But it must not be self-assessment: the epic's founding premise is that a model asked to judge its own additions answers in its own favour, and the architect is precisely the party motivated to keep its alternatives. The formatting stage runs in a different context from the architect subagent, so it is a genuinely second reader without introducing the new agent the epic's assumptions forbid. Rendering the observation only at the checkpoint means there is no marker to strip and no way for one to reach a durable body by omission. The provenance rule deliberately does not extend here: a refuted alternative is the model's own by construction, so asked-versus-inferred discriminates nothing, and a third label value would violate the two-valued vocabulary while restoring the self-judgment the epic removes.

The pre-filing checkpoint is a new stop that fills the gate the command already refers to

• Decision: the decision-record stage gains a mandatory checkpoint between formatting the body and filing it — the pre-filing gate the command already refers to and no phase defines. It runs on every path that would create or update the record sub-issue, including the revision path, and offers approve as drafted, approve with cuts, revise, and the proceed-without-a-record exit the existing reference already promises at this gate. Naming numbers to cut removes those alternatives from the body before any issue is created or updated; naming nothing is identical to plain approval.
• Why: the record body is durable the instant it is filed and frozen the instant it is approved, so a cut that happens after filing either edits a published body or requires the reopen path — both worse than not filing it in the first place. Placing the stop before filing is also what makes the story's promise true: the reviewer removes scope before it becomes binding. The checkpoint writes no file and is spent when answered, so under the forcing-function razor it survives as an interaction and earns no durable home.
• Refuted alternative: fold the cut list into the existing clarification gate rather than adding a stop. It reuses a mandatory stop that already exists and adds no phase, which is genuinely the cheaper shape. It loses on ordering and on coverage: that gate runs on the architect's output before the body is formatted, so there is nothing numbered to cut yet, and it is skipped entirely on the common run where no clarification was raised — which is most runs.
• Refuted alternative: extend the existing post-filing approval gate with a cut option and edit the body in place. One gate instead of two, and the reviewer is already there. It loses because the filed body would then differ from the body that was reviewed, the record digest is taken over that body, and an approved record is frozen — so a cut at that point is a reopen-and-republish rather than a reduction.

The two cut lists share a shape, not a mechanism

• Decision: the epic digest's cut list and the record checkpoint's list are separate implementations following one stated convention — stably numbered entries grouped by the parent they belong to, three coarse actions plus any stage-specific exit, selection by named numbers, and empty selection equal to plain approval. The convention is stated once in the shared razor skill both stages already load. No shared cut-list component is built.
• Why: everything mechanically decidable in either list — the presence assertions on the derived body — already lives in the shared checker and is reused. What remains is prose the stage generates and a selection it parses, and the two differ in every respect but shape: the epic's list carries cascade consequences with no analogue in a record, it is rendered by a gate agent where the record's is rendered in-command with no agent at all, and their item populations are unrelated. A convention with one home is enough to keep them consistent.
• Refuted alternative: build one cut-gate component both stages invoke, guaranteeing identical selection semantics by construction. This is the same argument that justified the shared checker, and a competent engineer would ask why it does not apply twice. It loses because the checker shares a computation while this would share only a rendering: the component would have to be parameterized on item populations and post-cut consequences it cannot itself check, which is a larger and less testable surface than the convention it replaces.

Constraints & Invariants

1. Every citation check in a run compares against that run's materialized source-text artifact and nothing else; no check re-reads a live stub issue, discovery folder, or command argument.
2. No provenance label, template placeholder token, or observation marker reaches a filed issue body, and filing proceeds only after a mechanical assertion that none survives in the derived body.
3. The razor has exactly one normative home; every template restatement is a pointer to it, and where the two disagree the normative source governs and the checker enforces it.
4. Every counted limit, citation comparison, and token-survival assertion is one shared deterministic operation invoked by all its consumers; no stage restates the counting or normalization rule in its own words.
5. Blocking findings are limited to counts, presence tests, and normalized substring comparison; any check requiring judgment is advisory and blocks nothing.
6. The acceptance-criteria count blocks on the ceiling only; no minimum-count check exists anywhere, and no rule may require an item to be generated to satisfy a floor.
7. The epic gate makes no edit to a draft and creates no issue; it reports and the caller fixes.
8. Cuts apply only to content not yet filed; a cut naming a story already filed by a prior partial run is refused with the reason rather than silently ignored.
9. An asked-for story is offered as a cut only on necessity grounds — because the necessity answer excludes it from the minimal usable set — and is rendered as asked-for, never as an inferred addition.
10. A whole-story cut re-derives the complexity rollup, the design-warrant that follows from it, and any risk banner quoting the pre-cut assessment; a stale banner is removed rather than left standing.
11. A whole-story cut re-parents its dependents onto the removed story's own blockers, and the cascade is stated in the digest before the lead confirms.
12. Approving with an empty selection produces an outcome identical to plain approval at either cut gate — no re-derivation, no re-render, no second confirmation.
13. The label vocabulary stays two-valued; no third state and no per-item confidence score is introduced anywhere, including on refuted alternatives.
14. At least one story must survive a cut; an all-stories cut is a revise, not an approval.
15. The materialized source text, the labelled draft, and the derived filing body are all session-scratch and transient; none is committed, none enters the queue, and none is written under the permanent documentation tree.
16. Security boundary: the materialized source text may contain anything the lead typed, including credentials pasted into an intent. It stays in ignored scratch and is never posted to an issue body, a comment, or a report; because labels and their fragments are stripped before filing, no quoted fragment of it reaches the issue tracker either.
17. Discovery's razor application writes nothing to the issue tracker and introduces no durable link into the discovery folder.
18. No decision template carries a standing slot, placeholder, or fixed line for a refuted alternative; the line exists only where an alternative was written.
19. The viability observation is advisory, is produced by a party other than the agent that authored the alternative, and lives only in the checkpoint render — it is never written into the draft body.
20. The record stage's pre-filing checkpoint precedes every path that creates or updates the record sub-issue, and no cut is applied after a body has been filed; an approved body stays frozen and is changed only through the existing reopen path.
21. The two cut gates share one stated convention and no shared implementation; neither stage restates the convention in its own words.

A cross-cutting statement of the razor's numeric limits would normally belong in the standards space rather than in any one stage. That space does not exist in this repository — verified again for this revision — so the shared skill serves as its stand-in, a deviation recorded here deliberately. If a standards space is later created, the limits move there and the skill references them. No standards-conformance pass was possible for this record for the same reason.

Risks (BLOCKER / ADDRESS only)

• ADDRESS — the citation check proves the quote exists, not that it supports the item. A drafting model that wants to keep an addition can label it asked and cite a real fragment that does not license it. The check passes and the reviewer sees a clean gate. The epic's first success metric, as worded, therefore overstates the guarantee the mechanism delivers. Decision needed during implementation: either the digest renders each asked item together with its fragment so the reviewer can see the non-sequitur — which lengthens the digest and cuts against its read-the-surface premise — or the metric is reworded to claim what the check actually establishes, with the fragment reachable only in drill-down. The word floor and the advisory weak-fragment finding narrow the gaming surface but do not close it.

• ADDRESS — the epic is now six stories and its recorded L no longer describes the work. The epic carries an L assessment with an explicit no-slack banner, derived from five stories before any of this record's changes. Since then The gate refuses a draft that breaks the rules #287 has been re-sized to M, The reviewer cuts scope in one action #288's own body records it as widened beyond its recorded M by the necessity-grounds decision and never re-sized, and A refuted alternative is offered, not required #424 has been added at M. The set is now five M-sized stories and one S, with one of the M's acknowledged as understated — that is at or past the top of L, and the banner asserting a sizing the epic no longer has is exactly the staleness this record's own re-derivation rule exists to remove. Decision needed before implementation starts: re-derive the rollup for the six-story set and either re-size The reviewer cuts scope in one action #288 and accept an L with negative slack, split the epic, or defer a story. The candidate for deferral is A refuted alternative is offered, not required #424 — it applies an already-decided pattern to a second template and is not needed for the razor to work in the epic stage, which is precisely the necessity ground this epic invents; and the epic still names no minimal usable set of its own.

• ADDRESS — the discovery stage's standing constraint contradicts story The other drafting stages apply the same rules #289. The discovery command states as a hard constraint that no new agents or skills are introduced and that every ticket type routes to existing machinery. Story The other drafting stages apply the same rules #289 loads the new shared razor skill into that stage. The epic's first assumption has been rewritten and that half of the risk is closed, but this constraint has not been narrowed; an implementer reading it will treat The other drafting stages apply the same rules #289 as forbidden or quietly violate a stated constraint. Mitigation: narrow the constraint to ticket-type routing in the same change that lands The other drafting stages apply the same rules #289, rather than leaving the two statements in conflict.

Open Clarifications

None. The two clarifications raised by the original analysis were resolved at this record's first approval gate — the acceptance-criteria limit blocks on the ceiling only, and asked-for stories outside the minimal usable set are cuttable at the digest — and every scope edit that record named has been applied to the issues, so both answers are now settled facts in the decisions above. The additions in this revision for story #424 raised no question the analysis could not resolve from the epic and the existing decisions.

[sameera]

Record revised — 2026-09-02

What changed: Story #424 ("A refuted alternative is offered, not required") was added to the epic and had no design coverage. The record gains four decisions covering it — the standing refuted-alternative slot is removed from the record template rather than annotated, viability becomes an advisory observation produced by the formatting stage rather than the authoring agent, the decision-record stage gains the pre-filing checkpoint its own text already referred to, and the two cut lists are held to a shared convention rather than a shared component — plus invariants 18 to 21. Separately, every scope edit the superseded body named has now been applied to the issues, so those edits are folded in as settled fact instead of pending instructions, and the sizing risk is restated for a six-story epic.

Why: The epic's own failure mode was found in a second template. The decision-record template carried a refuted-alternative line under every decision, with the permission to omit it in an adjacent comment, while the template's filling rules said to replace every placeholder — structurally identical to the personas heading whose deviations-only rule was beaten by the heading's presence. That produced manufactured alternatives in filed records. #424 closes it, and this revision is what gives #424 design coverage.

Superseded body hash: ce62d0a8ee8a18565efeca16bd2ef1c4ed4d6ae92e0e4ecb5a21eb0a9e225a2a

Superseded record body (verbatim)

# Decision Record: Planning Carries Only Asked-For Scope

## Summary

The razor is a rule set with one normative home and one deterministic enforcer: a shared checker in the existing toolkit that counts the limits, verifies asked-citations against a materialized copy of the run's source text, and asserts that no provenance label survives into a filed body. Provenance labels live inline beside the items they label in the session-scratch draft and never reach the issue tracker, because filing is done from a derived body whose cleanliness is asserted mechanically rather than remembered. The approval digest gains a numbered cut list, with whole-story cuts cascading into dependency re-parenting, complexity re-derivation, and the design-warrant that follows from it.

## Chosen Approach

One authoring skill states the razor normatively — the two-valued label vocabulary, the citation-normalization rule, the counted limits, the two content rules, and the necessity question — and the three drafting stages load it. One toolkit operation implements every check the rules make mechanically decidable, reading a draft plus the run's materialized source text and printing findings; the epic gate invokes it and reports its output rather than counting by eye, and the record and discovery stages invoke the same operation on their own drafts. Each drafting template restates its own limit as a short phrase adjacent to the heading it bounds, because the observed failure showed a heading beating an instruction placed far from it — the restatement is a pointer with a number in it, never the source of truth.

Two facts about the current system reshape the epic's stated assumptions and are recorded here because they drive the decisions below. There is no prose-style authoring skill: every skill in the components tree today is a mechanical wrapper over a toolkit operation, so the epic's first assumption weighs a new skill against an artifact that does not exist. And the epic template is not a separate file but an inline block inside the epic drafting stage itself, so "stated in the template" resolves to that block.

## Key Decisions

### The mechanical checks are one deterministic toolkit operation, not gate-side counting

- **Decision:** the counted limits, the asked-citation comparison, and the no-label-survives assertion are implemented once as a shared toolkit operation over text; the epic gate, the epic drafting stage, the decision-record stage, and the discovery stage all invoke that one operation and report or act on its findings.
- **Why:** the same rules must hold identically in four places. Prose-level counting restated four times diverges on the first edit, and the epic's own premise is that a model asked to judge its own additions answers in its own favour — asking that model to count its own list items and eyeball a substring reproduces the failure one layer down. Every mechanical operation in this system already routes through a tested toolkit operation, so this is the existing pattern rather than a new one, and it is what makes the third success metric ("enforced rather than advised") literally true.
- **Refuted alternative:** counting and substring matching inside the gate agent's own prompt, as story #287 assumes. It is genuinely cheaper — no library, no tests, nothing to release — and for a single consumer it would be the right call. It loses because there are four consumers and one of them, the decision-record stage, has no gate agent at all, so the alternative silently means either a second implementation or an unchecked rule for story #289.
- **Scope edit — story #287:** its work becomes "the gate invokes the shared checker and blocks on its findings" plus the checker itself. Story #289 shrinks correspondingly, since it reuses the checker rather than restating the rules.

### The run's source text is materialized once, beside the draft, before any item is labelled

- **Decision:** each drafting stage writes the text it was given — the typed capability description in intent mode, the stub issue body in promotion mode, the discovery document plus every resolved ticket in discovery mode — verbatim into a single transient artifact in the same session-scratch working folder as the draft. Every citation check in that run compares against that artifact and nothing else.
- **Why:** the gate is a separate agent that receives only a draft location, so it cannot see the arguments the lead typed; and typed intent has no durable home anywhere, so there is nothing for the gate to re-fetch. Materializing also makes a resumed draft checkable in a later session, where the original input is gone, and it makes drafting and the gate provably compare against the same bytes rather than two independent readings of "the intent".
- **Refuted alternative:** have the gate re-derive the source itself by re-reading the stub issue or the discovery folder. This is viable for two of the three modes and avoids an extra artifact, but it fails for intent mode entirely, makes the gate mode-aware, and permits the gate to check against a source that differs from what drafting actually used — a stub body edited between the two steps, for instance.
- **Scope edit — story #285:** its third criterion names only the stub body and the discovery ticket. It must also name intent mode, and it must say the comparison target is the materialized copy rather than the live source.

### Citation comparison is normalized substring containment with a minimum fragment length

- **Decision:** both the quoted fragment and the source text are normalized identically — whitespace runs collapsed, case folded, typographic quote and dash variants mapped to their plain forms — and the check is containment. A fragment shorter than a stated word floor fails as if it were absent.
- **Why:** the failure mode of an over-strict check is worse than that of an over-loose one. A model re-typing a quote substitutes typographic quotes and trims whitespace routinely; blocking on that trains the lead to reword until the gate relents, which is the same escape valve that makes an unenforced rule worthless. The word floor is what stops the opposite failure: without it, citing a single common word satisfies the rule for every item and the citation means nothing.
- **Refuted alternative:** exact byte containment. It is simpler and unambiguous, and it is what "string comparison" most literally means. It loses to typographic drift, which is frequent and invisible in rendered prose.
- **Refuted alternative:** a semantic or fuzzy-similarity judgment of whether the fragment supports the item. It would catch the real gaming case, but it reintroduces exactly the judgment story #287 exists to remove and makes the gate's verdict irreproducible run to run.

### Provenance labels live inline beside their items, and filing is done from a derived body whose cleanliness is asserted

- **Decision:** each labelled item carries its label — and, when asked, its fragment — immediately adjacent to it in the session-scratch draft. When filing begins, the stage derives a clean body by removing the labels, and the checker runs in an assertion mode over that derived body: any surviving label token fails the run before an issue is created.
- **Why:** the labels have three consumers — the human drafting, the gate comparing, and the digest building its cut list — and all three need the label attached to the item it belongs to. Inline adjacency also makes a cut a deletion of the lines the reviewer selected, which is what makes story #288 cheap. The derived-body assertion converts story #285's fourth criterion from an instruction the model must remember into a condition that is checked, at the cost of one extra invocation of a tool that already exists.
- **Refuted alternative:** hold labels in a separate provenance sidecar keyed to items, leaving the draft body clean by construction. This makes leakage impossible rather than merely detected, which is a real advantage. It loses because the key between sidecar and body goes stale the moment an item's wording is edited, and it goes stale silently — the checker would then compare fragments against items that no longer exist, and the cut list would remove the wrong lines.
- **Refuted alternative:** hidden-comment labels that survive into the filed body but do not render. There is precedent for hidden machine content on epic issues. It loses on story #285's fourth criterion as written, and on the decision-record side it would put churning bookkeeping inside the artifact the record digest is taken over.

### The razor is one shared skill; the counted limits are additionally restated at the point of authoring

- **Decision:** a single new authoring skill is the normative statement of the razor and is loaded by all three drafting stages. Each drafting template carries, adjacent to the heading it bounds, a one-phrase restatement of that heading's limit. Where a restatement and the skill disagree, the skill governs and the checker enforces the skill's numbers.
- **Why:** story #289's entire value is that three stages apply the *same* rules, and a single normative source is the only way to guarantee that. But the observed failure was specifically a heading's presence beating a rule stated far from it, so a rule that lived only in a loaded skill would repeat that failure — the restatement exists to sit where the model is actually writing. Bounding the duplication to a phrase-with-a-number, and naming the skill as the tiebreaker, keeps the drift surface small and its resolution stated.
- **Refuted alternative:** embed the rules once per command and add no skill. Commands here are conventionally self-contained, there is no precedent for a guidance-only skill, and this avoids a new component entirely — a competent engineer would reasonably choose it. It loses because three copies of the rule set diverge, and the divergence is undetectable: the gate would check against the epic stage's copy while the record stage drafted under its own.
- **Refuted alternative:** put the razor in a reviewing agent all three stages call. It loses because the razor is authoring guidance that must shape output as it is written; an agent runs in a separate context and can only judge after the fact, which is the review pass the gate already is.
- **Scope edit — the epic's first assumption:** it must be rewritten. The prose-style skill it contrasts against does not exist, and the real trade-off is one shared skill versus per-command duplication. This introduces the first guidance-only skill in the components tree — a new pattern, not an extension of one.

### The digest's cut list is numbered prose, and the selection is a named list rather than one control per item

- **Decision:** the digest renders the cut list as stably numbered entries grouped by the story each belongs to. The choice offered is three coarse actions — approve as drafted, approve with cuts, revise — and item selection is given as a list of those numbers. Selecting nothing under "approve with cuts" takes the plain-approval path with no re-derivation and no second confirmation.
- **Why:** the interactive choice surface is bounded to a handful of options per question, while five stories can easily yield twenty inferred items. Numbered prose plus a typed selection scales to any list length and keeps the cut a single action, which is the story's whole premise: removing scope must be cheaper than accepting it.
- **Refuted alternative:** paginate the cut list into batches that fit the choice surface. It preserves clicking over typing, which is genuinely lower-friction per item. It loses because it converts one action into several rounds, and a multi-round cut is no longer cheaper than approving as drafted — it re-creates the cost the story exists to remove.
- **Scope edit — story #288:** its second criterion should say the reviewer names the numbered items, rather than implying a per-item control.

### The cut list holds inferred items and, additionally, asked-for stories the necessity answer excludes

- **Decision:** the cut list offers every inferred item, every entirely-inferred story, and — resolved at this record's approval gate, against the analysis's own recommendation — each fully asked-for story that falls outside the minimal usable set named by the necessity answer. An asked-for story offered this way is rendered as such, so the reviewer can see that cutting it removes something they requested rather than something the model added.
- **Why:** the lead's judgement is that necessity, not provenance alone, is what should make a story cuttable at the digest; a story the lead asked for but which the smallest usable version does not need is exactly the scope worth deferring, and forcing that through a revise-and-re-run costs more than accepting it. The competing consideration — that cutting asked-for scope is not the razor's job and belongs in a revise — was raised and overruled.
- **Refuted alternative:** restrict the cut list to inferred items only, leaving an unnecessary but asked-for story visible in the ordering yet not selectable. This keeps story #288 a narrow razor action whose blast radius is exactly the model's own additions, and it was the analysis's recommendation. It lost to the reduction-cost argument above.
- **Scope edit — story #288:** its first criterion, which today says every *inferred* item appears in one cut list, widens to include asked-for stories outside the minimal usable set. This makes #288 a general scope-reduction control rather than a razor-only action — a materially larger story than the one filed, and the sizing risk below records that.

### A whole-story cut re-parents its dependents rather than dropping their edges

- **Decision:** removing a story removes it from the implementation sequence and re-parents every surviving story that named it onto that removed story's own blockers. The digest states the cascade — which stories are re-parented onto what — before the lead confirms.
- **Why:** dropping an edge can let a dependent start before a prerequisite that was only reachable through the removed story, and an under-constrained order breaks work while an over-constrained one merely delays it. Showing the cascade at the moment of choice matches the gate's own design: surface the consequence where the human is already deciding, rather than after filing.
- **Refuted alternative:** drop the dangling edges and leave the remainder unordered. It is simpler and never invents an edge the lead did not author, which is a real objection. It loses on the asymmetry of the two failure modes.

### Complexity, the design-warrant, and the risk banner are all re-derived after cuts

- **Decision:** after cuts, the epic's complexity is re-derived from the reduced story set by the existing rollup rule; the design-warrant label applied at filing is derived from that new value; and any utilization-risk or scope banner in the epic body that quoted the pre-cut assessment is re-derived or removed.
- **Why:** story #288's third criterion asks for the complexity re-derivation, but the design-warrant follows from complexity at filing, so a cut that drops the epic below the record threshold must also drop the label — otherwise the reduced epic demands a decision record it no longer warrants. The banner is the same class of staleness and is visible to every future reader of the issue, asserting a sizing the epic no longer has.

### The personas-table ban moves to the gate; only mechanism-naming stays unenforced, and it becomes advisory

- **Decision:** the presence of a table under the personas heading is a blocking check, because it is a structural presence test and not a judgment. Mechanism-naming remains prevented at drafting time, but the gate reports suspected instances as a non-blocking observation carried into the digest.
- **Why:** story #287 groups both content rules as unenforceable on the grounds that judging a mechanism is not a count or a comparison — true for mechanism-naming, false for a table. Enforcing the half that is decidable shrinks the unenforced surface to exactly one rule. For that remaining rule, an advisory finding at the digest is what stops it decaying: the fourth success metric is a one-time acceptance check, not a standing guard, and a non-blocking pointer costs nothing while putting the judgment in front of the only party who can make it.
- **Scope edit — story #287:** its notes currently exclude both content rules from the gate; only mechanism-naming stays excluded.

### The acceptance-criteria limit blocks on the ceiling only, and the overage reason is one stated reason per story

- **Decision:** resolved at this record's approval gate — the gate blocks only on more than five acceptance criteria with no stated reason. The lower bound of three stays drafting guidance in the skill and is never checked, so no minimum-count finding exists. A story exceeding the ceiling carries a single labelled one-line reason next to its acceptance-criteria heading; the checker tests only that the reason is present, and the digest renders it so the human judges its adequacy.
- **Why:** a blocking floor is a generation mandate. A story with two genuinely sufficient criteria would be held until a third is manufactured, which produces exactly the padding this epic exists to remove — the rule would work against its own purpose. On the reason: presence is mechanically decidable and adequacy is not, so splitting them keeps the gate free of judgment while still putting the reason in front of the reviewer. A per-criterion reason, which story #286's wording implies, is bookkeeping without a corresponding gain, since the overage is a property of the story rather than of the sixth criterion in particular.
- **Refuted alternative:** block below three as well, with its own stated-reason escape, making "three to five" literally enforced and symmetric. It is defensible — it is what the story's wording says — and it was put to the lead explicitly. It lost because the escape hatch would be exercised routinely on small stories, which converts a hard rule into ceremony while still permitting the gate to demand a criterion be invented.
- **Scope edit — stories #286 and #287:** #286's first criterion becomes a ceiling with a per-story stated reason; #287 must state explicitly that no minimum-count check exists.

### In the decision-record and discovery stages the labels are drafting-time only, and each stage self-checks with the shared checker

- **Decision:** the record's invariants and risks carry labels while the record is drafted and through its clarification gate; the stage runs the checker before formatting and strips the labels from the body it files. In discovery, labels attach to the discovery document's not-yet-specified and out-of-scope entries and to each ticket's question; resolutions are not labelled. Both stages invoke the same checker, and neither gains a gate agent.
- **Why:** the record body is the artifact its digest is taken over and must carry no churning content, so a label surviving into it would report a design that did not change as changed. A resolution is a decision made in session and is inferred by construction, so labelling it would be uniform noise. Reusing the checker is what makes "the same rules" true rather than asserted, and it honours the epic's assumption that no new agent is created.
- **Scope edit — story #289:** its second criterion says only "its content"; it must name which discovery items are labelled and state that resolutions are not.

### The necessity answer is one durable line, and it orders the cut list

- **Decision:** the epic names the minimal usable story set as a single line in its body, which reaches the filed issue, and the digest renders it beside the story list. Stories outside that set sort first within the cut list.
- **Why:** the necessity question is the only razor rule whose answer a later reader genuinely consumes — it is scope reasoning, not planning bookkeeping, so unlike the labels it earns a durable home. Ordering the cut list by it turns the answer from a statement into a lever: the reviewer's eye lands first on what the smallest usable version does not need. With asked-for stories now cuttable on necessity grounds, this line is also what determines which of them the cut list may offer.

## Constraints & Invariants

1. Every citation check in a run compares against that run's materialized source-text artifact and nothing else; no check re-reads a live stub issue, discovery folder, or command argument.
2. No provenance label reaches a filed issue body, and filing proceeds only after a mechanical assertion that no label token survives in the derived body.
3. The razor has exactly one normative home; every template restatement is a pointer carrying a number, and where the two disagree the normative source governs and the checker enforces it.
4. Every counted limit, citation comparison, and label-survival assertion is one shared deterministic operation invoked by all four consumers; no stage restates the counting or normalization rule in its own words.
5. Blocking findings are limited to counts, presence tests, and normalized substring comparison; any check requiring judgment is advisory and blocks nothing.
6. The acceptance-criteria count blocks on the ceiling only; no minimum-count check exists anywhere, and no rule may require an item to be generated to satisfy a floor.
7. The gate makes no edit to a draft and creates no issue; it reports and the caller fixes.
8. Cuts apply only to content not yet filed; a cut naming a story already filed by a prior partial run is refused with the reason rather than silently ignored.
9. An asked-for story is offered as a cut only on necessity grounds — because the necessity answer excludes it from the minimal usable set — and is rendered as asked-for, never as an inferred addition.
10. A whole-story cut re-derives the complexity rollup, the design-warrant that follows from it, and any risk banner quoting the pre-cut assessment; a stale banner is removed rather than left standing.
11. A whole-story cut re-parents its dependents onto the removed story's own blockers, and the cascade is stated in the digest before the lead confirms.
12. Approving with an empty selection produces an outcome identical to plain approval — no re-derivation, no re-render, no second confirmation.
13. The label vocabulary stays two-valued; no third state and no per-item confidence score is introduced anywhere.
14. At least one story must survive a cut; an all-stories cut is a revise, not an approval.
15. The materialized source text, the labelled draft, and the derived filing body are all session-scratch and transient; none is committed, none enters the queue, and none is written under the permanent documentation tree.
16. **Security boundary:** the materialized source text may contain anything the lead typed, including credentials pasted into an intent. It stays in ignored scratch and is never posted to an issue body, a comment, or a report; because labels and their fragments are stripped before filing, no quoted fragment of it reaches the issue tracker either.
17. Discovery's razor application writes nothing to the issue tracker and introduces no durable link into the discovery folder.

A cross-cutting statement of the razor's numeric limits would normally belong in the standards space rather than in any one stage. That space does not exist in this repository, so the shared skill serves as its stand-in — a deviation recorded here deliberately. If a standards space is later created, the limits move there and the skill references them. No standards-conformance pass was possible for this record for the same reason.

## Risks (BLOCKER / ADDRESS only)

- **ADDRESS — the citation check proves the quote exists, not that it supports the item.** A drafting model that wants to keep an addition can label it asked and cite a real fragment that does not license it. The check passes and the reviewer sees a clean gate. The epic's first success metric, as worded, therefore overstates the guarantee the mechanism delivers. Decision needed during implementation: either the digest renders each asked item together with its fragment so the reviewer can see the non-sequitur — which lengthens the digest and cuts against its read-the-surface premise — or the metric is reworded to claim what the check actually establishes, with the fragment reachable only in drill-down. The word floor and the advisory weak-fragment finding narrow the gaming surface but do not close it.

- **ADDRESS — the epic's recorded sizing no longer matches the work, and this record has increased the gap.** Story #287 is recorded S on the assumption that the gate counts inline; moving the checks into a shared toolkit operation adds a tested library and moves that story to roughly M, while #289 shrinks. Independently, the approval-gate decision to make asked-for stories cuttable on necessity grounds widens #288 beyond its recorded M. The epic is already assessed L with an explicit no-slack banner. Decision needed before implementation starts: re-size #287, #288 and #289 and re-check the rollup, or accept the L knowing the utilization risk it already carries has increased.

- **ADDRESS — the epic's first assumption names an artifact that does not exist.** The epic justifies a new skill by contrasting it against an existing prose-style skill's disclaimer; there is no such skill, and no precedent for a guidance-only skill at all. An implementer working from the assumption will search for it and improvise. Mitigation: rewrite the assumption to state the real trade-off, and note that this introduces the first guidance-only skill in the components tree. Relatedly, the discovery stage's standing constraint against new agents or skills needs narrowing to ticket-type routing when story #289 lands, or it will read as contradicting that story.

## Open Clarifications

None. Two clarifications were raised by the analysis and both were resolved by the lead at this record's approval gate — the acceptance-criteria limit blocks on the ceiling only, and asked-for stories outside the minimal usable set are cuttable at the digest. Both answers are folded into the decisions above and into the scope edits they name.