yaaw-se 0.3.11 → 0.3.13

package/dist/payload/payload.json

@@ -1,4 +1,4 @@
 {
   "schema": "yaaw.payload/v1",
-  "version": "0.3.11"
+  "version": "0.3.13"
 }

package/dist/payload/skills/yaaw-create-spec/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-create-spec
-description: Create the next YAAW specification from an engineering frontier whose readiness is currently PASS.
+description: Create the next specification from a ready YAAW engineering frontier.
 ---
 # yaaw-create-spec
 ROLE: `planner`
 WORKFLOW: `planning.create-spec`
 INTENT: `CREATE_SPEC`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-create-spec`
-
-Follow `orchestration.route` until `CURRENT_SPEC_ACCEPTED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute planner semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-create-spec` and follow Orchestrator routing until `CURRENT_SPEC_ACCEPTED`, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-create-ticket/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-create-ticket
-description: Create bounded YAAW implementation ticket contracts from the current accepted specification.
+description: Create bounded implementation tickets from the current accepted YAAW specification.
 ---
 # yaaw-create-ticket
 ROLE: `planner`
 WORKFLOW: `planning.create-tickets`
 INTENT: `CREATE_TICKETS`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-create-ticket`
-
-Follow `orchestration.route` until `CURRENT_TICKETS_REGISTERED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute planner semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-create-ticket` and follow Orchestrator routing until `CURRENT_TICKETS_REGISTERED`, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-create-tickets/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-create-tickets
-description: Create dependency-aware bounded YAAW implementation tickets from the current accepted specification.
+description: Create dependency-aware bounded implementation tickets from the current accepted YAAW specification.
 ---
 # yaaw-create-tickets
 ROLE: `planner`
 WORKFLOW: `planning.create-tickets`
 INTENT: `CREATE_TICKETS`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-create-tickets`
-
-Follow `orchestration.route` until `CURRENT_TICKETS_REGISTERED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute planner semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-create-tickets` and follow Orchestrator routing until `CURRENT_TICKETS_REGISTERED`, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-implement/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-implement
-description: Implement one admitted READY YAAW ticket and produce repository-identity-bound verification evidence.
+description: Implement one admitted READY ticket and produce repository-identity-bound verification evidence.
 ---
 # yaaw-implement
 ROLE: `implementer`
 WORKFLOW: `implementation.implement-ticket`
 INTENT: `IMPLEMENT`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-implement`
-
-Follow `orchestration.route` until `TICKET_REVIEW_REQUIRED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute implementer semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-implement` and follow Orchestrator routing until the selected ticket is `REVIEW_REQUIRED`, BLOCKED, or a framework stop occurs.

package/dist/payload/skills/yaaw-orchestrator/SKILL.md

@@ -7,8 +7,7 @@ ROLE: `orchestrator`
 WORKFLOW: `orchestration.route`
 INTENT: `CONTINUE`
 
-## Execute
 Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-orchestrator`
+`node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-orchestrator`
 
-Follow `orchestration.route` until `CONTINUE_UNTIL_STOP` is satisfied or a human-input, BLOCKED, or framework stop occurs. A `FRAMEWORK_STOP` is terminal for the current invocation: report it once and do not re-run the unchanged runtime unless the installation version, manifest, or managed framework bytes have changed. Do not execute orchestrator semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Follow the Orchestrator `route` operation until `CONTINUE_UNTIL_STOP` is satisfied or a human-input, BLOCKED, terminal, or framework stop occurs. Never execute semantic worker authority directly from this wrapper; every worker execution uses the exact fresh runtime handoff.

package/dist/payload/skills/yaaw-planner/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-planner
-description: Continue repository-backed YAAW engineering planning, challenge material technical assumptions, and advance decisions, readiness, specifications, or tickets.
+description: Continue repository-backed YAAW engineering planning.
 ---
 # yaaw-planner
 ROLE: `planner`
 WORKFLOW: `planning.route`
 INTENT: `CONTINUE_PLANNING`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-planner`
-
-Follow `orchestration.route` until `PLANNING_READY` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute planner semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-planner` and follow Orchestrator routing until `PLANNING_READY`, human input, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-planning-review/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-planning-review
-description: Freshly assess whether the current YAAW engineering frontier is ready for implementation without material invention.
+description: Assess whether the current engineering frontier is implementable without material invention.
 ---
 # yaaw-planning-review
 ROLE: `planner`
 WORKFLOW: `planning.readiness-review`
 INTENT: `PLANNING_REVIEW`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-planning-review`
