yaaw-se 0.3.3 → 0.3.4

package/dist/payload/yaaw-core/system/core/context-loading.md

@@ -3,16 +3,14 @@
 Load the smallest authoritative context needed for the current judgment.
 
 ## Progressive-disclosure invariant
-Workflow selection is metadata-first.
-
-A router may load its role contract, router workflow, workflow/execution registries, state/artifact metadata, and the minimum evidence needed to select one route. It must not preload sibling or downstream workflow bodies, their templates, or their expertise merely because they might be needed later.
+Workflow selection is metadata-first. Normal Orchestrator preparation is performed by `.yaaw-core/system/tools/orchestration-runtime.mjs`, which reads only durable metadata and the machine registries needed to produce one typed route/handoff. The Orchestrator consumes that result and **must not preload sibling or downstream workflow bodies**, templates, or expertise merely because they might be needed later.
 
 After exactly one workflow is selected:
 1. resolve that workflow through `.yaaw-core/system/registries/workflows.json`;
 2. load its body;
-3. load only its declared/current artifact references and applicable rules;
+3. load only handoff-declared/current artifact references and applicable rules;
 4. load selected expertise only after relevance is established;
-5. load a template only when the selected workflow is actually going to create that artifact.
+5. load a template only when the selected workflow will create that artifact.
 
 After durable output, return to routing before opening another workflow contract.
 
@@ -44,9 +42,15 @@ role contract
 Do not automatically load every PRD revision, research artifact, ticket, review, expertise module, template, or the full repository.
 
 ## Canonical artifact discovery
-Exact YAAW reads come from the handoff/registries. Roles do not grep for alternate YAAW artifact locations. Repository/application exploration is allowed only when the selected workflow admits it.
+Exact YAAW reads come from the deterministic handoff and registries. Roles do not grep for alternate YAAW artifact locations.
 
 ## Handoff freshness
-A handoff names exact artifact paths/revisions, read/write sets, selected expertise, repository requirement, observed repository basis, and transition sequence. Before executing it, verify those bases still match current reality. If they do not, discard the stale handoff and re-enter orchestration inspection.
+A handoff binds exact artifact revisions, read/write sets, selected expertise, repository requirement, canonical repository identity, transition sequence, installed YAAW version, installation/project-state schema versions, and manifest digest.
+
+Immediately before dispatch, run:
+
+```text
+node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --check-handoff
+```
 
-Runtime handoffs, intent, and observed-state snapshots live under `.yaaw-core/runtime/`; they are coordination caches, not semantic sources of truth.
+Only `HANDOFF_FRESH` may execute. A stale result discards the handoff and returns to orchestration preparation. Runtime handoffs, intent, and observed-state snapshots are coordination caches, not semantic sources of truth.

package/dist/payload/yaaw-core/system/core/dispatch-execution.md

@@ -14,7 +14,7 @@ Dispatch is a semantic request to execute exactly one already-selected YAAW hand
 9. The worker returns only a legal typed result from the handoff/workflow contract.
 10. A worker message is an execution signal, not project truth.
 11. After worker completion, failure, interruption, or lost response, Orchestrator re-enters `orchestration.inspect-state` before selecting another semantic workflow.
-12. If isolated execution is unavailable, the active host adapter applies its configured fallback policy.
+12. If the preferred execution mechanism is unavailable, the active host adapter may use an alternate mechanism only when it can preserve the configured effective authority execution profile; otherwise dispatch fails closed.
 
 ## Direct invocation
 A user who directly invokes PRD, Planner, Implementer, or Reviewer has intentionally selected that role/workflow and may execute it in the current context. Isolation policy here governs **Orchestrator dispatch**, not the existence of direct public entrypoints.
@@ -22,7 +22,7 @@ A user who directly invokes PRD, Planner, Implementer, or Reviewer has intention
 ## Execution-context policy
 `.yaaw-core/system/registries/execution-policy.json` declares one of:
 - `ROOT_ONLY`: run in the active root Orchestrator context.
-- `ISOLATED_PREFERRED`: prefer a fresh worker; host fallback may run inline.
+- `ISOLATED_PREFERRED`: prefer a fresh worker; host fallback may run through another mechanism only when the adapter establishes execution-profile equivalence. A deliberately selected host `inline` mode is an explicit opt-out from per-role isolation.
 - `INLINE_ALLOWED`: current-context execution is explicitly acceptable.
 
 A future `ISOLATED_REQUIRED` value may be introduced only with a schema/version update. Host adapters may still expose a stricter local runtime mode that blocks instead of falling back.
@@ -45,5 +45,21 @@ Legal workflow results such as `REPAIR`, `REPLAN`, `BLOCKED`, or a real precondi
 
 When a configured threshold is reached, the next attempt may use the host's stronger fallback execution profile while preserving the exact role and handoff. The fallback receives one attempt on an unchanged basis. If that attempt also fails with no progress, stop with `BLOCKED:AUTHORITY_EXECUTION_FAILED` rather than entering an unbounded retry loop.
 
