From b712bc7cb1dd0a43c263e327ee75590048a95a8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=8D=87=E9=BE=99?= Date: Sun, 30 Aug 2026 13:47:05 +0800 Subject: [PATCH 1/5] feat(orchestration): bind impact decisions to specifications --- .../contract/specification-v1.md | 31 +++++++++++++++++++ references/assets/orchestration/workflow.md | 2 ++ references/evals/orchestration/evals.json | 24 ++++++++++++++ skills/orch-create-specification/SKILL.md | 12 ++++--- .../test_orchestration_skill_rule_boundary.py | 5 +++ .../test_orchestration_workflow_contracts.py | 25 +++++++++++++++ 6 files changed, 95 insertions(+), 4 deletions(-) diff --git a/references/assets/orchestration/contract/specification-v1.md b/references/assets/orchestration/contract/specification-v1.md index 9c4e40f..d59e0a2 100644 --- a/references/assets/orchestration/contract/specification-v1.md +++ b/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 +``` + +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 every frontier relation is immaterial, already projected, excluded with evidence, or blocked for authority. Escalate to targeted Git history, prior work artifacts, or execution evidence only for contradictory current-state evidence, unresolved ownership, material regression/causality, or a suspected governing legacy decision; do not require full-history archaeology 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 diff --git a/references/assets/orchestration/workflow.md b/references/assets/orchestration/workflow.md index c0b8ed6..bb4bc93 100644 --- a/references/assets/orchestration/workflow.md +++ b/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. 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. A greenfield result may use `none_relevant` only with the searched boundary, reason, and `stopping_reason`. Targeted Git history, prior work artifacts, or execution evidence is an escalation for contradiction, unresolved ownership, material regression/causality, or suspected governing legacy decisions—not mandatory full-history archaeology. 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. diff --git a/references/evals/orchestration/evals.json b/references/evals/orchestration/evals.json index bc4b701..1b2ac3a 100644 --- a/references/evals/orchestration/evals.json +++ b/references/evals/orchestration/evals.json @@ -420,6 +420,30 @@ "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, or execution evidence 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": [] } ], "v4_evals": [ diff --git a/skills/orch-create-specification/SKILL.md b/skills/orch-create-specification/SKILL.md index 46fd41e..999b656 100644 --- a/skills/orch-create-specification/SKILL.md +++ b/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. 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 current-state traversal when every frontier relation is immaterial, already projected to a stable ID, excluded with evidence, or blocked for authority. Escalate to targeted Git history, prior work artifacts, or execution evidence 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 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. diff --git a/tests/test_orchestration_skill_rule_boundary.py b/tests/test_orchestration_skill_rule_boundary.py index a4b595d..2d88308 100644 --- a/tests/test_orchestration_skill_rule_boundary.py +++ b/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 diff --git a/tests/test_orchestration_workflow_contracts.py b/tests/test_orchestration_workflow_contracts.py index 0a6b63b..c22ecba 100644 --- a/tests/test_orchestration_workflow_contracts.py +++ b/tests/test_orchestration_workflow_contracts.py @@ -329,6 +329,31 @@ 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 "impact-decision view" in skill + assert "keep repository traversal out of `dev-semantic-convergence`" in skill + assert "Git history, prior work artifacts, or execution evidence" 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 + + 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 From ea7bdc5e4ae85bdacc5b86b288c734e2645b6d4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=8D=87=E9=BE=99?= Date: Sun, 30 Aug 2026 15:17:15 +0800 Subject: [PATCH 2/5] fix(orchestration): preserve conditional knowledge escalation --- .../assets/orchestration/contract/specification-v1.md | 2 +- references/assets/orchestration/workflow.md | 2 +- skills/orch-create-specification/SKILL.md | 2 +- tests/test_orchestration_workflow_contracts.py | 7 ++++++- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/references/assets/orchestration/contract/specification-v1.md b/references/assets/orchestration/contract/specification-v1.md index d59e0a2..ea20261 100644 --- a/references/assets/orchestration/contract/specification-v1.md +++ b/references/assets/orchestration/contract/specification-v1.md @@ -105,7 +105,7 @@ impact_decisions: 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 every frontier relation is immaterial, already projected, excluded with evidence, or blocked for authority. Escalate to targeted Git history, prior work artifacts, or execution evidence only for contradictory current-state evidence, unresolved ownership, material regression/causality, or a suspected governing legacy decision; do not require full-history archaeology by default. +Use `none_relevant` only after a bounded scan finds no material relation and records its searched boundary, reason, and `stopping_reason`. Stop when every frontier relation is immaterial, already projected, excluded with evidence, or blocked for authority. 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 diff --git a/references/assets/orchestration/workflow.md b/references/assets/orchestration/workflow.md index bb4bc93..d34a768 100644 --- a/references/assets/orchestration/workflow.md +++ b/references/assets/orchestration/workflow.md @@ -114,7 +114,7 @@ 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. 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. A greenfield result may use `none_relevant` only with the searched boundary, reason, and `stopping_reason`. Targeted Git history, prior work artifacts, or execution evidence is an escalation for contradiction, unresolved ownership, material regression/causality, or suspected governing legacy decisions—not mandatory full-history archaeology. This impact-decision view is compared by semantic convergence; repository traversal remains owned by specification authoring. +Specification authoring materializes `impact_decisions` from bounded current-state evidence about the requested surface, upstream/downstream relations, validation surfaces, and relevant dirty work. 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. 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 diff --git a/skills/orch-create-specification/SKILL.md b/skills/orch-create-specification/SKILL.md index 999b656..a90b644 100644 --- a/skills/orch-create-specification/SKILL.md +++ b/skills/orch-create-specification/SKILL.md @@ -16,7 +16,7 @@ Create the smallest authoritative specification under `.work-bundle/orchestratio 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. 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. 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 current-state traversal when every frontier relation is immaterial, already projected to a stable ID, excluded with evidence, or blocked for authority. Escalate to targeted Git history, prior work artifacts, or execution evidence 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 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. +6. Stop current-state traversal when every frontier relation is immaterial, already projected to a stable ID, excluded with evidence, or blocked for authority. 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: diff --git a/tests/test_orchestration_workflow_contracts.py b/tests/test_orchestration_workflow_contracts.py index c22ecba..0e41af3 100644 --- a/tests/test_orchestration_workflow_contracts.py +++ b/tests/test_orchestration_workflow_contracts.py @@ -345,9 +345,14 @@ def test_specification_contract_requires_bounded_impact_decisions() -> None: "dirty work", ]: assert token in text + assert "durable knowledge" in text + assert "projects_to" in text and "stable" 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, or execution evidence" 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 From 6e7b840db86dcd16bb675598002ad60fa2ef1574 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=8D=87=E9=BE=99?= Date: Sun, 30 Aug 2026 15:22:10 +0800 Subject: [PATCH 3/5] test(orchestration): align provenance pressure eval --- references/evals/orchestration/evals.json | 2 +- tests/test_orchestration_workflow_contracts.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/references/evals/orchestration/evals.json b/references/evals/orchestration/evals.json index 1b2ac3a..f50c30a 100644 --- a/references/evals/orchestration/evals.json +++ b/references/evals/orchestration/evals.json @@ -436,7 +436,7 @@ { "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, or execution evidence only for contradiction, unresolved ownership, regression causality, or governing legacy decisions.", + "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": [] }, { diff --git a/tests/test_orchestration_workflow_contracts.py b/tests/test_orchestration_workflow_contracts.py index 0e41af3..2991035 100644 --- a/tests/test_orchestration_workflow_contracts.py +++ b/tests/test_orchestration_workflow_contracts.py @@ -357,6 +357,7 @@ def test_specification_contract_requires_bounded_impact_decisions() -> None: 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 def test_archive_plan_uses_accepted_execution_dispositions_as_knowledge_gate(tmp_path: Path) -> None: From 5e1d05f8947f6aedcd1ab49f94ae1fa63635c911 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=8D=87=E9=BE=99?= Date: Sun, 30 Aug 2026 15:26:55 +0800 Subject: [PATCH 4/5] fix(orchestration): define impact materiality boundary --- .../assets/orchestration/contract/specification-v1.md | 4 ++-- references/assets/orchestration/workflow.md | 2 +- references/evals/orchestration/evals.json | 6 ++++++ skills/orch-create-specification/SKILL.md | 4 ++-- tests/test_orchestration_workflow_contracts.py | 3 +++ 5 files changed, 14 insertions(+), 5 deletions(-) diff --git a/references/assets/orchestration/contract/specification-v1.md b/references/assets/orchestration/contract/specification-v1.md index ea20261..b23f2b2 100644 --- a/references/assets/orchestration/contract/specification-v1.md +++ b/references/assets/orchestration/contract/specification-v1.md @@ -103,9 +103,9 @@ impact_decisions: reason: string ``` -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. +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 every frontier relation is immaterial, already projected, excluded with evidence, or blocked for authority. 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. +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 the materiality surfaces, every frontier relation is already projected, excluded with evidence, or blocked for authority, and the stop reason is recorded. 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 diff --git a/references/assets/orchestration/workflow.md b/references/assets/orchestration/workflow.md index d34a768..41a208d 100644 --- a/references/assets/orchestration/workflow.md +++ b/references/assets/orchestration/workflow.md @@ -114,7 +114,7 @@ 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. 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. 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. +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 diff --git a/references/evals/orchestration/evals.json b/references/evals/orchestration/evals.json index f50c30a..5eac181 100644 --- a/references/evals/orchestration/evals.json +++ b/references/evals/orchestration/evals.json @@ -444,6 +444,12 @@ "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": [ diff --git a/skills/orch-create-specification/SKILL.md b/skills/orch-create-specification/SKILL.md index a90b644..ead3f5c 100644 --- a/skills/orch-create-specification/SKILL.md +++ b/skills/orch-create-specification/SKILL.md @@ -15,8 +15,8 @@ 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. 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. 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 current-state traversal when every frontier relation is immaterial, already projected to a stable ID, excluded with evidence, or blocked for authority. 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. +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 current-state traversal when further exploration could change none of the materiality surfaces, every frontier relation is already projected to a stable ID, excluded with evidence, or blocked for authority, and the stop reason is recorded. 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: diff --git a/tests/test_orchestration_workflow_contracts.py b/tests/test_orchestration_workflow_contracts.py index 2991035..4e01124 100644 --- a/tests/test_orchestration_workflow_contracts.py +++ b/tests/test_orchestration_workflow_contracts.py @@ -347,6 +347,8 @@ def test_specification_contract_requires_bounded_impact_decisions() -> None: 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 for text in (contract, skill): assert "blocking" in text and "open question" in text.lower() assert "blocking relations prevent verification" in workflow @@ -358,6 +360,7 @@ def test_specification_contract_requires_bounded_impact_decisions() -> None: 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 b31881a9b2faf79f9adb5fd3144224a3ddec49fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=8D=87=E9=BE=99?= Date: Sun, 30 Aug 2026 15:31:09 +0800 Subject: [PATCH 5/5] fix(orchestration): make impact stop rule non-circular --- references/assets/orchestration/contract/specification-v1.md | 2 +- skills/orch-create-specification/SKILL.md | 2 +- tests/test_orchestration_workflow_contracts.py | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/references/assets/orchestration/contract/specification-v1.md b/references/assets/orchestration/contract/specification-v1.md index b23f2b2..d40a52e 100644 --- a/references/assets/orchestration/contract/specification-v1.md +++ b/references/assets/orchestration/contract/specification-v1.md @@ -105,7 +105,7 @@ impact_decisions: 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 the materiality surfaces, every frontier relation is already projected, excluded with evidence, or blocked for authority, and the stop reason is recorded. 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. +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 diff --git a/skills/orch-create-specification/SKILL.md b/skills/orch-create-specification/SKILL.md index ead3f5c..7df6fc9 100644 --- a/skills/orch-create-specification/SKILL.md +++ b/skills/orch-create-specification/SKILL.md @@ -16,7 +16,7 @@ Create the smallest authoritative specification under `.work-bundle/orchestratio 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. 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 current-state traversal when further exploration could change none of the materiality surfaces, every frontier relation is already projected to a stable ID, excluded with evidence, or blocked for authority, and the stop reason is recorded. 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. +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: diff --git a/tests/test_orchestration_workflow_contracts.py b/tests/test_orchestration_workflow_contracts.py index 4e01124..1421f92 100644 --- a/tests/test_orchestration_workflow_contracts.py +++ b/tests/test_orchestration_workflow_contracts.py @@ -349,6 +349,7 @@ def test_specification_contract_requires_bounded_impact_decisions() -> None: 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