@kylecheng3146/agent-ops 0.5.2 → 0.5.3

package/dist/runtime/src/parallel/integrate.js

@@ -0,0 +1,138 @@
+import { join } from "node:path";
+import { calculateConfigHash } from "../config/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { resolveReviewScope } from "../review/scope.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { checkTaskVerificationEvidence } from "../task/completion.js";
+import { FileEvidenceStore } from "../verify/evidence.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
+import { listWorktrees } from "./manage.js";
+function error(code, message) {
+    return new AgentOpsError(code, message);
+}
+async function git(deps, cwd, args) {
+    const result = await deps.git(cwd, args);
+    if (result.exitCode !== 0)
+        throw error("WORKTREE_INTEGRATION_FAILED", `${args.join(" ")}: ${result.stderr.trim()}`);
+    return result.stdout.trim();
+}
+function runner(deps, cwd) {
+    return { run: async (args) => {
+            const result = await deps.git(cwd, args);
+            return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
+        } };
+}
+function markerPath(record) {
+    return join(record.path, ".agent-ops", "tasks", "integrated-children.json");
+}
+async function previous(record) {
+    const source = await readPrivateFile(markerPath(record), record.path);
+    if (source === null)
+        return [];
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        value = null;
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "object" || item === null ||
+        typeof item.name !== "string" || typeof item.commit !== "string" ||
+        !/^[a-f0-9]{40,64}$/u.test(item.commit) ||
+        !Array.isArray(item.taskIds) || item.taskIds.some((id) => typeof id !== "string"))) {
+        throw error("WORKTREE_INTEGRATION_STATE_INVALID", "Child integration record is invalid.");
+    }
+    return value;
+}
+/** Integrate only this session's agent-owned branches; local proof is never promoted as final proof. */
+export async function integrateSessionChildren(deps, coordinator, parentTaskId) {
+    const statuses = await listWorktrees(deps, coordinator.mainRoot);
+    const children = statuses.map(({ record }) => record)
+        .filter((record) => record.sessionId === coordinator.sessionId && record.agentId !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const integrated = await previous(coordinator);
+    if (children.length === 0)
+        return integrated;
+    const config = await deps.loadConfig(coordinator.path);
+    const configHash = calculateConfigHash(config);
+    const deliveries = [];
+    const existing = new Map(integrated.map((item) => [item.name, item]));
+    for (const record of children) {
+        if (record.mainRoot !== coordinator.mainRoot || record.targetBranch !== coordinator.targetBranch ||
+            record.name === coordinator.name ||
+            await git(deps, record.path, ["symbolic-ref", "--short", "HEAD"]) !== record.branch) {
+            throw error("WORKTREE_CHILD_MISMATCH", `Child ${record.name} does not belong to this candidate branch.`);
+        }
+        if ((await collectChangeSurface(runner(deps, record.path))).paths.length > 0) {
+            throw error("WORKTREE_CHILD_DIRTY", `Commit the changes in child ${record.name} before integration.`);
+        }
+        const head = await git(deps, record.path, ["rev-parse", "HEAD"]);
+        const prior = existing.get(record.name);
+        if (prior !== undefined) {
+            if (prior.commit !== head)
+                throw error("WORKTREE_CHILD_MOVED", `Child ${record.name} changed after delivery; keep its worktree and replan integration.`);
+            continue;
+        }
+        if ((await deps.git(record.path, ["merge-base", "--is-ancestor", record.base, head])).exitCode !== 0 ||
+            Number(await git(deps, record.path, ["rev-list", "--count", `${record.base}..${head}`])) === 0) {
+            throw error("WORKTREE_CHILD_EMPTY", `Child ${record.name} has no committed delivery.`);
+        }
+        const childConfig = await deps.loadConfig(record.path);
+        if (calculateConfigHash(childConfig) !== configHash) {
+            throw error("WORKTREE_CHILD_CONFIG_CHANGED", `Child ${record.name} uses a different verifier policy.`);
+        }
+        const tasks = await deps.tasks(record.path).list();
+        const roots = tasks.filter(({ task }) => task.parentTaskId === undefined);
+        if (roots.length !== 1 || tasks.some(({ status }) => status === "archived")) {
+            throw error("WORKTREE_CHILD_TASK_INVALID", `Child ${record.name} must deliver one active task tree.`);
+        }
+        const scope = await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: record.base });
+        const fingerprint = await calculateSourceFingerprint(record.path, scope, runner(deps, record.path));
+        for (const task of tasks) {
+            if (task.task.intent === undefined || task.task.intent.trim() === "") {
+                throw error("WORKTREE_CHILD_INTENT_MISSING", `Child task ${task.task.id} needs its pre-work modification intent.`);
+            }
+            const problem = await checkTaskVerificationEvidence(task, {
+                root: record.path, config: childConfig, sourceFingerprint: fingerprint,
+                evidenceStore: new FileEvidenceStore(record.path, record.path)
+            });
+            if (problem !== null) {
+                throw error("WORKTREE_CHILD_UNVERIFIED", `Child task ${task.task.id}: ${problem.remedy}`);
+            }
+        }
+        deliveries.push({ record, head, tasks });
+    }
+    if (deliveries.length === 0)
+        return integrated;
+    const before = await git(deps, coordinator.path, ["rev-parse", "HEAD"]);
+    if ((await collectChangeSurface(runner(deps, coordinator.path))).paths.length > 0) {
+        throw error("WORKTREE_DIRTY", "Commit the candidate worktree before integrating children.");
+    }
+    try {
+        for (const delivery of deliveries) {
+            if ((await deps.git(coordinator.path, ["merge-base", "--is-ancestor", delivery.head, "HEAD"])).exitCode !== 0) {
+                const merge = await deps.git(coordinator.path, ["merge", "--no-ff", "--no-edit", delivery.head]);
+                if (merge.exitCode !== 0) {
+                    const files = (await deps.git(coordinator.path, ["diff", "--name-only", "--diff-filter=U"])).stdout.trim();
+                    await deps.git(coordinator.path, ["merge", "--abort"]);
+                    throw error("WORKTREE_INTEGRATION_CONFLICT", `Child ${delivery.record.name} conflicts in ${files || "unknown files"}. Resolve both recorded intents before retrying.`);
+                }
+            }
+            if (await git(deps, delivery.record.path, ["rev-parse", "HEAD"]) !== delivery.head) {
+                throw error("WORKTREE_CHILD_MOVED", `Child ${delivery.record.name} moved during integration.`);
+            }
+        }
+        await deps.tasks(coordinator.path).importDelivery(parentTaskId, deliveries.flatMap(({ tasks }) => tasks));
+        const next = [...integrated, ...deliveries.map(({ record, head, tasks }) => ({
+                name: record.name, commit: head, taskIds: tasks.map(({ task }) => task.id)
+            }))];
+        await writePrivateFile(markerPath(coordinator), `${JSON.stringify(next, null, 2)}\n`, coordinator.path);
+        return next;
+    }
+    catch (failure) {
+        await deps.git(coordinator.path, ["merge", "--abort"]);
+        await deps.git(coordinator.path, ["reset", "--hard", before]);
+        throw failure;
+    }
+}