+## Authority execution profile fidelity invariant
+A host adapter owns provider/model execution selection, but it may not silently substitute a different effective authority profile.
+
+- The canonical handoff remains provider-neutral: role, workflow, artifacts, basis, and allowed results do not carry provider model identifiers.
+- Before dispatch, the adapter resolves the required effective execution profile for the selected authority and, when applicable, the configured capability-fallback variant.
+- Changing named worker -> generic worker is legal only when the generic path is already profile-equivalent or every mismatched profile dimension can be authoritatively corrected by the active spawn mechanism.
+- Changing worker -> inline execution is legal only when the current/root execution profile is provably equivalent to the required authority profile. A user-selected host inline mode is the explicit exception because it deliberately opts out of per-role model isolation.
+- Model and reasoning dimensions are compared independently. A matching dimension needs no override; a mismatched dimension requires an authoritative override for that dimension.
+- Unknown inherited values remain symbolic. The adapter may treat two paths as equivalent when both resolve through the same `HOST_INHERIT` chain, but it must never guess that a concrete value equals an unknown inherited value.
+- If isolation exists but the host cannot guarantee the configured model/reasoning profile, stop with `BLOCKED:HOST_EXECUTION_PROFILE_UNAVAILABLE`.
+- If strict isolation is required and the host cannot create any isolated worker at all, stop with `BLOCKED:HOST_ISOLATION_UNAVAILABLE`.
+- A profile/isolation stop that occurs before child creation is a host precondition failure, not an authority execution failure. It must not increment `.yaaw-core/runtime/dispatch-failures.json` or trigger capability escalation.
+- Capability fallback uses the same resolver and fidelity rules as primary execution. If fallback selects a stronger profile, that exact effective profile must be preserved or dispatch blocks.
+
+The Orchestrator may route a configured profile through the adapter; it may not invent, weaken, or replace that profile.
+
 ## Provider boundary
 This contract is provider-neutral. Names of host tools, agent types, provider directories, model identifiers, and provider-specific spawning schemas belong only to integration adapters.

package/dist/payload/yaaw-core/system/core/execution-context.md

@@ -1,16 +1,15 @@
 # Execution context
 
 ## Purpose
-Define the runtime boundary for every YAAW workflow so provider shell state, ambient working directory, and repository layout cannot silently change semantic behavior.
+Define one runtime boundary for every YAAW workflow so ambient shell state and provider layout cannot silently change semantics.
 
 ## Canonical workspace root
 The **workspace root** is the consumer directory that owns the active YAAW installation. Resolve it before repository or application inspection by walking from the provider's current location toward ancestors until `.yaaw-core/install/manifest.json` is found. During recovery of a damaged installation, `.yaaw-core/system/registries/paths.json` may be used as a fallback marker.
 
-The process current working directory is never authoritative. `.yaaw-core/project/` is the **project memory root**, not the workspace root.
+The process CWD is never authoritative. `.yaaw-core/project/` is project memory, not the workspace root.
 
 ## Framework integrity
