yaaw-se 0.3.12 → 0.3.13

package/dist/payload/payload-files.json

@@ -28,7 +28,7 @@
     },
     {
       "path": "payload.json",
-      "sha256": "0b3fc978678213305ca54639416f95b66eef6d0a28e7390725e99d371723cf1e",
+      "sha256": "11921054038944aad1e18d9818ca049d06157201ea0bf9684e59b29a0a25096f",
       "bytes": 57
     },
     {
@@ -96,6 +96,11 @@
       "sha256": "6189616f6ddfb5992dcc22e562f2f2c061ce5f3202c09dfce0f5c9adef5bf42f",
       "bytes": 1247
     },
+    {
+      "path": "yaaw-core/system/engine/contracts.mjs",
+      "sha256": "b9541c15dcbb842da1812876c862e51b9a4422fcead81b274c19a864bf0885b3",
+      "bytes": 10180
+    },
     {
       "path": "yaaw-core/system/engine/frontmatter.mjs",
       "sha256": "2c90097563a91c52e6f9c7748dac583e67967fd4a9748e393bf61d753594277e",
@@ -113,18 +118,18 @@
     },
     {
       "path": "yaaw-core/system/engine/routing.mjs",
-      "sha256": "1e20ba87e76878aac6047d0ee62dbc55a24ee20a6a2551d36a803e892d32f170",
-      "bytes": 13250
+      "sha256": "7e051c636325d1c94b1a31ba409406e6ce9b5918857a3d39bf5fbd3b14c36365",
+      "bytes": 13728
     },
     {
       "path": "yaaw-core/system/engine/runtime.mjs",
-      "sha256": "dc30505164950e81ad6343b4c8d04cfe3604bfc84c8d4aec36eff424c614e614",
-      "bytes": 12293
+      "sha256": "605bef2be22d18cbeaa04cf0b2bbdec13a23ab5c3db857706e29bd309c25df63",
+      "bytes": 14049
     },
     {
       "path": "yaaw-core/system/kernel.yaml",
-      "sha256": "7e93d186484bebeed95ac0ddc68f489b198fbf94a6a222c92f577cd3b55cba41",
-      "bytes": 21373
+      "sha256": "706475307535f2e1c8042aab932e78cbada4af36460391d4fa29ad5067fb012c",
+      "bytes": 22539
     },
     {
       "path": "yaaw-core/system/modules/changeability.md",
@@ -168,8 +173,8 @@
     },
     {
       "path": "yaaw-core/system/roles/prd.md",
-      "sha256": "437c64a23575d353a86f8c81761394db99e855905c4f47beb6aad1dfa2f0efd6",
-      "bytes": 3372
+      "sha256": "9792407afb6ce55275b0acedf9727d7d79fbb4cfbd72aa5641078718c32e125a",
+      "bytes": 3874
     },
     {
       "path": "yaaw-core/system/roles/reviewer.md",
@@ -283,8 +288,8 @@
     },
     {
       "path": "yaaw-core/system/SYSTEM.md",
-      "sha256": "b793fbfae235c63861d7b131ff2b379c8dae3abc8fad85be3d089f1261d61a73",
-      "bytes": 9772
+      "sha256": "47d318e533ded5347fadaf63089f631b167cf7a28fc64377aa7d21f34c3f3a5e",
+      "bytes": 10940
     },
     {
       "path": "yaaw-core/system/templates/dispatch-failures.json",

package/dist/payload/payload.json

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

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

@@ -82,6 +82,10 @@ Workers never privately command or spawn peer YAAW authorities. After every work
 
 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.

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/routing.mjs

@@ -1,3 +1,4 @@
+import { ROUTES, dispatchableWorkflows } from "./contracts.mjs";
 const ACTIVE = new Set(["READY","IN_PROGRESS","REVIEW_REQUIRED","REPAIR_REQUIRED","PASS"]);
 const TERMINAL = new Set(["PASS","CANCELLED"]);
 const REVIEW_RESULT = { PASS:"PASS", REPAIR:"REPAIR_REQUIRED", REPLAN:"REPLAN_REQUIRED", BLOCKED:"BLOCKED" };
@@ -28,6 +29,7 @@ export function deriveState(a){
   const p=a.product?.meta??{},e=a.engineering?.meta??{};
   const product={artifact:a.product?.path??null,status:String(p.status??"missing"),revision:Number(p.revision??0)};
   const planning={artifact:a.engineering?.path??null,status:String(e.status??"missing"),revision:Number(e.revision??0),current_frontier:e.current_frontier??null,readiness:e.readiness??"pending",scope_status:e.scope_status??"UNKNOWN",active_spec:null};
+  if(e.product_revision!==undefined&&Number(e.product_revision)!==product.revision)planning.readiness="pending";
   const accepted=Object.entries(a.specs??{}).filter(([,x])=>x.meta?.status==="ACCEPTED"&&Number(x.meta.product_revision??0)===product.revision&&Number(x.meta.engineering_revision??0)===planning.revision).sort(([x],[y])=>byId(x,y));
   if(accepted.length===1)planning.active_spec=accepted[0][1].path;
   const tickets=Object.fromEntries(Object.entries(a.tickets??{}).map(([id,x])=>[id,String(x.meta?.status??"DRAFT")]));
@@ -86,7 +88,7 @@ export function intentComplete(intent,state,a){
   if(!intent)return false;const o=intent.desired_outcome,target=requestedTicket(intent,state),base=intent.created_from??{};
   if(o==="CONTINUE")return false;
   if(o==="CONTINUE_PRODUCT")return state.product.status==="ready";
-  if(o==="REVISE_PRODUCT")return Number(state.product.revision)>Number(base.product_revision??0);
+  if(o==="REVISE_PRODUCT")return state.product.status==="ready"&&Number(state.product.revision)>Number(base.product_revision??0);
   if(o==="REFINE_PRODUCT")return Boolean(a.product?.digest&&base.product_digest&&a.product.digest!==base.product_digest);
   if(o==="CONTINUE_PLANNING")return planningReady(state);
   if(o==="PLANNING_REVIEW")return state.planning.readiness!==base.planning_readiness||a.engineering?.digest!==base.engineering_digest;
@@ -98,23 +100,24 @@ export function intentComplete(intent,state,a){
 }
 
 function baseRoute(state,a){
-  if(state.product.status!=="ready")return {workflow:"prd.route",ticket:null};
-  const replan=Object.keys(state.tickets).sort(byId).find(id=>state.tickets[id]==="REPLAN_REQUIRED");if(replan)return{workflow:"planning.replan",ticket:replan};
-  if(state.planning.status!=="ready"||state.planning.readiness!=="PASS")return{workflow:"planning.route",ticket:null};
-  if(!currentSpecId(state))return{workflow:"planning.create-spec",ticket:null};
+  if(state.product.status!=="ready")return {workflow:ROUTES.product,ticket:null};
+  const replan=Object.keys(state.tickets).sort(byId).find(id=>state.tickets[id]==="REPLAN_REQUIRED");if(replan)return{workflow:ROUTES.replan,ticket:replan};
+  if(state.planning.status!=="ready"||state.planning.readiness!=="PASS")return{workflow:ROUTES.planning,ticket:null};
+  if(!currentSpecId(state))return{workflow:ROUTES.spec,ticket:null};
   const ids=currentTicketIds(state,a);
-  const repair=ids.find(id=>state.tickets[id]==="REPAIR_REQUIRED");if(repair)return{workflow:"implementation.repair-ticket",ticket:repair};
-  const review=ids.find(id=>state.tickets[id]==="REVIEW_REQUIRED");if(review)return{workflow:"review.review-ticket",ticket:review};
-  const progress=ids.find(id=>state.tickets[id]==="IN_PROGRESS");if(progress)return{workflow:"implementation.verify-ticket",ticket:progress};
-  const ready=ids.find(id=>state.tickets[id]==="READY"&&dependenciesPass(id,state,a));if(ready)return{workflow:"implementation.implement-ticket",ticket:ready};
-  const draft=ids.find(id=>state.tickets[id]==="DRAFT"&&dependenciesPass(id,state,a));if(draft)return{workflow:"planning.create-tickets",ticket:draft};
-  if(ids.length===0)return{workflow:"planning.create-tickets",ticket:null};
-  if(ids.every(id=>TERMINAL.has(state.tickets[id]))){if(state.planning.scope_status==="COMPLETE")return{terminal:"COMPLETE"};return{workflow:"planning.route",ticket:null};}
+  const repair=ids.find(id=>state.tickets[id]==="REPAIR_REQUIRED");if(repair)return{workflow:ROUTES.repair,ticket:repair};
+  const review=ids.find(id=>state.tickets[id]==="REVIEW_REQUIRED");if(review)return{workflow:ROUTES.review,ticket:review};
+  const progress=ids.find(id=>state.tickets[id]==="IN_PROGRESS");if(progress)return{workflow:ROUTES.verify,ticket:progress};
+  const ready=ids.find(id=>state.tickets[id]==="READY"&&dependenciesPass(id,state,a));if(ready)return{workflow:ROUTES.implement,ticket:ready};
+  const draft=ids.find(id=>state.tickets[id]==="DRAFT"&&dependenciesPass(id,state,a));if(draft)return{workflow:ROUTES.tickets,ticket:draft};
+  if(ids.length===0)return{workflow:ROUTES.tickets,ticket:null};
+  if(ids.every(id=>TERMINAL.has(state.tickets[id]))){if(state.planning.scope_status==="COMPLETE")return{terminal:"COMPLETE"};return{workflow:ROUTES.planning,ticket:null};}
   const blocked=ids.find(id=>state.tickets[id]==="BLOCKED");if(blocked)return{blocked:`ticket ${blocked} is BLOCKED`,ticket:blocked};
   return{blocked:"no legal next workflow from current durable artifacts",ticket:null};
 }
 
-function legalRequested(workflow,ticket,state,a){
+function legalRequested(kernel,workflow,ticket,state,a){
+  if(!dispatchableWorkflows(kernel).has(workflow))return false;
   if(workflow==="prd.route"||workflow==="prd.revise"||workflow==="prd.refine")return true;
   if(workflow==="planning.route"||workflow==="planning.readiness-review")return state.product.status==="ready";
   if(workflow==="planning.create-spec")return planningReady(state)&&!currentSpecId(state);
@@ -128,13 +131,14 @@ function legalRequested(workflow,ticket,state,a){
 export function planNext(kernel,state,a,repo,intent){
   const reconciliation=selectReconciliation(kernel,state,a,repo);if(reconciliation)return{type:"RECONCILE_REQUIRED",reconciliation};
   if(intentComplete(intent,state,a))return{type:"INTENT_COMPLETE",completion_kind:intent.completion_kind};
-  if(state.phase==="complete")return{type:"TERMINAL",terminal:"COMPLETE"};
+  if(state.phase==="complete"&&!["prd.revise","prd.refine"].includes(intent?.requested_workflow))return{type:"TERMINAL",terminal:"COMPLETE"};
+  if(intent?.desired_outcome==="REVISE_PRODUCT"&&Number(state.product.revision)>Number(intent.created_from?.product_revision??0)&&state.product.status!=="ready")return{type:"ROUTE",workflow:ROUTES.product,ticket:null};
   if(intent&&intent.requested_workflow&&intent.requested_workflow!=="orchestration.route"){
     let ticket=requestedTicket(intent,state);
     if(!ticket&&intent.desired_outcome==="IMPLEMENT")ticket=Object.keys(state.tickets).sort(byId).find(id=>state.tickets[id]==="READY"&&dependenciesPass(id,state,a))??null;
     if(!ticket&&intent.desired_outcome==="REPAIR")ticket=Object.keys(state.tickets).sort(byId).find(id=>state.tickets[id]==="REPAIR_REQUIRED")??null;
     if(!ticket&&intent.desired_outcome==="REVIEW")ticket=Object.keys(state.tickets).sort(byId).find(id=>state.tickets[id]==="REVIEW_REQUIRED")??null;
-    if(legalRequested(intent.requested_workflow,ticket,state,a))return{type:"ROUTE",workflow:intent.requested_workflow,ticket};
+    if(legalRequested(kernel,intent.requested_workflow,ticket,state,a))return{type:"ROUTE",workflow:intent.requested_workflow,ticket};
     return{type:"BLOCKED",reason:`PRECONDITION_UNSATISFIED:${intent.requested_workflow}`,ticket};
   }
   return{type:"ROUTE",...baseRoute(state,a)};

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

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { validateContracts, validateDispatchFiles } from "./contracts.mjs";
 import { parseFrontmatter } from "./frontmatter.mjs";
 import { deriveState, planNext, chooseIntentTarget } from "./routing.mjs";
 
@@ -35,7 +36,7 @@ function refsFor(reads,state,a,ticket){const refs=[];const push=x=>{if(x&&!refs.
 function revisions(state,a,ticket){const spec=selectedSpec(state,a,ticket);return{product:Number(state.product.revision??0),engineering:Number(state.planning.revision??0),spec:Number(spec?.meta?.revision??0),ticket:Number(ticket?a.tickets?.[ticket]?.meta?.revision??0:0)}}
 function basis(state,a,ticket){const spec=selectedSpec(state,a,ticket);return{product_digest:a.product?.digest??null,engineering_digest:a.engineering?.digest??null,spec_digest:spec?.digest??null,ticket_digest:ticket?a.tickets?.[ticket]?.digest??null:null,ticket_status:ticket?state.tickets?.[ticket]??null:null}}
 function modulesFor(kernel,role,policy,a,ticket){const names=[...(policy.required_modules??[])];if(policy.ticket_modules&&ticket)for(const x of a.tickets?.[ticket]?.meta?.expertise??[])names.push(x);return[...new Set(names)].filter(name=>kernel.modules[name]?.usable_by?.includes(role)).map(name=>kernel.modules[name].path)}
-function handoff(kernel,framework,state,a,repo,workflow,ticket,intent){const wf=kernel.workflows[workflow],policy=kernel.handoffs[workflow],role=kernel.roles[wf?.role];if(!wf||!policy||!role)throw new Error(`no handoff contract for ${workflow}`);for(const w of policy.writes??[])if(!role.writes.includes(w))throw new Error(`workflow ${workflow} writes unauthorized artifact ${w}`);return{schema:"yaaw.handoff/v4",framework:frameworkBasis(framework),role:wf.role,workflow,operation:wf.operation,instruction:{document:role.document,operation:wf.operation},desired_intent:intent?.desired_outcome??null,active_artifact:policy.active_artifact??null,ticket:ticket??null,references:refsFor(policy.reads,state,a,ticket),reads:policy.reads,writes:policy.writes,forbidden_writes:Object.keys(kernel.artifacts).filter(x=>!role.writes.includes(x)),revisions:revisions(state,a,ticket),basis:basis(state,a,ticket),expertise:modulesFor(kernel,wf.role,policy,a,ticket),host_expertise:[],expected_output:policy.expected_output,result_vocabulary:policy.result_vocabulary,repository_requirement:wf.repository_requirement,repository:repo}}
+function handoff(kernel,framework,state,a,repo,workflow,ticket,intent){const wf=kernel.workflows[workflow],policy=kernel.handoffs[workflow],role=kernel.roles[wf?.role];if(!wf||!policy||!role)throw new Error(`no handoff contract for ${workflow}`);for(const kind of ["reads","writes"])for(const artifact of policy[kind]??[])if(!role[kind].includes(artifact))throw new Error(`workflow ${workflow} ${kind} unauthorized artifact ${artifact}`);return{schema:"yaaw.handoff/v4",framework:frameworkBasis(framework),role:wf.role,workflow,operation:wf.operation,instruction:{document:role.document,operation:wf.operation},desired_intent:intent?.desired_outcome??null,active_artifact:policy.active_artifact??null,ticket:ticket??null,references:refsFor(policy.reads,state,a,ticket),reads:policy.reads,writes:policy.writes,forbidden_writes:Object.keys(kernel.artifacts).filter(x=>!role.writes.includes(x)),revisions:revisions(state,a,ticket),basis:basis(state,a,ticket),expertise:modulesFor(kernel,wf.role,policy,a,ticket),host_expertise:[],expected_output:policy.expected_output,result_vocabulary:policy.result_vocabulary,repository_requirement:wf.repository_requirement,repository:repo}}
 function repoAllowed(requirement,repo){if(requirement==="NONE")return true;if(requirement==="INSPECT")return repo?.status==="READY"||repo?.status==="UNVERSIONED";return repo?.status==="READY"}
 function patchStatus(text,status){const lines=String(text).split(/\r?\n/);if(lines[0]?.trim()!=="---")throw new Error("ticket missing frontmatter");const end=lines.slice(1).findIndex(x=>x.trim()==="---");if(end<0)throw new Error("ticket missing closing frontmatter");const idx=lines.slice(1,end+1).findIndex(x=>/^status:\s*/.test(x));if(idx<0)throw new Error("ticket missing status");lines[idx+1]=`status: ${status}`;return lines.join("\n")}
 async function observed(root,framework,repo,state,a,reconciliation){const value={schema:"yaaw.observed-state/v4",framework:{...frameworkBasis(framework),modified:framework.modified??[],missing:framework.missing??[],local_overrides:framework.local_overrides??[],repair_required:Boolean(framework.repair_required)},repository:repo,derived:state,reconstructable:true,artifacts:{product:a.product,engineering:a.engineering,specs:a.specs,tickets:a.tickets,reviews:a.reviews,evidence:a.evidence,research:a.research,rules:a.rules},inconsistencies:[],candidate_actions:[],reconciliation};await mkdir(join(root,".yaaw-core","runtime"),{recursive:true});await writeFile(join(root,".yaaw-core","runtime","observed-state.json"),JSON.stringify(value,null,2)+"\n");return value}
@@ -43,15 +44,23 @@ async function observed(root,framework,repo,state,a,reconciliation){const value=
 async function main(){
   const opt=argsOf(process.argv.slice(2)),root=resolve(opt.workspace),system=join(root,".yaaw-core","system"),runtime=join(root,".yaaw-core","runtime"),kernel=JSON.parse(await readFile(join(system,"kernel.yaml"),"utf8"));
   const integrity=execJson(join(system,"engine","integrity.mjs"),root);if(integrity.status!=="HEALTHY"){console.log(JSON.stringify({type:"FRAMEWORK_STOP",reason:`FRAMEWORK_${integrity.status}`,framework:integrity}));return}
+  const contractErrors=validateContracts(kernel);
+  if(contractErrors.length){
+    const intent=await json(join(runtime,"intent.json")),sourceSkill=opt.invoke??intent?.source_skill??null,requested=kernel.skills[sourceSkill]?.requested_workflow??intent?.requested_workflow??null;
+    const subject=contractErrors[0].split(": ")[0],workflow=kernel.workflows[subject]?subject:requested??subject;
+    throw Object.assign(new Error(contractErrors.join("; ")),{diagnostic:{classification:"FRAMEWORK_DEFECT_OR_DAMAGED_INSTALLATION",workflow,requested_workflow:requested,source_skill:sourceSkill,routing_source:sourceSkill?"PUBLIC_SKILL_INTENT":"DETERMINISTIC_ROUTER",owning_role:kernel.workflows[workflow]?.role??null,framework_version:integrity.package_version,contract_type:"DISPATCH_CONTRACT",recommendation:"Update or repair YAAW-SE through the supported installer; preserve project memory."}});
+  }
   const repo=execJson(join(system,"engine","repository-identity.mjs"),root),a=await inspectArtifacts(root),state=deriveState(a);
   let intent=await json(join(runtime,"intent.json"));if(opt.invoke)intent=await seedIntent(root,kernel,opt.invoke,state,a);
   const planned=planNext(kernel,state,a,repo,intent),reconciliation=planned.type==="RECONCILE_REQUIRED"?planned.reconciliation:null;await observed(root,integrity,repo,state,a,reconciliation);
   if(opt.inspect){console.log(JSON.stringify({type:"INSPECTED",state,reconciliation}));return}
   if(opt.reconcile){if(!reconciliation){console.log(JSON.stringify({type:"NO_RECONCILIATION"}));return}if(reconciliation.kind==="BLOCKED"){console.log(JSON.stringify({type:"BLOCKED",reason:reconciliation.reason}));return}const ticket=a.tickets?.[reconciliation.subject];if(!ticket)throw new Error(`reconciliation ticket missing: ${reconciliation.subject}`);const ticketPath=join(root,ticket.path),raw=await readFile(ticketPath,"utf8");await writeFile(ticketPath,patchStatus(raw,reconciliation.to),"utf8");for(const file of ["observed-state.json","handoff.json"])try{await writeFile(join(runtime,file),"")}catch{}console.log(JSON.stringify({type:"RECONCILED",reconciliation}));return}
-  if(opt.check){const old=await json(join(runtime,"handoff.json"));if(!old){console.log(JSON.stringify({type:"HANDOFF_STALE",reason:"missing handoff"}));return}const candidate=handoff(kernel,integrity,state,a,repo,old.workflow,old.ticket,intent);console.log(JSON.stringify(same(old,candidate)?{type:"HANDOFF_FRESH"}:{type:"HANDOFF_STALE",reason:"durable basis changed"}));return}
+  if(opt.check){const old=await json(join(runtime,"handoff.json"));if(!old){console.log(JSON.stringify({type:"HANDOFF_STALE",reason:"missing handoff"}));return}const candidate=handoff(kernel,integrity,state,a,repo,old.workflow,old.ticket,intent);const fileErrors=await validateDispatchFiles(system,kernel,old.workflow,candidate.expertise);if(fileErrors.length)throw new Error(fileErrors.join("; "));console.log(JSON.stringify(same(old,candidate)?{type:"HANDOFF_FRESH"}:{type:"HANDOFF_STALE",reason:"durable basis changed"}));return}
   if(planned.type!=="ROUTE"){if(planned.type!=="RECONCILE_REQUIRED")try{await writeFile(join(runtime,"handoff.json"),"")}catch{}console.log(JSON.stringify(planned));return}
   if(planned.terminal){console.log(JSON.stringify({type:"TERMINAL",terminal:planned.terminal}));return}if(planned.blocked){console.log(JSON.stringify({type:"BLOCKED",reason:planned.blocked,ticket:planned.ticket??null}));return}
   const wf=kernel.workflows[planned.workflow];if(!wf)throw new Error(`unknown workflow ${planned.workflow}`);if(wf.role==="orchestrator"){console.log(JSON.stringify({type:"ROOT_ACTION",workflow:planned.workflow,ticket:planned.ticket??null}));return}if(!repoAllowed(wf.repository_requirement,repo)){console.log(JSON.stringify({type:"BLOCKED",reason:"PRECONDITION_UNSATISFIED:REPOSITORY_IDENTITY_UNAVAILABLE",workflow:planned.workflow}));return}
-  const h=handoff(kernel,integrity,state,a,repo,planned.workflow,planned.ticket??null,intent);await mkdir(runtime,{recursive:true});await writeFile(join(runtime,"handoff.json"),JSON.stringify(h,null,2)+"\n");console.log(JSON.stringify({type:"DISPATCH_READY",workflow:planned.workflow,role:h.role,operation:h.operation,ticket:h.ticket,handoff:rel(root,join(runtime,"handoff.json"))}));
+  const h=handoff(kernel,integrity,state,a,repo,planned.workflow,planned.ticket??null,intent);
+  const fileErrors=await validateDispatchFiles(system,kernel,planned.workflow,h.expertise);if(fileErrors.length)throw Object.assign(new Error(fileErrors.join("; ")),{diagnostic:{classification:"FRAMEWORK_DEFECT_OR_DAMAGED_INSTALLATION",workflow:planned.workflow,source_skill:intent?.source_skill??null,owning_role:h.role,framework_version:integrity.package_version,contract_type:"INSTRUCTION_OR_MODULE_FILE",recommendation:"Update or repair YAAW-SE through the supported installer; preserve project memory."}});
+  await mkdir(runtime,{recursive:true});await writeFile(join(runtime,"handoff.json"),JSON.stringify(h,null,2)+"\n");console.log(JSON.stringify({type:"DISPATCH_READY",workflow:planned.workflow,role:h.role,operation:h.operation,ticket:h.ticket,handoff:rel(root,join(runtime,"handoff.json"))}));
 }
-main().catch(error=>{process.stdout.write(JSON.stringify({type:"FRAMEWORK_STOP",reason:"FRAMEWORK_CONTRACT_INCONSISTENCY",error:String(error?.stack??error)})+"\n");process.exitCode=2});
+main().catch(error=>{process.stdout.write(JSON.stringify({type:"FRAMEWORK_STOP",reason:"FRAMEWORK_CONTRACT_INCONSISTENCY",error:String(error?.message??error),...(error?.diagnostic?{diagnostic:error.diagnostic}:{})})+"\n");process.exitCode=2});

package/dist/payload/yaaw-core/system/kernel.yaml

@@ -76,6 +76,9 @@
     "orchestration.recover-interruption": {"role":"orchestrator","operation":"recover-interruption","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ROOT_ONLY"}
   },
   "handoffs": {
+    "prd.revise": {"active_artifact":"product","reads":["product"],"writes":["product"],"required_modules":[],"ticket_modules":false,"expected_output":"Human-approved revised product meaning, incremented semantic revision and provenance; READY or unresolved product questions. Downstream staleness is derived by Orchestrator.","result_vocabulary":["READY","HUMAN_INPUT_REQUIRED","BLOCKED"]},
+    "prd.refine": {"active_artifact":"product","reads":["product"],"writes":["product"],"required_modules":[],"ticket_modules":false,"expected_output":"Clarified product text preserving accepted meaning and semantic revision, or a typed product question/stop.","result_vocabulary":["READY","HUMAN_INPUT_REQUIRED","BLOCKED"]},
+    "planning.readiness-review": {"active_artifact":"engineering","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository"],"writes":["engineering"],"required_modules":[],"ticket_modules":false,"expected_output":"Current-frontier readiness result, source revisions, reason and evidence persisted only in engineering.md.","result_vocabulary":["PASS","MISSING_DECISIONS","PRODUCT_GAP","REPLAN","BLOCKED"]},
     "prd.route": {"active_artifact":"product","reads":["product"],"writes":["product"],"required_modules":[],"ticket_modules":false,"expected_output":"Current product intent or a typed stop.","result_vocabulary":["READY","HUMAN_INPUT_REQUIRED","BLOCKED"]},
     "planning.route": {"active_artifact":"engineering","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository"],"writes":["engineering","engineering_research","spec","ticket","project_rule"],"required_modules":[],"ticket_modules":false,"expected_output":"Current engineering frontier readiness or one typed planning result.","result_vocabulary":["READY","HUMAN_INPUT_REQUIRED","REPLAN","BLOCKED"]},
     "planning.create-spec": {"active_artifact":"engineering","reads":["product","engineering","engineering_research","project_rule","repository"],"writes":["spec"],"required_modules":[],"ticket_modules":false,"expected_output":"One accepted specification or a typed prerequisite/stop.","result_vocabulary":["SUCCESS","PRECONDITION_UNSATISFIED","BLOCKED"]},

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

@@ -15,13 +15,13 @@ Initialize `product.md` from the canonical template only when missing; never ove
 Challenge only material contradictions, ambiguous terminology, unsupported assumptions, premature abstractions, important flows/failures/edge cases, and scope/non-goal conflicts. Exclude engineering-only questions and questions whose prerequisites remain unresolved. Ask at most 10 high-leverage questions; options/recommendation are optional and free-form answers are first-class. Stop for human input.
 
 ## Operation: record-decisions (`prd.record-decisions`)
-Interpret only what the answer supports. Persist conclusions in the relevant product sections, not the question/challenge transcript. Remove settled questions, preserve corrections/non-goals, and increment product revision only when accepted product meaning materially changes. Recompute contradictions/questions and invalidate downstream planning/spec/ticket authority whose product basis became stale.
+Interpret only what the answer supports. Persist conclusions in the relevant product sections, not the question/challenge transcript. Remove settled questions, preserve corrections/non-goals, and increment product revision only when accepted product meaning materially changes. Recompute contradictions/questions and expose the changed product basis for downstream invalidation. Orchestrator derives staleness; Planner alone revises engineering/spec/ticket contracts.
 
 ## Operation: revise (`prd.revise`)
-Identify the exact old requirement and requested new meaning. Stress-test impact on behavior, scope, constraints, non-goals, and newly exposed product questions without drifting into engineering design. Update `product.md`, increment revision, record provenance, and invalidate downstream dependent contracts. Leave product draft if material questions remain; otherwise run readiness.
+Identify the exact old requirement and requested new meaning. Stress-test impact on behavior, scope, constraints, non-goals, and newly exposed product questions without drifting into engineering design. Update only `product.md`, increment revision for a material accepted meaning change, and record provenance. The changed product revision invalidates downstream authority through Orchestrator observation/reconciliation; do not mutate engineering, specifications, or tickets. Leave product draft if material questions remain; otherwise run readiness. Return `READY`, `HUMAN_INPUT_REQUIRED`, or `BLOCKED` for the dispatched invocation.
 
 ## Operation: refine (`prd.refine`)
-Improve clarity, organization, deduplication, and completeness without changing accepted semantic meaning or product revision. If the edit changes behavior, scope, constraints, or non-goals—or exposes a genuine semantic contradiction—switch to revision instead of silently changing meaning.
+Improve clarity, organization, deduplication, and completeness without changing accepted semantic meaning or product revision. If the edit changes behavior, scope, constraints, or non-goals—or exposes a genuine semantic contradiction—stop with `HUMAN_INPUT_REQUIRED` for explicit product revision authority instead of silently changing meaning. Return `READY` only when clarity work is complete and product readiness holds; otherwise return `HUMAN_INPUT_REQUIRED` or `BLOCKED`.
 
 ## Operation: readiness (`prd.readiness`)
 Ask whether a fresh Planner can understand goal, users, expected behavior, scope, constraints, non-goals, and remaining product unknowns without the original chat, and whether any material current-frontier ambiguity would force invented product intent. Return `READY`, `NEEDS_QUESTIONS`, or `BLOCKED`. On READY, persist `status: ready` in `product.md`. Future fog is allowed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaaw-se",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Artifact-first autonomous software engineering workflow installer.",
   "type": "module",
   "bin": {
@@ -28,7 +28,10 @@
     "prepack": "npm run test && npm run build",
     "smoke:tarball": "npm run build && node scripts/smoke_npm_tarball.mjs",
     "smoke:update": "npm run build && node scripts/smoke_npm_update.mjs",
-    "validate:schemas": "node scripts/validate_schemas.mjs"
+    "validate:schemas": "node scripts/validate_schemas.mjs",
+    "validate:contracts": "node scripts/validate_contracts.mjs .yaaw-core/system skills",
+    "smoke:dispatch-update": "npm run build && node scripts/smoke_dispatch_update.mjs",
+    "audit:workflows": "node scripts/audit_workflow_contracts.mjs .yaaw-core/system skills"
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",