yaaw-se 0.3.11 → 0.3.13

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

@@ -0,0 +1,153 @@
+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" };
+const idNum = value => Number(String(value??"").match(/(\d+)(?!.*\d)/)?.[1]??0);
+const byId=(a,b)=>idNum(a)-idNum(b)||String(a).localeCompare(String(b));
+const repoEq=(a,b)=>Boolean(a&&b&&a.status==="READY"&&b.status==="READY"&&a.algorithm===b.algorithm&&a.head_commit===b.head_commit&&a.worktree_digest===b.worktree_digest);
+const currentSpecId=(state)=>String(state?.planning?.active_spec??"").match(/SPEC-[0-9]+/)?.[0]??null;
+const sourceCurrent=(ticket,state,a)=>{
+  const t=a.tickets?.[ticket]?.meta;if(!t)return false;
+  const sid=String(t.spec??"");const s=a.specs?.[sid]?.meta;if(!s)return false;
+  return Number(t.product_revision??0)===Number(state.product.revision??0)
+    && Number(t.engineering_revision??0)===Number(state.planning.revision??0)
+    && Number(t.spec_revision??0)===Number(s.revision??0)
+    && Number(s.product_revision??0)===Number(state.product.revision??0)
+    && Number(s.engineering_revision??0)===Number(state.planning.revision??0);
+};
+const currentTicketIds=(state,a)=>Object.keys(a.tickets??{}).filter(id=>sourceCurrent(id,state,a)).sort(byId);
+const dependenciesPass=(ticket,state,a)=>((a.tickets?.[ticket]?.meta?.dependencies??[]).every(id=>state.tickets?.[id]==="PASS"));
+const evidenceFor=(ticket,a)=>Object.values(a.evidence??{}).filter(x=>x?.ticket===ticket&&x?.schema==="yaaw.evidence/v3");
+const reviewFor=(ticket,a)=>Object.values(a.reviews??{}).filter(x=>x?.meta?.ticket===ticket&&x?.meta?.schema==="yaaw.review/v2").sort((x,y)=>Number(x.meta.round??0)-Number(y.meta.round??0));
+const latestStart=(ticket,a)=>evidenceFor(ticket,a).filter(x=>x.kind==="implementation_start"&&x.result==="STARTED").sort((x,y)=>idNum(x.id)-idNum(y.id)).at(-1)??null;
+const latestVerification=(ticket,a)=>evidenceFor(ticket,a).filter(x=>x.kind==="implementation_verification").sort((x,y)=>idNum(x.id)-idNum(y.id)).at(-1)??null;
+const latestReview=(ticket,a)=>reviewFor(ticket,a).at(-1)??null;
+const verificationCurrent=(v,ticket,a,repo)=>Boolean(v&&v.result==="PASS"&&Number(v.ticket_revision??0)===Number(a.tickets?.[ticket]?.meta?.revision??0)&&Number(v.spec_revision??0)===Number(a.specs?.[a.tickets?.[ticket]?.meta?.spec]?.meta?.revision??0)&&repoEq(v.repository,repo));
+const reviewCurrent=(r,ticket,a,repo,v)=>Boolean(r&&REVIEW_RESULT[r.meta?.result]&&Number(r.meta.ticket_revision??0)===Number(a.tickets?.[ticket]?.meta?.revision??0)&&Number(r.meta.spec_revision??0)===Number(a.specs?.[a.tickets?.[ticket]?.meta?.spec]?.meta?.revision??0)&&repoEq(r.meta.repository,repo)&&Array.isArray(r.meta.evidence)&&(!v||r.meta.evidence.includes(v.id)));
+
+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")]));
+  const current=Object.keys(tickets).filter(id=>sourceCurrent(id,{product,planning,tickets},a));
+  const allTerminal=current.length>0&&current.every(id=>TERMINAL.has(tickets[id]));
+  let phase="implementation";
+  if(product.status!=="ready")phase="product";
+  else if(planning.status!=="ready"||planning.readiness!=="PASS")phase="planning";
+  else if(allTerminal&&planning.scope_status==="COMPLETE")phase="complete";
+  const precedence=["REPLAN_REQUIRED","REPAIR_REQUIRED","REVIEW_REQUIRED","IN_PROGRESS","READY","DRAFT","BLOCKED"];
+  let active_ticket=null;for(const status of precedence){active_ticket=current.find(id=>tickets[id]===status)??null;if(active_ticket)break;}
+  return {schema:"yaaw.derived-state/v1",phase,product,planning,active_ticket,tickets,accepted_specs:accepted.map(([id])=>id)};
+}
+
+function transition(kernel,ticket,from,to,id,reason,evidence=[],workflow="orchestration.reconcile-state"){
+  const legal=kernel.lifecycle.legal.some(t=>t.from===from&&t.to===to);
+  if(!legal)return {id:"ILLEGAL_TRANSITION",kind:"BLOCKED",subject:ticket,from,to,reason:`illegal derived transition ${from} -> ${to}`,workflow:null,evidence:[]};
+  return {id,kind:"TICKET_STATUS",subject:ticket,from,to,reason,workflow,evidence};
+}
+
+export function selectReconciliation(kernel,state,a,repo){
+  if((state.accepted_specs??[]).length>1)return {id:"MULTIPLE_CURRENT_SPECS",kind:"BLOCKED",subject:null,from:null,to:null,reason:"more than one current ACCEPTED specification exists",workflow:null,evidence:state.accepted_specs};
+  const ids=Object.keys(state.tickets??{}).sort(byId);
+  for(const ticket of ids){
+    const status=state.tickets[ticket];
+    if((ACTIVE.has(status)||status==="REPLAN_REQUIRED")&&!sourceCurrent(ticket,state,a)){
+      if(status==="REPLAN_REQUIRED")continue;
+      return transition(kernel,ticket,status,"REPLAN_REQUIRED","CONTRACT_SOURCE_STALE","ticket source revisions are stale",[],"planning.replan");
+    }
+  }
+  for(const ticket of ids){
+    const status=state.tickets[ticket];if(!sourceCurrent(ticket,state,a))continue;
+    const start=latestStart(ticket,a),verification=latestVerification(ticket,a),review=latestReview(ticket,a);
+    if(status==="READY"&&start){
+      const t=a.tickets[ticket].meta;
+      if(Number(start.ticket_revision??0)===Number(t.revision??0)&&Number(start.spec_revision??0)===Number(a.specs?.[t.spec]?.meta?.revision??0))return transition(kernel,ticket,"READY","IN_PROGRESS","IMPLEMENTATION_STARTED","implementation_start evidence exists",[start.id]);
+    }
+    if(status==="IN_PROGRESS"&&verificationCurrent(verification,ticket,a,repo))return transition(kernel,ticket,"IN_PROGRESS","REVIEW_REQUIRED","IMPLEMENTATION_VERIFIED","current PASS verification exists",[verification.id]);
+    if(status==="REPAIR_REQUIRED"&&verificationCurrent(verification,ticket,a,repo)){
+      const prior=review?.meta?.evidence??[];if(!prior.includes(verification.id))return transition(kernel,ticket,"REPAIR_REQUIRED","REVIEW_REQUIRED","IMPLEMENTATION_VERIFIED","fresh PASS verification exists after repair",[verification.id]);
+    }
+    if(status==="REVIEW_REQUIRED"&&reviewCurrent(review,ticket,a,repo,verification)){
+      const to=REVIEW_RESULT[review.meta.result];return transition(kernel,ticket,"REVIEW_REQUIRED",to,"REVIEW_RESULT_UNAPPLIED",`review result ${review.meta.result} authorizes ${to}`,[review.path,verification?.id].filter(Boolean));
+    }
+    if(status==="PASS"){
+      if(!verificationCurrent(verification,ticket,a,repo))return transition(kernel,ticket,"PASS","REVIEW_REQUIRED","ACCEPTANCE_STALE","accepted ticket lacks current PASS verification",verification?[verification.id]:[]);
+      if(!reviewCurrent(review,ticket,a,repo,verification))return transition(kernel,ticket,"PASS","REVIEW_REQUIRED","ACCEPTANCE_STALE","accepted ticket lacks current review for repository/evidence basis",review?[review.path]:[]);
+    }
+  }
+  return null;
+}
+
+function planningReady(state){return state.product.status==="ready"&&state.planning.status==="ready"&&state.planning.readiness==="PASS"}
+function requestedTicket(intent,state){const t=String(intent?.target_artifact??"").match(/TASK-[0-9]+/)?.[0];return t&&state.tickets?.[t]?t:null}
+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 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;
+  if(o==="CREATE_SPEC")return Boolean(currentSpecId(state));
+  if(o==="CREATE_TICKETS")return currentTicketIds(state,a).length>0;
+  if(o==="IMPLEMENT"||o==="REPAIR")return Boolean(target&&state.tickets[target]==="REVIEW_REQUIRED");
+  if(o==="REVIEW")return Boolean(target&&state.tickets[target]!=="REVIEW_REQUIRED");
+  return false;
+}
+
+function baseRoute(state,a){
+  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: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(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);
+  if(workflow==="planning.create-tickets")return planningReady(state)&&Boolean(currentSpecId(state));
+  if(workflow==="implementation.implement-ticket")return Boolean(ticket&&state.tickets[ticket]==="READY"&&sourceCurrent(ticket,state,a)&&dependenciesPass(ticket,state,a));
+  if(workflow==="implementation.repair-ticket")return Boolean(ticket&&state.tickets[ticket]==="REPAIR_REQUIRED"&&sourceCurrent(ticket,state,a));
+  if(workflow==="review.review-ticket")return Boolean(ticket&&state.tickets[ticket]==="REVIEW_REQUIRED"&&sourceCurrent(ticket,state,a));
+  return true;
+}
+
+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"&&!["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(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)};
+}
+
+export function chooseIntentTarget(skill,state,a){
+  if(!skill)return null;const ids=currentTicketIds(state,a);
+  if(skill.desired_outcome==="IMPLEMENT")return ids.find(id=>state.tickets[id]==="READY"&&dependenciesPass(id,state,a))??null;
+  if(skill.desired_outcome==="REPAIR")return ids.find(id=>state.tickets[id]==="REPAIR_REQUIRED")??null;
+  if(skill.desired_outcome==="REVIEW")return ids.find(id=>state.tickets[id]==="REVIEW_REQUIRED")??null;
+  return null;
+}

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+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";
+
+const hash=v=>"sha256:"+createHash("sha256").update(v).digest("hex");
+const stable=value=>Array.isArray(value)?value.map(stable):(value&&typeof value==="object"?Object.fromEntries(Object.keys(value).sort().map(k=>[k,stable(value[k])])):value);
+const same=(a,b)=>JSON.stringify(stable(a))===JSON.stringify(stable(b));
+const rel=(root,path)=>relative(root,path).replaceAll("\\","/");
+async function exists(path){try{await access(path);return true}catch{return false}}
+async function json(path,fallback=null){try{return JSON.parse(await readFile(path,"utf8"))}catch{return fallback}}
+async function meta(root,path){try{const raw=await readFile(path,"utf8");return{path:rel(root,path),meta:parseFrontmatter(raw),digest:hash(Buffer.from(raw,"utf8"))}}catch{return null}}
+async function list(dir,ext){try{return(await readdir(dir)).filter(x=>x.endsWith(ext)).sort()}catch{return[]}}
+function execJson(file,workspace){const r=spawnSync(process.execPath,[file,"--workspace",workspace],{encoding:"utf8",windowsHide:true});let value=null;try{value=JSON.parse(r.stdout)}catch{}return value??{status:"UNKNOWN",error:r.stderr||`exit ${r.status}`}}
+function argsOf(argv){const out={workspace:process.cwd(),invoke:null,inspect:false,reconcile:false,check:false};for(let i=0;i<argv.length;i+=1){const x=argv[i];if(x==="--workspace"&&argv[i+1]){out.workspace=argv[++i]}else if(x==="--invoke-skill"&&argv[i+1]){out.invoke=argv[++i]}else if(x==="--inspect-only")out.inspect=true;else if(x==="--reconcile-one")out.reconcile=true;else if(x==="--check-handoff")out.check=true;else throw new Error(`unknown argument: ${x}`)}return out}
+
+async function inspectArtifacts(root){
+  const p=join(root,".yaaw-core","project"),product=await meta(root,join(p,"product.md")),engineering=await meta(root,join(p,"engineering.md")),specs={},tickets={},reviews={},evidence={},research={},rules={};
+  for(const name of await list(join(p,"specs"),".md")){const x=await meta(root,join(p,"specs",name));if(x?.meta?.id)specs[x.meta.id]=x}
+  for(const name of await list(join(p,"tickets"),".md")){const x=await meta(root,join(p,"tickets",name));if(x?.meta?.id)tickets[x.meta.id]=x}
+  for(const name of await list(join(p,"reviews"),".md")){const x=await meta(root,join(p,"reviews",name));if(x?.meta?.ticket)reviews[name]=x}
+  for(const name of await list(join(p,"evidence"),".json")){const x=await json(join(p,"evidence",name));if(x?.id){x.path=rel(root,join(p,"evidence",name));evidence[x.id]=x}}
+  for(const name of await list(join(p,"research"),".md")){const x=await meta(root,join(p,"research",name));if(x)research[name]=x}
+  for(const name of await list(join(p,"rules"),".md")){const x=await meta(root,join(p,"rules",name));if(x)rules[name]=x}
+  return{product,engineering,specs,tickets,reviews,evidence,research,rules};
+}
+function frameworkBasis(i){return{yaaw_version:i.package_version??"unknown",system_schema:Number(i.system_schema??0),installation_schema:Number(i.installation_schema??0),project_schema:Number(i.project_schema??0),manifest_digest:i.manifest_digest??"unknown",integrity_status:i.status??"UNKNOWN"}}
+function baseline(state,a){return{product_revision:state.product.revision,product_digest:a.product?.digest??null,engineering_revision:state.planning.revision,engineering_digest:a.engineering?.digest??null,planning_readiness:state.planning.readiness,active_spec:state.planning.active_spec,ticket_statuses:state.tickets}}
+async function seedIntent(root,kernel,skillId,state,a){const s=kernel.skills[skillId];if(!s)throw new Error(`unknown skill ${skillId}`);const intent={schema:"yaaw.intent/v3",source_skill:skillId,desired_outcome:s.desired_outcome,requested_workflow:s.requested_workflow,target_artifact:chooseIntentTarget(s,state,a),completion_kind:s.completion_kind,created_from:baseline(state,a)};await mkdir(join(root,".yaaw-core","runtime"),{recursive:true});await writeFile(join(root,".yaaw-core","runtime","intent.json"),JSON.stringify(intent,null,2)+"\n");return intent}
+function selectedSpec(state,a,ticket){const sid=ticket?a.tickets?.[ticket]?.meta?.spec:String(state.planning.active_spec??"").match(/SPEC-[0-9]+/)?.[0];return sid?a.specs?.[sid]??null:null}
+function refsFor(reads,state,a,ticket){const refs=[];const push=x=>{if(x&&!refs.includes(x))refs.push(x)};for(const kind of reads){if(kind==="product")push(a.product?.path);else if(kind==="engineering")push(a.engineering?.path);else if(kind==="spec")push(selectedSpec(state,a,ticket)?.path);else if(kind==="ticket"){if(ticket)push(a.tickets?.[ticket]?.path);else Object.values(a.tickets??{}).forEach(x=>push(x.path))}else if(kind==="engineering_research")Object.values(a.research??{}).forEach(x=>push(x.path));else if(kind==="project_rule")Object.values(a.rules??{}).forEach(x=>push(x.path));else if(kind==="evidence")Object.values(a.evidence??{}).filter(x=>!ticket||x.ticket===ticket).forEach(x=>push(x.path));else if(kind==="review")Object.values(a.reviews??{}).filter(x=>!ticket||x.meta?.ticket===ticket).forEach(x=>push(x.path))}return 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 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}
+
+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);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);
+  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?.message??error),...(error?.diagnostic?{diagnostic:error.diagnostic}:{})})+"\n");process.exitCode=2});

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