-
-After resolving the workspace and before semantic project recovery, run:
+After resolving the workspace and before semantic project recovery, run only the canonical package-owned integrity gate:
 
 ```text
 node .yaaw-core/system/tools/framework-integrity.mjs --workspace <WORKSPACE_ROOT>
@@ -18,36 +17,45 @@ node .yaaw-core/system/tools/framework-integrity.mjs --workspace <WORKSPACE_ROOT
 
 Only `HEALTHY` permits semantic routing. Package drift, missing framework files, local framework overrides, or an invalid manifest produce a typed framework stop and invalidate executable handoffs. Orchestrator reports the condition; it never repairs package-managed files itself.
 
-## Repository capability
-Repository capability is observed independently from workflow semantics:
+There is no second framework-integrity implementation outside `.yaaw-core/system/tools/`.
+
+## Deterministic orchestration preparation
+Normal Orchestrator routing uses one deterministic preparation entrypoint:
+
+```text
+node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT>
+```
 
-- `READY`: Git is available and the workspace is inside a repository; trustworthy identity can be computed.
-- `UNVERSIONED`: the workspace is valid but is not inside a Git repository.
-- `UNAVAILABLE`: Git cannot be executed or repository inspection is prohibited by the host.
-- `ROOT_MISMATCH`: repository ownership cannot be reconciled safely with the resolved workspace.
-- `IDENTITY_FAILED`: a repository exists but exact identity cannot be established.
+That one invocation performs the framework gate, canonical repository identity, durable metadata inspection, routing, and handoff construction from one basis. The Orchestrator consumes its typed result; it must not reimplement repository hashing, routing precedence, artifact discovery, or handoff serialization in ad-hoc shell/Python code.
 
-A raw Git failure is evidence to classify; it is never permission to continue as though repository identity succeeded.
+Compatibility/debug inspection may use `--inspect-only`. Dispatch freshness uses `--check-handoff` immediately before execution.
+
+## Repository capability
+- `READY`: repository exists and exact identity is trustworthy.
+- `UNVERSIONED`: valid workspace, no Git repository.
+- `UNAVAILABLE`: Git or host permission unavailable.
+- `ROOT_MISMATCH`: repository/workspace ownership cannot be reconciled.
+- `IDENTITY_FAILED`: repository exists but exact identity failed.
 
 ## Root-anchored command rule
-Every YAAW Git command is explicitly scoped to the resolved workspace:
+Every Git command is explicitly scoped:
 
 ```text
 git -C <WORKSPACE_ROOT> ...
 ```
 
-Never rely on ambient CWD for `git status`, `git diff`, `git log`, `git rev-parse`, or verification commands.
+When Git top-level is an ancestor, inspection and identity remain workspace-scoped with `-- .`; unrelated sibling changes must not contaminate the active workspace identity.
 
-When the Git top-level is an ancestor of the workspace, repository inspection and worktree hashing are path-scoped to the workspace using the equivalent of `-- .` from `git -C <WORKSPACE_ROOT>`. Unrelated sibling work in a monorepo must not automatically contaminate the workspace identity.
+## Canonical identity execution
+For repository identity, every semantic workflow invokes or consumes output originating from:
 
-## Workflow requirements
-The machine policy in `.yaaw-core/system/registries/execution-policy.json` assigns one repository requirement to every workflow:
+```text
+node .yaaw-core/system/tools/repository-identity.mjs --workspace <WORKSPACE_ROOT>
+```
 
-- `NONE`: repository capability is not a prerequisite.
-- `INSPECT`: inspect repository/workspace reality when available; `UNVERSIONED` is representable and does not by itself block the workflow.
-- `IDENTITY`: exact repository identity is mandatory; dispatch is blocked unless repository status is `READY`.
+No role or workflow may independently compute or reserialize `worktree_digest`. Copy the returned repository identity into state, handoff, evidence, and review records.
 
-PRD work normally uses `NONE`. Planning discovery uses `INSPECT`. Implementation, code review, and implementation recovery use `IDENTITY`.
+## Workflow requirements
+The machine policy in `.yaaw-core/system/registries/execution-policy.json` assigns one repository requirement to every workflow.
 
-## Provider invariant
-Provider adapters may point to this contract but must not duplicate it. Codex, Claude Code, Gemini CLI, and Cline all execute against the same workspace-root and repository-capability semantics.
+Provider adapters point to this contract; Codex, Claude Code, Gemini CLI, and Cline do not fork repository semantics.

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

@@ -1,17 +1,10 @@
 # Invalidation propagation
 
-Accepted artifacts are historical records, not eternally valid truth. When an upstream basis changes, preserve history and invalidate downstream trust explicitly.
+Accepted artifacts are historical records, not eternally valid truth. Prior reviews remain immutable historical evidence; current authority may become `STALE` without rewriting history.
 
-## Product revision change
-1. Increment `product.md` revision and record the changed requirement.
-2. Identify `ENG-*` decisions whose product provenance depends on the changed requirement.
-3. Mark affected decisions superseded/invalidated in `engineering.md`; move planning readiness to unresolved.
-4. Mark dependent specs `STALE` rather than rewriting them in place.
-5. Move dependent tickets, including prior `PASS` tickets when behavior is affected, to `REPLAN_REQUIRED` using the transition contract.
-6. Prior reviews remain immutable historical evidence but no longer establish current acceptance.
+## Permanent rule
 
-## Engineering decision change
-Apply the same propagation from affected `ENG-*` decisions -> specs -> tickets -> reviews.
+**A stale contract and stale acceptance are not the same thing.**
 
 ## Acceptance invalidation
 If product/engineering/spec/ticket meaning remains current but review or verification proof is missing, repository-stale, or cannot be reproduced, preserve historical reviews and reconcile current acceptance to `REVIEW_REQUIRED`.
@@ -23,5 +16,29 @@ Stable acceptance causes: `REVIEW_MISSING`, `REVIEW_REPOSITORY_STALE`, `VERIFICA
 ## Framework integrity is not project invalidation
 Package-managed framework drift is neither contract invalidation nor acceptance invalidation. It means the execution engine is untrusted. Stop orchestration with the typed framework failure and use installer repair. Do not route framework drift to Planner or Reviewer and do not change ticket lifecycle state to encode it.
 
