yaaw-se 0.2.0 → 0.2.1

package/dist/payload/yaaw-core/system/core/transitions.md

@@ -2,6 +2,8 @@
 
 State names are not enough; only the transitions below are legal unless an explicit recovery rule documents a narrower evidence-backed exception.
 
+In the machine registry, `owner` is the semantic decision authority and `state_writer` is the role permitted to persist the resulting lifecycle mutation. Project-state ledger writes are performed by Orchestrator after validating the durable basis. This does not transfer product, planning, implementation, or acceptance authority to Orchestrator.
+
 The machine-readable transition table used by conformance tests lives in `.yaaw-core/system/registries/transitions.json`. This document remains the human-readable explanation and CI checks the registry against workflow IDs and the project-state schema.
 
 ## Ticket transitions
@@ -23,9 +25,12 @@ The machine-readable transition table used by conformance tests lives in `.yaaw-
 | REPLAN_REQUIRED | DRAFT | Planner | contract revised but not yet re-admitted |
 | REPLAN_REQUIRED | READY | Planner | revised contract passes readiness and dependencies |
 | BLOCKED | DRAFT/READY/IN_PROGRESS/REVIEW_REQUIRED/REPAIR_REQUIRED/REPLAN_REQUIRED | owning role | blocker resolved and prior valid boundary proven |
-| PASS | REPLAN_REQUIRED | Orchestrator/Planner | upstream revision invalidates current acceptance |
+| PASS | REVIEW_REQUIRED | Orchestrator recovery | source contract remains current but review/verification repository basis is missing, stale, or unverifiable |
+| PASS | REPLAN_REQUIRED | Orchestrator/Planner | upstream source/contract revision invalidates current acceptance |
 | PASS | CANCELLED | Human/Planner | accepted scope explicitly removed; history preserved |
 
+Repository identity mismatch alone does not establish `REPLAN_REQUIRED`.
+
 Forbidden examples: `DRAFT -> PASS`, `READY -> PASS`, `REPAIR_REQUIRED -> PASS`, or Implementer-authored `PASS`.
 
 ## Project transitions

package/dist/payload/yaaw-core/system/registries/role-io.json

@@ -1,10 +1,153 @@
 {
   "schema": "yaaw.role-io/v1",
   "roles": {
-    "prd": {"reads": ["product", "state"], "writes": ["product"], "forbidden_writes": ["engineering", "engineering_research", "spec", "ticket", "application_files", "evidence", "review", "observed_state", "handoff", "state"]},
-    "planner": {"reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository"], "writes": ["engineering", "engineering_research", "spec", "ticket", "project_rule"], "forbidden_writes": ["product", "application_files", "evidence", "review", "observed_state", "handoff", "state"]},
-    "implementer": {"reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository", "evidence", "review", "application_files"], "writes": ["application_files", "evidence"], "forbidden_writes": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "review", "observed_state", "handoff", "state"]},
-    "reviewer": {"reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository", "evidence", "review", "application_files"], "writes": ["review"], "forbidden_writes": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "application_files", "evidence", "observed_state", "handoff", "state"]},
-    "orchestrator": {"reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository", "evidence", "review", "state", "observed_state", "handoff", "intent"], "writes": ["state", "observed_state", "handoff", "intent"], "forbidden_writes": ["product", "engineering", "engineering_research", "spec", "project_rule", "application_files", "evidence", "review"]}
+    "prd": {
+      "reads": [
+        "product",
+        "state"
+      ],
+      "writes": [
+        "product"
+      ],
+      "forbidden_writes": [
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "application_files",
+        "evidence",
+        "review",
+        "observed_state",
+        "handoff",
+        "state",
+        "installation_manifest"
+      ]
+    },
+    "planner": {
+      "reads": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule",
+        "repository"
+      ],
+      "writes": [
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule"
+      ],
+      "forbidden_writes": [
+        "product",
+        "application_files",
+        "evidence",
+        "review",
+        "observed_state",
+        "handoff",
+        "state",
+        "installation_manifest"
+      ]
+    },
+    "implementer": {
+      "reads": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule",
+        "repository",
+        "evidence",
+        "review",
+        "application_files"
+      ],
+      "writes": [
+        "application_files",
+        "evidence"
+      ],
+      "forbidden_writes": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule",
+        "review",
+        "observed_state",
+        "handoff",
+        "state",
+        "installation_manifest"
+      ]
+    },
+    "reviewer": {
+      "reads": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule",
+        "repository",
+        "evidence",
+        "review",
+        "application_files",
+        "state"
+      ],
+      "writes": [
+        "review"
+      ],
+      "forbidden_writes": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule",
+        "application_files",
+        "evidence",
+        "observed_state",
+        "handoff",
+        "state",
+        "installation_manifest"
+      ]
+    },
+    "orchestrator": {
+      "reads": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "ticket",
+        "project_rule",
+        "repository",
+        "evidence",
+        "review",
+        "state",
+        "observed_state",
+        "handoff",
+        "intent",
+        "installation_manifest"
+      ],
+      "writes": [
+        "state",
+        "observed_state",
+        "handoff",
+        "intent"
+      ],
+      "forbidden_writes": [
+        "product",
+        "engineering",
+        "engineering_research",
+        "spec",
+        "project_rule",
+        "application_files",
+        "evidence",
+        "review",
+        "installation_manifest"
+      ]
+    }
   }
 }

package/dist/payload/yaaw-core/system/registries/routing-policy.json

@@ -7,10 +7,67 @@
   "next_frontier_workflow": "planning.route",
   "complete_terminal": "COMPLETE",
   "ticket_state_precedence": [
-    {"state": "REPLAN_REQUIRED", "workflow": "planning.replan"},
-    {"state": "REPAIR_REQUIRED", "workflow": "implementation.repair-ticket"},
-    {"state": "REVIEW_REQUIRED", "workflow": "review.review-ticket"},
-    {"state": "IN_PROGRESS", "workflow": "orchestration.recover-interruption"},
-    {"state": "READY", "workflow": "implementation.implement-ticket"}
-  ]
+    {
+      "state": "REPLAN_REQUIRED",
+      "workflow": "planning.replan"
+    },
+    {
+      "state": "REPAIR_REQUIRED",
+      "workflow": "implementation.repair-ticket"
+    },
+    {
+      "state": "REVIEW_REQUIRED",
+      "workflow": "review.review-ticket"
+    },
+    {
+      "state": "IN_PROGRESS",
+      "workflow": "orchestration.recover-interruption"
+    },
+    {
+      "state": "READY",
+      "workflow": "implementation.implement-ticket"
+    }
+  ],
+  "invalidation_routes": {
+    "PRODUCT_SOURCE_STALE": {
+      "state": "REPLAN_REQUIRED",
+      "workflow": "planning.replan"
+    },
+    "ENGINEERING_SOURCE_STALE": {
+      "state": "REPLAN_REQUIRED",
+      "workflow": "planning.replan"
+    },
+    "SPEC_SOURCE_STALE": {
+      "state": "REPLAN_REQUIRED",
+      "workflow": "planning.replan"
+    },
+    "TICKET_SOURCE_STALE": {
+      "state": "REPLAN_REQUIRED",
+      "workflow": "planning.replan"
+    },
+    "CONTRACT_INVALIDATED": {
+      "state": "REPLAN_REQUIRED",
+      "workflow": "planning.replan"
+    },
+    "REVIEW_MISSING": {
+      "state": "REVIEW_REQUIRED",
+      "workflow": "review.review-ticket"
+    },
+    "REVIEW_REPOSITORY_STALE": {
+      "state": "REVIEW_REQUIRED",
+      "workflow": "review.review-ticket"
+    },
+    "VERIFICATION_MISSING": {
+      "state": "REVIEW_REQUIRED",
+      "workflow": "review.review-ticket"
+    },
+    "VERIFICATION_REPOSITORY_STALE": {
+      "state": "REVIEW_REQUIRED",
+      "workflow": "review.review-ticket"
+    },
+    "LEGACY_IDENTITY_UNVERIFIABLE": {
+      "state": "REVIEW_REQUIRED",
+      "workflow": "review.review-ticket"
+    }
+  }
 }

package/dist/payload/yaaw-core/system/registries/transitions.json

@@ -1,29 +1,178 @@
 {
   "schema": "yaaw.transitions/v1",
-  "ticket_states": ["DRAFT", "READY", "IN_PROGRESS", "REVIEW_REQUIRED", "REPAIR_REQUIRED", "REPLAN_REQUIRED", "BLOCKED", "PASS", "CANCELLED"],
+  "ticket_states": [
+    "DRAFT",
+    "READY",
+    "IN_PROGRESS",
+    "REVIEW_REQUIRED",
+    "REPAIR_REQUIRED",
+    "REPLAN_REQUIRED",
+    "BLOCKED",
+    "PASS",
+    "CANCELLED"
+  ],
   "legal": [
-    {"from": "DRAFT", "to": "READY", "owner": "planner", "workflow": "planning.create-tickets"},
-    {"from": "DRAFT", "to": "CANCELLED", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "READY", "to": "IN_PROGRESS", "owner": "implementer", "workflow": "implementation.implement-ticket"},
-    {"from": "READY", "to": "REPLAN_REQUIRED", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "IN_PROGRESS", "to": "REVIEW_REQUIRED", "owner": "implementer", "workflow": "implementation.verify-ticket"},
-    {"from": "IN_PROGRESS", "to": "REPLAN_REQUIRED", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "IN_PROGRESS", "to": "BLOCKED", "owner": "implementer", "workflow": "implementation.implement-ticket"},
-    {"from": "REVIEW_REQUIRED", "to": "PASS", "owner": "reviewer", "workflow": "review.record-review"},
-    {"from": "REVIEW_REQUIRED", "to": "REPAIR_REQUIRED", "owner": "reviewer", "workflow": "review.record-review"},
-    {"from": "REVIEW_REQUIRED", "to": "REPLAN_REQUIRED", "owner": "reviewer", "workflow": "review.record-review"},
-    {"from": "REVIEW_REQUIRED", "to": "BLOCKED", "owner": "reviewer", "workflow": "review.record-review"},
-    {"from": "REPAIR_REQUIRED", "to": "REVIEW_REQUIRED", "owner": "implementer", "workflow": "implementation.repair-ticket"},
-    {"from": "REPAIR_REQUIRED", "to": "REPLAN_REQUIRED", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "REPLAN_REQUIRED", "to": "DRAFT", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "REPLAN_REQUIRED", "to": "READY", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "PASS", "to": "REPLAN_REQUIRED", "owner": "planner", "workflow": "planning.replan"},
-    {"from": "PASS", "to": "CANCELLED", "owner": "planner", "workflow": "planning.replan"}
+    {
+      "from": "DRAFT",
+      "to": "READY",
+      "owner": "planner",
+      "workflow": "planning.create-tickets",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "DRAFT",
+      "to": "CANCELLED",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "READY",
+      "to": "IN_PROGRESS",
+      "owner": "implementer",
+      "workflow": "implementation.implement-ticket",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "READY",
+      "to": "REPLAN_REQUIRED",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "IN_PROGRESS",
+      "to": "REVIEW_REQUIRED",
+      "owner": "implementer",
+      "workflow": "implementation.verify-ticket",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "IN_PROGRESS",
+      "to": "REPLAN_REQUIRED",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "IN_PROGRESS",
+      "to": "BLOCKED",
+      "owner": "implementer",
+      "workflow": "implementation.implement-ticket",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REVIEW_REQUIRED",
+      "to": "PASS",
+      "owner": "reviewer",
+      "workflow": "review.record-review",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REVIEW_REQUIRED",
+      "to": "REPAIR_REQUIRED",
+      "owner": "reviewer",
+      "workflow": "review.record-review",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REVIEW_REQUIRED",
+      "to": "REPLAN_REQUIRED",
+      "owner": "reviewer",
+      "workflow": "review.record-review",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REVIEW_REQUIRED",
+      "to": "BLOCKED",
+      "owner": "reviewer",
+      "workflow": "review.record-review",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REPAIR_REQUIRED",
+      "to": "REVIEW_REQUIRED",
+      "owner": "implementer",
+      "workflow": "implementation.repair-ticket",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REPAIR_REQUIRED",
+      "to": "REPLAN_REQUIRED",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REPLAN_REQUIRED",
+      "to": "DRAFT",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "REPLAN_REQUIRED",
+      "to": "READY",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "PASS",
+      "to": "CANCELLED",
+      "owner": "planner",
+      "workflow": "planning.replan",
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "PASS",
+      "to": "REVIEW_REQUIRED",
+      "owner": "orchestrator",
+      "workflow": "orchestration.reconcile-state",
+      "causes": [
+        "REVIEW_MISSING",
+        "REVIEW_REPOSITORY_STALE",
+        "VERIFICATION_MISSING",
+        "VERIFICATION_REPOSITORY_STALE",
+        "LEGACY_IDENTITY_UNVERIFIABLE"
+      ],
+      "state_writer": "orchestrator"
+    },
+    {
+      "from": "PASS",
+      "to": "REPLAN_REQUIRED",
+      "owner": "orchestrator",
+      "workflow": "orchestration.reconcile-state",
+      "causes": [
+        "PRODUCT_SOURCE_STALE",
+        "ENGINEERING_SOURCE_STALE",
+        "SPEC_SOURCE_STALE",
+        "TICKET_SOURCE_STALE",
+        "CONTRACT_INVALIDATED"
+      ],
+      "state_writer": "orchestrator"
+    }
+  ],
+  "blocked_exit_targets": [
+    "DRAFT",
+    "READY",
+    "IN_PROGRESS",
+    "REVIEW_REQUIRED",
+    "REPAIR_REQUIRED",
+    "REPLAN_REQUIRED"
   ],
-  "blocked_exit_targets": ["DRAFT", "READY", "IN_PROGRESS", "REVIEW_REQUIRED", "REPAIR_REQUIRED", "REPLAN_REQUIRED"],
   "forbidden": [
-    {"from": "DRAFT", "to": "PASS"},
-    {"from": "READY", "to": "PASS"},
-    {"from": "REPAIR_REQUIRED", "to": "PASS"}
+    {
+      "from": "DRAFT",
+      "to": "PASS"
+    },
+    {
+      "from": "READY",
+      "to": "PASS"
+    },
+    {
+      "from": "REPAIR_REQUIRED",
+      "to": "PASS"
+    }
   ]
 }

package/dist/payload/yaaw-core/system/roles/implementer.md

@@ -15,3 +15,6 @@ Own code changes for one bounded admitted ticket at a time.
 
 ## Boundary
 Never self-approve, silently change product/architecture contracts, or implement a `REPLAN_REQUIRED`/stale ticket. Missing material decisions route back to Planner through Orchestrator. Changeability guidance improves the authorized change; it never expands ticket scope.
+
+## Framework boundary
+Package-managed `.yaaw-core/system/**` is never a writable semantic-work surface. If a framework contract is missing, contradictory, or blocks valid work, do not edit YAAW to unblock yourself. Return `FRAMEWORK_INTEGRITY_VIOLATION`, `FRAMEWORK_INTEGRITY_UNKNOWN`, or `FRAMEWORK_CONTRACT_INCONSISTENCY` to Orchestrator with the exact evidence.

package/dist/payload/yaaw-core/system/roles/orchestrator.md

@@ -5,17 +5,18 @@ Own continuity, workspace/repository reconstruction, evidence-backed reconciliat
 
 ## Boot sequence
 1. Resolve the YAAW workspace root using `.yaaw-core/system/core/execution-context.md`; never assume provider CWD.
-2. Inspect repository capability with root-anchored commands and record `READY`, `UNVERSIONED`, `UNAVAILABLE`, `ROOT_MISMATCH`, or `IDENTITY_FAILED`.
-3. Inspect durable claims, active artifacts, runtime caches, and repository/application reality.
-4. Revalidate or discard stale runtime handoffs.
-5. Reconcile only evidence-backed inconsistencies using legal transitions.
-6. Determine exactly one next canonical workflow or terminal state.
-7. Populate a structured handoff from `role-io.json`, `execution-policy.json`, exact artifact references, and current repository basis.
-8. Dispatch exactly one canonical workflow using the host execution mechanism defined by `.yaaw-core/system/core/dispatch-execution.md`. Prefer a fresh isolated worker for non-Orchestrator semantic roles when available.
-9. After any worker completion, failure, interruption, or lost response, return to `orchestration.inspect-state` before selecting another semantic workflow.
-10. Repeat until a real stop condition.
+2. Run the read-only framework integrity gate from `.yaaw-core/system/core/framework-integrity.md`. If status is not `HEALTHY`, invalidate executable handoffs, report the typed framework failure and installer repair instruction, and stop without project lifecycle mutation.
+3. Inspect repository capability with root-anchored commands and record `READY`, `UNVERSIONED`, `UNAVAILABLE`, `ROOT_MISMATCH`, or `IDENTITY_FAILED`.
+4. Inspect durable claims, active artifacts, runtime caches, and repository/application reality.
+5. Revalidate or discard stale runtime handoffs.
+6. Reconcile only evidence-backed inconsistencies using legal transitions.
+7. Determine exactly one next canonical workflow or terminal state.
+8. Populate a structured handoff from `role-io.json`, `execution-policy.json`, exact artifact references, and current repository basis.
+9. Dispatch exactly one canonical workflow using the host execution mechanism defined by `.yaaw-core/system/core/dispatch-execution.md`. Prefer a fresh isolated worker for non-Orchestrator semantic roles when available.
+10. After any worker completion, failure, interruption, or lost response, return to `orchestration.inspect-state` before selecting another semantic workflow.
+11. Repeat until a real stop condition.
 
 ## Boundary
-The Orchestrator is a traffic controller, not a super-agent. It must not author product decisions, architecture, implementation, research conclusions, or acceptance. Roles never privately delegate to peers; every successor is chosen here.
+The Orchestrator is a traffic controller, not a super-agent. Package integrity is an execution precondition, not something Orchestrator may repair by editing YAAW. The Orchestrator never creates, edits, deletes, or weakens package-managed `.yaaw-core/system/**` content in a consumer run. It must not author product decisions, architecture, implementation, research conclusions, or acceptance. Roles never privately delegate to peers; every successor is chosen here.
 
 Child/worker text is not project truth. Durable artifacts, repository evidence, accepted reviews, and legal state transitions are authoritative.

package/dist/payload/yaaw-core/system/roles/planner.md

@@ -20,3 +20,6 @@ Own engineering understanding, architecture decisions, external engineering rese
 
 ## Boundary
 Never invent product intent. Product gaps return to PRD/human authority. Planner does not accept implementation on behalf of Reviewer. Research, host expertise, changeability, and assumption-challenge guidance never authorize speculative architecture, scope creep, or unrelated refactoring.
+
+## Framework boundary
+Package-managed `.yaaw-core/system/**` is never a writable semantic-work surface. If a framework contract is missing, contradictory, or blocks valid work, do not edit YAAW to unblock yourself. Return `FRAMEWORK_INTEGRITY_VIOLATION`, `FRAMEWORK_INTEGRITY_UNKNOWN`, or `FRAMEWORK_CONTRACT_INCONSISTENCY` to Orchestrator with the exact evidence.

package/dist/payload/yaaw-core/system/roles/prd.md

@@ -17,3 +17,6 @@ Own product goals, users, behaviors, constraints, scope, non-goals, and human-ap
 
 ## Boundary
 Never silently convert a technical preference into product intent or repair downstream engineering artifacts yourself. Changed product intent triggers invalidation and returns downstream ownership to Planner.
+
+## Framework boundary
+Package-managed `.yaaw-core/system/**` is never a writable semantic-work surface. If a framework contract is missing, contradictory, or blocks valid work, do not edit YAAW to unblock yourself. Return `FRAMEWORK_INTEGRITY_VIOLATION`, `FRAMEWORK_INTEGRITY_UNKNOWN`, or `FRAMEWORK_CONTRACT_INCONSISTENCY` to Orchestrator with the exact evidence.

package/dist/payload/yaaw-core/system/roles/reviewer.md

@@ -20,3 +20,6 @@ Own independent acceptance judgment and `PASS`, `REPAIR`, `REPLAN`, or `BLOCKED`
 - `BLOCKED`: acceptance cannot be determined because required evidence is unavailable.
 
 Reviewer does not author implementation while acting as Reviewer. Style preference alone is never a review failure.
+
+## Framework boundary
+Package-managed `.yaaw-core/system/**` is never a writable semantic-work surface. If a framework contract is missing, contradictory, or blocks valid work, do not edit YAAW to unblock yourself. Return `FRAMEWORK_INTEGRITY_VIOLATION`, `FRAMEWORK_INTEGRITY_UNKNOWN`, or `FRAMEWORK_CONTRACT_INCONSISTENCY` to Orchestrator with the exact evidence.