package/dist/runtime/src/parallel/receipt.js

@@ -0,0 +1,87 @@
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { findReviewAttestation, readReviewReportArtifact } from "../review/attestation.js";
+import { resolveReviewScope } from "../review/scope.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { checkTaskCompletionEvidence } from "../task/completion.js";
+import { FileEvidenceStore } from "../verify/evidence.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+function seal(value) {
+    return { digest: sha256(JSON.stringify(value)), value };
+}
+function validSeal(value) {
+    return value.digest === sha256(JSON.stringify(value.value));
+}
+function receiptPath(commonDir, record, head) {
+    return join(commonDir, "agent-ops", "receipts", `${sha256(record.sessionId)}-${head}.json`);
+}
+/** Complete local proof is copied into the Git common directory before the branch moves. */
+export async function prepareFinishReceipt(options) {
+    const { record, candidateHead, targetCommit, tasks, config } = options;
+    const scope = await resolveReviewScope({ root: record.path, runner: options.gitRunner, base: targetCommit });
+    const sourceFingerprint = await calculateSourceFingerprint(record.path, scope, options.gitRunner);
+    if (sourceFingerprint !== options.expectedFingerprint) {
+        throw new AgentOpsError("WORKTREE_FINAL_SOURCE_CHANGED", "The final candidate no longer matches the reviewed fingerprint.");
+    }
+    const evidenceStore = new FileEvidenceStore(record.path, record.path);
+    const verification = {};
+    const reviews = {};
+    const residualRisks = new Set();
+    const modes = new Set();
+    for (const task of tasks) {
+        const problem = await checkTaskCompletionEvidence(task, {
+            root: record.path, config, sourceFingerprint, evidenceStore
+        });
+        if (problem !== null) {
+            throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", `Task ${task.task.id}: ${problem.remedy}`);
+        }
+        for (const references of Object.values(task.evidence)) {
+            for (const reference of references) {
+                if (reference.startsWith("review:"))
+                    continue;
+                const value = await evidenceStore.load(reference);
+                if (value === null)
+                    throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", `Missing ${reference}.`);
+                verification[reference] = seal(value);
+            }
+        }
+        const attestation = await findReviewAttestation(record.path, sourceFingerprint, task.task.id);
+        const report = await readReviewReportArtifact(record.path, sourceFingerprint, task.task.id);
+        if (attestation === null || report === null || report.taskId !== task.task.id) {
+            throw new AgentOpsError("WORKTREE_FINAL_EVIDENCE_MISSING", `Missing review for ${task.task.id}.`);
+        }
+        modes.add(attestation.tree === undefined ? "per-task-fallback" : "tree");
+        for (const risk of [...(report.report?.residualRisks ?? []), ...(report.adversarial?.report.residualRisks ?? [])]) {
+            residualRisks.add(risk);
+        }
+        reviews[task.task.id] = { attestation: seal(attestation), report: seal(report) };
+    }
+    if (modes.size !== 1 || (modes.has("tree") && new Set(Object.values(reviews)
+        .map(({ attestation }) => JSON.stringify(attestation.value.tree))).size !== 1)) {
+        throw new AgentOpsError("WORKTREE_FINAL_REVIEW_MISMATCH", "Final tasks do not share one complete review mode and tree scope.");
+    }
+    const receipt = {
+        schemaVersion: 1,
+        sessionId: record.sessionId,
+        candidateHead,
+        targetCommit,
+        sourceFingerprint,
+        reviewMode: modes.has("tree") ? "tree" : "per-task-fallback",
+        tasks,
+        children: options.children,
+        verification,
+        reviews,
+        residualRisks: [...residualRisks],
+        createdAt: new Date().toISOString()
+    };
+    const content = `${JSON.stringify(receipt, null, 2)}\n`;
+    const path = receiptPath(options.commonDir, record, candidateHead);
+    await writePrivateFile(path, content, options.commonDir);
+    const reread = await readPrivateFile(path, options.commonDir);
+    if (reread !== content || Object.values(verification).some((item) => !validSeal(item)) ||
+        Object.values(reviews).some(({ attestation, report }) => !validSeal(attestation) || !validSeal(report))) {
+        throw new AgentOpsError("WORKTREE_RECEIPT_INVALID", "The local finish receipt could not be read back intact.");
+    }
+    return { path, digest: sha256(content), receipt };
+}

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