@@ -0,0 +1,145 @@
+{
+  "schema": "yaaw.kernel/v1",
+  "principle": "Persist semantic facts once; derive coordination state.",
+  "paths": {
+    "workspace_root": ".",
+    "system_root": ".yaaw-core/system",
+    "project_root": ".yaaw-core/project",
+    "runtime_root": ".yaaw-core/runtime",
+    "install_root": ".yaaw-core/install",
+    "product": ".yaaw-core/project/product.md",
+    "engineering": ".yaaw-core/project/engineering.md",
+    "research": ".yaaw-core/project/research",
+    "specs": ".yaaw-core/project/specs",
+    "tickets": ".yaaw-core/project/tickets",
+    "reviews": ".yaaw-core/project/reviews",
+    "evidence": ".yaaw-core/project/evidence",
+    "project_rules": ".yaaw-core/project/rules"
+  },
+  "artifacts": {
+    "product": {"path": ".yaaw-core/project/product.md", "durability": "PROJECT_DURABLE", "owner": "prd", "mutable": true},
+    "engineering": {"path": ".yaaw-core/project/engineering.md", "durability": "PROJECT_DURABLE", "owner": "planner", "mutable": true},
+    "engineering_research": {"path_pattern": ".yaaw-core/project/research/RSH-*.md", "durability": "PROJECT_DURABLE", "owner": "planner", "mutable": true},
+    "spec": {"path_pattern": ".yaaw-core/project/specs/SPEC-*.md", "durability": "PROJECT_DURABLE", "owner": "planner", "mutable": true},
+    "ticket": {"path_pattern": ".yaaw-core/project/tickets/TASK-*.md", "durability": "PROJECT_DURABLE", "owner": "planner", "mutable": true},
+    "ticket_status": {"embedded_in": "ticket", "field": "status", "durability": "PROJECT_DURABLE", "owner": "lifecycle", "mutable": true},
+    "review": {"path_pattern": ".yaaw-core/project/reviews/TASK-*-R*.md", "durability": "PROJECT_DURABLE", "owner": "reviewer", "mutable": false},
+    "evidence": {"path_pattern": ".yaaw-core/project/evidence/*.json", "durability": "PROJECT_DURABLE", "owner": "implementer", "mutable": false},
+    "project_rule": {"path_pattern": ".yaaw-core/project/rules/*.md", "durability": "PROJECT_DURABLE", "owner": "planner", "mutable": true},
+    "observed_state": {"path": ".yaaw-core/runtime/observed-state.json", "durability": "RUNTIME_REPLACEABLE", "owner": "orchestrator", "mutable": true},
+    "handoff": {"path": ".yaaw-core/runtime/handoff.json", "durability": "RUNTIME_REPLACEABLE", "owner": "orchestrator", "mutable": true},
+    "intent": {"path": ".yaaw-core/runtime/intent.json", "durability": "RUNTIME_REPLACEABLE", "owner": "orchestrator", "mutable": true},
+    "dispatch_failures": {"path": ".yaaw-core/runtime/dispatch-failures.json", "durability": "RUNTIME_REPLACEABLE", "owner": "orchestrator", "mutable": true},
+    "installation_manifest": {"path": ".yaaw-core/install/manifest.json", "durability": "INSTALLER_MANAGED", "owner": "installer", "mutable": true},
+    "repository": {"virtual": true, "durability": "OBSERVED", "owner": "none", "mutable": false},
+    "application_files": {"virtual": true, "durability": "APPLICATION", "owner": "implementer", "mutable": true}
+  },
+  "roles": {
+    "prd": {"document": ".yaaw-core/system/roles/prd.md", "reads": ["product"], "writes": ["product"]},
+    "planner": {"document": ".yaaw-core/system/roles/planner.md", "reads": ["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review"], "writes": ["engineering","engineering_research","spec","ticket","project_rule"]},
+    "implementer": {"document": ".yaaw-core/system/roles/implementer.md", "reads": ["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review","application_files"], "writes": ["application_files","evidence"]},
+    "reviewer": {"document": ".yaaw-core/system/roles/reviewer.md", "reads": ["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review","application_files"], "writes": ["review"]},
+    "orchestrator": {"document": ".yaaw-core/system/roles/orchestrator.md", "reads": ["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review","observed_state","handoff","intent","installation_manifest","dispatch_failures"], "writes": ["ticket_status","observed_state","handoff","intent","dispatch_failures"]}
+  },
+  "workflows": {
+    "prd.route": {"role":"prd","operation":"route","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "prd.create": {"role":"prd","operation":"create","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "prd.question-round": {"role":"prd","operation":"question-round","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "prd.record-decisions": {"role":"prd","operation":"record-decisions","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "prd.revise": {"role":"prd","operation":"revise","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "prd.refine": {"role":"prd","operation":"refine","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "prd.readiness": {"role":"prd","operation":"readiness","repository_requirement":"NONE","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.route": {"role":"planner","operation":"route","repository_requirement":"INSPECT","external_research":"metadata-only","execution_context":"ISOLATED_PREFERRED"},
+    "planning.discover": {"role":"planner","operation":"discover","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.write-understanding": {"role":"planner","operation":"write-understanding","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.decision-frontier": {"role":"planner","operation":"decision-frontier","repository_requirement":"INSPECT","external_research":"admission-only","execution_context":"ISOLATED_PREFERRED"},
+    "planning.research": {"role":"planner","operation":"research","repository_requirement":"INSPECT","external_research":"candidate-scoped","execution_context":"ISOLATED_PREFERRED"},
+    "planning.question-round": {"role":"planner","operation":"question-round","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.record-decisions": {"role":"planner","operation":"record-decisions","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.readiness-review": {"role":"planner","operation":"readiness-review","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.create-spec": {"role":"planner","operation":"create-spec","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.create-tickets": {"role":"planner","operation":"create-tickets","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "planning.replan": {"role":"planner","operation":"replan","repository_requirement":"INSPECT","external_research":"admission-only","execution_context":"ISOLATED_PREFERRED"},
+    "implementation.select-ticket": {"role":"implementer","operation":"select-ticket","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "implementation.implement-ticket": {"role":"implementer","operation":"implement-ticket","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "implementation.verify-ticket": {"role":"implementer","operation":"verify-ticket","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "implementation.repair-ticket": {"role":"implementer","operation":"repair-ticket","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "review.inspect-change": {"role":"reviewer","operation":"inspect-change","repository_requirement":"IDENTITY","external_research":"restricted","execution_context":"ISOLATED_PREFERRED"},
+    "review.review-ticket": {"role":"reviewer","operation":"review-ticket","repository_requirement":"IDENTITY","external_research":"restricted","execution_context":"ISOLATED_PREFERRED"},
+    "review.classify-findings": {"role":"reviewer","operation":"classify-findings","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "review.record-review": {"role":"reviewer","operation":"record-review","repository_requirement":"IDENTITY","external_research":"forbidden","execution_context":"ISOLATED_PREFERRED"},
+    "orchestration.route": {"role":"orchestrator","operation":"route","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ROOT_ONLY"},
+    "orchestration.inspect-state": {"role":"orchestrator","operation":"inspect-state","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ROOT_ONLY"},
+    "orchestration.reconcile-state": {"role":"orchestrator","operation":"reconcile-state","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ROOT_ONLY"},
+    "orchestration.determine-next-action": {"role":"orchestrator","operation":"determine-next-action","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ROOT_ONLY"},
+    "orchestration.dispatch": {"role":"orchestrator","operation":"dispatch","repository_requirement":"INSPECT","external_research":"forbidden","execution_context":"ROOT_ONLY"},
+    "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"]},
+    "planning.create-tickets": {"active_artifact":"spec","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository"],"writes":["ticket"],"required_modules":["changeability"],"ticket_modules":false,"expected_output":"Dependency-aware tickets or a typed prerequisite/stop.","result_vocabulary":["SUCCESS","PRECONDITION_UNSATISFIED","BLOCKED"]},
+    "planning.replan": {"active_artifact":"ticket","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review"],"writes":["engineering","engineering_research","spec","ticket","project_rule"],"required_modules":["changeability"],"ticket_modules":true,"expected_output":"Updated engineering contract and ticket admission state.","result_vocabulary":["READY","HUMAN_INPUT_REQUIRED","BLOCKED"]},
+    "implementation.implement-ticket": {"active_artifact":"ticket","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review","application_files"],"writes":["application_files","evidence"],"required_modules":["changeability"],"ticket_modules":true,"expected_output":"Start evidence, bounded implementation, and verification evidence or a typed stop.","result_vocabulary":["VERIFICATION_PASS","VERIFICATION_FAIL","REPLAN_REQUIRED","PRECONDITION_UNSATISFIED","BLOCKED"]},
+    "implementation.verify-ticket": {"active_artifact":"ticket","reads":["product","engineering","spec","ticket","project_rule","repository","evidence","application_files"],"writes":["evidence"],"required_modules":["changeability"],"ticket_modules":true,"expected_output":"One immutable implementation_verification record.","result_vocabulary":["VERIFICATION_PASS","VERIFICATION_FAIL","IMPLEMENTATION_INCOMPLETE","REPLAN_REQUIRED","BLOCKED"]},
+    "implementation.repair-ticket": {"active_artifact":"ticket","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review","application_files"],"writes":["application_files","evidence"],"required_modules":["changeability"],"ticket_modules":true,"expected_output":"Bounded repair plus fresh verification evidence or a typed stop.","result_vocabulary":["VERIFICATION_PASS","VERIFICATION_FAIL","REPLAN_REQUIRED","BLOCKED"]},
+    "review.review-ticket": {"active_artifact":"ticket","reads":["product","engineering","engineering_research","spec","ticket","project_rule","repository","evidence","review","application_files"],"writes":["review"],"required_modules":["testing","changeability"],"ticket_modules":true,"expected_output":"One immutable independent review round.","result_vocabulary":["PASS","REPAIR","REPLAN","BLOCKED"]}
+  },
+  "skills": {
+    "yaaw-orchestrator": {"role":"orchestrator","requested_workflow":"orchestration.route","desired_outcome":"CONTINUE","completion_kind":"CONTINUE_UNTIL_STOP","description":"Continue or recover by reconstructing reality and dispatching the next safe workflow."},
+    "yaaw-prd": {"role":"prd","requested_workflow":"prd.route","desired_outcome":"CONTINUE_PRODUCT","completion_kind":"PRODUCT_READY","description":"Create or continue product definition."},
+    "yaaw-revise-prd": {"role":"prd","requested_workflow":"prd.revise","desired_outcome":"REVISE_PRODUCT","completion_kind":"PRODUCT_REVISION_ADVANCED","description":"Change accepted product intent and invalidate stale downstream contracts."},
+    "yaaw-refine-prd": {"role":"prd","requested_workflow":"prd.refine","desired_outcome":"REFINE_PRODUCT","completion_kind":"PRODUCT_REFINED","description":"Improve product clarity without changing accepted meaning."},
+    "yaaw-planner": {"role":"planner","requested_workflow":"planning.route","desired_outcome":"CONTINUE_PLANNING","completion_kind":"PLANNING_READY","description":"Continue repository-backed engineering planning."},
+    "yaaw-planning-review": {"role":"planner","requested_workflow":"planning.readiness-review","desired_outcome":"PLANNING_REVIEW","completion_kind":"PLANNING_READINESS_DECIDED","description":"Assess current engineering-frontier readiness."},
+    "yaaw-create-spec": {"role":"planner","requested_workflow":"planning.create-spec","desired_outcome":"CREATE_SPEC","completion_kind":"CURRENT_SPEC_ACCEPTED","description":"Create the next specification from a ready frontier."},
+    "yaaw-create-ticket": {"role":"planner","requested_workflow":"planning.create-tickets","desired_outcome":"CREATE_TICKETS","completion_kind":"CURRENT_TICKETS_REGISTERED","description":"Create bounded implementation tickets."},
+    "yaaw-create-tickets": {"role":"planner","requested_workflow":"planning.create-tickets","desired_outcome":"CREATE_TICKETS","completion_kind":"CURRENT_TICKETS_REGISTERED","description":"Create dependency-aware bounded implementation tickets."},
+    "yaaw-implement": {"role":"implementer","requested_workflow":"implementation.implement-ticket","desired_outcome":"IMPLEMENT","completion_kind":"TICKET_REVIEW_REQUIRED","description":"Implement one READY ticket and produce verification evidence."},
+    "yaaw-repair": {"role":"implementer","requested_workflow":"implementation.repair-ticket","desired_outcome":"REPAIR","completion_kind":"TICKET_REVIEW_REQUIRED","description":"Repair one REPAIR_REQUIRED ticket."},
+    "yaaw-review": {"role":"reviewer","requested_workflow":"review.review-ticket","desired_outcome":"REVIEW","completion_kind":"TICKET_REVIEW_APPLIED","description":"Independently review implementation and classify its result."}
+  },
+  "modules": {
+    "frontend-design": {"path":".yaaw-core/system/modules/frontend-design.md","usable_by":["planner","implementer","reviewer"]},
+    "security": {"path":".yaaw-core/system/modules/security.md","usable_by":["planner","implementer","reviewer"]},
+    "testing": {"path":".yaaw-core/system/modules/testing.md","usable_by":["planner","implementer","reviewer"]},
+    "python": {"path":".yaaw-core/system/modules/python.md","usable_by":["planner","implementer","reviewer"]},
+    "changeability": {"path":".yaaw-core/system/modules/changeability.md","usable_by":["planner","implementer","reviewer"]}
+  },
+  "lifecycle": {
+    "ticket_states": ["DRAFT","READY","IN_PROGRESS","REVIEW_REQUIRED","REPAIR_REQUIRED","REPLAN_REQUIRED","BLOCKED","PASS","CANCELLED"],
+    "legal": [
+      {"from":"DRAFT","to":"READY","owner":"planner","workflow":"planning.create-tickets"},
+      {"from":"DRAFT","to":"CANCELLED","owner":"planner","workflow":"planning.replan"},
+      {"from":"READY","to":"IN_PROGRESS","owner":"implementer","workflow":"implementation.implement-ticket","writer":"orchestrator"},
+      {"from":"READY","to":"REPLAN_REQUIRED","owner":"planner","workflow":"planning.replan"},
+      {"from":"IN_PROGRESS","to":"REVIEW_REQUIRED","owner":"implementer","workflow":"implementation.verify-ticket","writer":"orchestrator"},
+      {"from":"IN_PROGRESS","to":"REPLAN_REQUIRED","owner":"planner","workflow":"planning.replan"},
+      {"from":"IN_PROGRESS","to":"BLOCKED","owner":"implementer","workflow":"implementation.implement-ticket","writer":"orchestrator"},
+      {"from":"REVIEW_REQUIRED","to":"PASS","owner":"reviewer","workflow":"review.record-review","writer":"orchestrator"},
+      {"from":"REVIEW_REQUIRED","to":"REPAIR_REQUIRED","owner":"reviewer","workflow":"review.record-review","writer":"orchestrator"},
+      {"from":"REVIEW_REQUIRED","to":"REPLAN_REQUIRED","owner":"reviewer","workflow":"review.record-review","writer":"orchestrator"},
+      {"from":"REVIEW_REQUIRED","to":"BLOCKED","owner":"reviewer","workflow":"review.record-review","writer":"orchestrator"},
+      {"from":"REPAIR_REQUIRED","to":"REVIEW_REQUIRED","owner":"implementer","workflow":"implementation.repair-ticket","writer":"orchestrator"},
+      {"from":"REPAIR_REQUIRED","to":"REPLAN_REQUIRED","owner":"planner","workflow":"planning.replan"},
+      {"from":"REPLAN_REQUIRED","to":"DRAFT","owner":"planner","workflow":"planning.replan"},
+      {"from":"REPLAN_REQUIRED","to":"READY","owner":"planner","workflow":"planning.replan"},
+      {"from":"PASS","to":"CANCELLED","owner":"planner","workflow":"planning.replan"},
+      {"from":"PASS","to":"REVIEW_REQUIRED","owner":"orchestrator","workflow":"orchestration.reconcile-state","causes":["REVIEW_MISSING","REVIEW_REPOSITORY_STALE","VERIFICATION_MISSING","VERIFICATION_REPOSITORY_STALE","LEGACY_IDENTITY_UNVERIFIABLE"],"writer":"orchestrator"},
+      {"from":"PASS","to":"REPLAN_REQUIRED","owner":"orchestrator","workflow":"orchestration.reconcile-state","causes":["PRODUCT_SOURCE_STALE","ENGINEERING_SOURCE_STALE","SPEC_SOURCE_STALE","TICKET_SOURCE_STALE","CONTRACT_INVALIDATED"],"writer":"orchestrator"}
+    ],
+    "forbidden": [{"from":"DRAFT","to":"PASS"},{"from":"READY","to":"PASS"},{"from":"REPAIR_REQUIRED","to":"PASS"}],
+    "routing": {
+      "product_unready_workflow":"prd.route","planning_unready_workflow":"planning.route","missing_spec_workflow":"planning.create-spec","missing_tickets_workflow":"planning.create-tickets","draft_admission_workflow":"planning.create-tickets","next_frontier_workflow":"planning.route","complete_terminal":"COMPLETE",
+      "invalidation_routes": {
+        "PRODUCT_SOURCE_STALE":{"state":"REPLAN_REQUIRED","workflow":"planning.replan"},"ENGINEERING_SOURCE_STALE":{"state":"REPLAN_REQUIRED","workflow":"planning.replan"},"SPEC_SOURCE_STALE":{"state":"REPLAN_REQUIRED","workflow":"planning.replan"},"TICKET_SOURCE_STALE":{"state":"REPLAN_REQUIRED","workflow":"planning.replan"},"CONTRACT_INVALIDATED":{"state":"REPLAN_REQUIRED","workflow":"planning.replan"},"REVIEW_MISSING":{"state":"REVIEW_REQUIRED","workflow":"review.review-ticket"},"REVIEW_REPOSITORY_STALE":{"state":"REVIEW_REQUIRED","workflow":"review.review-ticket"},"VERIFICATION_MISSING":{"state":"REVIEW_REQUIRED","workflow":"review.review-ticket"},"VERIFICATION_REPOSITORY_STALE":{"state":"REVIEW_REQUIRED","workflow":"review.review-ticket"},"LEGACY_IDENTITY_UNVERIFIABLE":{"state":"REVIEW_REQUIRED","workflow":"review.review-ticket"}
+      }
+    },
+    "reconciliation_priority": ["CONTRACT_SOURCE_STALE","IMPLEMENTATION_STARTED","IMPLEMENTATION_VERIFIED","REVIEW_RESULT_UNAPPLIED","ACCEPTANCE_STALE"],
+    "one_reconciliation_per_cycle": true
+  }
+}

package/dist/payload/yaaw-core/system/modules/changeability.md

@@ -0,0 +1,27 @@
+# Changeability expertise
+
+Use this optional module when a ticket, design, or review has non-trivial maintainability implications. The mandatory policy is summarized in `SYSTEM.md`; this module provides deeper reasoning and examples, not additional authority.
+
+## Goal
+Optimize the changed surface for future comprehension, modification, verification, and rollback while preserving the current product/spec/ticket contract and repository conventions.
+
+## Reasoning sequence
+1. Identify the actual domain behavior being changed.
+2. Identify the minimum authorized code surface needed to implement it safely.
+3. Locate relevant boundaries, state models, decision logic, errors, and tests.
+4. Apply only principles that materially affect that surface.
+5. Prefer the smallest design that removes concrete ambiguity/coupling/risk.
+6. Verify behavior and the relevant structural property.
+7. Leave unrelated cleanup out of scope.
+
+## Heuristics
+- **Visible main path:** use guard clauses/decomposition when exceptional cases bury the operation; avoid mechanical style rewrites.
+- **Domain naming:** expose business meaning where known; generic names are fine for genuinely generic mechanics.
+- **External boundaries:** keep provider/transport/ORM schemas and failures at narrow adapters when the accepted architecture benefits.
+- **Invalid states:** prefer explicit variants/constructors/validators when they remove meaningful runtime uncertainty.
+- **Decisions versus actions:** keep important policy independently testable from side effects when practical.
+- **Useful failures:** preserve stable machine identity plus safe human context; never expose secrets.
+- **Focused changes:** a discovered smell is not automatically ticket scope; supporting refactors must be necessary for safe implementation or verification.
+
+## Review guidance
+Classify a concrete bounded changeability defect as REPAIR when the accepted contract remains valid. Use REPLAN only when satisfying it changes accepted architecture/spec meaning. Style preference alone is non-blocking.

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

@@ -1,17 +1,21 @@
-# Implementer role
+# Implementer
 
 ## Authority
-Own application changes and implementation evidence for one bounded admitted ticket at a time.
+Own application changes and implementation evidence for one bounded admitted ticket at a time. Never self-approve or silently change product/engineering contracts.
 
-## Required behavior
-- Require an exact handoff, repository requirement `IDENTITY`, repository status `READY`, reconciled state read access, and current source revisions.
-- Before the first application mutation, write immutable `yaaw.evidence/v3` `implementation_start` evidence with result `STARTED` and the pre-edit repository identity.
-- Then implement only the admitted scope and apply relevant changeability rules.
-- Run required verification and write a new immutable v3 `implementation_verification` record with explicit `PASS`, `FAIL`, or `BLOCKED`.
-- Never rewrite failed evidence as success.
-- Never write `state.json`. Orchestrator adopts valid start/verification facts through legal transitions.
-- If no READY ticket exists, return `PRECONDITION_UNSATISFIED:NO_READY_TICKET`; do not create tickets or command Planner.
-- Missing material decisions route back to Planner through Orchestrator.
+Use `SYSTEM.md` for shared invariants. Execute only the operation named by the deterministic handoff.
+
+## Operation: select-ticket (`implementation.select-ticket`)
+Require repository status READY. Reject DRAFT, BLOCKED, REPLAN_REQUIRED, REPAIR_REQUIRED, REVIEW_REQUIRED, PASS, CANCELLED, stale-source, or dependency-unsatisfied tickets for normal implementation. Choose the specifically requested eligible READY ticket, otherwise the next dependency-satisfied READY ticket. Revalidate product/engineering/spec/ticket revisions immediately before admission.
+
+## Operation: implement-ticket (`implementation.implement-ticket`)
+Require exact current handoff, ticket status READY, current source revisions/dependencies, and repository identity READY. **Before the first application mutation**, write immutable `yaaw.evidence/v3` `implementation_start` evidence with result STARTED, current ticket/spec revisions, workflow ID, and exact pre-edit repository identity. Only then implement inside allowed scope, applying changeability guidance and selected modules. Material contract gaps stop as REPLAN_REQUIRED/BLOCKED rather than being invented. Run verify-ticket and persist verification evidence. Do not edit ticket lifecycle status; Orchestrator derives/adopts READY->IN_PROGRESS from start evidence and IN_PROGRESS->REVIEW_REQUIRED from current PASS verification.
+
+## Operation: verify-ticket (`implementation.verify-ticket`)
+Run every ticket-required check plus justified targeted regressions. Verify materially relevant structural/changeability properties. After verification completes, capture canonical repository identity and write a new immutable `.yaaw-core/project/evidence/EVIDENCE-TASK-NNN-VK.json` using `yaaw.evidence/v3`, kind `implementation_verification`, with exactly PASS, FAIL, or BLOCKED. Preserve failed records; fixes create later records. If verification proves implementation materially incomplete, return `IMPLEMENTATION_INCOMPLETE` rather than silently broadening this operation.
+
+## Operation: repair-ticket (`implementation.repair-ticket`)
+Require ticket status REPAIR_REQUIRED and the latest current review result REPAIR. Load the unchanged contract, bounded findings, prior evidence, selected modules, and relevant code. Repair only those findings. Contract changes route to REPLAN_REQUIRED. Rerun verification and write fresh evidence distinct from the evidence referenced by the REPAIR review. Orchestrator adopts REPAIR_REQUIRED->REVIEW_REQUIRED only from fresh current PASS verification.
 
 ## Boundary
-Never self-approve, silently change product/architecture contracts, or implement stale/`REPLAN_REQUIRED` work. A lost context is not permission to restart implementation from scratch.
+A lost worker response is not permission to restart implementation. Missing material decisions return through Orchestrator to Planner/PRD. Package-managed `.yaaw-core/system/**` is never writable semantic output.

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

@@ -1,20 +1,30 @@
-# Orchestrator role
+# Orchestrator
 
 ## Authority
-Own continuity, evidence-backed reconciliation, invalidation coordination, public-intent continuation, and next-workflow dispatch. Orchestrator is the only physical writer of `.yaaw-core/project/state.json`; durable semantic facts from the owning roles authorize its mutations.
+Own continuity, evidence-backed observation, deterministic lifecycle adoption, invalidation coordination, recovery, public-intent continuation, and next-workflow dispatch. Orchestrator is a traffic controller, not a super-agent; it never authors product, engineering, implementation, research, or acceptance meaning.
 
-## Boot sequence
-1. Resolve the workspace root through `.yaaw-core/system/core/execution-context.md`.
-2. For a public skill, invoke `orchestration-runtime.mjs --invoke-skill <skill>`; otherwise prepare with `--workspace <root>`.
-3. Consume exactly one typed result. `RECONCILE_REQUIRED` applies exactly one reconciliation, then observation repeats.
-4. Dispatch exactly one semantic handoff only after framework health, reconciliation, source-current validation, repository policy, and intent prerequisites pass.
-5. After worker success, failure, interruption, or lost response, throw away worker text as authority and observe durable reality again.
-6. Continue until intent completion, human input, an unrecoverable typed blocker/framework stop, or project `COMPLETE`. Recoverable proof gaps must be routed to the owning verification/review workflow rather than surfaced as terminal blockers.
+Use `SYSTEM.md` and `kernel.yaml` as the compact system contract.
 
-## Boundary
-The Orchestrator is a traffic controller, not a super-agent. It must not author product decisions, architecture, implementation, research conclusions, or acceptance. Framework integrity is a fail-closed execution precondition. The Orchestrator never creates, edits, deletes, or weakens package-managed `.yaaw-core/system/**` content to unblock work; installer repair is the only supported framework mutation path.
+## Operation: route (`orchestration.route`)
+For normal continuation run `node .yaaw-core/system/engine/runtime.mjs --workspace <WORKSPACE_ROOT>`. For a public entrypoint append `--invoke-skill <skill-id>`. Repeat one deterministic boundary at a time: FRAMEWORK_STOP -> stop; RECONCILE_REQUIRED -> apply exactly one `--reconcile-one` then observe again; ROOT_ACTION -> run only the returned interruption-recovery operation; DISPATCH_READY -> execute exactly the persisted fresh handoff once; after any worker result/disappearance -> discard worker prose as authority and reobserve; INTENT_COMPLETE/TERMINAL/BLOCKED/human input -> stop.
 
-Worker output does not update lifecycle state directly. Workers write durable semantic facts. Orchestrator observes those facts and records only legal lifecycle changes.
+## Operation: inspect-state (`orchestration.inspect-state`)
+Run runtime with `--inspect-only`. It reconstructs product/planning/current spec/ticket lifecycle from durable artifacts, evidence/reviews, and repository identity and writes replaceable `runtime/observed-state.json`. Do not serialize a second state model or mutate semantic artifacts.
 
-## Execution-profile boundary
-The Orchestrator routes the execution profile selected by the host adapter but never invents or substitutes provider/model settings. It has no authority to choose arbitrary models or reasoning levels.
+## Operation: reconcile-state (`orchestration.reconcile-state`)
+Run runtime with `--reconcile-one`. Apply exactly one deterministic evidence-backed ticket lifecycle update permitted by `kernel.yaml`, then return to route. The only durable coordination mutation is the `status` scalar inside the affected ticket frontmatter. Do not maintain a global state/transition ledger. Planner-owned semantic contract edits remain Planner work; Reviewer outcomes remain Reviewer authority.
+
+## Operation: determine-next-action (`orchestration.determine-next-action`)
+Normal runtime preparation owns routing and handoff construction. Consume its typed result; do not duplicate route selection, repository identity, module selection, or handoff serialization in model reasoning.
+
+## Operation: dispatch (`orchestration.dispatch`)
+Immediately before execution run runtime with `--check-handoff` and require HANDOFF_FRESH. Execute the selected role and exact operation from the handoff using the host adapter's required effective execution profile. Prefer an isolated authority worker when available; never silently substitute an incompatible profile. If a child was created and failed, reobserve before any retry. The worker loads only its role document/operation, exact handoff references, selected modules, and minimal relevant application context. A worker never routes or spawns another YAAW authority. Treat worker text only as an execution signal; reobserve durable reality afterward.
+
+## Operation: recover-interruption (`orchestration.recover-interruption`)
+Use only for a proven interrupted execution boundary, never as the generic fallback for DRAFT admission or shortcut precondition failure. Discard stale runtime caches, identify the last trustworthy durable boundary from ticket status/evidence/reviews/repository identity, and route forward without duplicating completed work. IN_PROGRESS with current PASS verification goes to review; valid start evidence without PASS verification goes to verify; missing proof returns an exact blocker. If no interruption exists, return immediately to normal route.
+
+## Runtime invariant
+Delete `.yaaw-core/runtime/` and invoke YAAW again: the safe next semantic action must be reconstructable. If it is not, durable truth leaked into a cache and the framework contract is violated.
+
+## Framework boundary
+Never modify `.yaaw-core/system/**` during semantic work. Framework integrity failures stop and require installer repair/update.