@agilno-tech/rivet 0.1.0-alpha.0 → 0.1.0-alpha.2

package/src/feature/decisions.js

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { types } from 'node:util';
+import { containsSecretMaterial } from '../clients/contract.js';
+
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const INPUT = ['id', 'tier', 'title', 'options', 'choice', 'rationale', 'approvedPlanDecisionId'];
+const RECORD = ['schemaVersion', ...INPUT, 'runId', 'requestDigest', 'planDigest', 'actor', 'createdAt', 'status', 'approval', 'digest'];
+const BINDINGS = ['runId', 'requestDigest', 'planDigest'];
+const CONTEXT = [...BINDINGS, 'actor', 'now', 'approvedPlanDecisions', 'secretValues', 'humanConfirmed'];
+
+export class DecisionError extends Error {
+  constructor(reason = 'invalid-decision') {
+    super({
+      'invalid-decision': 'Decision data is invalid.',
+      'secret-material': 'Decision data contains sensitive material. Remove credentials before recording it.',
+      'binding-mismatch': 'Decision does not match the current task and approved plan.',
+      'digest-mismatch': 'Decision content changed after it was recorded.',
+      'plan-reference-required': 'Tier 0 requires a matching decision reference from the approved plan.',
+      'human-confirmation-required': 'This decision requires explicit human confirmation.',
+      'approval-conflict': 'Only a pending decision can be approved. Read the current decision before retrying.',
+    }[reason] ?? 'Decision data is invalid.');
+    this.name = 'DecisionError';
+    this.code = 'ERR_INVALID_DECISION';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+const fail = reason => { throw new DecisionError(reason); };
+
+function record(value, allowed, required = allowed) {
+  if (!value || typeof value !== 'object' || types.isProxy(value) || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const keys = Reflect.ownKeys(value);
+  if (keys.length > allowed.length || keys.some(key => typeof key !== 'string' || !allowed.includes(key))) fail();
+  const copy = {};
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value') || descriptor.value === undefined) fail();
+    Object.defineProperty(copy, key, { value: descriptor.value, enumerable: true });
+  }
+  if (required.some(key => !Object.hasOwn(copy, key))) fail();
+  return copy;
+}
+function array(value, max, min = 0) {
+  if (!Array.isArray(value) || types.isProxy(value) || Object.getPrototypeOf(value) !== Array.prototype) fail();
+  const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
+  if (!Number.isInteger(length) || length < min || length > max) fail();
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== length + 1) fail();
+  const result = [];
+  for (let index = 0; index < length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value') || descriptor.value === undefined) fail();
+    result.push(descriptor.value);
+  }
+  return result;
+}
+function text(value, max, secrets) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > max || value.trim() !== value
+    || /[\u0000-\u001f\u007f-\u009f\p{Cf}]/u.test(value)) fail();
+  if (containsSecretMaterial(value) || /\b(?:npm_|glpat-|hf_)[A-Za-z0-9_-]{16,}\b/.test(value) || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(value)
+    || /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@:]+:[^\s/@]+@/i.test(value)
+    || secrets.some(secret => value.includes(secret))) fail('secret-material');
+  return value;
+}
+function id(value, secrets = []) {
+  if (typeof value !== 'string' || value.length > 64 || !ID.test(value)) fail();
+  return text(value, 64, secrets);
+}
+function digest(value) { if (typeof value !== 'string' || !DIGEST.test(value)) fail(); return value; }
+function instant(value) {
+  if (typeof value !== 'string' || value.length !== 24 || !Number.isFinite(Date.parse(value))
+    || new Date(value).toISOString() !== value) fail();
+  return value;
+}
+function actor(value, secrets) {
+  const result = record(value, ['kind', 'id']);
+  if (!['human', 'agent'].includes(result.kind)) fail();
+  return { kind: result.kind, id: text(result.id, 128, secrets) };
+}
+function context(value, mode = 'validate') {
+  const result = record(value, CONTEXT, mode === 'validate' ? BINDINGS : [...BINDINGS, 'actor', 'now']);
+  id(result.runId); digest(result.requestDigest); digest(result.planDigest);
+  const secrets = result.secretValues === undefined ? [] : array(result.secretValues, 64).map(secret => {
+    if (typeof secret !== 'string' || !secret || secret.length > 4096) fail();
+    return secret;
+  });
+  const approved = result.approvedPlanDecisions === undefined ? [] : array(result.approvedPlanDecisions, 128).map(item => {
+    const reference = record(item, ['id', 'choice']);
+    return { id: id(reference.id), choice: id(reference.choice) };
+  });
+  if (new Set(approved.map(item => item.id)).size !== approved.length) fail();
+  return { ...result, secretValues: secrets, approvedPlanDecisions: approved,
+    ...(result.actor === undefined ? {} : { actor: actor(result.actor, secrets) }),
+    ...(result.now === undefined ? {} : { now: instant(result.now) }),
+  };
+}
+function input(value, ctx, stored = false) {
+  const source = record(value, INPUT, stored ? INPUT : INPUT.filter(key => key !== 'approvedPlanDecisionId'));
+  if (!Number.isInteger(source.tier) || source.tier < 0 || source.tier > 3) fail();
+  const options = array(source.options, 8, 2).map(option => {
+    const candidate = record(option, ['id', 'description']);
+    return { id: id(candidate.id, ctx.secretValues), description: text(candidate.description, 1000, ctx.secretValues) };
+  });
+  if (new Set(options.map(option => option.id)).size !== options.length || !options.some(option => option.id === source.choice)) fail();
+  if (Object.hasOwn(source, 'approvedPlanDecisionId') && source.approvedPlanDecisionId !== null && typeof source.approvedPlanDecisionId !== 'string') fail();
+  const reference = source.approvedPlanDecisionId ?? null;
+  if (source.tier === 0) {
+    if (!reference || !ctx.approvedPlanDecisions.some(item => item.id === reference && item.choice === source.choice)) fail('plan-reference-required');
+    id(reference, ctx.secretValues);
+  } else if (reference !== null) fail();
+  return { id: id(source.id, ctx.secretValues), tier: source.tier, title: text(source.title, 160, ctx.secretValues), options,
+    choice: id(source.choice, ctx.secretValues), rationale: text(source.rationale, 4000, ctx.secretValues), approvedPlanDecisionId: reference };
+}
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value !== null && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+function hash(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+function freeze(value) {
+  if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
+  return value;
+}
+function sealed(value) { return freeze({ ...value, digest: hash(value) }); }
+
+export function createDecision(value, suppliedContext) {
+  const ctx = context(suppliedContext, 'create');
+  const fields = input(value, ctx);
+  return sealed({ schemaVersion: 1, ...fields, runId: ctx.runId, requestDigest: ctx.requestDigest,
+    planDigest: ctx.planDigest, actor: ctx.actor, createdAt: ctx.now,
+    status: fields.tier < 2 ? 'recorded' : 'pending', approval: null });
+}
+
+export function validateDecision(value, suppliedContext) {
+  const ctx = context(suppliedContext);
+  const source = record(value, RECORD);
+  if (source.schemaVersion !== 1) fail();
+  for (const key of BINDINGS) if (source[key] !== ctx[key]) fail('binding-mismatch');
+  const fields = input(Object.fromEntries(INPUT.map(key => [key, source[key]])), ctx, true);
+  if (!['recorded', 'pending', 'approved'].includes(source.status)
+    || (fields.tier < 2 ? source.status !== 'recorded' : source.status === 'recorded')) fail();
+  const result = { schemaVersion: 1, ...fields, runId: ctx.runId, requestDigest: ctx.requestDigest,
+    planDigest: ctx.planDigest, actor: actor(source.actor, ctx.secretValues), createdAt: instant(source.createdAt),
+    status: source.status, approval: null };
+  if (source.status === 'approved') {
+    const approval = record(source.approval, ['actor', 'approvedAt', 'decisionDigest']);
+    const approvedBy = actor(approval.actor, ctx.secretValues);
+    if (approvedBy.kind !== 'human' || instant(approval.approvedAt) < result.createdAt) fail();
+    if (digest(approval.decisionDigest) !== hash({ ...result, status: 'pending' })) fail('digest-mismatch');
+    result.approval = { actor: approvedBy, approvedAt: approval.approvedAt, decisionDigest: approval.decisionDigest };
+  } else if (source.approval !== null) fail();
+  if (digest(source.digest) !== hash(result)) fail('digest-mismatch');
+  return sealed(result);
+}
+
+export function approveDecision(value, suppliedContext) {
+  const ctx = context(suppliedContext, 'approve');
+  if (ctx.humanConfirmed !== true || ctx.actor.kind !== 'human') fail('human-confirmation-required');
+  const original = validateDecision(value, ctx);
+  if (original.status !== 'pending') fail('approval-conflict');
+  if (ctx.now < original.createdAt) fail();
+  const { digest: previousDigest, ...fields } = original;
+  return sealed({ ...fields, status: 'approved', approval: { actor: ctx.actor, approvedAt: ctx.now, decisionDigest: previousDigest } });
+}
+
+function markdown(value) {
+  // Encode Markdown punctuation and HTML to prevent links, mentions and injected structure.
+  return value.replace(/[&<>"'`*_{}[\]()#+.!|\\@~-]/g, character => `&#${character.codePointAt(0)};`);
+}
+export function renderDecisions(values, suppliedContext) {
+  const ctx = context(suppliedContext);
+  const decisions = array(values, 128).map(value => validateDecision(value, ctx));
+  if (new Set(decisions.map(item => item.id)).size !== decisions.length) fail();
+  const lines = ['## Decisions', '', 'Decision records do not grant execution, file access, merge, deployment, or other permissions.'];
+  if (!decisions.length) return `${lines.join('\n')}\n\nNo decisions recorded.\n`;
+  for (const decision of decisions) {
+    lines.push('', `### ${markdown(decision.title)}`, '', `Tier ${decision.tier} · ${decision.status}`,
+      `Decision: ${markdown(decision.id)}`, `Choice: ${markdown(decision.choice)}`, `Rationale: ${markdown(decision.rationale)}`,
+      `Recorded by: ${markdown(decision.actor.id)} (${decision.actor.kind}) at ${decision.createdAt}`, '', 'Options:');
+    for (const option of decision.options) lines.push(`- ${markdown(option.id)}: ${markdown(option.description)}`);
+    if (decision.approvedPlanDecisionId) lines.push('', `Approved plan reference: ${markdown(decision.approvedPlanDecisionId)}`);
+    if (decision.approval) lines.push('', `Confirmed by: ${markdown(decision.approval.actor.id)} at ${decision.approval.approvedAt}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/feature/governance.js

@@ -0,0 +1,203 @@
+import {createHash} from 'node:crypto';
+import {isDeepStrictEqual} from 'node:util';
+import {immutableJson,containsSecretMaterial} from '../clients/contract.js';
+import {loadProjectConfig,parseYaml} from '../config/load.js';
+import {createSnapshotStore,readSnapshotWithoutLock} from '../state/snapshot-store.js';
+import {governancePaths,resolveExistingFeatureRunPaths,acceptedIntegrationPaths} from '../state/paths.js';
+import {createFeatureRunStore} from './run-store.js';
+import {createAcceptedIntegrationStore} from './accepted-integration.js';
+import {acquireHostRunLock} from './host-run-lock.js';
+import {createDecision,validateDecision,approveDecision,renderDecisions} from './decisions.js';
+import {normalizeReviewPolicy,evaluateReviewReports} from '../quality/content-review.js';
+import {scanChangedContent,validateContentScanPolicy} from '../quality/content-scan.js';
+
+export class GovernanceError extends Error {
+  constructor(message='Task decision or review evidence is invalid or stale.') {
+    super(message);this.name='GovernanceError';this.code='ERR_TASK_GOVERNANCE';this.safeMessage=message;
+  }
+}
+const fail=message=>{throw new GovernanceError(message);};
+const digest=value=>createHash('sha256').update(typeof value==='string'?value:JSON.stringify(value)).digest('hex');
+const binding=run=>({runId:run.runId,requestDigest:run.workRequest.digest,planDigest:run.proposalDigest});
+const sameBinding=(left,right)=>Object.entries(right).every(([key,value])=>left[key]===value);
+const approved=decisions=>decisions.filter(value=>value.status==='approved').map(({id,choice})=>({id,choice}));
+
+async function journal(paths,run) {
+  const selected=await governancePaths(paths), snapshot=await readSnapshotWithoutLock(selected);
+  const events=snapshot?.data?.events??[];
+  if(snapshot&&(snapshot.data.schemaVersion!==1||!sameBinding(snapshot.data,binding(run))
+    ||!Array.isArray(events)||events.length>1000||Buffer.byteLength(JSON.stringify(snapshot.data))>1024*1024))fail();
+  const decisions=new Map(),reviews=[];
+  for(const event of events){
+    if(!event||!['decision.recorded','decision.approved','review.recorded','scan.recorded'].includes(event.type))fail();
+    if(event.type.startsWith('decision.')){
+      const context={...binding(run),approvedPlanDecisions:approved([...decisions.values()])};
+      const value=validateDecision(event.data,context),prior=decisions.get(value.id);
+      if(event.type==='decision.recorded' ? prior!==undefined : !prior||prior.status!=='pending'||value.status!=='approved')fail();
+      if(prior&&value.approval?.decisionDigest!==prior.digest)fail();
+      decisions.set(value.id,value);
+    }else if(event.type==='review.recorded'){
+      if(!sameBinding(event.subject,binding(run)))fail();
+      evaluateReviewReports(event.policy,event.subject,[event.data]);reviews.push(event);
+    }
+  }
+  return {paths:selected,version:snapshot?.version??0,events,decisions:[...decisions.values()],reviews};
+}
+async function append(state,run,event){
+  const data={schemaVersion:1,...binding(run),events:[...state.events,event]};
+  if(data.events.length>1000||Buffer.byteLength(JSON.stringify(data))>1024*1024)fail('Task evidence storage limit reached. Start a new bounded task.');
+  await createSnapshotStore(state.paths,{environment:{}}).write(data,{expectedVersion:state.version});
+}
+async function inputs(project,runId){
+  const paths=await resolveExistingFeatureRunPaths(project,runId);if(!paths)fail('Task was not found.');
+  const run=await createFeatureRunStore(paths).readOnly();if(!run)fail();
+  return {paths,run};
+}
+
+export async function assertGovernancePolicy({project,baselineCommit,gitClient,config}) {
+  const baselineQuality=await gitClient.readCommittedFile(project,baselineCommit,'.rivet/quality.yaml');
+  if(!baselineQuality){
+    if(config.quality.review!==undefined||config.quality.contentScan!==undefined)
+      fail('Commit the quality policy before proposing a task with review or content scanning.');
+    return; // Preserve existing local-only configuration when governance is not enabled.
+  }
+  if(!isDeepStrictEqual(parseYaml(baselineQuality.content,'quality.yaml'),config.quality))
+    fail('Quality policy changed since the task was proposed. Restore the approved policy or propose a new task.');
+}
+
+export async function inspectGovernance({project,run,gitClient,config,phase,checkout,forceReview=false}) {
+  const paths=await resolveExistingFeatureRunPaths(project,run.runId);if(!paths)fail();
+  const state=await journal(paths,run);
+  const configured=config??await loadProjectConfig(project);
+  await assertGovernancePolicy({project,baselineCommit:run.featurePlan.baselineCommit,gitClient,config:configured});
+  const policy=normalizeReviewPolicy(forceReview?{...configured.quality.review,required:true}:configured.quality.review);
+  const selectedPhase=phase??(run.status==='proposed'?'plan':'final');
+  if(!['plan','final'].includes(selectedPhase))fail();
+  let target=checkout;
+  if(selectedPhase==='final'&&!target){
+    const accepted=await createAcceptedIntegrationStore(await acceptedIntegrationPaths(paths)).readOnly();
+    if(accepted)target={path:accepted.path,commitSha:accepted.commitSha,branch:accepted.branch};
+  }
+  const baseSha=run.featurePlan.baselineCommit;
+  let headSha=baseSha,patch='',changedPaths=[];
+  if(target){
+    const identity=await gitClient.inspectRepository(target.path);
+    if(identity.dirty||identity.headSha!==target.commitSha||identity.branch!==target.branch)fail('Review checkout changed. Inspect task status before continuing.');
+    headSha=target.commitSha;
+    changedPaths=await gitClient.changedPaths(target.path,baseSha,headSha);
+    if(policy.required||state.reviews.length)patch=(await gitClient.reviewDiff(target.path,{fromSha:baseSha,toSha:headSha})).patch;
+  }
+  const subject={phase:selectedPhase,...binding(run),baseSha,headSha,
+    diffDigest:digest(selectedPhase==='plan'?run.featurePlan:patch),
+    acceptanceCriteria:run.workRequest.acceptanceCriteria,
+    planNodeIds:run.featurePlan.nodes.filter(node=>node.role==='worker').map(node=>node.id),
+    criterionPlanNodeIds:run.workRequest.acceptanceCriteria.map(criterion=>run.featurePlan.nodes.filter(node=>node.role==='worker'&&node.acceptanceCriteria.includes(criterion)).map(node=>node.id)),changedPaths,
+    workerActorIds:['host-agent',...run.featurePlan.nodes.filter(node=>node.role==='worker').map(node=>node.id)]};
+  // Historical reports remain auditable; only reports for these exact inputs can satisfy a gate.
+  const phaseReviews=state.reviews.filter(event=>event.subject.phase===selectedPhase);
+  const reports=phaseReviews.filter(event=>event.subject.headSha===headSha
+    &&event.subject.diffDigest===subject.diffDigest).map(event=>event.data);
+  const evaluated=evaluateReviewReports(policy,subject,reports);
+  // Corrections consume the task phase's budget even when their new inputs invalidate old evidence.
+  const rounds=Math.max(0,...phaseReviews.map(event=>event.data.round));
+  const otherInputRound=Math.max(0,...phaseReviews.filter(event=>event.subject.headSha!==headSha
+    ||event.subject.diffDigest!==subject.diffDigest).map(event=>event.data.round));
+  const pendingAtCap=otherInputRound<policy.maxRounds?evaluated.requiredReviewerIds.filter(reviewerId=>
+    !reports.some(report=>report.reviewerId===reviewerId&&report.round===policy.maxRounds)):[];
+  const repairableAtCap=blocker=>['missing-review','blocking-review'].includes(blocker.code)
+    ?pendingAtCap.includes(blocker.reviewerId):blocker.code==='unreviewed-path'
+      &&pendingAtCap.some(reviewerId=>evaluated.reviewerPaths[reviewerId].includes(blocker.path));
+  const review={...evaluated,rounds,humanEscalation:!evaluated.valid&&rounds>=policy.maxRounds
+    &&!evaluated.blockers.every(repairableAtCap)};
+  const blockers=[...review.blockers];
+  if(selectedPhase==='final'&&!target&&policy.required)blockers.push({code:'integration-not-ready'});
+  for(const decision of state.decisions)if(decision.status==='pending')blockers.push({code:'decision-needs-human-approval',decisionId:decision.id});
+  let scan=null;
+  if(selectedPhase==='final'&&target&&configured.quality.contentScan!==undefined){
+    const scanPolicy=validateContentScanPolicy(configured.quality.contentScan);
+    if(changedPaths.length>scanPolicy.maxFiles)fail('Content scan file limit exceeded. Split the task or review its scan policy.');
+    const files=[];let bytes=0;
+    for(const path of changedPaths){
+      const file=await gitClient.readCommittedFile(target.path,headSha,path);
+      if(file){
+        bytes+=Buffer.byteLength(file.content);
+        if(bytes>scanPolicy.maxBytes)fail('Content scan byte limit exceeded. Split the task or review its scan policy.');
+        files.push({path,content:file.content});
+      }
+    }
+    scan=scanChangedContent({files,policy:configured.quality.contentScan});
+    if(scan.status!=='passed')blockers.push({code:'content-scan-failed'});
+  }
+  return immutableJson({subject,policy,decisions:state.decisions,decisionMarkdown:renderDecisions(state.decisions,{...binding(run),approvedPlanDecisions:approved(state.decisions)}),
+    review,scan,blockers,ready:blockers.length===0,patch,
+    nextAction:blockers.length?'Use rivet task decisions and rivet task review to inspect required evidence. Human approval never replaces failed required checks.':'Decision and content review requirements are satisfied.'});
+}
+export async function requireGovernance(input){
+  const result=await inspectGovernance(input);
+  if(result.scan){
+    const {paths}=await inputs(input.project,input.run.runId),state=await journal(paths,input.run);
+    const identity=digest({subject:result.subject,scan:result.scan});
+    if(!state.events.some(event=>event.type==='scan.recorded'&&event.digest===identity))
+      await append(state,input.run,{type:'scan.recorded',digest:identity,subject:result.subject,data:result.scan,checkedAt:new Date().toISOString()});
+  }
+  if(!result.ready)fail(`${result.nextAction} Blocking: ${result.blockers.map(item=>item.code).join(', ')}.`);
+  return result;
+}
+
+export async function taskGovernance({project,runId,gitClient,operation,input,phase,decisionId,confirm,signal,now=()=>new Date().toISOString()}){
+  const {paths}=await inputs(project,runId),lock=await acquireHostRunLock(paths);
+  try{
+    const run=await createFeatureRunStore(paths).readOnly(),state=await journal(paths,run);
+    if(['decide','approve-decision','review-submit'].includes(operation)&&['completed','cancelled'].includes(run.status))fail('Completed tasks cannot accept new decision or review evidence.');
+    const context={...binding(run),approvedPlanDecisions:approved(state.decisions)};
+    if(operation==='decisions')return {decisions:state.decisions,markdown:renderDecisions(state.decisions,context)};
+    signal?.throwIfAborted();
+    if(operation==='decide'){
+      if(state.decisions.length>=128)fail('Decision journal limit reached. Start a new bounded task.');
+      const record=createDecision(input,{...context,actor:{kind:'agent',id:'host-agent'},now:now()});
+      if(state.decisions.some(value=>value.id===record.id))fail('Decision ID already exists. Record a new decision that explains the change.');
+      await append(state,run,{type:'decision.recorded',data:record});return record;
+    }
+    if(operation==='approve-decision'){
+      const record=state.decisions.find(value=>value.id===decisionId);if(!record)fail('Decision was not found.');
+      if(typeof confirm!=='function'||await confirm(record)!==true)return {status:'declined'};
+      signal?.throwIfAborted();
+      const updated=approveDecision(record,{...context,actor:{kind:'human',id:'human-cli-operator'},now:now(),humanConfirmed:true});
+      await append(state,run,{type:'decision.approved',data:updated});return updated;
+    }
+    if(operation==='review'||operation==='review-submit'){
+      const config=await loadProjectConfig(project);
+      // Explicit review exports always include the actual diff, even for optional policies.
+      const observed=await inspectGovernance({project,run,gitClient,config,phase,forceReview:true});
+      if(operation==='review'){
+        const keys=['phase','runId','requestDigest','planDigest','baseSha','headSha','diffDigest'];
+        const identity=Object.fromEntries(keys.map(key=>[key,observed.subject[key]]));
+        const atCap=observed.review.rounds>=observed.policy.maxRounds;
+        const otherInputRound=Math.max(0,...state.reviews.filter(event=>event.subject.phase===observed.subject.phase
+          &&(event.subject.headSha!==observed.subject.headSha||event.subject.diffDigest!==observed.subject.diffDigest)).map(event=>event.data.round));
+        const templateReviewers=atCap&&observed.review.valid?[]:atCap?observed.review.requiredReviewerIds.filter(reviewerId=>
+          otherInputRound<observed.policy.maxRounds&&!observed.review.reports.some(report=>report.reviewerId===reviewerId&&report.round===observed.policy.maxRounds))
+          :observed.review.requiredReviewerIds;
+        const reportTemplates=templateReviewers.map(reviewerId=>({
+          ...identity,reviewerId,actorId:'replace-with-reviewer-identity',round:atCap?observed.policy.maxRounds:observed.review.rounds+1,
+          status:'FAIL',blocking:true,coverage:[],findings:[{kind:'general',summary:'Review has not been performed yet.',blocking:true}],
+          filesReviewed:[],commandsExecuted:[],checkedAt:now(),
+        }));
+        return {...observed,request:run.workRequest,plan:run.featurePlan,reportTemplates,
+          reportInstructions:'Complete the review before submitting. For each acceptance criterion provide its 1-based criterionIndex, assigned planNodeIds, reviewed paths and evidence [{kind:test|manual,reference,summary}]. Record missing or unrequested work as blocking findings. PASS requires complete coverage and no blocking findings. Templates intentionally do not claim a passing review.'};
+      }
+      const report=evaluateReviewReports(observed.policy,observed.subject,[input]).reports[0];
+      if(containsSecretMaterial(JSON.stringify(report)))fail('Review evidence contains credential-like material. Remove it before recording the report.');
+      const phaseReviews=state.reviews.filter(event=>event.subject.phase===observed.subject.phase);
+      const matchesCurrent=event=>event.subject.headSha===observed.subject.headSha&&event.subject.diffDigest===observed.subject.diffDigest;
+      const prior=phaseReviews.filter(matchesCurrent).map(event=>event.data);
+      const previousInputRound=Math.max(0,...phaseReviews.filter(event=>!matchesCurrent(event)).map(event=>event.data.round));
+      if(report.round<=previousInputRound)fail('A revised review subject must advance the phase review round.');
+      if(prior.some(value=>value.reviewerId===report.reviewerId&&value.round===report.round))fail('This reviewer round is already recorded.');
+      evaluateReviewReports(observed.policy,observed.subject,[...prior,report]);
+      await append(state,run,{type:'review.recorded',subject:observed.subject,policy:observed.policy,data:report});
+      return {status:'recorded',reviewerId:report.reviewerId,round:report.round};
+    }
+    fail('Unknown task evidence operation.');
+  }finally{await lock.release();}
+}

package/src/feature/host-execution.js

@@ -1,3 +1,4 @@
+import { inspectGovernance, requireGovernance } from './governance.js';
 import {assertSelectedProtocolRefs, selectedProtocolStatus} from '../protocols/project.js';
 import {createProtocolPresentation, protocolLookupContext} from '../protocols/presentation.js';
 import { lstat, realpath } from 'node:fs/promises';
@@ -260,6 +261,7 @@ export function createHostExecution(input) {
     const value = request(inputValue, 'expectedRunVersion');
     const { store, run } = await runRecord(value.project, value.runId);
     if (!['approved', 'running'].includes(run.status) || run.version !== value.expectedRunVersion) fail('state-conflict');
+    await requireGovernance({project:value.project,run,gitClient,phase:'plan'});
     const preparedContext = await runtimeContext(value.project, run);
     const running = run.status === 'running' ? run : await store.update({
       status: 'running',
@@ -299,6 +301,7 @@ export function createHostExecution(input) {
     try {
       const { run } = await runRecord(value.project, value.runId);
       if (run.status !== 'running') fail('state-conflict');
+      await requireGovernance({project:value.project,run,gitClient,phase:'plan'});
       const { instance, runtime } = await runtimeContext(value.project, run);
       const prepared = await runtime.prepareAction(instance, { expectedVersion: value.expectedRuntimeVersion });
       if (prepared.action === null) {
@@ -450,6 +453,7 @@ export function createHostExecution(input) {
           gates: await configuredFeatureGates(config, resolveCommandExecutable, integration.path),
           environment,
         }, { gitClient, now: () => featureNowMilliseconds(now) });
+        if(quality.status==='pass') await requireGovernance({project:value.project,run,gitClient,config,phase:'final',checkout:{path:integration.path,branch:integration.branch,commitSha:integrated.headSha}});
       } catch (error) {
         failure = typeof error?.safeMessage === 'string' ? error.safeMessage : 'Verification could not complete safely.';
       }
@@ -462,7 +466,7 @@ export function createHostExecution(input) {
         run, state, integration, commitSha: integrated.headSha, changedPaths,
         quality, failure, checkedAt: now(),
       }));
-      if (quality?.status !== 'pass') fail('verification-failed');
+      if (failure || quality?.status !== 'pass') fail('verification-failed');
       const beforeFinal = await gitClient.inspectRepository(integration.path);
       if (beforeFinal.dirty || beforeFinal.branch !== integration.branch
         || beforeFinal.headSha !== accepted.commitSha) fail('repository');
@@ -592,7 +596,10 @@ export function createHostExecution(input) {
     const verificationStale = verification !== null && accepted !== null
       && (verification.commitSha !== accepted.commitSha || checkout?.status !== 'clean');
     const protocols = selectedProtocolStatus(value.project, run.workRequest.contextRefs);
-    const deliverable = protocols.status === 'current' && run.status === 'awaiting-final-approval'
+    let governance;
+    try { governance = await inspectGovernance({project:value.project,run,gitClient,phase:readyForVerification?'final':'plan'}); }
+    catch (error) { governance = {ready:false,decisions:[],review:{humanEscalation:false},blockers:[{code:'governance-unavailable'}],nextAction:error.safeMessage ?? 'Decision or review evidence could not be read safely. Inspect private task state before continuing.'}; }
+    const deliverable = governance.ready && protocols.status === 'current' && run.status === 'awaiting-final-approval'
       && runtime !== null && readyForVerification
       && accepted !== null && checkout?.status === 'clean'
       && verification?.status === 'pass'
@@ -603,6 +610,7 @@ export function createHostExecution(input) {
       && verification.integration.branch === accepted.branch;
     const nextAction = protocols.status === 'changed' ? protocols.message : checkout?.status === 'stale' || verificationStale
       ? 'The integration checkout no longer matches the accepted tested commit. Do not deliver it; create a new reviewed proposal for source changes.'
+      : !governance.ready ? governance.nextAction
       : run.status === 'awaiting-final-approval' && !deliverable
       ? 'Final approval evidence is missing or inconsistent. Do not deliver this run; inspect private state and create a new reviewed proposal if it cannot be restored.'
       : deliverable
@@ -626,7 +634,7 @@ export function createHostExecution(input) {
                 ? 'Use work prepare with run.version to create the isolated execution state.'
                 : 'Use rivet task resume to continue the approved spawned task.'
               : 'Review the proposal and current run state before proceeding.';
-    return immutableJson({ run, runtime, protocols, verification, checkout, workerCheckouts, deliveryReady: deliverable, blockedNodes, nextAction });
+    return immutableJson({ run, runtime, protocols, governance, verification, checkout, workerCheckouts, deliveryReady: deliverable, blockedNodes, nextAction });
   }
 
   return Object.freeze({ prepare, nextAction, submitResult, verify, status, recover });

package/src/feature/runtime-bridge.js

@@ -1,3 +1,4 @@
+import { requireGovernance } from './governance.js';
 import {assertSelectedProtocolRefs, selectedProtocolStatus} from '../protocols/project.js';
 import {createProtocolPresentation} from '../protocols/presentation.js';
 import { createHash } from 'node:crypto';
@@ -517,6 +518,7 @@ export function createFeatureExecutor(input) {
     if (repository.root !== project || repository.detached || repository.dirty
       || repository.branch !== config.project.repository.defaultBranch
       || repository.headSha !== run.featurePlan.baselineCommit) fail();
+    await requireGovernance({project,run,gitClient:configured.gitClient,config,phase:'plan'});
     // Only select adapters after the saved approval and current role configuration
     // are validated. Probe before creating integration or worker checkouts.
     const selectedClients = new Map();
@@ -743,6 +745,7 @@ export function createFeatureExecutor(input) {
       }
       const maximumTicks = run.featurePlan.nodes.length * 4 + 8;
       for (let tick = 0; tick < maximumTicks; tick += 1) {
+        await requireGovernance({project,run,gitClient:configured.gitClient,phase:'plan'});
         const outcome = await runtime.tick(instance, { expectedVersion: state.version, maxActiveNodes: 1, signal });
         state = await inspectFeatureRuntime(instance);
         if (['blocked', 'failed', 'budget-exhausted', 'cancelled'].includes(outcome.terminal)) {
@@ -803,6 +806,7 @@ export function createFeatureExecutor(input) {
         gates: await configuredFeatureGates(config, configured.resolveCommandExecutable, integration.path),
         environment: configured.environment,
       }, { gitClient: configured.gitClient, now: nowMs, signal });
+      if(quality.status==='pass') await requireGovernance({project,run,gitClient:configured.gitClient,config,phase:'final',checkout:{path:integration.path,branch:integration.branch,commitSha:identity.commitSha}});
     } catch (error) {
       failure = typeof error?.safeMessage === 'string' ? error.safeMessage : 'Configured quality gates could not complete safely.';
     }

package/src/feature/workflow.js

@@ -1,3 +1,4 @@
+import { assertGovernancePolicy, requireGovernance } from './governance.js';
 import {assertSelectedProtocolRefs, selectedProtocolStatus} from '../protocols/project.js';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 
@@ -212,6 +213,8 @@ export function createFeatureWorkflow(input) {
       new Set(['project', 'source']),
     );
     const { observed, config } = await repository(request.project);
+    if(config.quality.review!==undefined||config.quality.contentScan!==undefined)
+      await assertGovernancePolicy({project:request.project,baselineCommit:observed.headSha,gitClient,config});
     const selectedClient = request.client ?? 'claude';
     if (!CLIENTS.has(selectedClient)) fail('invalid-input');
     const source = capture(request.source, new Set(['kind', 'value']));
@@ -286,13 +289,14 @@ export function createFeatureWorkflow(input) {
       baselineCommit: record.featurePlan.baselineCommit, client: record.featurePlan.client });
   }
 
-  async function start(raw) {
+  async function startLocked(raw) {
     const request = capture(raw, new Set(['project', 'runId', 'expectedVersion', 'proposalDigest']));
     const { store, record } = await readRun(request.project, request.runId);
     if (record.status !== 'proposed' || record.version !== expectedVersion(request.expectedVersion)) fail('state-conflict');
     if (typeof request.proposalDigest !== 'string' || !DIGEST.test(request.proposalDigest)
       || request.proposalDigest !== record.proposalDigest) fail('proposal-mismatch');
     await validateSavedPlan(request.project, record);
+    await requireGovernance({project:request.project,run:record,gitClient,config:await loadConfig(request.project),phase:'plan'});
     const at = now();
     const updated = await store.update({
       status: 'approved', updatedAt: at,
@@ -305,6 +309,13 @@ export function createFeatureWorkflow(input) {
     return lifecycleView(updated);
   }
 
+  async function start(raw) {
+    const request = capture(raw, new Set(['project', 'runId', 'expectedVersion', 'proposalDigest']));
+    const paths = await resolveFeatureRunPaths(absolute(request.project), exactRunId(request.runId));
+    const lock = await acquireHostRunLock(paths);
+    try { return await startLocked(raw); } finally { await lock.release(); }
+  }
+
   async function status(raw) {
     const request = capture(raw, new Set(['project', 'runId']));
     const record = (await readRun(request.project, request.runId)).record;

package/src/git/client.js

@@ -425,6 +425,18 @@ export async function createGitClient(options = {}) {
       }
     },
 
+    async readCommittedFile(cwd, commit, path) {
+      if (!validSha(commit)) fail('invalid-input');
+      repositoryPath(path);
+      const tree = await run(absoluteInput(cwd), ['ls-tree', '-z', commit, '--', path]);
+      if (!tree.output) return null; // Deleted paths have no blob in the target tree.
+      const match = /^(100644|100755) blob ([0-9a-f]{40}|[0-9a-f]{64})\t([^\0]+)\0$/.exec(tree.output);
+      if (!match || match[3] !== path) fail('repository-path-unsafe');
+      const result = await run(absoluteInput(cwd), ['cat-file', 'blob', match[2]], [0], 1024 * 1024);
+      if (result.output.includes('\0')) fail('git-output-invalid');
+      return Object.freeze({path, blob:match[2], content:result.output});
+    },
+
     async inspectTrackedFile(cwd, commit, path) {
       if (!validSha(commit)) fail('invalid-input');
       repositoryPath(path);