@kylecheng3146/agent-ops 0.5.3 → 0.6.0

package/dist/runtime/src/task/completion.js

@@ -2,12 +2,16 @@ import { calculateConfigHash } from "../config/hash.js";
 import { findReviewAttestation } from "../review/attestation.js";
 import { validateEvidence, validateTaskAgainstConfig } from "../schema/validate.js";
 import { isPassingVerificationEvidence } from "../verify/evidence.js";
+import { taskContractHash } from "./contract.js";
+import { acceptanceCoverage } from "../verify/acceptance-coverage.js";
 export async function checkTaskCompletionEvidence(stored, options) {
     const problem = await checkTaskVerificationEvidence(stored, options);
     if (problem !== null)
         return problem;
     const attestation = await findReviewAttestation(options.root, options.sourceFingerprint, stored.task.id);
     if (attestation === null || attestation.taskId !== stored.task.id ||
+        ((stored.task.criteria.some(c => c.acceptance !== undefined) || (stored.task.contractRevision ?? 0) > 0 || stored.task.goal !== undefined) &&
+            (attestation.schemaVersion !== 3 || attestation.taskContracts?.[stored.task.id] !== taskContractHash(stored.task))) ||
         (attestation.tree !== undefined && stored.task.criteria.some((criterion) => !attestation.tree.criterionIds.includes(`${stored.task.id}:${criterion.id}`)))) {
         return { status: "FAIL", code: "REVIEW_REQUIRED", remedy: `Run agent-ops review --task ${stored.task.id} --yes for the whole task and current source.` };
     }
@@ -24,8 +28,9 @@ export async function checkTaskVerificationEvidence(stored, options) {
         return { status: "FAIL", code: "TASK_STALE", remedy: "Recreate the task against the current config, then verify and review it." };
     }
     for (const criterion of stored.task.criteria) {
-        const commands = config.verification.commands.filter(({ id, required }) => criterion.verifierIds.includes(id) && required);
-        if (commands.length === 0) {
+        const commands = config.verification.commands.filter(({ id, required }) => required &&
+            (criterion.acceptance !== undefined || criterion.verifierIds.includes(id)));
+        if (commands.length === 0 && criterion.acceptance === undefined) {
             return { status: "FAIL", code: "REQUIRED_VERIFIER_MISSING", remedy: "Configure a required verifier for every criterion, then recreate, verify and review the task." };
         }
         for (const command of commands) {
@@ -42,6 +47,7 @@ export async function checkTaskVerificationEvidence(stored, options) {
                 if (evidence.taskId === stored.task.id && evidence.criterionId === criterion.id &&
                     evidence.commandId === command.id && evidence.configHash === configHash &&
                     evidence.sourceFingerprint === sourceFingerprint &&
+                    ((stored.task.goal === undefined && (stored.task.contractRevision ?? 0) === 0 && stored.task.criteria.every(c => c.acceptance === undefined)) || evidence.taskContractHash === taskContractHash(stored.task)) &&
                     (latest === undefined || Date.parse(evidence.finishedAt) > Date.parse(latest.finishedAt) ||
                         (Date.parse(evidence.finishedAt) === Date.parse(latest.finishedAt) && !isPassingVerificationEvidence(command, evidence)))) {
                     latest = evidence;
@@ -52,6 +58,10 @@ export async function checkTaskVerificationEvidence(stored, options) {
             }
         }
     }
+    const coverage = await acceptanceCoverage(stored, config, sourceFingerprint, evidenceStore);
+    if (coverage.some(row => (row.mode === "behavioral" || row.mode === "invariant") && row.status !== "proven")) {
+        return { status: "FAIL", code: "ACCEPTANCE_EVIDENCE_REQUIRED", remedy: "Run current paired acceptance checks; UNKNOWN and non-discriminating checks do not prove a criterion." };
+    }
     return null;
 }
 /** Include descendants so legacy completed children cannot hide unfinished work. */
@@ -61,6 +71,8 @@ export function findIncompleteSubtask(records, taskId) {
     while (previousSize !== descendants.size) {
         previousSize = descendants.size;
         for (const record of records) {
+            if (record.supersededBy !== undefined)
+                continue;
             if (record.task.parentTaskId !== undefined && descendants.has(record.task.parentTaskId)) {
                 descendants.add(record.task.id);
                 if (record.status === "active" || record.completedAt === null || record.failureFingerprint !== null)

package/dist/runtime/src/task/contract.js

@@ -0,0 +1,17 @@
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+export function goalHash(task) {
+    return sha256(task.goal ?? task.intent ?? task.title);
+}
+export function criterionContractHash(criterion) {
+    return sha256(canonicalJson(criterion));
+}
+export function taskContractHash(task) {
+    return sha256(canonicalJson({ goalHash: goalHash(task), title: task.title,
+        intent: task.intent ?? null, revision: task.contractRevision ?? 0,
+        criteria: task.criteria.map(criterionContractHash) }));
+}
+export function treeContractHash(tasks) {
+    return sha256(canonicalJson(tasks.map(task => ({ id: task.id, hash: taskContractHash(task) }))
+        .sort((a, b) => a.id.localeCompare(b.id))));
+}

package/dist/runtime/src/task/pin-finding.js

@@ -0,0 +1,81 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { sha256 } from "../fs/hash.js";
+import { readPrivateFile } from "../security/permissions.js";
+import { reviewReportDigest, REVIEW_ATTESTATION_DIRECTORY, REVIEW_REPORT_ARTIFACT_SUFFIX } from "../review/attestation.js";
+import { validateReviewReport } from "../review/report.js";
+import { validateCriterion } from "../schema/validate.js";
+import { commitIdentity } from "../schema/acceptance.js";
+import { goalHash, taskContractHash } from "./contract.js";
+export async function loadFindingPin(root, record, reference, input, records = [record]) {
+    const checked = validateCriterion(input.finding !== undefined && input.acceptance !== undefined
+        ? { ...input, acceptance: { ...input.acceptance, baselineCommit: input.finding.candidateCommit } } : input, "$.criterion");
+    if (!checked.ok)
+        throw new AgentOpsError("TASK_PIN_CRITERION_INVALID", "Pin requires a valid acceptance criterion.");
+    const match = reference.match(/^([a-f0-9]{64}):(0|[1-9][0-9]{0,2})$/u);
+    if (match === null)
+        throw new AgentOpsError("TASK_FINDING_REFERENCE_INVALID", "Finding reference must be report digest:finding index.");
+    const digest = match[1];
+    const index = Number(match[2]);
+    const directory = join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"));
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        names = [];
+    }
+    const hashes = new Set([taskContractHash(record.task), ...(record.revisions ?? []).flatMap(r => [r.previousHash, r.currentHash])]);
+    for (const name of names.filter(n => /^[a-f0-9]{64}(?:\.[a-z][a-z0-9-]{0,127})?\.reports\.json$/u.test(n)).sort()) {
+        const source = await readPrivateFile(join(directory, name), root);
+        if (source === null || Buffer.byteLength(source) > 512 * 1024)
+            continue;
+        let artifact;
+        try {
+            artifact = JSON.parse(source);
+        }
+        catch {
+            continue;
+        }
+        if (typeof artifact !== "object" || artifact === null || Array.isArray(artifact))
+            continue;
+        if (artifact.tree !== undefined && (typeof artifact.tree !== "object" || artifact.tree === null ||
+            !Array.isArray(artifact.tree.taskIds) || typeof artifact.tree.rootTaskId !== "string"))
+            continue;
+        if (artifact.schemaVersion !== 2 || artifact.status !== "FAIL" || !commitIdentity(artifact.candidateCommit) ||
+            artifact.taskContracts?.[record.task.id] === undefined || !hashes.has(artifact.taskContracts[record.task.id]) ||
+            name !== artifact.sourceFingerprint + (artifact.taskId === undefined ? "" : "." + artifact.taskId) + REVIEW_REPORT_ARTIFACT_SUFFIX)
+            continue;
+        const owner = artifact.tree === undefined ? record : records.find(r => r.task.id === artifact.tree.rootTaskId);
+        if (owner === undefined || artifact.goalHash !== goalHash(owner.task) ||
+            (artifact.tree === undefined ? artifact.taskId !== record.task.id : !artifact.tree.taskIds.includes(record.task.id)))
+            continue;
+        for (const report of [artifact.report, artifact.adversarial?.report]) {
+            if (typeof report !== "object" || report === null || !Array.isArray(report.results) ||
+                report.results.some(r => typeof r !== "object" || r === null || typeof r.criterionId !== "string"))
+                continue;
+            const valid = validateReviewReport(report, report.results.map(r => r.criterionId));
+            if (!valid.ok || reviewReportDigest(valid.value) !== digest || index >= valid.value.findings.length)
+                continue;
+            const finding = valid.value.findings[index];
+            if (input.acceptance === undefined || input.acceptance.mode === "invariant")
+                throw new AgentOpsError("TASK_PIN_ACCEPTANCE_REQUIRED", "Pinned findings require behavioral red checks or an explicit review-only contract.");
+            const pinId = sha256(digest + ":" + index);
+            const requestedPin = input.finding?.pinId;
+            const existing = record.task.criteria.find(c => c.finding?.pinId === (requestedPin ?? pinId));
+            if (requestedPin !== undefined && existing === undefined)
+                throw new AgentOpsError("TASK_PIN_UNKNOWN", "Explicit recurrence must name an existing pin ID.");
+            if (existing !== undefined && requestedPin === undefined) {
+                if (input.id !== existing.id)
+                    throw new AgentOpsError("TASK_PIN_EXISTS", "This finding already has a criterion; name its pin ID to record recurrence.");
+                return structuredClone(existing);
+            }
+            return { ...structuredClone(input), id: existing?.id ?? input.id,
+                acceptance: { ...input.acceptance, baselineCommit: existing?.acceptance?.baselineCommit ?? artifact.candidateCommit },
+                finding: existing?.finding ?? { pinId, reportDigest: digest, findingIndex: index,
+                    candidateCommit: artifact.candidateCommit, criterionIds: [...finding.criterionIds] } };
+        }
+    }
+    throw new AgentOpsError("TASK_FINDING_NOT_FOUND", "No saved failed report binds this finding to the task's goal, contract and candidate commit.");
+}

package/dist/runtime/src/task/service.js

@@ -1,13 +1,19 @@
+import { canonicalJson } from "../config/hash.js";
 import { randomUUID } from "node:crypto";
 import { TASK_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { validateEvidence, validateTask } from "../schema/validate.js";
+import { validateEvidence, validateTask, validateTaskAgainstConfig } from "../schema/validate.js";
 import { renderTaskMarkdown } from "./render.js";
 import { checkTaskCompletionEvidence, findIncompleteSubtask } from "./completion.js";
 import { calculateConfigHash, FileEvidenceStore, isPassingVerificationEvidence } from "../verify/evidence.js";
 import { resolveReviewScope } from "../review/scope.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { acceptanceCoverage } from "../verify/acceptance-coverage.js";
+import { loadFindingPin } from "./pin-finding.js";
+import { findReviewAttestation } from "../review/attestation.js";
 import { advanceFailureFingerprint } from "../verify/fingerprint.js";
+import { taskContractHash, treeContractHash } from "./contract.js";
+import { commitIdentity } from "../schema/acceptance.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
     return `task-${randomUUID()}`;
@@ -86,12 +92,25 @@ export class TaskService {
         if (input.sessionId !== undefined) {
             assertSessionId(input.sessionId);
         }
+        let createdSourceCommit = input.createdSourceCommit;
+        if (createdSourceCommit === undefined && this.#completion !== undefined) {
+            const head = await this.#completion.gitRunner.run(["rev-parse", "--verify", "HEAD"]);
+            const resolved = head.stdout.toString().trim();
+            if (head.exitCode === 0 && commitIdentity(resolved))
+                createdSourceCommit = resolved;
+        }
+        if (createdSourceCommit !== undefined && !commitIdentity(createdSourceCommit))
+            throw taskError("TASK_BASELINE_INVALID", "Task creation commit must be a resolved SHA.");
+        const criteria = structuredClone(input.criteria).map(criterion => ({ ...criterion,
+            ...(criterion.acceptance === undefined ? {} : { acceptance: { ...criterion.acceptance,
+                    baselineCommit: criterion.acceptance.baselineCommit ?? createdSourceCommit } }) }));
         const task = {
             schemaVersion: TASK_SCHEMA_VERSION,
             id: this.#generateId(),
             title: input.title,
             ...(input.intent === undefined ? {} : { intent: input.intent }),
-            criteria: [...input.criteria],
+            criteria,
+            ...(input.goal === undefined ? {} : { goal: input.goal }),
             ...(input.parentTaskId === undefined
                 ? {}
                 : { parentTaskId: input.parentTaskId })
@@ -100,6 +119,16 @@ export class TaskService {
         if (!validation.ok) {
             throw taskError("TASK_INVALID", validation.errors[0]?.message ?? "Task input is invalid.");
         }
+        if (validation.value.criteria.some(c => c.finding !== undefined))
+            throw taskError("TASK_PIN_REQUIRED", "New finding identities must be validated with pin-finding against a saved failed review.");
+        if (validation.value.criteria.some(c => c.acceptance !== undefined)) {
+            if (this.#completion === undefined)
+                throw taskError("TASK_BASELINE_CONTEXT_REQUIRED", "Typed acceptance requires repository context.");
+            const configured = validateTaskAgainstConfig(validation.value, await this.#completion.loadConfig());
+            if (!configured.ok)
+                throw taskError("TASK_INVALID", configured.errors[0]?.message ?? "Invalid runner binding.");
+            await this.#retainBaselines(validation.value);
+        }
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             if (state.tasks.some((record) => record.task.id === validation.value.id)) {
@@ -115,9 +144,15 @@ export class TaskService {
                 if (parent.status !== "active") {
                     throw taskError("TASK_PARENT_NOT_ACTIVE", "Only an active task can take new subtasks.");
                 }
+                if (parent.task.goal !== undefined) {
+                    if (validation.value.goal !== undefined && validation.value.goal !== parent.task.goal)
+                        throw taskError("TASK_GOAL_IMMUTABLE", "Subtasks must retain their parent original goal.");
+                    validation.value.goal = parent.task.goal;
+                }
             }
             const record = {
                 task: validation.value,
+                ...(createdSourceCommit === undefined ? {} : { createdSourceCommit }),
                 status: "active",
                 evidence: {},
                 createdAt: now,
@@ -154,9 +189,183 @@ export class TaskService {
             return cloneRecord(record);
         });
     }
+    async #retainBaselines(task) {
+        if (this.#completion === undefined)
+            throw taskError("TASK_BASELINE_CONTEXT_REQUIRED", "Baseline retention needs Git context.");
+        for (const criterion of task.criteria) {
+            const sha = criterion.acceptance?.baselineCommit;
+            if (sha === undefined)
+                continue;
+            const result = await this.#completion.gitRunner.run(["rev-parse", "--verify", sha + "^{commit}"]);
+            if (result.exitCode !== 0 || result.stdout.toString().trim() !== sha)
+                throw taskError("BASELINE_UNAVAILABLE", "Criterion baseline is not the exact available commit.");
+            const retained = await this.#completion.gitRunner.run(["update-ref", "refs/agent-ops/baselines/" + task.id + "/" + criterion.id + "/" + sha, sha]);
+            if (retained.exitCode !== 0)
+                throw taskError("BASELINE_RETENTION_FAILED", "Could not retain criterion baseline.");
+        }
+    }
+    async revise(taskId, input) {
+        if (!/^[a-f0-9]{64}$/u.test(input.expectedContractHash) || input.reason.trim() === "" || input.reason.length > 8192 || input.reason.includes("\0") ||
+            (input.diagnostics ?? []).some(d => d.length > 4096 || d.includes("\0")))
+            throw taskError("TASK_REVISION_INVALID", "Revision requires expected contract and bounded reason/diagnostics.");
+        const previous = await this.status({ taskId });
+        if (previous.status !== "active")
+            throw taskError("TASK_NOT_ACTIVE", "Only active tasks can revise acceptance.");
+        if (taskContractHash(previous.task) !== input.expectedContractHash)
+            throw taskError("TASK_CONTRACT_CHANGED", "Task contract changed.");
+        const baseline = input.baseline ?? previous.createdSourceCommit;
+        const criteria = structuredClone(input.criteria).map(criterion => {
+            if (criterion.acceptance === undefined)
+                return criterion;
+            const sha = criterion.acceptance.baselineCommit ?? baseline;
+            if (sha === undefined)
+                throw taskError("BASELINE_REQUIRED", "Legacy tasks need an explicit baseline before typed acceptance.");
+            const old = previous.task.criteria.find(c => c.id === criterion.id)?.acceptance;
+            if (old !== undefined && sha !== old.baselineCommit)
+                throw taskError("BASELINE_IMMUTABLE", "Create a replacement criterion instead of changing its baseline.");
+            return { ...criterion, acceptance: { ...criterion.acceptance, baselineCommit: sha } };
+        });
+        const next = { ...previous.task, schemaVersion: TASK_SCHEMA_VERSION,
+            contractRevision: (previous.task.contractRevision ?? 0) + 1, criteria };
+        const checked = validateTask(next);
+        if (!checked.ok)
+            throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid criterion revision.");
+        const records = (await this.#store.read()).tasks;
+        for (const criterion of next.criteria)
+            await this.#validateFindingSource(previous, criterion, records);
+        let policyConfigHash = previous.policyConfigHash;
+        if (this.#completion !== undefined) {
+            const config = await this.#completion.loadConfig();
+            const configured = validateTaskAgainstConfig(next, config);
+            if (!configured.ok)
+                throw taskError("TASK_INVALID", configured.errors[0]?.message ?? "Invalid binding.");
+            policyConfigHash = calculateConfigHash(config);
+        }
+        if (criteria.some(c => c.acceptance !== undefined))
+            await this.#retainBaselines(next);
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate(state => {
+            const current = findTask(state, taskId);
+            if (current.status !== "active" || JSON.stringify(current) !== JSON.stringify(previous))
+                throw taskError("TASK_CONTRACT_CHANGED", "Concurrent revision preserved; retry from current task.");
+            const result = { ...current, task: next, evidence: {}, failureFingerprint: null,
+                policyConfigHash, completionBase: null, updatedAt: now,
+                revisions: [...(current.revisions ?? []), { previousTask: current.task, previousEvidence: current.evidence,
+                        previousFailure: current.failureFingerprint, previousHash: input.expectedContractHash,
+                        currentHash: taskContractHash(next), reason: input.reason, diagnostics: [...(input.diagnostics ?? [])], at: now }] };
+            const { reviewBase: _reviewBase, noChangePaths: _paths, ...withoutReview } = result;
+            replaceTask(state, withoutReview);
+            return cloneRecord(withoutReview);
+        });
+    }
+    async replan(taskId, input) {
+        if (input.reason.trim() === "" || input.reason.includes("\0") || input.reason.length > 8192 ||
+            input.tasks.length === 0 || input.tasks.length > 128)
+            throw taskError("TASK_REPLAN_INVALID", "Replan requires bounded children and a reason.");
+        const snapshot = await this.#store.read();
+        const root = findTask(snapshot, taskId);
+        if (root.status !== "active")
+            throw taskError("TASK_NOT_ACTIVE", "Only active roots can be replanned.");
+        const ids = new Set([taskId]);
+        for (let n = 0; n !== ids.size;) {
+            n = ids.size;
+            for (const r of snapshot.tasks)
+                if (r.supersededBy === undefined && r.task.parentTaskId !== undefined && ids.has(r.task.parentTaskId))
+                    ids.add(r.task.id);
+        }
+        const previous = snapshot.tasks.filter(r => ids.has(r.task.id) && r.supersededBy === undefined);
+        if (treeContractHash(previous.map(r => r.task)) !== input.expectedTreeContractHash)
+            throw taskError("TASK_CONTRACT_CHANGED", "Task tree changed.");
+        if (previous.some(r => r.status !== "active"))
+            throw taskError("TASK_REPLAN_INVALID", "Replan cannot replace completed or archived contracts.");
+        if (input.tasks.reduce((count, t) => count + t.replaces.length, 0) > 512)
+            throw taskError("TASK_REPLAN_MAPPING_INVALID", "Replan provenance exceeds its bounded history limit.");
+        const sources = new Map(previous.flatMap(r => r.task.criteria.map(c => [r.task.id + ":" + c.id, c])));
+        const covered = new Set();
+        const now = assertTimestamp(this.#now());
+        const children = [];
+        const config = this.#completion === undefined ? undefined : await this.#completion.loadConfig();
+        for (const planned of input.tasks) {
+            if (planned.replaces.length === 0 || new Set(planned.replaces).size !== planned.replaces.length ||
+                planned.replaces.some(ref => !sources.has(ref)))
+                throw taskError("TASK_REPLAN_MAPPING_INVALID", "Every child must reference existing criterion identities.");
+            for (const ref of planned.replaces)
+                covered.add(ref);
+            for (const c of planned.criteria) {
+                const originals = planned.replaces.map(ref => sources.get(ref)).filter(old => old.id === c.id);
+                if (originals.some(original => original.acceptance !== undefined && c.acceptance?.baselineCommit !== original.acceptance.baselineCommit))
+                    throw taskError("BASELINE_IMMUTABLE", "Replan must preserve criterion baselines.");
+            }
+            for (const criterion of planned.criteria) {
+                if (criterion.finding === undefined)
+                    continue;
+                const inherited = planned.replaces.map(ref => sources.get(ref)).find(c => c.finding?.pinId === criterion.finding.pinId);
+                if (inherited !== undefined) {
+                    if (canonicalJson(inherited.finding) !== canonicalJson(criterion.finding))
+                        throw taskError("TASK_PIN_IMMUTABLE", "Replan must retain immutable finding identity.");
+                }
+                else {
+                    let authorized = false;
+                    for (const record of previous.filter(r => planned.replaces.some(ref => ref.startsWith(r.task.id + ":")))) {
+                        try {
+                            await this.#validateFindingSource(record, criterion, snapshot.tasks);
+                            authorized = true;
+                            break;
+                        }
+                        catch { }
+                    }
+                    if (!authorized)
+                        throw taskError("TASK_PIN_REQUIRED", "New replan pins require a saved failed report bound to the replaced contracts.");
+                }
+            }
+            for (const ref of planned.replaces) {
+                const pin = sources.get(ref).finding?.pinId;
+                if (pin !== undefined && !planned.criteria.some(c => c.finding?.pinId === pin))
+                    throw taskError("TASK_REPLAN_PIN_REQUIRED", "Split contracts must preserve mapped regression pin identities.");
+            }
+            const task = { schemaVersion: TASK_SCHEMA_VERSION, id: planned.id ?? this.#generateId(),
+                title: planned.title, intent: planned.intent, goal: root.task.goal ?? root.task.intent ?? root.task.title,
+                criteria: structuredClone(planned.criteria), parentTaskId: taskId };
+            const checked = config === undefined ? validateTask(task) : validateTaskAgainstConfig(task, config);
+            if (!checked.ok)
+                throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid split task.");
+            if (task.criteria.some(c => c.acceptance !== undefined))
+                await this.#retainBaselines(task);
+            children.push({ task, status: "active", evidence: {}, createdAt: now, updatedAt: now,
+                completedAt: null, archivedAt: null, failureFingerprint: null, completionBase: null,
+                policyConfigHash: config === undefined ? root.policyConfigHash : calculateConfigHash(config),
+                ...(root.createdSourceCommit === undefined ? {} : { createdSourceCommit: root.createdSourceCommit }) });
+        }
+        if ([...sources.keys()].some(ref => !covered.has(ref)))
+            throw taskError("TASK_REPLAN_COVERAGE_REQUIRED", "Split must account for every previous criterion.");
+        if (new Set(children.map(c => c.task.id)).size !== children.length || children.some(c => snapshot.tasks.some(r => r.task.id === c.task.id)))
+            throw taskError("TASK_ID_CONFLICT", "Split task IDs must be new and unique.");
+        return await this.#store.mutate(state => {
+            if (JSON.stringify(state.tasks) !== JSON.stringify(snapshot.tasks))
+                throw taskError("TASK_CONTRACT_CHANGED", "Concurrent tree change preserved.");
+            const updated = { ...root.task, schemaVersion: TASK_SCHEMA_VERSION, contractRevision: (root.task.contractRevision ?? 0) + 1 };
+            const newRoot = { ...root, task: updated, evidence: {}, failureFingerprint: null, updatedAt: now, completionBase: null,
+                revisions: [...(root.revisions ?? []), { previousTask: root.task, previousEvidence: root.evidence, previousFailure: root.failureFingerprint,
+                        previousHash: taskContractHash(root.task), currentHash: taskContractHash(updated), reason: input.reason, at: now,
+                        diagnostics: input.tasks.flatMap((t, i) => t.replaces.map(ref => ref + " -> " + children[i].task.id)) }] };
+            const { reviewBase: _base, noChangePaths: _paths, ...clearedRoot } = newRoot;
+            replaceTask(state, clearedRoot);
+            for (const old of previous.filter(r => r.task.id !== taskId)) {
+                const successors = children.filter((_child, i) => input.tasks[i].replaces.some(ref => ref.startsWith(old.task.id + ":"))).map(c => c.task.id);
+                replaceTask(state, { ...old, status: "archived", archivedAt: now, updatedAt: now, supersededBy: successors });
+            }
+            state.tasks.push(...children);
+            for (let i = 0; i < state.sessions.length; i++) {
+                const attachment = state.sessions[i];
+                if (ids.has(attachment.taskId))
+                    state.sessions[i] = { ...attachment, taskId, attachedAt: now };
+            }
+            return children.map(cloneRecord);
+        });
+    }
     /** Import a child worktree's intent and criteria, never its source-bound proof. */
     async importDelivery(parentTaskId, delivered) {
-        if (delivered.length === 0 || delivered.some(({ status, task }) => status === "archived" || task.intent === undefined || task.intent.trim() === "")) {
+        if (delivered.length === 0 || delivered.some(({ status, task }) => (status === "archived" && delivered.find(r => r.task.id === task.id)?.supersededBy === undefined) || task.intent === undefined || task.intent.trim() === "")) {
             throw taskError("TASK_DELIVERY_INVALID", "Every delivered task needs a recorded intent and must not be archived.");
         }
         await this.#store.mutate((state) => {
@@ -188,12 +397,15 @@ export class TaskService {
                 }
                 state.tasks.push({
                     task,
-                    status: "active",
+                    ...(record.createdSourceCommit === undefined ? {} : { createdSourceCommit: record.createdSourceCommit }),
+                    ...(record.revisions === undefined ? {} : { revisions: structuredClone(record.revisions) }),
+                    ...(record.supersededBy === undefined ? {} : { supersededBy: [...record.supersededBy] }),
+                    status: record.supersededBy === undefined ? "active" : "archived",
                     evidence: {},
                     createdAt: record.createdAt,
                     updatedAt: this.#now(),
                     completedAt: null,
-                    archivedAt: null,
+                    archivedAt: record.supersededBy === undefined ? null : record.archivedAt,
                     failureFingerprint: null,
                     policyConfigHash: record.policyConfigHash,
                     completionBase: null
@@ -299,7 +511,8 @@ export class TaskService {
         const fingerprint = async () => {
             try {
                 const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
-                    ...(completion.base === undefined ? {} : { base: completion.base }) });
+                    ...(completion.base === undefined ? {} : { base: completion.base }),
+                    ...((current.noChangePaths ?? completion.noChangePaths) === undefined ? {} : { noChangePaths: current.noChangePaths ?? completion.noChangePaths }) });
                 // Recorded so the completion gate can recompute this exact range once
                 // the work is committed and the worktree has nothing left to measure.
                 completionBase = scope.mode === "base" ? scope.resolvedBase : null;
@@ -365,7 +578,7 @@ export class TaskService {
      * A PASS review's base: set records it, null clears it (the review covered
      * uncommitted work), undefined leaves the record's value alone.
      */
-    reviewBase) {
+    reviewBase, noChangePaths) {
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             const current = findTask(state, taskId);
@@ -395,6 +608,7 @@ export class TaskService {
                 ...rest,
                 evidence,
                 updatedAt: now,
+                ...(noChangePaths === undefined ? {} : { noChangePaths: [...noChangePaths] }),
                 ...(base === undefined ? {} : { reviewBase: base })
             };
             replaceTask(state, updated);
@@ -422,12 +636,15 @@ export class TaskService {
             const validation = validateEvidence(value);
             return validation.ok && validation.value.taskId === snapshot.task.id &&
                 validation.value.criterionId === criterionId && validation.value.commandId === commandId &&
-                validation.value.configHash === configHash && validation.value.sourceFingerprint === sourceFingerprint
+                validation.value.configHash === configHash && validation.value.sourceFingerprint === sourceFingerprint &&
+                (!(snapshot.task.goal !== undefined || (snapshot.task.contractRevision ?? 0) > 0 || snapshot.task.criteria.some(c => c.acceptance !== undefined)) ||
+                    validation.value.taskContractHash === taskContractHash(snapshot.task))
                 ? validation.value : null;
         };
         for (const criterion of snapshot.task.criteria) {
-            const commands = config.verification.commands.filter(({ id, required }) => required && criterion.verifierIds.includes(id));
-            if (commands.length === 0)
+            const commands = config.verification.commands.filter(({ id, required }) => required &&
+                (criterion.acceptance !== undefined || criterion.verifierIds.includes(id)));
+            if (commands.length === 0 && criterion.acceptance === undefined)
                 throw taskError("TASK_REVERIFICATION_CHANGED", "Completed task criteria lack required coverage.");
             for (const command of commands) {
                 let original = false;
@@ -442,7 +659,7 @@ export class TaskService {
                 }
                 for (const reference of evidenceInput[criterion.id] ?? []) {
                     const evidence = matches(await store.load(reference), criterion.id, command.id);
-                    if (evidence !== null && evidence.schemaVersion === 3 &&
+                    if (evidence !== null && evidence.schemaVersion >= 3 &&
                         !snapshot.evidence[criterion.id]?.includes(reference) && isPassingVerificationEvidence(command, evidence))
                         fresh = true;
                 }
@@ -454,13 +671,25 @@ export class TaskService {
         for (const [criterionId, references] of Object.entries(appended)) {
             for (const reference of references) {
                 const validation = validateEvidence(await store.load(reference));
-                if (!validation.ok || !snapshot.task.criteria.find(({ id }) => id === criterionId)?.verifierIds.includes(validation.value.commandId) || matches(validation.value, criterionId, validation.value.commandId) === null) {
+                const criterion = snapshot.task.criteria.find(({ id }) => id === criterionId);
+                const permitted = validation.ok && criterion !== undefined && (criterion.acceptance === undefined
+                    ? criterion.verifierIds.includes(validation.value.commandId)
+                    : validation.value.acceptance === undefined
+                        ? config.verification.commands.some(command => command.id === validation.value.commandId)
+                        : criterion.acceptance.bindings.some(binding => binding.runnerId === validation.value.commandId));
+                if (!validation.ok || !permitted || matches(validation.value, criterionId, validation.value.commandId) === null) {
                     throw taskError("TASK_EVIDENCE_INVALID", "Fresh verification references must belong to this task, criterion, source and config.");
                 }
             }
         }
+        for (const record of [snapshot, { ...snapshot, evidence: appended }]) {
+            const rows = await acceptanceCoverage(record, config, sourceFingerprint, store);
+            if (rows.some(row => (row.mode === "behavioral" || row.mode === "invariant") && row.status !== "proven"))
+                throw taskError("TASK_REVERIFICATION_CHANGED", "Completed mechanical contracts require both original and fresh paired acceptance proof.");
+        }
         const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
-            ...(completion.base === undefined ? {} : { base: completion.base }) });
+            ...(completion.base === undefined ? {} : { base: completion.base }),
+            ...(snapshot.noChangePaths === undefined ? {} : { noChangePaths: snapshot.noChangePaths }) });
         if (sourceFingerprint !== await calculateSourceFingerprint(completion.root, scope, completion.gitRunner) ||
             configHash !== calculateConfigHash(await completion.loadConfig())) {
             throw taskError("TASK_REVERIFICATION_CHANGED", "Source or config changed during reverification.");
@@ -528,4 +757,78 @@ export class TaskService {
             });
         });
     }
+    async coverage(taskId) {
+        const record = await this.status({ taskId });
+        const originalMechanical = record.task.criteria.filter(c => {
+            const original = record.revisions?.map(r => r.previousTask.criteria.find(old => old.id === c.id)).find(Boolean) ?? c;
+            return original.acceptance?.mode === "behavioral" || original.acceptance?.mode === "invariant";
+        }).length;
+        const unavailable = () => ({ originalMechanical, reviewed: false, rows: record.task.criteria.map(c => ({ criterionId: c.id,
+                mode: c.acceptance?.mode ?? "legacy", status: "undischarged", evidenceReferences: [],
+                reason: "Current source-bound coverage is unavailable; verify and review the current contract." })) });
+        if (this.#completion === undefined)
+            return unavailable();
+        try {
+            const config = await this.#completion.loadConfig();
+            const base = this.#completion.base ?? record.reviewBase ?? record.completionBase ?? record.createdSourceCommit;
+            const scope = await resolveReviewScope({ root: this.#completion.root, runner: this.#completion.gitRunner,
+                ...(base === undefined ? {} : { base }), ...(record.noChangePaths === undefined ? {} : { noChangePaths: record.noChangePaths }) });
+            const fingerprint = await calculateSourceFingerprint(this.#completion.root, scope, this.#completion.gitRunner);
+            const rows = await acceptanceCoverage(record, config, fingerprint, new FileEvidenceStore(this.#completion.root, this.#completion.root));
+            const attestation = await findReviewAttestation(this.#completion.root, fingerprint, taskId);
+            const reviewed = attestation !== null && (attestation.schemaVersion === 3 ? attestation.taskContracts?.[taskId] === taskContractHash(record.task) :
+                record.task.goal === undefined && (record.task.contractRevision ?? 0) === 0 && record.task.criteria.every(c => c.acceptance === undefined));
+            return { rows, reviewed, originalMechanical };
+        }
+        catch {
+            return unavailable();
+        }
+    }
+    async #validateFindingSource(record, criterion, records) {
+        const finding = criterion.finding;
+        if (finding === undefined)
+            return;
+        const existing = record.task.criteria.find(c => c.finding?.pinId === finding.pinId);
+        if (existing !== undefined) {
+            if (canonicalJson(existing.finding) !== canonicalJson(finding))
+                throw taskError("TASK_PIN_IMMUTABLE", "Finding source identity cannot change.");
+            return;
+        }
+        if (this.#completion === undefined)
+            throw taskError("TASK_PIN_REQUIRED", "New pins require a saved review source.");
+        const { finding: _finding, ...unbound } = criterion;
+        const resolved = await loadFindingPin(this.#completion.root, record, finding.reportDigest + ":" + finding.findingIndex, unbound, records);
+        if (canonicalJson(resolved.finding) !== canonicalJson(finding) || resolved.acceptance?.baselineCommit !== criterion.acceptance?.baselineCommit)
+            throw taskError("TASK_PIN_REQUIRED", "Pin identity and baseline must match the saved failed report.");
+    }
+    async pinFinding(taskId, expectedContractHash, reference, criterion, reason) {
+        if (this.#completion === undefined)
+            throw taskError("TASK_COMPLETION_UNAVAILABLE", "Pin requires a repository and saved review artifacts.");
+        const state = await this.#store.read();
+        const record = findTask(state, taskId);
+        if (record.status !== "active" || taskContractHash(record.task) !== expectedContractHash)
+            throw taskError("TASK_CONTRACT_CHANGED", "Pin requires the current active contract.");
+        const pinned = await loadFindingPin(this.#completion.root, record, reference, criterion, state.tasks);
+        const existing = record.task.criteria.find(c => c.finding?.pinId === pinned.finding?.pinId);
+        if (existing === undefined && record.task.criteria.length === 5)
+            return { record: null, pendingCriterion: pinned };
+        if (existing === undefined && record.task.criteria.some(c => c.id === pinned.id))
+            throw taskError("TASK_CRITERION_ID_CONFLICT", "A new pin requires a new criterion ID.");
+        const criteria = existing === undefined ? [...record.task.criteria, pinned] : record.task.criteria.map(c => c.id === existing.id ? pinned : c);
+        const updated = await this.revise(taskId, { expectedContractHash, criteria,
+            reason: reason ?? "Pin saved review finding " + reference + " against the immutable original goal.", diagnostics: ["finding:" + reference, "pin:" + pinned.finding.pinId] });
+        return { record: updated, pendingCriterion: pinned };
+    }
+    async treeContract(taskId) {
+        const state = await this.#store.read();
+        findTask(state, taskId);
+        const ids = new Set([taskId]);
+        for (let size = 0; size !== ids.size;) {
+            size = ids.size;
+            for (const record of state.tasks)
+                if (record.supersededBy === undefined && record.task.parentTaskId !== undefined && ids.has(record.task.parentTaskId))
+                    ids.add(record.task.id);
+        }
+        return treeContractHash(state.tasks.filter(record => ids.has(record.task.id) && record.supersededBy === undefined).map(record => record.task));
+    }
 }