@@ -231,9 +231,11 @@ export async function bindSession(deps, record, mainConfig, baselineFingerprint)
     else
         await mainGate.addRoot(record.sessionId, record.path);
 }
-export async function removeCheckout(deps, record, force) {
+export async function removeCheckout(deps, record, force, expectedHead) {
     await git(deps, record.mainRoot, ["worktree", "remove", ...(force ? ["--force"] : []), record.path], "WORKTREE_REMOVE_FAILED", `Git could not remove ${record.path}.`);
-    await git(deps, record.mainRoot, ["branch", force ? "-D" : "-d", record.branch], "WORKTREE_REMOVE_FAILED", `Git could not delete ${record.branch}.`);
+    await git(deps, record.mainRoot, expectedHead === undefined
+        ? ["branch", force ? "-D" : "-d", record.branch]
+        : ["update-ref", "-d", `refs/heads/${record.branch}`, expectedHead], "WORKTREE_REMOVE_FAILED", `Git could not delete ${record.branch}.`);
 }
 /**
  * Creates `.worktrees/<name>` on `agent-ops/<name>` from `from` and makes it a

package/dist/runtime/src/review/attestation.js

@@ -55,11 +55,12 @@ function artifactPath(root, fingerprint, taskId) {
 export function reviewReportDigest(report) {
     return sha256(JSON.stringify(redactReviewReport(report)));
 }
-function reportArtifact(result, sourceFingerprint, taskId) {
+function reportArtifact(result, sourceFingerprint, taskId, tree) {
     return {
         schemaVersion: 1,
         sourceFingerprint,
         ...(taskId === undefined ? {} : { taskId }),
+        ...(tree === undefined ? {} : { tree }),
         status: result.status,
         harness: result.harness,
         plannedTargets: [...(result.plannedTargets ?? [result.harness])],
@@ -105,6 +106,7 @@ function matchingReportArtifact(value, attestation) {
         record.harness !== attestation.harness ||
         record.harness !== attestation.reviewTargets[0] ||
         record.taskId !== attestation.taskId ||
+        JSON.stringify(record.tree) !== JSON.stringify(attestation.tree) ||
         record.hostTarget !== attestation.hostTarget ||
         !Array.isArray(plannedTargets) ||
         plannedTargets.length !== 2 ||
@@ -126,6 +128,16 @@ function matchingReportArtifact(value, attestation) {
         return false;
     }
     const adversarialRecord = adversarial;
+    if (attestation.tree !== undefined) {
+        const expected = new Set(attestation.tree.criterionIds);
+        for (const report of [record.report, adversarialRecord.report]) {
+            const results = report?.results;
+            if (!Array.isArray(results) || results.length !== expected.size ||
+                results.some((item) => !expected.has(item.criterionId)) ||
+                new Set(results.map((item) => item.criterionId)).size !== expected.size)
+                return false;
+        }
+    }
     return (adversarialRecord.target === attestation.reviewTargets[1] &&
         adversarialRecord.refuted === false &&
         typeof adversarialRecord.report === "object" &&
@@ -149,14 +161,14 @@ async function hasMatchingReportArtifact(root, attestation) {
         return false;
     }
 }
-export async function saveReviewReportArtifact(root, result, sourceFingerprint, taskId) {
+export async function saveReviewReportArtifact(root, result, sourceFingerprint, taskId, tree) {
     if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
         throw new AgentOpsError("REVIEW_REPORT_ARTIFACT_INVALID", "Review report artifact has an invalid source fingerprint.");
     }
     if (taskId !== undefined && !TASK_ID_PATTERN.test(taskId)) {
         throw new AgentOpsError("REVIEW_REPORT_ARTIFACT_INVALID", "Review report artifact has an invalid task id.");
     }
-    const value = reportArtifact(result, sourceFingerprint, taskId);
+    const value = reportArtifact(result, sourceFingerprint, taskId, tree);
     const serialized = `${JSON.stringify(value, null, 2)}\n`;
     if (Buffer.byteLength(serialized, "utf8") > REPORT_ARTIFACT_MAX_BYTES) {
         throw new AgentOpsError("REVIEW_REPORT_ARTIFACT_TOO_LARGE", "Review report artifact exceeds the capture limit.");
@@ -173,11 +185,22 @@ function parseAttestation(value) {
         return null;
     }
     const record = value;
+    const tree = record.tree;
     if (record.schemaVersion !== 2 ||
         record.status !== "PASS" ||
         (record.taskId !== undefined &&
             (typeof record.taskId !== "string" ||
                 !TASK_ID_PATTERN.test(record.taskId))) ||
+        (tree !== undefined &&
+            (typeof tree !== "object" || tree === null ||
+                typeof tree.rootTaskId !== "string" || !TASK_ID_PATTERN.test(tree.rootTaskId) ||
+                !Array.isArray(tree.taskIds) || tree.taskIds.length === 0 ||
+                tree.taskIds.some((id) => typeof id !== "string" || !TASK_ID_PATTERN.test(id)) ||
+                new Set(tree.taskIds).size !== tree.taskIds.length ||
+                !tree.taskIds.includes(record.taskId) ||
+                !Array.isArray(tree.criterionIds) || tree.criterionIds.length === 0 ||
+                tree.criterionIds.some((id) => typeof id !== "string" || id.length > 256) ||
+                new Set(tree.criterionIds).size !== tree.criterionIds.length)) ||
         !isReviewTarget(record.harness) ||
         typeof record.sourceFingerprint !== "string" ||
         !FINGERPRINT_PATTERN.test(record.sourceFingerprint) ||
@@ -208,6 +231,7 @@ function parseAttestation(value) {
     return {
         schemaVersion: 2,
         ...(record.taskId === undefined ? {} : { taskId: record.taskId }),
+        ...(tree === undefined ? {} : { tree: tree }),
         harness: record.harness,
         status: "PASS",
         sourceFingerprint: record.sourceFingerprint,

package/dist/runtime/src/review/render.js

@@ -173,3 +173,74 @@ export function renderReviewResult(result) {
     lines.push("", "Supporting files inspected:", ...lineList(report.supportingFilesInspected));
     return `${lines.join("\n")}\n`;
 }
+function fullReportLines(report) {
+    const lines = ["Summary:", safe(report.summary), "", "Criteria:"];
+    for (const item of report.results) {
+        lines.push(`- ${safe(item.criterionId)}: ${item.status} — ${safe(item.summary)}`);
+        lines.push(...item.evidence.map((evidence) => `  - ${safe(evidence)}`));
+    }
+    lines.push("", "Findings:");
+    if (report.findings.length === 0)
+        lines.push("- none");
+    for (const finding of report.findings) {
+        lines.push(`- [${finding.severity}] ${finding.blocking ? "blocking" : "non-blocking"}: ${safe(finding.title)}`);
+        lines.push(`  Criteria: ${finding.criterionIds.length === 0 ? "none" : finding.criterionIds.map(safe).join(", ")}`);
+        lines.push(`  ${safe(finding.details)}`);
+        lines.push(`  Recommendation: ${safe(finding.recommendation)}`);
+        lines.push(...finding.locations.map((location) => `  Location: ${safe(location.path)}${location.line === undefined ? "" : `:${location.line}`}`));
+        lines.push(...finding.evidence.map((evidence) => `  Evidence: ${safe(evidence)}`));
+    }
+    lines.push("", "Residual risks:", ...lineList(report.residualRisks));
+    lines.push("", "Changed files inspected:", ...lineList(report.changedFilesInspected));
+    lines.push("", "Supporting files inspected:", ...lineList(report.supportingFilesInspected));
+    return lines;
+}
+/** Full, already-redacted reports, with unrun rounds explicitly named. */
+export function renderReviewDetails(entries, mode) {
+    const lines = [`Recorded review (${mode}):`];
+    for (const { taskId, title, artifact } of entries) {
+        lines.push("", `Task ${safe(taskId)}: ${safe(title)}`);
+        if (artifact === null) {
+            lines.push("No review for the current candidate.", "Round 1 — primary: NOT_RUN.", "Round 2 — adversarial: NOT_RUN.");
+            continue;
+        }
+        const first = artifact.attempts?.[0];
+        lines.push(`Round 1 — primary (${safe(first?.target ?? artifact.harness ?? "unassigned")}): ${first?.status ?? "NOT_RUN"}.`);
+        if (artifact.report === undefined)
+            lines.push(`Reason: ${safe(first?.reason ?? artifact.reason ?? "no report")}.`);
+        else
+            lines.push(...fullReportLines(artifact.report));
+        const second = artifact.attempts?.[1];
+        lines.push("", `Round 2 — adversarial (${safe(second?.target ?? artifact.adversarial?.target ?? "unassigned")}): ${second?.status ?? "NOT_RUN"}.`);
+        if (artifact.adversarial !== undefined)
+            lines.push(artifact.adversarial.refuted ? "Outcome: refuted the primary PASS." : "Outcome: upheld the primary PASS.");
+        if (artifact.adversarial?.report === undefined) {
+            lines.push(`Not run: ${safe(second?.reason ?? (artifact.report === undefined ? "first round did not run" :
+                first?.status === "FAIL" ? "first round failed" : artifact.reason ?? "no second-round report"))}.`);
+        }
+        else {
+            lines.push(...fullReportLines(artifact.adversarial.report));
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Short finish output still names every concrete non-blocking issue and risk. */
+export function renderReviewHighlights(entries) {
+    const lines = [];
+    for (const { title, artifact } of entries) {
+        if (artifact === null)
+            continue;
+        const rounds = [artifact.report, artifact.adversarial?.report];
+        for (const [index, report] of rounds.entries()) {
+            if (report === undefined)
+                continue;
+            lines.push(`${entries.length > 1 ? `${safe(title)} — ` : ""}Round ${index + 1}: ${safe(report.summary)}`);
+            for (const finding of report.findings.filter(({ blocking }) => !blocking)) {
+                lines.push(`- [${finding.severity}] ${safe(finding.title)}: ${safe(finding.details)}`);
+            }
+            for (const risk of report.residualRisks)
+                lines.push(`- Risk: ${safe(risk)}`);
+        }
+    }
+    return lines.length === 0 ? "No review report is available.\n" : `${lines.join("\n")}\n`;
+}

package/dist/runtime/src/schema/validate.js

@@ -523,7 +523,7 @@ function validateCriterion(value, path) {
     return success(value);
 }
 export function validateTask(value) {
-    const root = validateRoot(value, ["criteria", "id", "parentTaskId", "schemaVersion", "title"], TASK_SCHEMA_VERSION);
+    const root = validateRoot(value, ["criteria", "id", "intent", "parentTaskId", "schemaVersion", "title"], TASK_SCHEMA_VERSION);
     if (isFailure(root)) {
         return root;
     }
@@ -539,6 +539,11 @@ export function validateTask(value) {
     if (!isNonEmptyString(root.title)) {
         return failure("INVALID_TITLE", "$.title", "Task title is required.");
     }
+    if (root.intent !== undefined &&
+        (typeof root.intent !== "string" || root.intent.trim() === "" ||
+            root.intent.includes("\0") || Buffer.byteLength(root.intent, "utf8") > 8192)) {
+        return failure("INVALID_INTENT", "$.intent", "Task intent must be non-empty and at most 8 KiB.");
+    }
     if (!Array.isArray(root.criteria) ||
         root.criteria.length < 2 ||
         root.criteria.length > 5) {

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

@@ -3,7 +3,19 @@ import { findReviewAttestation } from "../review/attestation.js";
 import { validateEvidence, validateTaskAgainstConfig } from "../schema/validate.js";
 import { isPassingVerificationEvidence } from "../verify/evidence.js";
 export async function checkTaskCompletionEvidence(stored, options) {
-    const { root, config, sourceFingerprint, evidenceStore } = 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 ||
+        (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.` };
+    }
+    return null;
+}
+/** The same mechanical proof check used by final completion and child delivery. */
+export async function checkTaskVerificationEvidence(stored, options) {
+    const { config, sourceFingerprint, evidenceStore } = options;
     if (stored.failureFingerprint !== null) {
         return { status: "FAIL", code: "VERIFICATION_FAILED", remedy: "Resolve the latest verification failure before completing the task." };
     }
@@ -40,10 +52,6 @@ export async function checkTaskCompletionEvidence(stored, options) {
             }
         }
     }
-    const attestation = await findReviewAttestation(root, sourceFingerprint, stored.task.id);
-    if (attestation === null || attestation.taskId !== stored.task.id) {
-        return { status: "FAIL", code: "REVIEW_REQUIRED", remedy: `Run agent-ops review --task ${stored.task.id} --yes for the whole task and current source.` };
-    }
     return null;
 }
 /** Include descendants so legacy completed children cannot hide unfinished work. */

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

@@ -26,6 +26,9 @@ export function renderTaskMarkdown(record) {
         ...(record.archivedAt === null
             ? []
             : [`Archived: ${record.archivedAt}`]),
+        ...(record.task.intent === undefined
+            ? []
+            : ["", "## Modification intent", "", safeTaskText(record.task.intent)]),
         "",
         "## Acceptance criteria",
         ""

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

@@ -90,6 +90,7 @@ export class TaskService {
             schemaVersion: TASK_SCHEMA_VERSION,
             id: this.#generateId(),
             title: input.title,
+            ...(input.intent === undefined ? {} : { intent: input.intent }),
             criteria: [...input.criteria],
             ...(input.parentTaskId === undefined
                 ? {}
@@ -153,6 +154,53 @@ export class TaskService {
             return cloneRecord(record);
         });
     }
+    /** 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() === "")) {
+            throw taskError("TASK_DELIVERY_INVALID", "Every delivered task needs a recorded intent and must not be archived.");
+        }
+        await this.#store.mutate((state) => {
+            const parent = findTask(state, parentTaskId);
+            if (parent.status !== "active") {
+                throw taskError("TASK_PARENT_NOT_ACTIVE", "Only an active parent can accept delivery.");
+            }
+            const ids = new Set(delivered.map(({ task }) => task.id));
+            if (ids.size !== delivered.length) {
+                throw taskError("TASK_DELIVERY_INVALID", "Delivered task IDs must be unique.");
+            }
+            for (const record of delivered) {
+                const task = {
+                    ...record.task,
+                    ...(record.task.parentTaskId === undefined ? { parentTaskId } : {})
+                };
+                if (task.parentTaskId !== parentTaskId && !ids.has(task.parentTaskId)) {
+                    throw taskError("TASK_DELIVERY_INVALID", `Task ${task.id} has a parent outside this delivery.`);
+                }
+                if (record.policyConfigHash !== parent.policyConfigHash || !validateTask(task).ok) {
+                    throw taskError("TASK_DELIVERY_INVALID", `Task ${task.id} has an incompatible policy or definition.`);
+                }
+                const existing = state.tasks.find((item) => item.task.id === task.id);
+                if (existing !== undefined) {
+                    if (JSON.stringify(existing.task) !== JSON.stringify(task)) {
+                        throw taskError("TASK_ID_CONFLICT", `Task ${task.id} conflicts with an existing task.`);
+                    }
+                    continue;
+                }
+                state.tasks.push({
+                    task,
+                    status: "active",
+                    evidence: {},
+                    createdAt: record.createdAt,
+                    updatedAt: this.#now(),
+                    completedAt: null,
+                    archivedAt: null,
+                    failureFingerprint: null,
+                    policyConfigHash: record.policyConfigHash,
+                    completionBase: null
+                });
+            }
+        });
+    }
     async list(filter = {}) {
         const state = await this.#store.read();
         return state.tasks

package/docs/en/guides/configuration.md

@@ -265,6 +265,16 @@ evidence. Give each editing conversation its own worktree instead:
   Creating a subtask keeps the session attached to the top of its tree, and
   each task keeps its own review record, so a parent and a subtask reviewed
   on the same source do not overwrite each other.
+- When writing subagents use separate worktrees, create each child task with
+  `--intent` before editing, then commit and verify locally. From the main
+  checkout run `agent-ops task advance --task <parent-id> --session <id> --yes`
+  through the trusted outer host runner. It integrates all child commits and
+  intents into the coordinator worktree, reruns each task's required verifier
+  on the same candidate, and performs one two-round tree review. Only an
+  explicit `NOT_RUN / scope-too-large` falls back to per-task two-round review.
+  After PASS it saves a complete receipt under `.git/agent-ops/receipts/` and
+  calls finish; a moved target may trigger one repeat of the final gate.
+  A direct finish of one child while siblings exist is refused.
 - `agent-ops worktree finish <name>` merges by fast-forward only, one finish
   at a time. When the main checkout is on the target branch the merge updates
   its files, so uncommitted changes there block it. When the main checkout is

package/docs/en/spec/acceptance-and-evidence.md

@@ -10,6 +10,16 @@ Every acceptance criterion MUST map to observable evidence.
 - Positive: `criterion tests → npm test (354 passing tests)`.
 - Negative: `The implementation looks correct, so no evidence is needed.`
 
+## EVIDENCE-INTENT-001
+
+Each child worktree MUST record its modification intent before editing.
+
+- Trigger: A subagent will edit in its own worktree.
+- Action: Use `task create --intent <text>` to record the user-approved behavior, constraints and integration points. The coordinator imports the intent with the child task and re-runs verification on the integrated candidate.
+- Evidence: The child task and final receipt contain the intent, with final verifier evidence bound to the integrated candidate.
+- Positive: `A child records its planned API change, commits it, and the final receipt includes that intent and integrated verification.`
+- Negative: `A child edits first and supplies a retrospective one-line intent at delivery.`
+
 ## EVIDENCE-AGGREGATE-001
 
 The verifier MUST return FAIL when a criterion is missing, duplicated, unknown, or has empty evidence.

package/docs/en/spec/delegation.md

@@ -42,10 +42,10 @@ Parallel editing conversations in one repository MUST each work in their own age
 
 ## DELEGATE-ISOLATION-003
 
-Subagents that write files in one session MUST each work in their own agent-ops worktree, with their own task, verification and review.
+Subagents that write files in one session MUST each work in their own agent-ops worktree, with their own task, pre-work modification intent and local verification.
 
 - Trigger: `worktree.mode` is `auto` and a subagent writes a file. Hook calls made inside a subagent carry its `agent_id` under the parent's `session_id`; a payload without `agent_id` is treated as the session's main thread.
-- Action: The first blocked write allocates a worktree owned by that session and agent; edit there using absolute paths, because the hook's `cwd` does not follow a `cd`. The subagent commits and runs `agent-ops verify` and `agent-ops review` in its worktree. At most two reviews run at once across all worktrees of the repository; the rest wait. The coordinator runs `agent-ops worktree finish <name>` for each worktree in turn, and Stop is allowed only when every worktree of the session has a completed task.
-- Evidence: `agent-ops worktree list` shows an `agent:` line for each subagent worktree, writing into another writer's worktree is refused with `WORKTREE_OWNED_BY_OTHER_AGENT`, and each finish reports a fast-forward merge.
-- Positive: `Two subagents implement independent tasks in .worktrees/session-ab12cd34-a9230363 and .worktrees/session-ab12cd34-b1111111; each reviews itself and the coordinator finishes them one after the other.`
+- Action: The first blocked write allocates a worktree owned by that session and agent; edit there using absolute paths, because the hook's `cwd` does not follow a `cd`. Each subagent records `task create --intent` before editing, then commits and runs `agent-ops verify --task` locally. The coordinator runs `agent-ops task advance --task <parent-id> --session <id> --yes` from the main checkout. It integrates every child into the session candidate, verifies all criteria on that candidate, reviews the whole tree in two fresh sessions, archives proof locally and finishes. A direct finish of one child while siblings exist is refused.
+- Evidence: `agent-ops worktree list` shows an `agent:` line for each child; the final receipt under `.git/agent-ops/receipts/` contains the integrated task tree, intents, verifier evidence and review reports.
+- Positive: `Two subagents commit and verify separate worktrees; one task advance integrates them and completes the final gate before finish.`
 - Negative: `A subagent edits the coordinator's worktree, or two subagents edit one worktree, so one review covers two tasks' changes.`

package/docs/en/spec/review.md

@@ -5,9 +5,9 @@
 An independent reviewer MUST receive a minimal packet containing the request, criteria, artifact references, and evidence requirements.
 
 - Trigger: A multi-step change reaches a review checkpoint.
-- Action: Omit implementation rationale, hidden reasoning, raw logs, and credentials.
+- Action: Include user-approved task intent in the request when recorded; omit hidden reasoning, raw logs, and credentials.
 - Evidence: The packet keys and artifact references are visible without sensitive content.
-- Positive: `Packet contains criteria, files, and evidence requirements only.`
+- Positive: `Packet contains recorded task intent, criteria, files, and evidence requirements.`
 - Negative: `Forward the complete session transcript and environment.`
 
 ## REVIEW-RESULT-001
@@ -126,6 +126,28 @@ FAIL.
 - Positive: `NOT_RUN: unparseable-output; one criterion was missing.`
 - Negative: `Record a failed review because the model's JSON was malformed.`
 
+## REVIEW-TREE-001
+
+`task advance` MUST prove one integrated candidate against every parent and descendant criterion before it calls finish.
+
+- Trigger: A session has a parent task and one or more agent-owned child worktrees.
+- Action: Import each child task's pre-work intent and committed code into the coordinator candidate. Run every task's required verifier against the same final base and source fingerprint. Run `review --task <parent-id> --tree --base <final-base> --yes`, which sends all uniquely qualified criteria and intents through the existing two fresh reviewer sessions. Save a task-bound alias for every task, all pointing to that complete tree report.
+- Evidence: The final receipt contains the complete task tree, intents, source fingerprint, verifier evidence, two reviewer reports, review mode, and residual risks.
+- Positive: `Two child worktrees with three criteria each and a parent with two criteria receive one two-round final review covering all eight criteria.`
+- Negative: `Review the parent alone, then finish children whose criteria were never checked against the integrated code.`
+
+Only `NOT_RUN / scope-too-large` may fall back to a separate complete two-round review for each task. A substantive FAIL, missing verifier evidence, reviewer unavailability, or any other NOT_RUN blocks finish. `task advance` may rebase onto a moved target and repeat the entire final gate once. The receipt is written under the main checkout's `.git/agent-ops/receipts/` before the target branch moves; failure to write or read it back blocks the merge. A late target move rejects the merge so final proof can be repeated. A post-merge cleanup failure is reported as partial, not as successful finish.
+
+## REVIEW-SHOW-001
+
+The user MUST be able to inspect both recorded reviewer reports for the latest candidate from the main checkout without starting another review.
+
+- Trigger: `review show --task <id>` for an active or finished task.
+- Action: Display the full redacted structured primary and adversarial reports, including every criterion, finding, inspected file, and residual risk. For a successful tree review, display the shared report once; for a per-task fallback, group both rounds by task. Validate a finished receipt against its Git note digest. If the candidate changed since review, state that the current candidate has no review instead of showing an old verdict. A failed or unavailable round names the missing report explicitly. `task advance` summarizes concrete nonblocking findings and risks on PASS and shows available report details on failure.
+- Evidence: The read-only command invokes no reviewer and its output is bound to the active fingerprint or the finished receipt.
+- Positive: `After finish, review show from main displays both full reports and residual risks for the final candidate.`
+- Negative: `A new commit still displays the preceding candidate's PASS as current.`
+
 ## REVIEW-BATCH-001
 
 A batch review MUST cover exactly the active subtasks of the named parent and the parent itself.