WOR-61: bind impact decisions to specifications

references/assets/orchestration/contract/specification-v1.md

@@ -77,6 +77,36 @@ When material non-authority evidence appears, record agent-owned polarity and ma
 - **User resolution**: Record accepted answer or unresolved.
 - **Evidence conclusion**: Record any accepted conclusion as specification evidence.
 
+### 4.2 Impact Decisions
+
+Before verification, record one bounded current-state evidence basis covering the requested surface, material upstream dependencies or producers, downstream consumers, validation/test surfaces, and relevant dirty work.
+
+```yaml
+impact_decisions:
+  basis:
+    requested_surface: [path-or-symbol]
+    current_state_sources: [evidence-ref]
+    dirty_work: clean | related | unrelated
+    stopping_reason: string
+  relations:
+    - id: IMP-001
+      relation: string
+      direction: upstream | downstream | validation | cross-cutting
+      materiality: string
+      disposition: accepted | excluded | blocking
+      evidence: [evidence-ref]
+      projects_to: [REQ-001, AC-001]
+      reason: string
+  none_relevant:
+    value: false
+    searched_boundary: string
+    reason: string
+```
+
+Treat a relation as material only when its disposition could change a requirement, constraint, acceptance criterion, user-observable or contractual outcome, architectural boundary, measurable quality target, validation target, or declared boundary. Every material relation has exactly one `accepted | excluded | blocking` disposition. `projects_to` is required for accepted relations and must name stable requirements, constraints, interfaces, acceptance criteria, or validation targets. Excluded relations require evidence and a concise reason; "the user did not mention it" is not sufficient. Blocking relations create blocking Open Questions and keep the quality gate blocked.
+
+Use `none_relevant` only after a bounded scan finds no material relation and records its searched boundary, reason, and `stopping_reason`. Stop when further exploration could change none of those surfaces and record the reason. Escalate to targeted Git history, prior work artifacts, execution evidence, or durable knowledge only for contradictory current-state evidence, unresolved ownership, material regression/causality, or a suspected governing legacy decision; do not require full-history archaeology or broad knowledge retrieval by default.
+
 ## 5. Requirements, Constraints & Guidelines
 
 [Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
@@ -230,6 +260,7 @@ Semantic convergence lenses:
 - authority and evidence support
 - requirement, constraint, and open-question consistency
 - impact radius
+- impact-decision view, including disposition and `projects_to` agreement
 - Knowledge Base Update disposition
 - execution-workspace policy when applicable
 

references/assets/orchestration/workflow.md

@@ -114,6 +114,8 @@ Final review aggregates accepted task dispositions from execution and task-revie
 
 Only approved keep-summarizing owners write durable knowledge. Final orchestration review owns approved persistence delegation and may invoke that owner, then validate returned paths or an evidence-backed no-write result; executors and orchestration itself must not write knowledge directly.
 
+Specification authoring materializes `impact_decisions` from bounded current-state evidence about the requested surface, upstream/downstream relations, validation surfaces, and relevant dirty work. A relation is material only when its disposition could change a requirement, constraint, acceptance criterion, user-observable or contractual outcome, architectural boundary, measurable quality target, validation target, or declared boundary. Each material relation is `accepted | excluded | blocking`: accepted relations use `projects_to` for stable specification IDs, excluded relations require evidence, and blocking relations prevent verification. Stop when further exploration could change none of those surfaces and record the reason; a greenfield result may use `none_relevant` only with the searched boundary, reason, and `stopping_reason`. Targeted Git history, prior work artifacts, execution evidence, or durable knowledge is an escalation for contradiction, unresolved ownership, material regression/causality, or suspected governing legacy decisions—not mandatory full-history archaeology or broad knowledge retrieval. This impact-decision view is compared by semantic convergence; repository traversal remains owned by specification authoring.
+
 ## Lightweight development lane
 
 Use `dev-create-task-plan` for bounded mechanical work with stable decisions. After preflight and source grounding it invokes one bounded `ks-what-is-helpful` gateway, carries accepted authority or evidence-backed `none relevant`, writes one disposable plan under `.work-bundle/runtime/dev-plans/`, and creates no orchestration artifact tree. Its lightweight completion owner records an evidence-backed no-write result for `none`; for `update`, `supersede`, or `reclassify`, it invokes the approved keep-summarizing lifecycle and validates return evidence before completion. Escalate to full orchestration for unresolved architecture/API/data/workflow decisions, wide impact, multiple repositories, migration/deployment sequencing, unresolved durable-knowledge decisions, or parallel contract/barrier needs.

references/evals/orchestration/evals.json

@@ -420,6 +420,36 @@
       "prompt": "Resolve v4 repository context when portable project metadata and device-local checkout observations disagree.",
       "expected_output": "Keeps project.yaml as portable project/topology authority, resolves local observations only from bootstrap-resolved project_registry device_bindings, and blocks the contradiction without restoring v3 local fields.",
       "files": []
+    },
+    {
+      "id": 77,
+      "prompt": "Create a specification for retiring a producer when current source evidence shows an existing downstream consumer that the user did not mention.",
+      "expected_output": "Builds a bounded current-state impact basis, records the consumer as a material relation, and blocks verification until it is accepted and projected to stable IDs or excluded with evidence; omission from the request is not an exclusion reason.",
+      "files": []
+    },
+    {
+      "id": 78,
+      "prompt": "Create a specification for a greenfield isolated utility after a bounded current-state scan finds no material upstream, downstream, validation, or dirty-work relations.",
+      "expected_output": "Records impact_decisions none_relevant with the searched boundary, reason, and stopping_reason, then permits verification without inventing legacy impact.",
+      "files": []
+    },
+    {
+      "id": 79,
+      "prompt": "Current-state evidence fully explains a material relation and is not contradictory, but a reviewer asks for mandatory full-history archaeology before specification verification.",
+      "expected_output": "Declines mandatory archaeology, records the current-state evidence and stopping reason, and escalates to targeted Git history, prior work artifacts, execution evidence, or durable knowledge only for contradiction, unresolved ownership, regression causality, or governing legacy decisions.",
+      "files": []
+    },
+    {
+      "id": 80,
+      "prompt": "A material current relation has unresolved ownership and could change the accepted API contract.",
+      "expected_output": "Marks the relation blocking, creates a blocking open question, keeps Quality gate blocked, and uses targeted provenance evidence to resolve ownership rather than silently accepting or excluding it.",
+      "files": []
+    },
+    {
+      "id": 81,
+      "prompt": "An impact scan finds one relation that is merely adjacent and cannot change an accepted contract surface, plus another relation whose disposition can change a user-observable outcome and validation target.",
+      "expected_output": "Stops traversing the related-but-non-material relation with a recorded reason, treats the outcome-changing relation as material, and requires accepted, excluded, or blocking disposition because it can change a user-observable or contractual outcome, architectural boundary, measurable quality target, validation target, or declared boundary.",
+      "files": []
     }
   ],
   "v4_evals": [

skills/orch-create-specification/SKILL.md

@@ -15,10 +15,11 @@ Create the smallest authoritative specification under `.work-bundle/orchestratio
 2. Run project metadata preflight. Record each target repository, expected and actual branch/commit, cleanliness trust, and CodeGraph index or `no-index` state. Repository blockers limit source inspection but do not stop bounded knowledge-gateway classification when it remains accessible.
 3. Through `ks-what-is-helpful`, discover with polarity-neutral and stage/perspective/status-neutral query anchors. `implementation_spec` is classification and output-grouping intent, not a discovery-stage lifecycle filter.
 4. Classify results as authority, candidate, background, or blocked. Only authority shapes requirements and only accepted authority enters front-matter `source_knowledge` as `path` plus the already-reconciled `constraint`; keep candidate, background, blocked, superseded, supporting, opposing, constraining, unresolved/open-question, obsolete, and irrelevant-with-reason evidence in Source Context when material. Downstream planning allocates `AUTH-NNN` aliases from the accepted list so execution does not require `.work-bundle/knowledge/` reads or expose knowledge paths.
-5. Inspect bounded current repository evidence, including upstream/downstream and validation/test impact-radius evidence. For WorkBundle scope, include related active violations by ID, severity, deviation, scope, required resolution, and expected review closure. Exact-current-work conflicts may remain specification-owned.
-6. Ask Design Interrogation questions only for unresolved intent that changes requirements, architecture, workflow, API, persistence, validation, execution safety, or user purpose. Evidence class alone does not make an open question blocking.
-7. Normalize stable IDs, requirements, constraints, interfaces, acceptance criteria, decisions, open questions, and Knowledge Base Update disposition.
-8. Decide execution-workspace policy without provisioning it:
+5. Build one bounded current-state impact basis from the requested surface, material upstream dependencies or producers, downstream consumers, validation/test surfaces, and relevant dirty work. Treat a relation as material only when its disposition could change a requirement, constraint, acceptance criterion, user-observable or contractual outcome, architectural boundary, measurable quality target, validation target, or declared boundary. Record `impact_decisions` and give each material relation exactly one disposition: `accepted | excluded | blocking`. An accepted relation must use `projects_to` to name stable requirement, constraint, interface, acceptance-criterion, or validation-target IDs. An excluded relation requires evidence and a reason stronger than user omission. A blocking relation creates a blocking open question. When no material relation exists, record `none_relevant` with the searched boundary, reason, and `stopping_reason`.
+6. Stop when further exploration could change none of those surfaces and record the reason. Escalate to targeted Git history, prior work artifacts, execution evidence, or durable knowledge only when current-state evidence is contradictory, ownership is unresolved, regression or causality is material, or a governing legacy decision is suspected. Do not require full-history archaeology or broad knowledge retrieval by default. For WorkBundle scope, include related active violations by ID, severity, deviation, scope, required resolution, and expected review closure. Exact-current-work conflicts may remain specification-owned.
+7. Ask Design Interrogation questions only for unresolved intent that changes requirements, architecture, workflow, API, persistence, validation, execution safety, or user purpose. Evidence class alone does not make an open question blocking.
+8. Normalize stable IDs, requirements, constraints, interfaces, acceptance criteria, decisions, open questions, and Knowledge Base Update disposition.
+9. Decide execution-workspace policy without provisioning it:
 
 ```yaml
 execution_workspace:
@@ -37,6 +38,7 @@ Use `dev-semantic-convergence` with these lenses:
 - authority and evidence support;
 - requirement, constraint, and open-question consistency;
 - impact radius;
+- impact-decision view, including disposition and `projects_to` agreement;
 - Knowledge Base Update disposition;
 - execution-workspace policy when applicable.
 
@@ -52,6 +54,8 @@ semantic_loop:
 
 Do not preserve verbose per-round transcripts.
 
+The caller materializes the impact-decision view. Use `dev-semantic-convergence` to compare and repair it, but keep repository traversal out of `dev-semantic-convergence`.
+
 ## Completion gate
 
 The body must contain `Quality gate: verified|blocked`. Planning may proceed only with `verified`, a converged semantic loop, resolved blocking questions, stable IDs, and explicit Knowledge Base Update disposition. Set that disposition to `required` when the work establishes durable reusable decisions; specification authors do not write durable knowledge directly.

tests/test_orchestration_skill_rule_boundary.py

@@ -64,6 +64,11 @@ def test_specification_uses_compact_semantic_convergence_and_workspace_policy()
         "Quality gate: verified|blocked",
         "Initial User Purpose Evidence",
         "Design Interrogation",
+        "impact-decision view",
+        "accepted | excluded | blocking",
+        "none_relevant",
+        "stopping_reason",
+        "projects_to",
     ]:
         assert token in text
     assert "Extra evidence loop" not in text