-## No silent cascade
-Every invalidated artifact records why it became stale and which upstream revision/decision caused it. Never delete prior decisions/specs/reviews merely to make current state look clean.
+Result: `PASS -> REPLAN_REQUIRED`.
+
+Next semantic owner: Planner.
+
+### Acceptance invalidation
+The source contract remains current, but review or verification proof is missing, repository-stale, or cannot be reproduced under the canonical identity algorithm.
+
+Result: `PASS -> REVIEW_REQUIRED`.
+
+Next semantic owner: Reviewer.
+
+Repository identity mismatch alone does not establish `REPLAN_REQUIRED`. The Orchestrator may mechanically invalidate trust, but it must not decide that current code satisfies the contract or that architecture is invalid.
+
+Reviewer may then return `PASS`, `REPAIR`, `REPLAN`, or `BLOCKED`.
+
+## Stable cause IDs
+
+Contract causes: `PRODUCT_SOURCE_STALE`, `ENGINEERING_SOURCE_STALE`, `SPEC_SOURCE_STALE`, `TICKET_SOURCE_STALE`, `CONTRACT_INVALIDATED`.
+
+Acceptance causes: `REVIEW_MISSING`, `REVIEW_REPOSITORY_STALE`, `VERIFICATION_MISSING`, `VERIFICATION_REPOSITORY_STALE`, `LEGACY_IDENTITY_UNVERIFIABLE`.
+
+Every invalidation records a stable cause plus human-readable evidence. Runtime-looking paths are not automatically acceptance-irrelevant.
+
+## Framework integrity is not acceptance invalidation
+
+Package-managed framework drift is neither contract invalidation nor acceptance invalidation. It means the execution engine is not trusted. Stop orchestration with the typed framework failure and use installer repair. Do not route framework drift to Planner or Reviewer and do not change ticket lifecycle state to encode it.

package/dist/payload/yaaw-core/system/core/io-contract.md

@@ -37,6 +37,14 @@ Common results include `SUCCESS`, `READY`, `HUMAN_INPUT_REQUIRED`, `PRECONDITION
 
 Framework-level stop results are `FRAMEWORK_INTEGRITY_VIOLATION`, `FRAMEWORK_INTEGRITY_UNKNOWN`, and `FRAMEWORK_CONTRACT_INCONSISTENCY`. They are installation/runtime trust failures, not ticket lifecycle states, and must not be represented by fabricating a ticket transition.
 
+Host-execution stop results are `HOST_ISOLATION_UNAVAILABLE`, `HOST_EXECUTION_PROFILE_UNAVAILABLE`, and `AUTHORITY_EXECUTION_FAILED`. They describe execution transport/capability failures, not semantic workflow outcomes or ticket lifecycle states.
+
+- `HOST_ISOLATION_UNAVAILABLE`: strict isolation was required, but the host could not create an isolated worker.
+- `HOST_EXECUTION_PROFILE_UNAVAILABLE`: an execution mechanism existed, but the host could not guarantee the configured effective authority model/reasoning profile.
+- `AUTHORITY_EXECUTION_FAILED`: the correct authority execution actually started and failed under the bounded retry/fallback policy.
+
+A host isolation/profile stop raised before child creation is a pre-execution host failure: no authority worker ran, so it must not be counted as an authority execution failure.
+
 `PRECONDITION_UNSATISFIED` includes a reason such as `NO_PRODUCT`, `PLANNING_UNREADY`, `SPEC_MISSING`, `NO_READY_TICKET`, `STALE_SOURCE`, or `REPOSITORY_IDENTITY_UNAVAILABLE`.
 
 A missing ticket never authorizes Implementer to create one. Implementer returns `PRECONDITION_UNSATISFIED:NO_READY_TICKET`; Orchestrator routes Planner.

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

@@ -5,29 +5,24 @@ YAAW advances only through evidence-backed workflow boundaries.
 ```text
 product missing/unready -> PRD
 product ready, planning unresolved -> Planner
-planning frontier ready, spec missing -> create spec
+planning ready, spec missing -> create spec
 spec accepted, tickets missing -> create tickets
 READY -> Implementer
-IN_PROGRESS -> recover/continue only when evidence proves the boundary
+IN_PROGRESS -> recovery/continue
 REVIEW_REQUIRED -> Reviewer
-REPAIR_REQUIRED -> repair same ticket -> REVIEW_REQUIRED
+REPAIR_REQUIRED -> Implementer repair -> REVIEW_REQUIRED
 REPLAN_REQUIRED -> Planner
 PASS -> next admitted work