-
-Follow `orchestration.route` until `PLANNING_READINESS_DECIDED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute planner semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-planning-review` and follow Orchestrator routing until `PLANNING_READINESS_DECIDED`, human input, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-prd/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-prd
-description: Create or continue YAAW product definition, challenge material product assumptions, and route clarification or revision work.
+description: Create or continue YAAW product definition and route clarification or revision work.
 ---
 # yaaw-prd
 ROLE: `prd`
 WORKFLOW: `prd.route`
 INTENT: `CONTINUE_PRODUCT`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-prd`
-
-Follow `orchestration.route` until `PRODUCT_READY` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute prd semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-prd` and follow Orchestrator routing until `PRODUCT_READY`, human input, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-refine-prd/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-refine-prd
-description: Improve clarity and completeness of a YAAW product artifact without changing accepted product meaning.
+description: Improve product clarity without changing accepted meaning.
 ---
 # yaaw-refine-prd
 ROLE: `prd`
 WORKFLOW: `prd.refine`
 INTENT: `REFINE_PRODUCT`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-refine-prd`
-
-Follow `orchestration.route` until `PRODUCT_REFINED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute prd semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-refine-prd` and follow Orchestrator routing until `PRODUCT_REFINED`, human input, BLOCKED, or framework stop.

package/dist/payload/skills/yaaw-repair/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-repair
-description: Repair a YAAW ticket in REPAIR_REQUIRED state while preserving its accepted product and engineering contract.
+description: Repair one ticket in REPAIR_REQUIRED while preserving the accepted YAAW contract.
 ---
 # yaaw-repair
 ROLE: `implementer`
 WORKFLOW: `implementation.repair-ticket`
 INTENT: `REPAIR`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-repair`
-
-Follow `orchestration.route` until `TICKET_REVIEW_REQUIRED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute implementer semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-repair` and follow Orchestrator routing until the selected ticket returns to `REVIEW_REQUIRED`, BLOCKED, or a framework stop occurs.

