feat(templates): reconcile authored scope against originating issues in propose, propose-batch, and decompose-phase

.ratchet/changes/issue-scope-reconciliation/.ratchet.yaml

@@ -0,0 +1,10 @@
+schema: ratchet
+created: 2026-08-26
+standards:
+  - security-remediation
+  - documentation
+  - testing
+  - multi-agent-support
+  - generalizable-defaults
+  - instruction-fed-config
+  - delegated-lifecycle

.ratchet/changes/issue-scope-reconciliation/features/scope-reconciliation/close-claim-honesty.feature

@@ -0,0 +1,28 @@
+Feature: Honest close-claims in batch manifests and change authoring
+  As a maintainer reading a manifest or a plan
+  I want a "Closes #N" claim to be earned rather than assumed
+  So that GitHub never auto-closes an issue whose material requirements are still unimplemented
+
+  Scenario: Propose-batch forbids hard-coding a close-claim for unscoped work
+    Given the propose-batch workflow body
+    When an author reads its manifest-authoring rules
+    Then it forbids writing "Closes #N" or "Fixes #N" into a phase goal, a phase success criterion, or a change-level done for work that has not yet been scoped and verified
+    And it states that a close-claim is an output of verification and never an input of planning
+
+  Scenario: Phase contracts reference issues without claiming closure
+    Given the propose-batch workflow body
+    When an author writes a phase contract that addresses an issue
+    Then the body requires the phrasing "targets #N" or "addresses #N"
+    And it states that the "Closes #N" linkage is earned at pull-request-authoring time only after the issue's material requirements are confirmed implemented
+
+  Scenario: Partial coverage is stated as partial
+    Given the propose-batch workflow body
+    When a change-level done criterion covers only part of an issue
+    Then the body requires that done criterion to say "partially addresses #N"
+    And it forbids that done criterion from saying "Fixes #N" or "Closes #N"
+
+  Scenario: The close-claim rule is shared by all three change-authoring workflows
+    Given the propose, propose-batch, and decompose-phase workflow bodies
+    When each body is inspected for the close-claim rule
+    Then each contains the shared rule that a close-claim is permitted only when the issue's material requirements are actually implemented
+    And each contains the shared rule that partial work must use "partially addresses #N"

.ratchet/changes/issue-scope-reconciliation/features/scope-reconciliation/deferral-carry-forward.feature

@@ -0,0 +1,36 @@
+Feature: Deferrals survive phase boundaries during decomposition
+  As a maintainer decomposing a later batch phase
+  I want deferred scope and unearned close-claims from prior phases to reach this decomposition
+  So that "revisit in the next phase" prose cannot evaporate at a phase boundary
+
+  Scenario: Decomposition reads the prior phases' plans, not only their done criteria
+    Given the decompose-phase workflow body
+    When an author reads its grounding step
+    Then it requires reading each prior phase's shipped change plan file in addition to the injected done criteria
+    And it explains that the injected done criteria are a paraphrase in which deferrals recorded as plan prose are invisible
+
+  Scenario: Every deferred item is extracted from the prior plans
+    Given the decompose-phase workflow body
+    When an author sweeps a prior phase's plan
+    Then it requires extracting every out-of-scope, deferred, revisit, or equivalent item recorded there
+
+  Scenario: Each extracted deferral gets one of exactly three outcomes
+    Given the decompose-phase workflow body
+    And an item extracted from a prior phase's plan
+    When the author decides what to do with it
+    Then the body requires the item to be carried forward as a change intent in the phase being decomposed, or matched to an existing open tracking issue and reported as tracked, or surfaced to the user as an explicit drop decision
+    And it states that silently ignoring an extracted item is not an available outcome
+
+  Scenario: A prior phase's close-claim is verified before the issue is treated as shipped
+    Given the decompose-phase workflow body
+    And a prior phase whose done criterion claims "Fixes #N"
+    When the author grounds this phase in that prior result
+    Then the body requires comparing the issue's material requirements against what the prior phase's done criterion and plan describe as implemented
+    And it requires surfacing an unearned close-claim and carrying the remaining scope forward
+    And it forbids inheriting the close-claim as fact
+
+  Scenario: The decomposition rules reach every supported coding agent
+    Given the decompose-phase command template
+    When it is rendered through every registered tool command adapter
+    Then the rendered command file for every adapter contains the prior-plan deferral sweep
+    And the rendered command file for every adapter contains the earned-close verification

.ratchet/changes/issue-scope-reconciliation/features/scope-reconciliation/issue-reconciliation.feature