-frontier complete but accepted scope remains -> Planner reassesses frontier
-all accepted scope complete with fresh acceptance -> COMPLETE
+all accepted scope current -> COMPLETE
 ```
 
-## Fresh-context invariant
-Every workflow must be resumable from durable artifacts and repository evidence without previous chat history.
-
-## Admission invariant
-Implementation may begin only for a bounded `READY` ticket whose source spec/frontier is currently valid.
+## Accepted-but-stale
+A historical `PASS` whose source contract is still current but whose acceptance proof is stale becomes `REVIEW_REQUIRED`, not `REPLAN_REQUIRED`.
 
-## Acceptance invariant
-A ticket is accepted only by a fresh review tied to the exact repository identity and the current ticket/spec revisions.
+## PASS meaning
+`PASS` means the currently observed repository/worktree state satisfies the current accepted ticket contract according to an independent Reviewer.
 
-## Transition invariant
-Every state transition follows `core/transitions.md`, records provenance in `.yaaw-core/project/state.json`, and cites the evidence or artifact that justified it.
+It does not inherently mean committed, pushed, merged, or deployed. When accepted state is dirty, reporting must distinguish acceptance from persistence and disclose that the review basis is the current worktree.
 
-## Invalidation invariant
-Changed product intent or engineering decisions propagate through `core/invalidation.md`; historical artifacts are preserved but stale acceptance is never treated as current.
+## Fresh-context invariant
+Every workflow must be resumable from durable artifacts and repository evidence without previous chat history.

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

@@ -2,15 +2,15 @@
 
 Routing chooses exactly one next canonical workflow from observed reality. Explicit state beats broad heuristics. Workflow selection is metadata-first; target workflow bodies are loaded only after selection.
 
+The machine implementation of this precedence is `.yaaw-core/system/tools/orchestration-runtime.mjs`, driven by `.yaaw-core/system/registries/routing-policy.json`. Orchestrator consumes the tool's typed route instead of manually replaying the precedence with shell commands or model reasoning.
+
 Before any semantic routing, require framework integrity `HEALTHY` under `.yaaw-core/system/core/framework-integrity.md`. Framework drift is not repository drift and never routes to Planner, Implementer, or Reviewer. It stops execution until installer repair restores the package boundary.
 
 Before dispatch, enforce the selected workflow repository requirement from `.yaaw-core/system/registries/execution-policy.json`. `IDENTITY` workflows require repository status `READY`; `INSPECT` workflows may represent an `UNVERSIONED` workspace; `NONE` workflows do not require Git.
 
-The machine-readable precedence used by conformance tests lives in `.yaaw-core/system/registries/routing-policy.json`. This document explains the same semantics; CI must fail if the machine contract drifts from the workflow registry or lifecycle fixtures.
-
 ## Priority
 1. Stop on unhealthy/unknown framework integrity or canonical framework-contract inconsistency.
-2. Resolve material state inconsistency or incomplete recovery.
+2. Resolve material state inconsistency or incomplete recovery before creating a semantic handoff.
 3. If accepted product intent is missing or newly invalidated, route to PRD.
 4. If a ticket is `REPLAN_REQUIRED`, route to `planning.replan`.
 5. If current engineering frontier is unresolved, route through `planning.route`.
@@ -20,8 +20,8 @@ The machine-readable precedence used by conformance tests lives in `.yaaw-core/s
 9. If a ticket is `REVIEW_REQUIRED`, route to `review.review-ticket`.
 10. If a ticket is `IN_PROGRESS`, use recovery evidence to continue safely or reconcile to the next proven boundary; never restart blindly.
 11. If a dependency-satisfied ticket is `READY`, route to `implementation.implement-ticket`.
-12. If all current tickets are `PASS` but accepted product scope remains, route to `planning.route` for the next frontier.
-13. Declare `COMPLETE` only when accepted scope is covered by fresh, non-stale acceptance evidence.
+12. If all current tickets are `PASS`/`CANCELLED` but accepted product scope remains, route to `planning.route` for the next frontier.
+13. Declare `COMPLETE` only when the durable phase is complete and accepted scope is covered by fresh, non-stale acceptance evidence.
 
 ## Tie breaking
 - Never review a `REPAIR_REQUIRED` ticket before repair.