tests/test_orchestration_workflow_contracts.py

@@ -329,6 +329,41 @@ def test_specification_contract_uses_semantic_loop_and_workspace_policy() -> Non
     assert "Extra evidence loop" not in contract
 
 
+def test_specification_contract_requires_bounded_impact_decisions() -> None:
+    contract = read("references/assets/orchestration/contract/specification-v1.md")
+    skill = read("skills/orch-create-specification/SKILL.md")
+    workflow = read("references/assets/orchestration/workflow.md")
+    evals = read("references/evals/orchestration/evals.json")
+    for text in (contract, skill, workflow):
+        for token in [
+            "impact_decisions",
+            "accepted | excluded | blocking",
+            "none_relevant",
+            "stopping_reason",
+            "projects_to",
+            "current-state evidence",
+            "dirty work",
+        ]:
+            assert token in text
+        assert "durable knowledge" in text
+        assert "projects_to" in text and "stable" in text
+        assert "user-observable or contractual outcome" in text
+        assert "measurable quality target" in text
+        assert "Stop when further exploration could change none of those surfaces and record the reason" in text
+    for text in (contract, skill):
+        assert "blocking" in text and "open question" in text.lower()
+    assert "blocking relations prevent verification" in workflow
+    assert "impact-decision view" in skill
+    assert "keep repository traversal out of `dev-semantic-convergence`" in skill
+    assert "Git history, prior work artifacts, execution evidence, or durable knowledge" in skill
+    assert "user did not mention" in contract
+    assert "existing downstream consumer" in evals
+    assert "greenfield isolated utility" in evals
+    assert "mandatory full-history archaeology" in evals
+    assert "prior work artifacts, execution evidence, or durable knowledge" in evals
+    assert "related-but-non-material relation" in evals
+
+
 def test_archive_plan_uses_accepted_execution_dispositions_as_knowledge_gate(tmp_path: Path) -> None:
     from plans import cmd_archive_plan
     from test_orchestration_execution_context import ACCEPTED_AUTHORITY, workspace, write_executor_handoff