@@ -0,0 +1,42 @@
+Feature: Originating-issue reconciliation in change authoring
+  As a maintainer whose work originates from tracked issues
+  I want the propose and propose-batch workflows to reconcile authored scope against every originating issue
+  So that a requirement the issue states can never be dropped without a human being asked
+
+  Background:
+    Given the ratchet workflow templates are the single source of the propose and propose-batch skill bodies
+    And the generated skill and command artifacts for every supported coding agent render from those templates
+
+  Scenario: Propose fetches every originating issue before authoring artifacts
+    Given the propose workflow body
+    When an author reads its steps
+    Then it instructs the author to identify every originating issue referenced by the user, the batch manifest, or the injected done criterion
+    And it instructs the author to fetch each originating issue through the project's issue tracker before writing any artifact
+    And it names "gh issue view <n>" only as a GitHub example rather than a required command
+    And it instructs the author to ask the user to paste the issue text when no tracker client is available
+
+  Scenario: Propose reconciles authored scope against the fetched issue
+    Given the propose workflow body
+    When an author reads its reconciliation step
+    Then it requires enumerating the issue's material requirements from both its explicit fix items and the problems named in its narrative
+    And it requires mapping every enumerated requirement to an authored feature scenario or plan task
+    And it requires listing every requirement that the authored scope does not cover
+
+  Scenario: An omitted requirement is surfaced as an explicit decision point
+    Given the propose workflow body
+    When an author reads its rules for a requirement the authored scope omits
+    Then it requires surfacing the omission to the user as an enumerated "issue asks X, this proposal does not include X" decision point before artifacts are finalized
+    And it forbids self-approving the omission by writing it into plan prose
+
+  Scenario: Propose-batch reconciles the manifest against the originating issues
+    Given the propose-batch workflow body
+    When an author reads its steps
+    Then it instructs the author to fetch every issue an objective or phase originates from
+    And it requires reconciling each phase goal, success criterion, and change-level done against those issues' material requirements
+    And it requires surfacing any material requirement the manifest omits to the user before the manifest is scaffolded
+
+  Scenario: The reconciliation rules reach every supported coding agent
+    Given the propose and propose-batch command templates
+    When each is rendered through every registered tool command adapter
+    Then the rendered command file for every adapter contains the originating-issue reconciliation step
+    And no adapter's rendering drops the prohibition on self-approved omissions

.ratchet/changes/issue-scope-reconciliation/features/scope-reconciliation/stop-and-surface-guardrail.feature

@@ -0,0 +1,24 @@
+Feature: Stop-and-surface guardrail for security-relevant de-scopes
+  As a maintainer relying on agents to author changes unattended
+  I want any de-scope of security, permission, or integrity work to halt the run and ask
+  So that a security exposure can never be narrowed by momentum inside an agent run
+
+  Scenario: The guardrail is defined exactly once
+    Given the workflow template layer
+    When the stop-and-surface guardrail is located
+    Then it is defined as a single shared constant that the propose, propose-batch, and decompose-phase bodies all embed
+    And no workflow body restates it as a hand-authored copy
+
+  Scenario: All three change-authoring workflows carry the guardrail verbatim
+    Given the propose, propose-batch, and decompose-phase workflow bodies
+    When each body's guardrails section is inspected
+    Then each contains the shared guardrail text verbatim
+    And each states that a de-scope of security, permission, or integrity work is a stop-and-surface event in which the workflow halts and asks the user rather than proceeding on momentum
+
+  Scenario: An approved security de-scope requires a filed, linked, owned tracking issue
+    Given a workflow body carrying the shared guardrail
+    And a user who approves deferring a security-relevant requirement
+    When the author records the deferral
+    Then the guardrail requires an explicitly filed tracking issue with a named owner
+    And it requires that issue to be linked from the change plan before the author proceeds
+    And it states that a prose bullet in a plan is not a deferral mechanism

.ratchet/changes/issue-scope-reconciliation/features/scope-reconciliation/worked-example-check.feature

@@ -0,0 +1,28 @@
+Feature: The reconciliation procedure is demonstrated on a worked example
+  As a maintainer who has seen a scope reduction escape review once already
+  I want a runnable check that replays the failure on the hardened workflows
+  So that the reconciliation rules are demonstrated to work rather than merely asserted
+
+  Background:
+    Given an eval fixture holding the originating issue's text, the phase-one manifest excerpt that hard-codes the close-claim, and the phase-one change plan carrying the out-of-scope bullet
+    And an eval spec that binds this scenario to that fixture
+
+  Scenario: Replaying the worked example flags all three escapes
+    Given the hardened propose and propose-batch reconciliation procedure
+    When the procedure is applied to the fixture's issue text and the fixture's manifest and plan
+    Then it flags the issue's gating requirement as present in the issue and absent from the authored scope
+    And it flags the permission-posture bypass named in the issue's narrative as absent from the authored scope
+    And it flags the manifest's hard-coded close-claim as premature because the issue's material requirements are not all implemented
+    And it reports each of the three as a decision point requiring the user rather than a self-approved omission
+
+  Scenario: The hedged wording in the issue does not lower the bar
+    Given the fixture's issue text phrases its gating requirement as something to "consider"
+    When the reconciliation procedure enumerates that issue's material requirements
+    Then the hedged requirement is still enumerated as material because the exposure is security-relevant
+    And the procedure does not treat the hedge as permission to drop the requirement
+
+  Scenario: The check is runnable and its verdict is recorded
+    Given the eval spec bound to this scenario
+    When the eval is run for this case
+    Then the run produces a recorded verdict for the case
+    And the verdict is available as evidence that the worked example was actually replayed