@yunhozz/arc 0.1.7 → 0.1.10

package/lib/policy/placement.mjs

@@ -2,12 +2,12 @@
 const reviews = ['review.significant-no-plan', 'review.significant-plan', 'review.final-plan-recheck'];
 export const POLICY_PROJECTIONS = Object.freeze(Object.fromEntries(Object.entries({
   core: ['scope.non-escalation', 'external.explicit-user-authority', 'role.orchestrator-boundary'],
-  assignment: ['git.specialists-deny', 'role.scouter-read-only', 'role.planner-draft-only', 'role.coder-implementation', 'role.qa-verification', 'role.reviewer-independent'],
-  planning: ['git.orchestrator-accept-commit', ...reviews],
-  handoff: ['git.specialists-deny', 'role.coder-implementation', ...reviews],
-  preparation: ['scope.non-escalation', 'git.specialists-deny', 'git.orchestrator-accept-commit', 'external.explicit-user-authority'],
-  verification: ['git.orchestrator-accept-commit', ...reviews],
-  commit: ['scope.non-escalation', 'git.orchestrator-accept-commit', 'external.explicit-user-authority'],
+  assignment: ['git.specialists-deny', 'role.scouter-read-only', 'role.planner-draft-only', 'role.implementer-implementation', 'role.qa-verification', 'role.reviewer-independent'],
+  planning: ['git.orchestrator-accept-commit', ...reviews, 'planning.plan-amend', 'planning.planner-brief'],
+  handoff: ['git.specialists-deny', 'role.implementer-implementation', ...reviews],
+  preparation: ['scope.non-escalation', 'git.specialists-deny', 'git.orchestrator-accept-commit', 'external.explicit-user-authority', 'planning.plan-amend'],
+  verification: ['git.orchestrator-accept-commit', ...reviews, 'planning.plan-amend'],
+  commit: ['scope.non-escalation', 'git.orchestrator-accept-commit', 'external.explicit-user-authority', 'planning.plan-amend'],
 }).map(([name, ids]) => [name, Object.freeze(ids)])));
 
 export function validatePolicyProjections(policy, projections = POLICY_PROJECTIONS) {

package/lib/policy/render.mjs

@@ -2,7 +2,7 @@ import {renderSourceClaudeHook} from './claude-hook.mjs';
 import {POLICY_PROJECTIONS, validatePolicyProjections} from './placement.mjs';
 import {validateGitPolicy} from '../../claude/skill/hooks/role-git-guard.mjs';
 import source from './role-policy.json' with {type: 'json'};
-const ROLES = ['orchestrator','scouter','planner','coder','qa','reviewer'];
+const ROLES = ['orchestrator','scouter','planner','implementer','qa','reviewer'];
 const CONTROLS = ['prompt','capability','hook'];
 const fail = message => { throw new Error(`Role policy: ${message}`); };
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -18,10 +18,10 @@ export function validateRolePolicy(input) {
     if (!strings(rule.roles) || rule.roles.some(x=>!ROLES.includes(x)) || !['allow','deny','require'].includes(rule.effect) || !strings(rule.operations) || !strings(rule.evidence) || !['user','orchestrator'].includes(rule.authority) || typeof rule.text !== 'string' || !rule.text || /[\r\n]/.test(rule.text)) fail(`invalid rule ${rule.id}`);
     if (!object(rule.controls) || !same(Object.keys(rule.controls).sort(),['claude','codex']) || Object.values(rule.controls).some(x=>!CONTROLS.includes(x))) fail(`invalid control level for ${rule.id}`);
   }
-  for (const id of ['scope.non-escalation','git.specialists-deny','git.orchestrator-accept-commit','external.explicit-user-authority',...ROLES.map(x=>({orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',coder:'role.coder-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'})[x]),'review.significant-no-plan','review.significant-plan','review.final-plan-recheck']) if(!ids.has(id)) fail(`missing required rule ${id}`);
+  for (const id of ['scope.non-escalation','git.specialists-deny','git.orchestrator-accept-commit','external.explicit-user-authority',...ROLES.map(x=>({orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',implementer:'role.implementer-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'})[x]),'review.significant-no-plan','review.significant-plan','review.final-plan-recheck']) if(!ids.has(id)) fail(`missing required rule ${id}`);
   for (const platform of ['codex','claude']) if (!object(input.platforms?.[platform]) || !CONTROLS.includes(input.platforms[platform].level) || typeof input.platforms[platform].notice !== 'string' || !input.platforms[platform].notice) fail(`invalid ${platform} controls`);
   // These are workflow invariants, not customizable scheduling options.
-  const routes = {noPlan:['coder','qa','reviewer','orchestrator-accept'],planTask:['coder','fresh-qa','orchestrator-accept','orchestrator-commit'],planFinal:['required-qa','reviewer'],planFinding:['coder','reviewer']};
+  const routes = {noPlan:['implementer','qa','reviewer','orchestrator-accept'],planTask:['implementer','fresh-qa','orchestrator-accept','orchestrator-commit'],planFinal:['required-qa','reviewer'],planFinding:['implementer','reviewer']};
   if (!object(input.review) || Object.keys(input.review).length !== 4 || Object.entries(routes).some(([key,value])=>!same(input.review[key],value))) fail('invalid review routing');
   try {validateGitPolicy(input.git);} catch {fail('invalid Git policy');}
   if (!object(input.runtime) || input.runtime.schemaVersion !== 1 || !same(input.runtime.roles,ROLES) || !strings(input.runtime.requiredEvidence) || !strings(input.runtime.ruleIds) || ['platform-identity','user-approval','current-target-versions','resolved-paths'].some(x=>!input.runtime.requiredEvidence.includes(x)) || ['runtime.schema','runtime.policy','runtime.identity','runtime.target','runtime.assignment','runtime.approval','runtime.paths','runtime.docs-commit','runtime.mode','runtime.transition'].some(x=>!input.runtime.ruleIds.includes(x)) || input.runtime.status !== 'decision-only') fail('invalid runtime policy');

package/lib/policy/role-policy.json

@@ -14,7 +14,7 @@
       "description": "Return design, spec and plan drafts to Orchestrator."
     },
     {
-      "id": "coder",
+      "id": "implementer",
       "description": "Implement assigned approved changes and focused checks."
     },
     {
@@ -33,7 +33,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -58,7 +58,7 @@
       "roles": [
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -114,7 +114,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -150,7 +150,7 @@
         "role-ownership"
       ],
       "authority": "orchestrator",
-      "text": "Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it. Use a fresh Coder per top-level task and a fresh QA per top-level task that needs QA; QA findings alone do not create a new task. While approved scope, workspace, ownership and relevant assignment context remain valid, default same-task QA findings to the current Coder and post-fix rechecks to the current QA. Replace or restart a role only when its context is invalid or unavailable, or the task boundary changes; an approved plan or acceptance-criteria amendment requires a fresh Coder even within the task. Before reusing Coder, refresh actual workspace, branch/HEAD and change state; QA reruns the reproduction path and invalidated related checks and reports actual actor, target state, outcomes and limitations. Preserve task-boundary acceptance and the final plan Reviewer correction exception.",
+      "text": "Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Implementer. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it. Use a fresh Implementer per top-level task and a fresh QA per top-level task that needs QA; QA findings alone do not create a new task. While approved scope, workspace, ownership and relevant assignment context remain valid, default same-task QA findings to the current Implementer and post-fix rechecks to the current QA. Replace or restart a role only when its context is invalid or unavailable, or the task boundary changes; an approved plan or acceptance-criteria amendment requires a fresh Implementer even within the task. Before reusing Implementer, refresh actual workspace, branch/HEAD and change state; QA reruns the reproduction path and invalidated related checks and reports actual actor, target state, outcomes and limitations. Preserve task-boundary acceptance and the final plan Reviewer correction exception.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -197,9 +197,9 @@
       }
     },
     {
-      "id": "role.coder-implementation",
+      "id": "role.implementer-implementation",
       "roles": [
-        "coder"
+        "implementer"
       ],
       "effect": "allow",
       "operations": [
@@ -233,7 +233,7 @@
         "criterion-evidence"
       ],
       "authority": "orchestrator",
-      "text": "Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.",
+      "text": "Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Implementer correction and required QA recheck.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -265,7 +265,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -278,7 +278,7 @@
         "qa-rechecks"
       ],
       "authority": "orchestrator",
-      "text": "For significant/high-risk work without a plan: Coder \u2192 QA and required QA rechecks \u2192 Reviewer of the final full change \u2192 Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.",
+      "text": "For significant/high-risk work without a plan: Implementer \u2192 QA and required QA rechecks \u2192 Reviewer of the final full change \u2192 Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -290,7 +290,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -303,7 +303,7 @@
         "required-qa"
       ],
       "authority": "orchestrator",
-      "text": "For significant/high-risk plan work: each task uses Coder \u2192 fresh QA as required \u2192 Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
+      "text": "For significant/high-risk plan work: each task uses Implementer \u2192 fresh QA as required \u2192 Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -315,7 +315,7 @@
         "orchestrator",
         "scouter",
         "planner",
-        "coder",
+        "implementer",
         "qa",
         "reviewer"
       ],
@@ -327,7 +327,52 @@
         "reviewer-findings"
       ],
       "authority": "orchestrator",
-      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Coder \u2192 Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
+      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Implementer \u2192 Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "planning.plan-amend",
+      "roles": [
+        "orchestrator"
+      ],
+      "effect": "require",
+      "operations": [
+        "plan-update",
+        "plan-commit-amend"
+      ],
+      "evidence": [
+        "change-classification",
+        "actual-approval-chronology",
+        "rewrite-safety",
+        "sha-mapping"
+      ],
+      "authority": "orchestrator",
+      "text": "During approved task execution, mechanical plan progress records need no new user approval; changed goals, scope, criteria, method, risk, dependencies or required verification require revised-version approval and preparation before affected work. In both cases Orchestrator amends the original planning-document commit at a safe boundary, without a separate document or fixup commit. Preserve actual approval chronology, recoverable old/new contents, hashes, versions and SHA mappings; never retroactively authorize earlier work. Rewrite only unpublished, unshared local linear history with clear ownership and no merges; stop on unknown publication, ownership, unexpected state or replay conflicts, without force push or a fallback document commit. Preserve implementation task boundaries and revalidate affected evidence. See planning, handoff-prep, commit and verification for the full contract.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "planning.planner-brief",
+      "roles": [
+        "orchestrator"
+      ],
+      "effect": "require",
+      "operations": [
+        "planner-brief",
+        "planner-feedback"
+      ],
+      "evidence": [
+        "complete-stage-brief",
+        "prepared-target",
+        "preceding-approval"
+      ],
+      "authority": "orchestrator",
+      "text": "Before formal drafting, Orchestrator supplies one complete stage-specific brief with original requirements and criteria IDs, approved/open decisions, verified target and ownership, document paths and preceding approved versions, current behavior and connected source/generated/runtime/installer/documentation surfaces, policy conflicts, depth, dependencies, checks, holds and exact deliverable. Preserve shared brief field order. Review the complete draft once and consolidate substantive feedback as changed fields with other fields marked unchanged. Preserve sequential design, spec and plan approvals; no fixed call cap or incomplete drafts, and no calls for already resolved questions.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -337,7 +382,7 @@
   "platforms": {
     "codex": {
       "level": "prompt",
-      "notice": "Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Coder and QA need shell for approved checks."
+      "notice": "Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Implementer and QA need shell for approved checks."
     },
     "claude": {
       "level": "capability",
@@ -346,13 +391,13 @@
   },
   "review": {
     "noPlan": [
-      "coder",
+      "implementer",
       "qa",
       "reviewer",
       "orchestrator-accept"
     ],
     "planTask": [
-      "coder",
+      "implementer",
       "fresh-qa",
       "orchestrator-accept",
       "orchestrator-commit"
@@ -362,7 +407,7 @@
       "reviewer"
     ],
     "planFinding": [
-      "coder",
+      "implementer",
       "reviewer"
     ]
   },
@@ -580,7 +625,7 @@
       "orchestrator",
       "scouter",
       "planner",
-      "coder",
+      "implementer",
       "qa",
       "reviewer"
     ],

package/lib/release/artifact.mjs

@@ -30,7 +30,7 @@ function metadata(pkg,lock,{artifact=false}={}){
   if(artifact?root.hasInstallScript!==true:Object.hasOwn(root,'hasInstallScript'))throw new Error('Package lock install script metadata mismatch');
  }
 }
-function inputNames(pkg){const names=new Set(['README.md','package.json','package-lock.json','MANIFEST.sha256']);for(const entry of pkg.files??[]){const name=entry.replace(/\/$/,'');if(!name||name.startsWith('/')||name.includes('\\')||name.split('/').some(part=>!part||part==='.'||part==='..')||/[*?\[\]]/.test(name))throw new Error('Unsupported package files entry');names.add(name);}return [...names].sort();}
+function inputNames(pkg){const names=new Set(['README.md','package.json','package-lock.json','MANIFEST.sha256']);for(const entry of pkg.files??[]){if(entry==='!**/__pycache__/**'||entry==='!**/*.pyc')continue;const name=entry.replace(/\/$/,'');if(!name||name.startsWith('/')||name.startsWith('!')||name.includes('\\')||name.split('/').some(part=>!part||part==='.'||part==='..')||/[*?\[\]]/.test(name))throw new Error('Unsupported package files entry');names.add(name);}return [...names].sort();}
 function sourceMetadata(root){
  const directory=openRoot(root);
  try{const result={};for(const name of ['package.json','package-lock.json']){const stat=directory.lstat(name);if(typeOf(stat)!==0o100000)throw new Error('Expected regular source metadata: '+name);result[name]=readCheckedFile(directory,name,stat).bytes;}return result;}

package/lib/runtime/acceptance.mjs

@@ -0,0 +1,68 @@
+import path from 'node:path';
+import {fingerprintRequest} from './store.mjs';
+import {validateGitPreflight,validateGitCommitResult} from './git-evidence.mjs';
+import {within} from './scope.mjs';
+const reconciliations=new WeakMap();
+export function verifiedCooperativeReconciliation(decision,state){const proof=reconciliations.get(decision);return !!proof&&proof.before===fingerprintRequest(state)&&proof.after===fingerprintRequest(decision.proposedTransition);}
+const completed=(state,id)=>state.tasks?.some(t=>t.id===id&&t.status==='committed'&&!t.invalidated)&&state.commits?.some(c=>c.taskId===id&&c.observationSource==='local-git'&&state.intents.some(i=>i.operation==='commit'&&i.requestId===c.requestId&&i.taskId===id&&i.status==='succeeded'));
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const text=v=>typeof v==='string'&&v.length>0;
+const list=v=>Array.isArray(v)&&v.every(text)&&new Set(v).size===v.length;
+const exact=(a,b)=>list(a)&&list(b)&&same([...a].sort(),[...b].sort());
+const fields=(v,keys)=>v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).every(k=>keys.includes(k));
+const semanticLimit='Semantically unrelated hunks inside the same file require Orchestrator inspection; path and byte evidence cannot distinguish them automatically.';
+const base=state=>({expectedRevision:state?.revision??0,coverage:{enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false},semanticLimit,requiredEvidence:[],nextActions:[],proposedTransition:null});
+const hold=(state,reason)=>({...base(state),decision:'hold',ruleIds:['cooperative.acceptance'],reason});
+const allow=(state,transition)=>({...base(state),decision:'allow',ruleIds:['cooperative.acceptance'],proposedTransition:transition});
+const approval=(state,id)=>state.records.filter(r=>r.kind==='approval'&&(!r.data.affectedTaskIds||r.data.affectedTaskIds.includes(id))).at(-1);
+function authorized(state,task){const a=approval(state,task?.id);return state.mode==='plan'&&task&&!task.invalidated&&a?.source==='operator-attested'&&a.targetVersion===state.targetVersion&&task.targetVersion===state.targetVersion&&task.scopeVersion===a.scopeVersion&&task.approvalRef===a.messageRef&&task.approvalVersion===a.data.approvalVersion&&task.documentVersion===a.data.documentVersion;}
+function checkEvidence(state,task,a,changes){
+ if(!same(a.criteria,task.criteria)||!task.criteria.length||!list(a.checkIds)||!list(a.findingIds)||a.changeFingerprint!==changes?.tasks?.[task.id])return false;
+ const checks=state.checks.filter(c=>c.scope==='task'&&c.taskId===task.id);
+ const latest=task.requiredChecks.map(d=>checks.filter(c=>same(c.descriptor,d)).at(-1));
+ if(!task.requiredChecks.length||latest.some(c=>!c||c.stale||c.status!=='passed'||c.verdict!=='proven'||!text(c.resultRef)||c.source!=='operator-attested'||c.verificationActor?.role!=='qa'||!text(c.verificationActor.id)||state.assignments.some(a=>a.agentId===c.verificationActor.id)||c.changeFingerprint!==a.changeFingerprint)||!exact(a.checkIds,latest.map(c=>c?.id)))return false;
+ const findings=state.findings.filter(f=>f.scope==='task'&&f.taskId===task.id);
+ return exact(a.findingIds,findings.map(f=>f.id))&&findings.every(f=>f.status==='closed'&&text(f.resolutionRef)&&text(f.recheckRef)&&f.resolutionActor?.role==='implementer'&&f.recheckActor?.role==='qa'&&f.changeFingerprint===a.changeFingerprint);
+}
+function waitingFor(state,task,predecessor){
+ if(task.status!=='pending'||state.intents.some(i=>i.taskId===task.id&&i.operation==='assign-agent'&&['prepared','unknown','mismatch','succeeded'].includes(i.status)))return false;
+ const seen=new Set(),queue=[...(task.dependencies??[])];while(queue.length){const id=queue.pop();if(id===predecessor)return true;if(seen.has(id))continue;seen.add(id);queue.push(...(state.tasks.find(t=>t.id===id)?.dependencies??[]));}return false;
+}
+function dirtyOtherTask(state,task,git){return git.stagedPaths?.some(name=>state.tasks.some(t=>t.id!==task.id&&!completed(state,t.id)&&!waitingFor(state,t,task.id)&&t.paths.some(p=>within(p,path.join(state.target.realpath,...name.split('/'))))));}
+function freshAcceptance(state,task,acceptance,changes){return acceptance&&!acceptance.stale&&authorized(state,task)&&acceptance.taskFingerprint===fingerprintRequest({...task,status:'pending'})&&same(acceptance.approval,approval(state,task.id))&&same(acceptance.target,state.target)&&same(acceptance.versions,state.versions)&&checkEvidence(state,task,acceptance,changes);}
+/** Operator attests semantic sufficiency; code binds exact current evidence only. */
+export function evaluateCooperativeAcceptance({state,request,evidence}={}){
+ const task=state?.tasks?.find(t=>t.id===request?.taskId),a=request?.arguments,g=evidence?.git;
+ if(request?.expectedRevision!==state?.revision||request.actor?.role!=='orchestrator'||!authorized(state,task)||task.status!=='pending'||state.acceptances.some(v=>v.taskId===task.id&&!v.stale)||state.commits.some(v=>v.taskId===task.id))return hold(state,'Current pending approved task and Orchestrator acceptance required');
+ if(!fields(a,['messageRef','criteria','checkIds','findingIds','changeFingerprint'])||!text(a.messageRef)||!checkEvidence(state,task,a,evidence?.changes)||state.checks.some(c=>a.checkIds?.includes(c.id)&&c.verificationActor?.id===request.actor.id))return hold(state,'Exact criteria, current required QA checks and closed findings required');
+ const descriptor={kind:'task',parent:state.target.head,indexTree:g?.indexTree,fingerprint:g?.stagedFingerprint,paths:g?.stagedPaths};
+ const invalid=validateGitPreflight({target:state.target,descriptor,scope:task.paths,gitEvidence:g});
+ if(invalid||dirtyOtherTask(state,task,g))return hold(state,invalid??'Index includes another task changes');
+ return allow(state,{acceptance:{...structuredClone(a),id:request.requestId,taskId:task.id,actor:structuredClone(request.actor),source:'operator-attested',descriptor:structuredClone(descriptor),taskFingerprint:fingerprintRequest({...task,status:'pending'}),approval:structuredClone(approval(state,task.id)),target:structuredClone(state.target),versions:structuredClone(state.versions)}});
+}
+/** Prepares a durable intent; never stages or executes a commit. */
+export function prepareCooperativeCommit({state,request,gitEvidence,evidence}={}){
+ const task=state?.tasks?.find(t=>t.id===request?.taskId),a=state?.acceptances?.find(a=>a.id===request?.arguments?.acceptanceId&&a.taskId===request.taskId);
+ if(request?.expectedRevision!==state?.revision||request.actor?.role!=='orchestrator'||!fields(request.arguments,['acceptanceId'])||task?.status!=='accepted'||!freshAcceptance(state,task,a,evidence?.changes)||state.commits.some(c=>c.taskId===task.id)||state.intents.some(i=>i.operation==='commit'&&i.taskId===task.id&&['prepared','unknown','mismatch'].includes(i.status)))return hold(state,'Exact current acceptance and no prior task commit or unresolved commit required');
+ const invalid=validateGitPreflight({target:state.target,descriptor:a.descriptor,scope:task.paths,gitEvidence});
+ if(invalid||dirtyOtherTask(state,task,gitEvidence))return hold(state,invalid??'Index includes another task changes');
+ const expected={parent:a.descriptor.parent,tree:a.descriptor.indexTree,paths:[...a.descriptor.paths],fingerprint:a.descriptor.fingerprint,remainingPaths:[...new Set([...gitEvidence.workingPaths,...gitEvidence.untrackedPaths])].sort()};
+ return allow(state,{intent:{requestId:request.requestId,operation:'commit',taskId:task.id,status:'prepared',acceptanceId:a.id,acceptanceFingerprint:fingerprintRequest(a),expected,target:structuredClone(state.target),versions:structuredClone(state.versions),fingerprint:fingerprintRequest(request),source:'operator-attested'}});
+}
+/** Results are local Git observations, correlated with an operator statement.
+ * Mismatch observations remain historical evidence and never rebind the target. */
+export function reconcileCooperativeCommit({state,intent,result,gitEvidence}={}){
+ if(!intent||intent.operation!=='commit'||!['prepared','unknown','mismatch'].includes(intent.status)||state.commits.some(c=>c.taskId===intent.taskId))return hold(state,'Matching unresolved commit intent required; replay cannot authorize another effect');
+ const task=state.tasks.find(t=>t.id===intent.taskId),a=state.acceptances.find(a=>a.id===intent.acceptanceId),g=gitEvidence;
+ const observation=g?structuredClone(g):null;
+ const transition={observation,result:{...structuredClone(result),status:'mismatch',source:'operator-attested'}};
+ const reject=reason=>({...hold(state,reason),proposedTransition:transition});
+ if(!result||!text(result.messageRef)||!fields(result.data,['commit'])||!['succeeded','failed','unknown','mismatch'].includes(result.status))return reject('Exact commit result statement required');
+ if(result.status!=='succeeded'){transition.result.status=result.status;return reject('Execution did not establish a successful commit');}
+ if(task?.status!=='accepted'||!authorized(state,task)||a?.stale||!a||intent.acceptanceFingerprint!==fingerprintRequest(a)||a.taskFingerprint!==fingerprintRequest({...task,status:'pending'})||!same(a.approval,approval(state,task.id))||!checkEvidence(state,task,a,{tasks:{[task.id]:a.changeFingerprint}})||!same(intent.target,state.target)||!same(intent.versions,state.versions)||!g?.commit||result.data.commit!==g.commit.commit||g.stagedPaths?.length||g.indexTree!==g.commit.tree)return reject('Acceptance, observed commit or clean resulting index mismatch');
+ const actual={...g.commit,target:g.target,remainingPaths:[...new Set([...g.workingPaths??[],...g.untrackedPaths??[]])].sort()};
+ const invalid=validateGitCommitResult({target:state.target,expected:intent.expected,result:actual,scope:task.paths});
+ if(invalid)return reject(invalid);
+ transition.result.status='succeeded';transition.commit={...actual,taskId:task.id,requestId:intent.requestId,acceptanceId:a.id,source:'operator-attested',observationSource:'local-git',fingerprint:a.changeFingerprint};transition.target=structuredClone(g.target);
+ const decision=allow(state,transition);reconciliations.set(decision,{before:fingerprintRequest(state),after:fingerprintRequest(transition)});return decision;
+}

package/lib/runtime/assignment.mjs

@@ -0,0 +1,42 @@
+import {fingerprintRequest} from './store.mjs';
+import {absolute,within} from './scope.mjs';
+const completed=(state,id)=>state.tasks?.some(t=>t.id===id&&t.status==='committed'&&!t.invalidated)&&state.commits?.some(c=>c.taskId===id&&c.observationSource==='local-git'&&state.intents.some(i=>i.operation==='commit'&&i.requestId===c.requestId&&i.taskId===id&&i.status==='succeeded'));
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const text=value=>typeof value==='string'&&value.length>0;
+const version=value=>Number.isSafeInteger(value)&&value>0;
+const setEqual=(a,b)=>Array.isArray(a)&&Array.isArray(b)&&new Set(a).size===a.length&&new Set(b).size===b.length&&same([...a].sort(),[...b].sort());
+const base=state=>({expectedRevision:state?.revision??0,coverage:{enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false},requiredEvidence:[],nextActions:[],proposedTransition:null});
+const hold=(state,id,reason)=>({...base(state),decision:'hold',ruleIds:['cooperative.'+id],reason});
+/** Pure gate. observations are supplied by trusted local readers, never JSON input. */
+export function prepareCooperativeAssignment({policy,state,request,observations}={}){
+ if(policy!==undefined&&policy.workflowKind!=='cooperative')return hold(state,'contract','Explicit cooperative contract required');
+ const args=request?.arguments;
+ if(state?.mode!=='plan'||request?.operation!=='assign-agent'||!args)return hold(state,'unsupported','Only explicit plan assignment is supported');
+ const allowed=['role','paths','operations','documents','approvalRef','approvalVersion','documentVersion','correlation'];
+ if(Object.keys(args).some(k=>!allowed.includes(k))||args.role!=='implementer'||!text(request.taskId)||!text(request.requestId)||!text(args.correlation)||!text(args.approvalRef)||!version(args.approvalVersion)||!version(args.documentVersion)||!Array.isArray(args.paths)||!args.paths.length||new Set(args.paths).size!==args.paths.length||args.paths.some(p=>!absolute(p)||!within(state.target.realpath,p))||!Array.isArray(args.operations)||!args.operations.length||args.operations.some(o=>o!=='edit'))return hold(state,'assignment','Invalid assignment or unsupported historical agent import');
+ if(!same(observations?.target,state.target)||!same(observations?.git?.target,state.target))return hold(state,'target','Re-observe target and renew approval after drift');
+ if(request.expectedRevision!==state.revision)return hold(state,'revision','Stale assignment request');
+ if(state.records.some(r=>r.data?.priorExecution===true)||state.assignments.some(a=>a.source!=='operator-attested'))return hold(state,'history','Earlier execution remains unverified; a late commit cannot authorize it');
+ if(state.intents.some(i=>i.operation==='assign-agent'&&['prepared','unknown','mismatch','succeeded'].includes(i.status)&&(i.taskId===request.taskId||i.correlation===args.correlation||!(i.status==='succeeded'&&completed(state,i.taskId))&&i.paths?.some(p=>args.paths.some(q=>within(p,q)||within(q,p))))))return hold(state,'assignment-active','Resolve the existing dispatch before preparing another');
+ const task=state.tasks?.find(t=>t.id===request.taskId);
+ if(task&&(task.invalidated||task.status==='held'||task.dependencies?.some(id=>{const predecessor=state.tasks.find(t=>t.id===id);return !predecessor||predecessor.invalidated||!['accepted','committed'].includes(predecessor.status);})))return hold(state,'task-stale','Affected task or predecessor requires renewed readiness and approval');
+ const scope=state.scopes?.findLast(s=>s.scopeVersion===state.scopeVersion&&(!s.data.affectedTaskIds||s.data.affectedTaskIds.includes(request.taskId)));
+ if(!task||!task.paths?.length||args.paths.some(p=>!task.paths.some(base=>within(base,p)))||scope&&args.paths.some(p=>!scope.data.paths?.some(base=>within(base,p))))return hold(state,'assignment-scope','Assignment must stay inside approved task and recorded scope');
+ const documents=args.documents,git=observations.git;
+ if(!Array.isArray(documents)||documents.length!==2||!setEqual(documents.map(d=>d.kind),['spec','plan'])||!git.docsCommit||!setEqual(git.docsCommit.paths,documents.map(d=>d.gitPath))||!same(git.docsCommit.documents,documents)||documents.some(d=>d.commit!==git.docsCommit.commit)||!Array.isArray(git.documents)||git.documents.length!==2||documents.some(d=>!git.documents.some(o=>o.path===d.path&&o.gitPath===d.gitPath&&o.kind===d.kind&&o.observedHash===d.contentHash&&o.currentHash===d.contentHash)))return hold(state,'documents','Exact committed spec and plan plus current bytes must match approval');
+ const approval=state.records.filter(r=>r.kind==='approval'&&(!r.data.affectedTaskIds||r.data.affectedTaskIds.includes(request.taskId))).at(-1);
+ if(task.approvalRef!==args.approvalRef||task.approvalVersion!==args.approvalVersion||task.documentVersion!==args.documentVersion||task.scopeVersion!==state.scopeVersion||task.targetVersion!==state.targetVersion||!approval||approval.source!=='operator-attested'||approval.messageRef!==args.approvalRef||approval.targetVersion!==state.targetVersion||approval.scopeVersion!==state.scopeVersion||approval.data.approvalVersion!==args.approvalVersion||approval.data.documentVersion!==args.documentVersion||!same(approval.data.documents,documents)||documents.some(d=>d.approvalRef!==args.approvalRef))return hold(state,'approval','Current document and approval versions must match');
+ const intent={requestId:request.requestId,taskId:request.taskId,operation:request.operation,status:'prepared',role:args.role,paths:[...args.paths],operations:[...args.operations],correlation:args.correlation,documents:structuredClone(documents),docsCommit:git.docsCommit.commit,approvalRef:args.approvalRef,approvalVersion:args.approvalVersion,documentVersion:args.documentVersion,target:structuredClone(state.target),targetVersion:state.targetVersion,scopeVersion:state.scopeVersion,revision:state.revision+1,fingerprint:fingerprintRequest(request),source:'operator-attested'};
+ return {...base(state),decision:'allow',ruleIds:['cooperative.assignment-prepared'],proposedTransition:{intent}};
+}
+/** A native response is an operator statement, not authenticated identity or compliance. */
+export function recordCooperativeAssignmentResult({state,intent,result,observations}={}){
+ if(!intent||intent.operation!=='assign-agent')return hold(state,'intent','No matching assignment intent');
+ if(!['prepared','unknown','mismatch'].includes(intent.status))return hold(state,'assignment-terminal','Preserve the prior terminal native response');
+ if(!result||!['succeeded','failed','unknown','mismatch'].includes(result.status)||!text(result.messageRef)||!result.data)return hold(state,'assignment-result','Invalid native result statement');
+ if(result.status==='succeeded'&&(state.assignments.some(a=>a.agentId===result.data.agentId&&a.taskId!==intent.taskId)||state.intents?.some(i=>i.verificationActor?.id===result.data.agentId)||state.checks?.some(c=>c.verificationActor?.id===result.data.agentId)))return hold(state,'assignment-freshness','Implementer actor statements cannot cross tasks');
+ let status=result.status;
+ if(!same(intent.target,observations?.target)||result.data.correlation!==intent.correlation||result.data.taskId!==intent.taskId||status==='succeeded'&&!text(result.data.agentId))status='mismatch';
+ const entry={...structuredClone(result),status,requestId:intent.requestId,source:'operator-attested'};
+ return {...base(state),decision:['succeeded','failed'].includes(status)?'allow':'hold',ruleIds:['cooperative.assignment-'+status],proposedTransition:{result:entry}};
+}

package/lib/runtime/bootstrap.mjs

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {validateCooperativeCommand,validateCooperativeState} from './cooperative-schema.mjs';
+import {observeCooperativeTarget,validateObservedTarget,validateWorkflowId,workflowStatePath,inspectPath} from './scope.mjs';
+import {saveDurableState} from './store.mjs';
+export const COOPERATIVE_RUNTIME_MODULES=Object.freeze([
+ 'bootstrap.mjs','cooperative-schema.mjs','cooperative.mjs','evaluate.mjs',
+ 'scope.mjs','store.mjs','git-evidence.mjs','assignment.mjs','verification.mjs','acceptance.mjs','external.mjs'
+]);
+export const cooperativeCoverage=()=>({enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false});
+export function commandResult({workflowId,state,input,decision='allow',ruleId='cooperative.recorded',persisted=false,...extra}){
+ return {decision,ruleIds:[ruleId],workflowId,taskId:input?.taskId??null,requestId:input?.requestId??null,revision:state?.revision??0,coverage:cooperativeCoverage(),requiredEvidence:[],nextActions:[],persisted,...extra};
+}
+export async function cooperativeVersions(){
+ const hash=bytes=>'sha256:'+crypto.createHash('sha256').update(bytes).digest('hex');
+ let policy;try{policy=await fs.readFile(new URL('../policy/role-policy.json',import.meta.url));}catch(error){if(error.code!=='ENOENT')throw error;policy=await fs.readFile(new URL('./role-policy.json',import.meta.url));}
+ const runtime=await Promise.all(COOPERATIVE_RUNTIME_MODULES.map(file=>fs.readFile(new URL(file,import.meta.url))));
+ return {policy:'1',runtime:'cooperative-1',policyHash:hash(policy),runtimeHash:hash(Buffer.concat(runtime))};
+}
+export async function initializeCooperativeWorkflow({cwd,workflowId,input,observe=observeCooperativeTarget,storage={}}){
+ validateWorkflowId(workflowId);validateCooperativeCommand({command:'init',input});
+ if(input.mode!=='plan')return commandResult({workflowId,input,decision:'hold',ruleId:'cooperative.unsupported'});
+ const target=await validateObservedTarget(cwd,await observe(cwd));const statePath=await workflowStatePath(target,workflowId);
+ const parent=path.dirname(statePath);await fs.mkdir(parent,{recursive:true,mode:0o700});await inspectPath(parent,{directory:true});
+ const lockPath=statePath+'.lock';let lock;
+ try{
+  lock=await fs.open(lockPath,'wx',0o600);await inspectPath(statePath,{missing:true});
+  const state={schemaVersion:1,workflowKind:'cooperative',contractVersion:1,workflowId,revision:0,mode:'plan',coverage:cooperativeCoverage(),versions:await cooperativeVersions(),target,targetVersion:1,scopeVersion:0};
+  for(const key of ['actors','selections','assignments','identities','leases','scopes','approvals','documents','tasks','requests','intents','results','checks','findings','acceptances','commits','audit','unresolved','records','targetHistory'])state[key]=[];
+  state.actors.push({actor:input.actor,source:'operator-attested'});state.selections.push({...input.selection,actor:input.actor,source:'operator-attested',targetVersion:1});
+  state.audit.push({command:'init',revision:0,source:'operator-attested',actor:input.actor});validateCooperativeState(state);
+  await saveDurableState({statePath,state,create:true,storage});return commandResult({workflowId,state,input,persisted:true,ruleId:'cooperative.initialized'});
+ }finally{if(lock){await lock.close();await fs.unlink(lockPath);}}
+}

package/lib/runtime/cooperative-schema.mjs

@@ -0,0 +1,55 @@
+import {ROLES} from './operations.mjs';
+import {assertSecretFree} from './external.mjs';
+import {object,text} from './schema.mjs';
+import {absolute,validateWorkflowId} from './scope.mjs';
+const fail=message=>{throw Error('Cooperative schema: '+message);};
+const hash=value=>typeof value==='string'&&/^sha256:[a-f0-9]{64}$/.test(value);
+const revision=value=>Number.isSafeInteger(value)&&value>=0;
+const actor=value=>object(value)&&text(value.id)&&Object.keys(value).every(k=>['id','role'].includes(k))&&(value.role===undefined||ROLES.includes(value.role));
+const statement=value=>object(value)&&text(value.messageRef)&&object(value.data);
+function fields(value,allowed){if(!object(value)||Object.keys(value).some(k=>!allowed.includes(k)))fail('unexpected input field');}
+function json(value){try{const encoded=JSON.stringify(value);if(encoded===undefined)fail('JSON input');}catch{fail('JSON input');}}
+export function validateCooperativeCommand(command){
+ assertSecretFree(command);fields(command,['command','input']);const {input,command:name}=command;
+ if(!['init','record','status','reconcile','prepare','result'].includes(name))fail('command');
+ if(name==='status'){if(input!==undefined)fail('status takes no input');return command;}
+ const resultStatement=name==='reconcile'||name==='result'&&input?.operation===undefined;
+ const allowed=name==='init'?['mode','actor','selection']:name==='record'?['requestId','expectedRevision','actor','evidence']:resultStatement?['requestId','expectedRevision','actor','intentId','result']:['requestId','expectedRevision','actor','operation','taskId','arguments'];
+ fields(input,allowed);json(input);
+ if(!actor(input.actor))fail('actor attestation');
+ if(name==='init'){
+  if(!['plan','no-plan','small-task'].includes(input.mode)||!object(input.selection)||!text(input.selection.messageRef)||!hash(input.selection.contentHash)||Object.keys(input.selection).some(k=>!['messageRef','contentHash'].includes(k)))fail('target selection');
+  return command;
+ }
+ if(!text(input.requestId)||input.requestId.length>128||!revision(input.expectedRevision))fail('request identity or revision');
+ if(name==='record'){
+  fields(input.evidence,['kind','messageRef','data']);
+  if(input.evidence?.data?.affectedTaskIds!==undefined&&(!Array.isArray(input.evidence.data.affectedTaskIds)||!input.evidence.data.affectedTaskIds.every(text)||new Set(input.evidence.data.affectedTaskIds).size!==input.evidence.data.affectedTaskIds.length))fail('affected task IDs');
+  if(!statement(input.evidence)||!['note','approval','external-approval','document','scope','check','finding','review','acceptance-evidence'].includes(input.evidence.kind))fail('evidence');
+ }
+ if(resultStatement){
+  fields(input.result,['status','messageRef','data','notExecutedEvidence']);
+  if(!text(input.intentId)||!statement(input.result)||!['succeeded','failed','unknown','mismatch','cancelled'].includes(input.result.status))fail('result evidence');
+  if(input.result.status==='cancelled'&&(!object(input.result.notExecutedEvidence)||!text(input.result.notExecutedEvidence.messageRef)))fail('cancel requires not-executed evidence');
+ }
+ if((name==='prepare'||name==='result'&&!resultStatement)&&!text(input.operation))fail('operation');
+ return command;
+}
+export function validateCooperativeState(state){
+ if(!object(state)||state.workflowKind!=='cooperative'||state.contractVersion!==1||state.schemaVersion!==1||!revision(state.revision)||state.mode!=='plan')fail('explicit cooperative contract');
+ validateWorkflowId(state.workflowId);
+ if(!object(state.target)||!absolute(state.target.realpath)||!absolute(state.target.gitCommonDir)||!absolute(state.target.gitDir)||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(state.target.head)||!(state.target.branch===null||text(state.target.branch)))fail('target');
+ if(!object(state.versions)||!text(state.versions.policy)||!text(state.versions.runtime)||!hash(state.versions.policyHash)||!hash(state.versions.runtimeHash))fail('versions');
+ if(!object(state.coverage)||state.coverage.provenance!=='operator-attested'||state.coverage.nativeVerified!==false||state.coverage.enforcement!=='cooperative')fail('coverage');
+ for(const key of ['actors','selections','assignments','identities','leases','scopes','approvals','documents','tasks','requests','intents','results','checks','findings','acceptances','commits','audit','unresolved','records','targetHistory'])if(!Array.isArray(state[key]))fail(key);
+ if(state.tasks.some(t=>!object(t)||!text(t.id)||!Array.isArray(t.paths)||!Array.isArray(t.criteria)||!Array.isArray(t.requiredChecks)||!Array.isArray(t.dependencies))||new Set(state.tasks.map(t=>t.id)).size!==state.tasks.length)fail('task contracts');
+ if(state.commitObservations!==undefined&&(!Array.isArray(state.commitObservations)||state.commitObservations.some(o=>!object(o)||o.source!=='local-git'||!text(o.intentId)||!revision(o.revision))))fail('commit observations');
+ if(!revision(state.scopeVersion)||!revision(state.targetVersion))fail('scope/target version');
+ if(state.actors.some(a=>!actor(a.actor)||a.source!=='operator-attested')||state.selections.some(s=>s.source!=='operator-attested'||!text(s.messageRef)))fail('attestations');
+ for(const key of ['scopes','approvals','documents','checks','findings','acceptances','commits'])if(state[key].some(entry=>!object(entry)||entry.source!=='operator-attested'))fail('attestation source');
+ if(state.records.some(r=>!actor(r.actor)||r.source!=='operator-attested'||!text(r.kind)||!statement(r)))fail('records');
+ if(state.requests.some(r=>!text(r.requestId)||!hash(r.requestFingerprint)||!object(r.decision))||new Set(state.requests.map(r=>r.requestId)).size!==state.requests.length)fail('request replay');
+ if(state.intents.some(i=>!text(i.requestId)||!['prepared','succeeded','failed','unknown','mismatch','cancelled'].includes(i.status)||!hash(i.fingerprint))||new Set(state.intents.map(i=>i.requestId)).size!==state.intents.length)fail('intents');
+ if(state.results.some(r=>!text(r.requestId)||!['succeeded','failed','unknown','mismatch','cancelled'].includes(r.status)||r.source!=='operator-attested'||!object(r.data)))fail('results');
+ assertSecretFree(state);json(state);return state;
+}