package/dist/payload/skills/yaaw-review/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-review
-description: Independently review actual YAAW implementation and classify PASS, REPAIR, REPLAN, or BLOCKED against current evidence.
+description: Independently review implementation and classify PASS, REPAIR, REPLAN, or BLOCKED.
 ---
 # yaaw-review
 ROLE: `reviewer`
 WORKFLOW: `review.review-ticket`
 INTENT: `REVIEW`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-review`
-
-Follow `orchestration.route` until `TICKET_REVIEW_APPLIED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute reviewer semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-review` and follow Orchestrator routing until the selected review result is applied, BLOCKED, or a framework stop occurs.

package/dist/payload/skills/yaaw-revise-prd/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: yaaw-revise-prd
-description: Change accepted YAAW product intent and invalidate downstream engineering contracts whose basis became stale.
+description: Change accepted YAAW product intent and invalidate stale downstream contracts.
 ---
 # yaaw-revise-prd
 ROLE: `prd`
 WORKFLOW: `prd.revise`
 INTENT: `REVISE_PRODUCT`
 
-## Execute
-Resolve the YAAW workspace root, then invoke:
-`node .yaaw-core/system/tools/orchestration-runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-revise-prd`
-
-Follow `orchestration.route` until `PRODUCT_REVISION_ADVANCED` is satisfied or a human-input, BLOCKED, or framework stop occurs. Do not execute prd semantics directly from this wrapper; every semantic execution requires the exact runtime handoff.
+Invoke `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT> --invoke-skill yaaw-revise-prd` and follow Orchestrator routing until `PRODUCT_REVISION_ADVANCED`, human input, BLOCKED, or framework stop.

package/dist/payload/yaaw-core/registries/skills.json

@@ -0,0 +1,38 @@
+{
+  "yaaw-orchestrator": {
+    "description": "Continue or recover by reconstructing reality and dispatching the next safe workflow."
+  },
+  "yaaw-prd": {
+    "description": "Create or continue product definition."
+  },
+  "yaaw-revise-prd": {
+    "description": "Change accepted product intent and invalidate stale downstream contracts."
+  },
+  "yaaw-refine-prd": {
+    "description": "Improve product clarity without changing accepted meaning."
+  },
+  "yaaw-planner": {
+    "description": "Continue repository-backed engineering planning."
+  },
+  "yaaw-planning-review": {
+    "description": "Assess current engineering-frontier readiness."
+  },
+  "yaaw-create-spec": {
+    "description": "Create the next specification from a ready frontier."
+  },
+  "yaaw-create-ticket": {
+    "description": "Create bounded implementation tickets."
+  },
+  "yaaw-create-tickets": {
+    "description": "Create dependency-aware bounded implementation tickets."
+  },
+  "yaaw-implement": {
+    "description": "Implement one READY ticket and produce verification evidence."
+  },
+  "yaaw-repair": {
+    "description": "Repair one REPAIR_REQUIRED ticket."
+  },
+  "yaaw-review": {
+    "description": "Independently review implementation and classify its result."
+  }
+}

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

@@ -0,0 +1,121 @@
+# YAAW system kernel
+
+YAAW is an autonomous software-engineering workflow with one compact rule: **persist semantic facts once and derive coordination state**.
+
+## Mental model
+
+Agents are disposable. Artifacts are durable. A fresh context must be able to continue from repository and YAAW artifacts without depending on the original conversation.
+
+There are five semantic authorities:
+
+- **PRD** owns product meaning: goals, users, behavior, scope, constraints, and non-goals.
+- **Planner** owns engineering meaning: repository understanding, architecture decisions, research admission, readiness, specifications, and ticket contracts.
+- **Implementer** owns application changes and implementation evidence for one admitted ticket.
+- **Reviewer** owns independent acceptance and the semantic result `PASS`, `REPAIR`, `REPLAN`, or `BLOCKED`.
+- **Orchestrator** owns observation, deterministic routing, lifecycle adoption, recovery, and dispatch. It never invents product, engineering, implementation, research, or acceptance decisions.
+
+`kernel.yaml` is the machine-readable contract. The role documents contain the human-readable workflow operations. Modules are optional expertise loaded only after routing.
+
+## One authority per fact
+
+| Fact | Canonical location |
+| --- | --- |
+| Product requirement or accepted product decision | `.yaaw-core/project/product.md` |
+| Engineering decision / frontier / readiness | `.yaaw-core/project/engineering.md` |
+| Bounded external research | `.yaaw-core/project/research/RSH-*.md` |
+| Feature implementation contract | `.yaaw-core/project/specs/SPEC-*.md` |
+| Executable work unit and its lifecycle status | `.yaaw-core/project/tickets/TASK-*.md` |
+| Implementation proof | `.yaaw-core/project/evidence/*.json` |
+| Acceptance judgment | `.yaaw-core/project/reviews/TASK-*-R*.md` |
+| Reusable project-local invariant | `.yaaw-core/project/rules/*.md` |
+| Current user intent / observation / handoff / dispatch failures | `.yaaw-core/runtime/*` |
+| Package ownership and integrity | `.yaaw-core/install/manifest.json` |
+
+There is no durable global `state.json`, `memory.md`, conversation log, role summary, or project summary. Product, engineering, specs, tickets, evidence, and reviews **are** project memory.
+
+Store conclusions, not cognition. Never persist `User said...`, question transcripts, debate history, or a summary merely because another worker needs context. Reference artifact/decision IDs instead of copying upstream history.
+
+## Durable truth versus derived coordination
+
+Ticket frontmatter `status` is the canonical lifecycle state for that ticket. Product and engineering frontmatter carry their own status/revision/readiness metadata. The active accepted specification is derived from current accepted spec metadata. Project completion is derived from current ticket statuses plus Planner-owned `scope_status`.
+
+`.yaaw-core/runtime/` is replaceable coordination. `intent.json`, `observed-state.json`, `handoff.json`, and dispatch-failure data may be deleted at any time. The next orchestration invocation must reconstruct the same safe next action from durable artifacts and repository evidence. Runtime deletion must never lose a semantic decision.
+
+Lifecycle transitions remain constrained by `kernel.yaml`. When Implementer evidence or Reviewer output authorizes a transition, Orchestrator may update only the ticket frontmatter `status` scalar after deterministic validation. That physical write does not transfer the semantic authority that produced the evidence.
+
+Planner may directly create/revise ticket contracts and owns Planner-authorized lifecycle states such as `DRAFT`, `READY`, `REPLAN_REQUIRED`, and `CANCELLED` where the lifecycle contract permits them. A status-only admission change does not require a ticket revision bump; a semantic contract change does.
+
+## Artifact-writing rules
+
+- Markdown artifacts use YAML frontmatter for schema/identity/revision/status metadata and Markdown for durable reasoning.
+- Prefer concise durable facts over duplicated upstream content.
+- Product language stays product-focused; engineering decisions stay in engineering artifacts.
+- Distinguish repository observations from assumptions.
+- Record provenance for material product, engineering, repository, research, evidence, and review dependencies.
+- Reviews and implementation evidence are immutable rounds/records. Never rewrite failed evidence or prior reviews into success.
+- Preserve superseded/stale artifacts as history; invalidate authority rather than erasing the record.
+- A fresh context unable to continue from artifacts indicates incomplete durable documentation.
+
+## Execution and progressive disclosure
+
+Resolve the workspace root as the consumer directory containing `.yaaw-core/install/manifest.json`. Package-managed `.yaaw-core/system/**` is immutable during semantic work; only installer/update/repair may replace it.
+
+Normal orchestration invokes:
+
+```text
+node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT>
+```
+
+Public skills use the same command with `--invoke-skill <skill-id>`.
+
+Routing is metadata-first. Before exactly one workflow is selected, do not load sibling workflow operations, unrelated role documents, downstream workflow bodies, or optional modules. A dispatched worker receives only:
+
+1. this system contract as needed;
+2. its role document and selected operation;
+3. the exact artifact references in the handoff;
+4. selected optional modules; and
+5. minimal relevant application/repository context.
+
+Workers never privately command or spawn peer YAAW authorities. After every worker result, failure, interruption, or disappearance, Orchestrator discards worker prose as authority and observes durable reality again.
+
+## Framework integrity
+
+Before semantic routing, verify the installer manifest and package-managed system bytes. `MODIFIED`, `MISSING`, `LOCAL_OVERRIDE`, unknown integrity, or contract inconsistency fails closed. Semantic workers never edit `.yaaw-core/system/**` to unblock themselves.
+
+Dispatch completeness is a framework invariant. A worker dispatch target is the union of non-Orchestrator public-skill requests, deterministic router targets (the values used by router branches), and declared worker handoffs. Other role operations are internal suboperations; root Orchestrator operations do not require worker handoffs. Every target must resolve a workflow, owning role, valid handoff, role-bounded reads/writes, active artifact, authorized existing modules, and the typed worker result protocol. Public skill metadata and completion vocabulary must agree with the kernel. `engine/contracts.mjs` is the canonical validator used by core, distribution, payload generation/verification, and runtime. Missing contracts stop as framework defects, never consumer semantic blockers.
+
+Product revision changes the downstream product basis. Orchestrator derives stale ticket authority and performs only legal status reconciliation; Planner owns changed downstream contracts. Engineering readiness based on an older product revision cannot authorize a specification. Clarity-only product refinement preserves semantic revision and downstream source authority.
+
+## Repository identity
+
+Repository identity is produced only by `.yaaw-core/system/engine/repository-identity.mjs`; roles do not reimplement it. Runtime caches, ticket lifecycle files, immutable implementation evidence, and immutable reviews are excluded from the application worktree digest because their normal lifecycle writes would otherwise invalidate their own basis. Ticket semantic freshness is instead bound explicitly by ticket revision and ticket content digest in handoffs/evidence/reviews.
+
+Exact repository identity is required for executable tickets, implementation, repair, and review. Unversioned projects may be inspected for planning but cannot claim executable identity-dependent admission.
+
+## Assumption challenge and questions
+
+PRD and Planner challenge only material assumptions that could change intent, architecture, readiness, scope, failure behavior, or implementation. Establish inspectable facts before asking the human. Do not ask repository-answerable questions. Respect decision dependencies and the current frontier; future-dependent issues remain future fog.
+
+Ask at most 10 meaningful questions per round; the maximum is not a target and zero is valid. Options and a recommendation are useful when they expose a real tradeoff, but free-form answers remain first-class. Record accepted conclusions before another question round, then recompute the frontier and downstream invalidation.
+
+PRD never chooses engineering implementation unless the human explicitly made a method a product constraint. Planner never invents product meaning and resolves routine reversible engineering choices it owns.
+
+## Research admission
+
+Vendor/framework/package/platform research is allowed only when justified by observed repository technology, an accepted product constraint, an accepted `ENG-*` decision, or an explicit current-frontier candidate. Tool or host-skill availability is never an architectural reason. Prefer primary sources and record version/date for version-sensitive facts. Persist only bounded material research that blocks a current decision; do not research future fog.
+
+## Changeability
+
+Planner, Implementer, and Reviewer apply the mandatory principle: **make the next correct change easier without expanding the current authorized change**. Keep the main path visible, name by domain meaning, contain external systems behind boundaries, make invalid states harder to represent, separate important decisions from side effects, make failures useful without exposing secrets, and keep changes focused. A preference is not a defect; blocking findings require concrete engineering impact.
+
+## Ticket sizing
+
+A ticket is correctly sized when one fresh Implementer can complete one coherent engineering change and verify a concrete outcome without inventing material product or architecture decisions. Avoid both multi-subsystem rediscovery tickets and bookkeeping-only fragments.
+
+## Review independence
+
+Reviewer evaluates actual repository work, not Implementer summaries. Every review is tied to exact repository identity, ticket/spec revisions, and current PASS verification evidence. Reviewer must execute in a semantically independent fresh authority context from the Implementer when the host supports it; host fallback never removes the independence requirement. Reviewer may classify `REPLAN`, but Planner owns contract changes.
+
+## Recovery
+
+Evidence beats claims. Use current artifact revisions/content, repository identity, implementation evidence, and reviews to identify the last trustworthy boundary. Never rerun full implementation merely because a response disappeared. If the boundary cannot be proven, preserve evidence and return an exact blocker rather than destructive re-execution.

package/dist/payload/yaaw-core/system/engine/contracts.mjs

@@ -0,0 +1,147 @@
+import { readFile, lstat, realpath } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, join } from 'node:path';
+// The router uses these values at each branch; there is no separate target inventory.
+export const ROUTES = Object.freeze({product:'prd.route',planning:'planning.route',spec:'planning.create-spec',tickets:'planning.create-tickets',replan:'planning.replan',repair:'implementation.repair-ticket',review:'review.review-ticket',verify:'implementation.verify-ticket',implement:'implementation.implement-ticket'});
+export const ROUTER_DISPATCH_TARGETS = Object.freeze([...new Set(Object.values(ROUTES))]);
+// Typed worker outcomes consumed by the host continuation/lifecycle protocol.
+const RESULTS = {
+  'prd.route':['READY','HUMAN_INPUT_REQUIRED','BLOCKED'],
+  'prd.revise':['READY','HUMAN_INPUT_REQUIRED','BLOCKED'],
+  'prd.refine':['READY','HUMAN_INPUT_REQUIRED','BLOCKED'],
+  'planning.route':['READY','HUMAN_INPUT_REQUIRED','REPLAN','BLOCKED'],
+  'planning.readiness-review':['PASS','MISSING_DECISIONS','PRODUCT_GAP','REPLAN','BLOCKED'],
+  'planning.create-spec':['SUCCESS','PRECONDITION_UNSATISFIED','BLOCKED'],
+  'planning.create-tickets':['SUCCESS','PRECONDITION_UNSATISFIED','BLOCKED'],
+  'planning.replan':['READY','HUMAN_INPUT_REQUIRED','BLOCKED'],
+  'implementation.implement-ticket':['VERIFICATION_PASS','VERIFICATION_FAIL','REPLAN_REQUIRED','PRECONDITION_UNSATISFIED','BLOCKED'],
+  'implementation.verify-ticket':['VERIFICATION_PASS','VERIFICATION_FAIL','IMPLEMENTATION_INCOMPLETE','REPLAN_REQUIRED','BLOCKED'],
+  'implementation.repair-ticket':['VERIFICATION_PASS','VERIFICATION_FAIL','REPLAN_REQUIRED','BLOCKED'],
+  'review.review-ticket':['PASS','REPAIR','REPLAN','BLOCKED']
+};
+// A shortcut's completion must describe the operation it actually requests.
+const INTENTS = {
+  CONTINUE:['orchestration.route','CONTINUE_UNTIL_STOP'],
+  CONTINUE_PRODUCT:['prd.route','PRODUCT_READY'],
+  REVISE_PRODUCT:['prd.revise','PRODUCT_REVISION_ADVANCED'],
+  REFINE_PRODUCT:['prd.refine','PRODUCT_REFINED'],
+  CONTINUE_PLANNING:['planning.route','PLANNING_READY'],
+  PLANNING_REVIEW:['planning.readiness-review','PLANNING_READINESS_DECIDED'],
+  CREATE_SPEC:['planning.create-spec','CURRENT_SPEC_ACCEPTED'],
+  CREATE_TICKETS:['planning.create-tickets','CURRENT_TICKETS_REGISTERED'],
+  IMPLEMENT:['implementation.implement-ticket','TICKET_REVIEW_REQUIRED'],
+  REPAIR:['implementation.repair-ticket','TICKET_REVIEW_REQUIRED'],
+  REVIEW:['review.review-ticket','TICKET_REVIEW_APPLIED']
+};
+export function dispatchableWorkflows(kernel) {
+  return new Set([...ROUTER_DISPATCH_TARGETS,...Object.values(kernel.skills??{}).filter(s=>s.role!=='orchestrator').map(s=>s.requested_workflow),...Object.keys(kernel.handoffs??{})]);
+}
+const managedPath=p=>typeof p==='string'&&p.startsWith('.yaaw-core/system/')&&!p.includes('\\')&&!p.split('/').includes('..')&&p.endsWith('.md');
+async function managedFile(system,path) {
+  if(!managedPath(path))throw new Error(`invalid managed system reference ${path}`);
+  const target=resolve(system,path.slice('.yaaw-core/system/'.length)),root=await realpath(system),actual=await realpath(target),rel=relative(root,actual);
+  if(rel.startsWith('..')||isAbsolute(rel)||!(await lstat(target)).isFile())throw new Error(`invalid managed system file ${path}`);
+  return target;
+}
+const operationHeader=(id,w)=>`## Operation: ${w.operation} (\`${id}\`)`;
+export async function validateDispatchFiles(system,k,workflow,expertise=[]) {
+  const paths=[k.roles[k.workflows[workflow]?.role]?.document,...expertise],errors=[];
+  for(const path of paths)try{await managedFile(system,path)}catch{errors.push(`${workflow}: missing/invalid dispatch file ${path}`)}
+  const w=k.workflows[workflow];
+  try{const text=await readFile(await managedFile(system,k.roles[w.role].document),"utf8");if(!text.includes(operationHeader(workflow,w)))errors.push(`${workflow}: missing selected role operation`)}catch{}
+  return errors;
+}
+const stringList=x=>Array.isArray(x)&&x.every(v=>typeof v==='string'&&v.length>0)&&new Set(x).size===x.length;
+const sameSet=(a,b)=>stringList(a)&&stringList(b)&&a.length===b.length&&a.every(x=>b.includes(x));
+export function validateContracts(k) {
+  const errors=[],roles=k.roles??{},workflows=k.workflows??{},artifacts=k.artifacts??{},modules=k.modules??{},handoffs=k.handoffs??{};
+  const error=(id,message)=>errors.push(`${id}: ${message}`);
+  for(const [id,a] of Object.entries(artifacts)) {
+    if(!roles[a.owner]&&!['lifecycle','installer','none'].includes(a.owner))error(id,'unknown artifact owner');
+    if(a.embedded_in&&!artifacts[a.embedded_in])error(id,'unknown embedded artifact');
+    if(!a.path&&!a.path_pattern&&!a.embedded_in&&!a.virtual)error(id,'artifact has no locator');
+  }
+  for(const [id,r] of Object.entries(roles)){
+    if(!managedPath(r.document))error(id,'invalid role document reference');
+    for(const kind of ['reads','writes']) {
+    if(!stringList(r[kind]))error(id,`invalid role ${kind}`);
+    else for(const a of r[kind])if(!artifacts[a])error(id,`unknown ${kind} artifact ${a}`);
+  }
+  }
+  for(const [id,w] of Object.entries(workflows)) {
+    if(!roles[w.role])error(id,`unknown owning role ${w.role}`);
+    if(typeof w.operation!=='string'||!w.operation)error(id,'missing operation');
+    if(!['NONE','INSPECT','IDENTITY'].includes(w.repository_requirement))error(id,'invalid repository requirement');
+  }
+  for(const [id,s] of Object.entries(k.skills??{})) {
+    const w=workflows[s.requested_workflow];
+    if(!w)error(id,`unknown requested workflow ${s.requested_workflow}`);
+    else if(w.role!==s.role)error(id,'skill role differs from workflow owner');
+    if(!roles[s.role])error(id,'unknown skill role');
+    const intent=INTENTS[s.desired_outcome];
+    if(!intent||s.requested_workflow!==intent[0]||s.completion_kind!==intent[1])error(id,'shortcut intent/workflow/completion semantics disagree');
+  }
+  for(const id of dispatchableWorkflows(k)) {
+    const w=workflows[id];
+    if(!w)error(id,'dispatch target has no workflow');
+    if(w?.role==='orchestrator')error(id,'root operation cannot be a worker dispatch target');
+    if(!handoffs[id])error(id,'dispatch target has no handoff contract');
+  }
+  for(const [id,h] of Object.entries(handoffs)) {
+    const w=workflows[id],r=roles[w?.role];
+    if(!w||!r){error(id,'handoff has no workflow/owning role');continue}
+    for(const kind of ['reads','writes']) {
+      if(!stringList(h[kind])){error(id,`invalid handoff ${kind}`);continue}
+      for(const a of h[kind]) {
+        if(!artifacts[a])error(id,`unknown ${kind} artifact ${a}`);
+        if(!r[kind]?.includes(a))error(id,`${kind} outside ${w.role} authority: ${a}`);
+      }
+    }
+    if(!artifacts[h.active_artifact])error(id,`unknown active artifact ${h.active_artifact}`);
+    else if(!h.reads?.includes(h.active_artifact)&&!h.writes?.includes(h.active_artifact))error(id,'active artifact outside handoff I/O');
+    if(!stringList(h.required_modules))error(id,'invalid required modules');
+    else for(const m of h.required_modules)if(!modules[m]?.usable_by?.includes(w.role))error(id,`missing/unauthorized module ${m}`);
+    if(typeof h.ticket_modules!=='boolean')error(id,'invalid ticket_modules');
+    if(typeof h.expected_output!=='string'||!h.expected_output.trim())error(id,'missing expected output');
+    if(!sameSet(h.result_vocabulary,RESULTS[id]))error(id,'result vocabulary incompatible with worker protocol');
+  }
+  for(const [id,m] of Object.entries(modules)) {
+    if(!managedPath(m.path))error(id,'invalid module path reference');
+    if(!stringList(m.usable_by)||m.usable_by.some(r=>!roles[r]))error(id,'unknown module role');
+  }
+  for(const row of k.lifecycle?.legal??[]) {
+    if(!workflows[row.workflow]||!roles[row.owner])error('lifecycle','unresolved workflow/owner');
+    if(row.writer&&!roles[row.writer])error('lifecycle','unknown writer');
+  }
+  const routing=k.lifecycle?.routing??{};
+  for(const [name,value] of Object.entries(routing)) {
+    if(name.endsWith('_workflow')&&!ROUTER_DISPATCH_TARGETS.includes(value))error(name,'routing workflow is not a router target');
+  }
+  for(const row of Object.values(routing.invalidation_routes??{}))if(!ROUTER_DISPATCH_TARGETS.includes(row.workflow))error('invalidation_routes','unknown router target');
+  return errors;
+}
+export async function validateSystemContracts(system,skills=null) {
+  const k=JSON.parse(await readFile(join(system,'kernel.yaml'),'utf8')),errors=validateContracts(k);
+  async function textAt(path,id) {
+    try{return await readFile(await managedFile(system,path),'utf8')}catch{errors.push(`${id}: missing/invalid referenced file ${path}`);return ''}
+  }
+  for(const [id,r] of Object.entries(k.roles??{})) {
+    const text=await textAt(r.document,id);
+    for(const [wid,w] of Object.entries(k.workflows??{}))if(w.role===id&&!text.includes(operationHeader(wid,w)))errors.push(`${wid}: missing role operation`);
+  }
+  for(const [id,m] of Object.entries(k.modules??{}))await textAt(m.path,id);
+  if(skills) {
+    const {readdir}=await import('node:fs/promises');
+    const dirs=(await readdir(skills,{withFileTypes:true})).filter(e=>e.isDirectory()).map(e=>e.name);
+    if(!sameSet(dirs,Object.keys(k.skills??{})))errors.push('public skill directory/catalog mismatch');
+    for(const [id,s] of Object.entries(k.skills??{})) {
+      try {
+        const text=await readFile(join(skills,id,'SKILL.md'),'utf8');
+        for(const marker of [`name: ${id}`,`ROLE: \`${s.role}\``,`WORKFLOW: \`${s.requested_workflow}\``,`INTENT: \`${s.desired_outcome}\``, 'system/engine/runtime.mjs',`--invoke-skill ${id}`])if(!text.includes(marker))errors.push(`${id}: skill metadata/runtime invocation mismatch (${marker})`);
+      }catch{errors.push(`${id}: missing public skill`)}
+    }
+  }
+  // Completion and intent enums are already machine contracts; do not duplicate them.
+  const schema=JSON.parse(await readFile(join(system,'schemas/intent.schema.json'),'utf8'));
+  for(const [id,s] of Object.entries(k.skills??{}))for(const field of ['desired_outcome','completion_kind'])if(!schema.properties[field].enum.includes(s[field]))errors.push(`${id}: invalid ${field}`);
+  return errors;
+}

package/dist/payload/yaaw-core/system/engine/repository-identity.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const ALGORITHM = "yaaw-worktree-v3";
+const CONTROL_OUTPUT_EXCLUDES = [
+  ".yaaw-core/runtime/**",
+  ".yaaw-core/project/tickets/**",
+  ".yaaw-core/project/evidence/**",
+  ".yaaw-core/project/reviews/**"
+];
+const EXCLUDE_PATHSPECS = CONTROL_OUTPUT_EXCLUDES.map(path => `:(exclude)${path}`);
+const hash = value => createHash("sha256").update(value).digest("hex");
+function stable(value){if(Array.isArray(value))return value.map(stable);if(value&&typeof value==="object")return Object.fromEntries(Object.keys(value).sort().map(k=>[k,stable(value[k])]));return value}
+const canonicalJson=value=>JSON.stringify(stable(value));
+function fail(status,message){process.stdout.write(JSON.stringify({schema:"yaaw.repository-identity/v2",algorithm:null,status,workspace_scope:".",git_root_relation:status==="UNVERSIONED"?"none":"unknown",head_commit:null,dirty:null,worktree_digest:null,components:null,changed_paths:[],error:message})+"\n");process.exitCode=2}
+function git(workspace,args){const r=spawnSync("git",["-C",workspace,...args],{encoding:null,windowsHide:true,maxBuffer:64*1024*1024});if(r.error)throw r.error;if(r.status!==0)throw new Error((r.stderr??Buffer.alloc(0)).toString("utf8").trim()||`git ${args.join(" ")} exited ${r.status}`);return r.stdout??Buffer.alloc(0)}
+const nulPaths=buf=>buf.toString("utf8").split("\0").filter(Boolean).map(p=>p.replaceAll("\\","/")).sort();
+function untrackedRecord(workspace,path){const absolute=resolve(workspace,path),stat=lstatSync(absolute);if(stat.isSymbolicLink())return{path,kind:"symlink",sha256:hash(Buffer.from(readlinkSync(absolute),"utf8"))};if(stat.isFile())return{path,kind:"file",sha256:hash(readFileSync(absolute))};throw new Error(`unsupported untracked filesystem object: ${path}`)}
+const args=process.argv.slice(2);let workspaceArg=".";for(let i=0;i<args.length;i+=1){if(args[i]==="--workspace"&&args[i+1]){workspaceArg=args[i+1];i+=1}else{process.stderr.write("usage: repository-identity.mjs [--workspace <path>]\n");process.exit(2)}}
+const workspace=resolve(workspaceArg);let workspacePrefix;try{const inside=git(workspace,["rev-parse","--is-inside-work-tree"]).toString("utf8").trim();if(inside!=="true")throw new Error("workspace is not inside a Git work tree");workspacePrefix=git(workspace,["rev-parse","--show-prefix"]).toString("utf8").trim().replaceAll("\\","/")}catch(error){fail("UNVERSIONED",error instanceof Error?error.message:String(error))}
+if(workspacePrefix!==undefined){try{const head=git(workspace,["rev-parse","HEAD"]).toString("utf8").trim(),scoped=[".",...EXCLUDE_PATHSPECS],status=git(workspace,["status","--porcelain=v1","-z","--untracked-files=all","--",...scoped]),unstaged=git(workspace,["diff","--binary","--no-ext-diff","--no-textconv","HEAD","--",...scoped]),staged=git(workspace,["diff","--cached","--binary","--no-ext-diff","--no-textconv","HEAD","--",...scoped]),untracked=nulPaths(git(workspace,["ls-files","--others","--exclude-standard","-z","--",...scoped])).map(p=>untrackedRecord(workspace,p)),tracked=new Set([...nulPaths(git(workspace,["diff","--name-only","-z","HEAD","--",...scoped])),...nulPaths(git(workspace,["diff","--cached","--name-only","-z","HEAD","--",...scoped]))]),components={status_sha256:hash(status),unstaged_diff_sha256:hash(unstaged),staged_diff_sha256:hash(staged),untracked_manifest_sha256:hash(Buffer.from(canonicalJson(untracked),"utf8"))},payload={algorithm:ALGORITHM,workspace_scope:".",head_commit:head,excluded:CONTROL_OUTPUT_EXCLUDES,...components,untracked},changed_paths=[...[...tracked].sort().map(path=>({path,kind:"tracked"})),...untracked.map(x=>({path:x.path,kind:"untracked",sha256:x.sha256}))].sort((a,b)=>a.path.localeCompare(b.path));process.stdout.write(JSON.stringify({schema:"yaaw.repository-identity/v2",algorithm:ALGORITHM,status:"READY",workspace_scope:".",git_root_relation:workspacePrefix?"ancestor":"same",head_commit:head,dirty:status.length>0,worktree_digest:"sha256:"+hash(Buffer.from(canonicalJson(payload),"utf8")),components,changed_paths,error:null})+"\n")}catch(error){if(process.exitCode!==2)fail("IDENTITY_FAILED",error instanceof Error?error.message:String(error))}}