@@ -31,6 +31,6 @@ The machine-readable precedence used by conformance tests lives in `.yaaw-core/s
 - When evidence is insufficient to choose safely, route to recovery and ultimately `BLOCKED` rather than guessing.
 
 ## Conformance rule
-Behavioral fixtures may reconcile only transitions explicitly justified by durable/repository evidence. They must never make product or architecture decisions. The conformance oracle is test infrastructure, not a second runtime orchestrator.
+Behavioral fixtures and the deterministic runtime may reconcile/route only transitions explicitly justified by durable/repository evidence. They must never make product or architecture decisions.
 
-The Orchestrator selects the workflow; the target role owns semantic work inside it.
+The Orchestrator selects/consumes the route; the target role owns semantic work inside it.

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

@@ -1,6 +1,6 @@
 # State transition contract
 
-State names are not enough; only the transitions below are legal unless an explicit recovery rule documents a narrower evidence-backed exception.
+Only transitions represented by the machine registry are legal.
 
 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.
 
@@ -33,7 +33,4 @@ Repository identity mismatch alone does not establish `REPLAN_REQUIRED`.
 
 Forbidden examples: `DRAFT -> PASS`, `READY -> PASS`, `REPAIR_REQUIRED -> PASS`, or Implementer-authored `PASS`.
 
-## Project transitions
-Normal phase order is `product -> planning -> implementation -> complete`. `blocked` may be entered from any phase and exited only when its blocker is resolved. A new accepted product revision may move `complete` back to `product` or `planning`; historical completion evidence remains immutable.
-
-Every transition increments `transition_sequence` and writes `last_transition` in `.yaaw-core/project/state.json`.
+Every transition increments `transition_sequence` and records a stable cause plus evidence. Historical PASS reviews remain immutable even when their authority becomes stale.

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

@@ -0,0 +1,85 @@
+{
+  "schema": "yaaw.handoff-policy/v1",
+  "workflows": {
+    "prd.route": {
+      "desired_intent": "CONTINUE_PRODUCT",
+      "active_artifact": "product",
+      "reads": ["product", "state"],
+      "writes": ["product"],
+      "required_expertise": [],
+      "ticket_expertise": false,
+      "expected_output": "Current product intent or an explicit human-input/blocker result.",
+      "result_vocabulary": ["READY", "HUMAN_INPUT_REQUIRED", "BLOCKED"]
+    },
+    "planning.route": {
+      "desired_intent": "CONTINUE_PLANNING",
+      "active_artifact": "engineering",
+      "reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository"],
+      "writes": ["engineering", "engineering_research", "spec", "ticket", "project_rule"],
+      "required_expertise": [],
+      "ticket_expertise": false,
+      "expected_output": "Current engineering frontier readiness or one typed planning stop/result.",
+      "result_vocabulary": ["READY", "HUMAN_INPUT_REQUIRED", "REPLAN", "BLOCKED"]
+    },
+    "planning.create-spec": {
+      "desired_intent": "CREATE_SPEC",
+      "active_artifact": "engineering",
+      "reads": ["product", "engineering", "engineering_research", "project_rule", "repository"],
+      "writes": ["spec"],
+      "required_expertise": [],
+      "ticket_expertise": false,
+      "expected_output": "One accepted specification for the current frontier or a typed prerequisite/stop result.",
+      "result_vocabulary": ["SUCCESS", "PRECONDITION_UNSATISFIED", "BLOCKED"]
+    },
+    "planning.create-tickets": {
+      "desired_intent": "CREATE_TICKETS",
+      "active_artifact": "spec",
+      "reads": ["product", "engineering", "engineering_research", "spec", "project_rule", "repository"],
+      "writes": ["ticket"],
+      "required_expertise": [],
+      "ticket_expertise": false,
+      "expected_output": "Dependency-aware executable tickets for the accepted specification or a typed prerequisite/stop result.",
+      "result_vocabulary": ["SUCCESS", "PRECONDITION_UNSATISFIED", "BLOCKED"]
+    },
+    "planning.replan": {
+      "desired_intent": "REPLAN",
+      "active_artifact": "ticket",
+      "reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository"],
+      "writes": ["engineering", "engineering_research", "spec", "ticket", "project_rule"],
+      "required_expertise": [],
+      "ticket_expertise": true,
+      "expected_output": "Updated engineering contract and downstream admission state for the invalidated work.",
+      "result_vocabulary": ["READY", "HUMAN_INPUT_REQUIRED", "BLOCKED"]
+    },
+    "implementation.implement-ticket": {
+      "desired_intent": "IMPLEMENT",
+      "active_artifact": "ticket",
+      "reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository", "evidence", "review", "application_files"],
+      "writes": ["application_files", "evidence"],
+      "required_expertise": ["changeability"],
+      "ticket_expertise": true,
+      "expected_output": "Bounded implementation plus verification evidence and one legal lifecycle result.",
+      "result_vocabulary": ["REVIEW_REQUIRED", "REPLAN_REQUIRED", "PRECONDITION_UNSATISFIED", "BLOCKED"]
+    },
+    "implementation.repair-ticket": {
+      "desired_intent": "REPAIR",
+      "active_artifact": "ticket",
+      "reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository", "evidence", "review", "application_files"],
+      "writes": ["application_files", "evidence"],
+      "required_expertise": ["changeability"],
+      "ticket_expertise": true,
+      "expected_output": "Bounded repair plus fresh verification evidence and one legal lifecycle result.",
+      "result_vocabulary": ["REVIEW_REQUIRED", "REPLAN_REQUIRED", "BLOCKED"]
+    },
+    "review.review-ticket": {
+      "desired_intent": "REVIEW",
+      "active_artifact": "ticket",
+      "reads": ["product", "engineering", "engineering_research", "spec", "ticket", "project_rule", "repository", "evidence", "review", "application_files", "state"],
+      "writes": ["review"],
+      "required_expertise": ["testing", "changeability"],
+      "ticket_expertise": true,
+      "expected_output": "One immutable independent review round tied to the current contract and repository basis.",
+      "result_vocabulary": ["PASS", "REPAIR", "REPLAN", "BLOCKED"]
+    }
+  }
+}

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

@@ -1,23 +1,25 @@
 # Orchestrator role
 
 ## Authority
-Own continuity, workspace/repository reconstruction, evidence-backed reconciliation, invalidation coordination, and next-workflow routing.
+Own continuity, evidence-backed reconciliation, invalidation coordination, and next-workflow dispatch. Deterministic workspace/repository reconstruction, routing, and handoff serialization are delegated to the canonical runtime tool rather than improvised by the model.
 
 ## Boot sequence
 1. Resolve the YAAW workspace root using `.yaaw-core/system/core/execution-context.md`; never assume provider CWD.
-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. For Implementer/Reviewer execution failures, update or reset the replaceable dispatch-failure ledger only after confirming durable progress and the current handoff basis.
-11. Apply any configured host capability fallback only through `orchestration.dispatch`; never change semantic role or bypass fresh-context review independence.
-12. Repeat until a real stop condition.
+2. Execute `node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT>` exactly once for the current basis.
+3. Consume the typed result:
+   - `FRAMEWORK_STOP` -> report the typed framework failure/repair instruction and stop without lifecycle mutation;
+   - `RECONCILE_REQUIRED` -> execute only `orchestration.reconcile-state`, then run the deterministic preparation again;
+   - `ROOT_ACTION` -> execute the selected Orchestrator recovery workflow, then prepare again;
+   - `TERMINAL`/`BLOCKED` -> stop with that result;
+   - `DISPATCH_READY` -> use the persisted handoff exactly as produced.
+4. Do not independently recalculate worktree digests, grep for alternate artifact locations, replay routing precedence, or hand-serialize `observed-state.json`/`handoff.json`.
+5. Dispatch exactly one canonical workflow using `.yaaw-core/system/workflows/orchestration/dispatch.md`. The host adapter resolves the configured authority execution profile; Orchestrator never invents or substitutes provider/model settings.
+6. Permit a change of execution mechanism only through the host adapter and only when the adapter establishes execution-profile equivalence or authoritative per-dimension correction under the configured policy.
+7. After any worker completion, failure, interruption, or lost response, return to deterministic preparation before selecting another semantic workflow. For Implementer/Reviewer execution failures, update or reset the replaceable dispatch-failure ledger only after confirming durable progress and the current handoff basis. A pre-execution host isolation/profile stop never increments that ledger.
+8. Apply any configured host capability fallback only through `orchestration.dispatch`; preserve the exact semantic role/handoff and require the adapter to preserve the configured fallback profile.
+9. Repeat until a real stop condition.
 
 ## Boundary
-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.
+The Orchestrator is a traffic controller, not a super-agent. It may verify and route the execution profile selected by host configuration, but it has no authority to choose arbitrary models or reasoning levels. Framework 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.
+Child/worker text is not project truth. Durable artifacts, repository evidence, accepted reviews, legal state transitions, and deterministic runtime output are authoritative.

package/dist/payload/yaaw-core/system/rules/repository-identity.md

@@ -3,26 +3,40 @@
 Repository capability and repository identity are related but distinct.
 
 ## Capability
-Resolve the YAAW workspace root using `.yaaw-core/system/core/execution-context.md`, then inspect Git with root-anchored commands.
+Resolve the YAAW workspace root using `.yaaw-core/system/core/execution-context.md`, then inspect Git only through the canonical utility.
 
-Record one status:
-- `READY`: Git repository exists and exact workspace identity is trustworthy.
-- `UNVERSIONED`: workspace is valid but not versioned.
-- `UNAVAILABLE`: Git or required host permission is unavailable.
-- `ROOT_MISMATCH`: workspace/repository ownership cannot be reconciled safely.
-- `IDENTITY_FAILED`: repository exists but identity calculation failed.
+No semantic workflow may independently calculate `worktree_digest`. All repository identity used in handoff, verification, recovery, or review must originate from:
 
-Also record `workspace_scope`, `git_root_relation` (`same`, `ancestor`, `none`, or `unknown`), and a safe diagnostic in `error` when status is not `READY`.
+```text
+node .yaaw-core/system/tools/repository-identity.mjs --workspace <WORKSPACE_ROOT>
+```
 
-## Identity
-When status is `READY`, record `head_commit`, `dirty`, and `worktree_digest`.
+The tool emits machine-readable JSON on stdout, diagnostics on stderr, and exits non-zero when exact identity cannot be produced. The algorithm identifier is `yaaw-worktree-v2`. Roles and workflows **must not reimplement** it.
 
-Recommended digest inputs, always executed with `git -C <WORKSPACE_ROOT>`:
-1. `git status --porcelain=v1 -z -- .`;
-2. `git diff --binary HEAD -- .`;
-3. `git diff --cached --binary HEAD -- .`;
-4. sorted untracked paths inside the workspace scope and their byte hashes where accessible.
+## Canonical digest inputs
+All commands execute with `git -C <WORKSPACE_ROOT>` and remain workspace-scoped:
 
-When the Git top-level is an ancestor, unrelated sibling changes are outside the identity scope unless the active ticket explicitly includes them.
+1. `git status --porcelain=v1 -z --untracked-files=all -- . <control-output exclusions>`
+2. `git diff --binary --no-ext-diff --no-textconv HEAD -- . <control-output exclusions>`
+3. `git diff --cached --binary --no-ext-diff --no-textconv HEAD -- . <control-output exclusions>`
+4. `git ls-files --others --exclude-standard -z -- . <control-output exclusions>`
 
-If trustworthy identity cannot be produced for a workflow requiring `IDENTITY`, return a typed prerequisite/blocker rather than pretending the state is uniquely identified.
+Hash raw stdout bytes. Never hash stderr, warnings, timestamps, absolute paths, ambient CWD, PIDs, or hostnames.
+
+Untracked paths are slash-normalized and sorted. Regular files are hashed from exact bytes. Symlinks are hashed from their exact link-target representation. Unsupported or unreadable objects produce `IDENTITY_FAILED`; they are never silently omitted.
+
+The final digest is SHA-256 over stable canonical UTF-8 JSON containing algorithm, workspace-relative scope, HEAD, component hashes, the explicit exclusions, and the sorted untracked manifest.
+
+## Lifecycle-output exclusions
+`yaaw-worktree-v2` excludes only YAAW files whose normal lifecycle write would otherwise invalidate the repository basis that the file itself records:
+
+- `.yaaw-core/runtime/**` — replaceable observation/handoff/intent/failure caches;
+- `.yaaw-core/project/state.json` — Orchestrator lifecycle ledger;
+- `.yaaw-core/project/evidence/**` — immutable verification attestations;
+- `.yaaw-core/project/reviews/**` — immutable acceptance attestations.
+
+This prevents circular freshness: writing an observation, handoff, state transition, evidence record, or review cannot by itself make the implementation repository identity stale. These artifacts remain governed by their own schemas, revisions, immutability rules, transition sequence, and handoff references.
+
+The exclusion deliberately does **not** cover product, engineering, research, specs, tickets, project rules, `.yaaw-core/install/**`, package-managed `.yaaw-core/system/**`, application files, `.codex/`, `.agents/`, `.claude/`, `.gemini/`, `.cline/`, or other provider/project paths. Changes to those continue to change repository identity.
+
+When the Git top-level is an ancestor, unrelated sibling changes remain outside identity because all commands are scoped to the active workspace.

package/dist/payload/yaaw-core/system/schemas/evidence-v1.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "yaaw.evidence/v1",
+  "type": "object",
+  "required": ["schema","id","ticket","ticket_revision","spec_revision","kind","repository","workflow","commands","checks"],
+  "properties": {
+    "schema": {"const": "yaaw.evidence/v1"},
+    "id": {"type": "string"},
+    "ticket": {"type": "string", "pattern": "^TASK-[0-9]+$"},
+    "ticket_revision": {"type": "integer", "minimum": 0},
+    "spec_revision": {"type": "integer", "minimum": 0},
+    "kind": {"type": "string"},
+    "repository": {
+      "type": "object",
+      "required": ["head_commit","dirty","worktree_digest"],
+      "properties": {
+        "head_commit": {"type": ["string","null"]},
+        "dirty": {"type": ["boolean","null"]},
+        "worktree_digest": {"type": ["string","null"]}
+      },
+      "additionalProperties": false
+    },
+    "workflow": {"type": "string"},
+    "commands": {"type": "array"},
+    "checks": {"type": "array"}
+  },
+  "additionalProperties": false
+}

package/dist/payload/yaaw-core/system/schemas/evidence-v2.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "yaaw.evidence/v2",
+  "type": "object",
+  "required": ["schema","id","ticket","ticket_revision","spec_revision","kind","repository","workflow","commands","checks"],
+  "properties": {
+    "schema": {"const": "yaaw.evidence/v2"},
+    "id": {"type": "string"},
+    "ticket": {"type": "string", "pattern": "^TASK-[0-9]+$"},
+    "ticket_revision": {"type": "integer", "minimum": 0},
+    "spec_revision": {"type": "integer", "minimum": 0},
+    "kind": {"type": "string"},
+    "repository": {"$ref": "repository-identity.schema.json"},
+    "workflow": {"type": "string"},
+    "commands": {"type": "array"},
+    "checks": {"type": "array"}
+  },
+  "additionalProperties": false
+}