@kylecheng3146/agent-ops 0.11.2 → 0.11.3

package/README.md

@@ -17,7 +17,9 @@ command behavior may change before 1.0.
 Every new task, including DEBUG and native run parent/child tasks, waits for one
 independent advisory review of its goal, criteria and assigned surface before
 implementation. Read the suggestions, decide which to adopt, and record reasons
-through `task revise`. Revisions do not automatically re-review.
+through `task revise`. The first revision that changes criteria, intent or
+goal reruns the advisory once; surface-only revisions do not, and later
+reruns are explicit (`review --criteria --rerun`).
 
 The advisory has no time/token budget; explicit cancellation stops work. Genuine
 execution errors report NOT_RUN and allow work. Detailed reports remain private;

package/dist/packages/cli/src/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { reviewCreatedCriteria, criteriaReviewStatus } from "./criteria-review.js";
+import { reviewCreatedCriteria, reviewRevisedCriteria, criteriaReviewStatus } from "./criteria-review.js";
 import { renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
 import { advancePhaseObserver, productionRunContext } from "./run-deps.js";
 import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
@@ -520,6 +520,7 @@ else {
                         service: taskService,
                         onTaskCreated: async (record, createdRoot) => await reviewCreatedCriteria(createdRoot ?? root, record.task),
                         criteriaStatus: async (record) => await criteriaReviewStatus(root, record.task),
+                        onTaskRevised: async (record) => await reviewRevisedCriteria(root, record.task),
                         ...(policyConfigHash === undefined ? {} : { policyConfigHash }),
                         ...(sessionId === undefined ? {} : { sessionId }),
                         ...(fromMain

package/dist/packages/cli/src/commands/review.js

@@ -2,7 +2,7 @@ import { buildReviewPacket } from "../../../../runtime/src/review/packet.js";
 import { runIndependentReview } from "../../../../runtime/src/review/runner.js";
 import { renderReviewResult } from "../../../../runtime/src/review/render.js";
 import { reviewReportResults } from "../../../../runtime/src/review/report.js";
-import { findPriorFailingFindings, findReviewAttestation, invalidateReviewAttestation, readReviewReportArtifact, reviewReportDigest, saveReviewAttestation, saveReviewReportArtifact } from "../../../../runtime/src/review/attestation.js";
+import { countFailedReviewRounds, findPriorFailingFindings, REVIEW_ROUND_CAP, findReviewAttestation, invalidateReviewAttestation, readReviewReportArtifact, reviewReportDigest, saveReviewAttestation, saveReviewReportArtifact } from "../../../../runtime/src/review/attestation.js";
 import { detectHostTarget, planReviewTargets, resolveReviewRole } from "../../../../runtime/src/review/roles.js";
 import { evidenceMatchesContract, taskContractHash, treeContractHash, goalHash } from "../../../../runtime/src/task/contract.js";
 import { acceptanceCoverage, coverageDigest } from "../../../../runtime/src/verify/acceptance-coverage.js";
@@ -649,6 +649,20 @@ export async function runReviewCommand(options) {
         ? await treeContext(options)
         : await taskContext(options);
     options = { ...options, noChangePaths: options.noChangePaths ?? context?.records.find(r => r.task.id === context.taskId)?.noChangePaths };
+    // Before any scope, surface or reviewer cost: a contract that keeps failing
+    // needs a new approach, not another round of one-by-one fixes.
+    if (context !== undefined && options.root !== undefined) {
+        const own = context.records.find(r => r.task.id === context.taskId).task;
+        if (await countFailedReviewRounds(options.root, context.taskId, taskContractHash(own)) >= REVIEW_ROUND_CAP) {
+            const result = { ...resultBase, status: "NOT_RUN", reason: "round-cap", taskId: context.taskId };
+            const message = "Independent review was not run.";
+            return { code: "REVIEW_NOT_RUN", status: "error", errors: [{ code: "REVIEW_NOT_RUN", message }], data: { message, result,
+                    text: renderReviewResult(result) +
+                        `Review failed ${REVIEW_ROUND_CAP} times under this contract. Stop fixing findings one by one: reconsider ` +
+                        "the approach, then record the new plan (criteria or intent) with a reason, or ask the user how to proceed:\n" +
+                        `  agent-ops task revise --task ${context.taskId} --expected-contract ${taskContractHash(own)} --reason "<what changed in the approach>"\n` } };
+        }
+    }
     const evidenceRequirements = (options.args.evidence ?? []).map((value) => {
         const separator = value.indexOf("=");
         return {

package/dist/packages/cli/src/commands/task.js

@@ -6,7 +6,12 @@ import { renderTaskMarkdown, safeTaskText } from "../../../../runtime/src/task/r
 import { errorEnvelope, okEnvelope } from "../output.js";
 async function withCriteriaStatus(envelope, options) {
     const item = envelope.data?.record;
-    const advice = item === undefined ? null : await options.criteriaStatus?.(item).catch(() => null);
+    // A status read is best effort; a cancelled advisory round must still stop the caller.
+    const advice = item === undefined ? null : await options.criteriaStatus?.(item).catch((error) => {
+        if (error instanceof AgentOpsError && error.code === "CRITERIA_REVIEW_CANCELLED")
+            throw error;
+        return null;
+    });
     return advice == null || envelope.data === null ? envelope : { ...envelope, data: { ...envelope.data, criteriaReview: advice,
             text: envelope.data.text + "\n\n" + renderCriteriaReview(advice) } };
 }
@@ -202,7 +207,8 @@ export async function runTaskCommand(options) {
                 ...(origin === undefined ? {} : { origin }),
                 reason: options.args.reason, ...(options.args.baseline === undefined ? {} : { baseline: options.args.baseline })
             });
-            return await withCriteriaStatus(await withEscape(taskEnvelope(action, "TASK_REVISED", "Contract revised; obtain a fresh review, and new verification if the criteria or configuration changed.", record), origin === undefined ? undefined : await options.service.declareEscape(record.task.id), options.service), options);
+            // The revision is saved first: an advisory NOT_RUN keeps TASK_REVISED, and a cancelled round throws with it kept.
+            return await withCriteriaStatus(await withEscape(taskEnvelope(action, "TASK_REVISED", "Contract revised; obtain a fresh review, and new verification if the criteria or configuration changed.", record), origin === undefined ? undefined : await options.service.declareEscape(record.task.id), options.service), options.onTaskRevised === undefined ? options : { ...options, criteriaStatus: options.onTaskRevised });
         }
         if (action === "replan") {
             const payload = await jsonFile(options.args.planFile);

package/dist/packages/cli/src/criteria-review.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
-import { runCriteriaReview, readCriteriaReview, renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
+import { runCriteriaReview, readCriteriaReview, renderCriteriaReview, revisionReviewDue } from "../../../runtime/src/review/criteria.js";
 import { registeredRunProofRunner } from "../../../runtime/src/verify/spawn.js";
 import { appendLocalLog } from "../../../runtime/src/logging/local-log.js";
 import { localStatePaths } from "../../../runtime/src/security/permissions.js";
@@ -24,7 +24,7 @@ export async function criteriaReviewStatus(root, task) {
     return await readCriteriaReview(root, task, await parentScope(root, task).catch(() => undefined));
 }
 /** Only production creation/explicit review installs this hook; TaskService stays model-free. */
-export async function reviewCreatedCriteria(root, task, rerun = false) {
+export async function reviewCreatedCriteria(root, task, rerun = false, trigger) {
     const controller = new AbortController();
     const interrupt = (signal) => { controller.abort(signal); };
     const int = () => interrupt("SIGINT"), term = () => interrupt("SIGTERM");
@@ -38,7 +38,7 @@ export async function reviewCreatedCriteria(root, task, rerun = false) {
         const parent = await parentScope(root, task).catch(() => undefined);
         process.stderr.write(`Criteria advisory for ${task.id}: waiting for one independent reviewer (no time budget; Ctrl-C cancels).\n`);
         let result = await runCriteriaReview({ root, task, parent, target, model: role?.model, effort: role?.effort,
-            rerun, signal: controller.signal, runner: registeredRunProofRunner(),
+            rerun, ...(trigger === undefined ? {} : { trigger }), signal: controller.signal, runner: registeredRunProofRunner(),
             unavailableCode: config === undefined ? "CRITERIA_REVIEW_CONFIG_UNAVAILABLE" : target === undefined && role !== undefined ? "CRITERIA_REVIEW_NO_INDEPENDENT_TARGET" : "CRITERIA_REVIEW_UNCONFIGURED",
             log: async (report, path) => {
                 const state = localStatePaths(process.env.AGENT_OPS_HOME ?? homedir());
@@ -61,3 +61,8 @@ export async function reviewCreatedCriteria(root, task, rerun = false) {
         process.removeListener("SIGTERM", term);
     }
 }
+/** A revise that changed what the advice judged reruns it once; otherwise it reports the current advisory. */
+export async function reviewRevisedCriteria(root, task) {
+    const view = await criteriaReviewStatus(root, task);
+    return revisionReviewDue(view) ? await reviewCreatedCriteria(root, task, true, "revise") : view;
+}

package/dist/packages/cli/src/run-entry.js

@@ -113,7 +113,7 @@ export function coordinatorWakeNote(state, coordinator) {
 export function workerInstructionLines() {
     return ["Keep the original goal fixed. Read this repository's AGENTS.md and use its existing verifier authority.",
         "Plan 2–5 substantive acceptance criteria. Submit a plan request before changing product files; the supervisor creates the task with the fixed goal.",
-        "Read the criteria advisory before implementation. Decide which suggestions to adopt and use task revise with reasons (including rejected advice). A revision does not automatically rerun criteria review; formal final proof remains required.",
+        "Read the criteria advisory before implementation. Decide which suggestions to adopt and use task revise with reasons (including rejected advice). The first revision that changes criteria, intent or goal reruns criteria review once and waits for it; later ones do not. Formal final proof remains required.",
         "For every mechanically testable requirement use a configured acceptance runner; explicit review-only fallback requires a recorded reason and fresh goal review.",
         "Implement, run targeted fast checks on changed code, commit and submit action=handoff so the supervisor runs full verification outside your context window. Do not poll full-suite verification in a loop. Repair failed checks and pin mechanically testable review findings into regression criteria. Never disable a mandatory policy verifier.",
         "Only registered run workers may write. Use isolated worktrees and supervisor-issued leases; do not launch an unregistered writing subagent.",

package/dist/runtime/src/install/harness.js

@@ -367,7 +367,7 @@ export function managedRules(descriptor, context) {
     if (context.capabilities.includes("task"))
         lines.push("To fix a bug, run `agent-ops task create --debug --goal <verbatim issue>` with a", "behavioral criterion whose `redCheckIds` fail at the baseline and pass on the", "candidate, then verify, review and finish as for any task. If you know where the", "bug came from, record it with `task revise --escape-of <commit> --escape-label", "<label>`; the origin is advisory and never blocks finish.", "");
     if (context.capabilities.includes("rules")) {
-        lines.push("   Every production task creation waits for one independent criteria advisory", "   before implementation (also DEBUG and native run parents/children). It has", "   no time/token budget; real launch/auth/output errors report NOT_RUN and", "   allow work, while explicit cancellation means stop. Read the private report,", "   decide which advice to adopt, and use task revise with reasons (including", "   rejections). Revise does not rerun it. Explicit rerun only:", "   `agent-ops review --criteria --task <id> --rerun --yes`.", "   Start task creation/criteria review through the trusted outer host when", "   the host sandbox blocks reviewer auth/network, using the same outer-host", "   invocation described below for review. Never bypass a native denial.", "   This advisory never replaces verify, final two-round review or finish.", "", "For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("   Every production task creation waits for one independent criteria advisory", "   before implementation (also DEBUG and native run parents/children). It has", "   no time/token budget; real launch/auth/output errors report NOT_RUN and", "   allow work, while explicit cancellation means stop. Read the private report,", "   decide which advice to adopt, and use task revise with reasons (including", "   rejections). The first revise that changes criteria, intent or goal", "   reruns it once and waits; surface-only revises do not. Later reruns are", "   explicit only: `agent-ops review --criteria --task <id> --rerun --yes`.", "   Start task creation/revise/criteria review through the trusted outer host when", "   the host sandbox blocks reviewer auth/network, using the same outer-host", "   invocation described below for review. Never bypass a native denial.", "   This advisory never replaces verify, final two-round review or finish.", "", "For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
         lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria and verification; final review covers all", "tasks together when their worktrees are integrated;", "completing one never completes its parent.", "", ...autoRunInstruction(descriptor, context), "To review every active subtask of a parent together, run", "`agent-ops batch --parent <task-id> --yes` instead of one review per", "subtask. It needs what review needs: start it through the trusted outer", "host runner as its first and only invocation, with the same Codex", "elevation, and keep `--output <file>` instead of a shell redirect. It", "verifies, one task at a time, each task that lacks fresh evidence, and", "reviews a few tasks at once. Do not commit or edit the worktree while it", "runs: a moved HEAD voids every verify and review in the batch.", "For subagents in separate worktrees, use `task advance` instead.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "", "For a session with writing subagents, record each child task's complete", "modification intent with `task create --intent <text>` before editing.", "Each child commits and runs local `verify --task` in its own worktree.", "From the main checkout run `agent-ops task advance --task <parent-id>", "--session <session-id> --yes` through the trusted outer host runner,", "unsetting `CODEX_SANDBOX_NETWORK_DISABLED` on Codex. Advance integrates", "child commits and intent into the coordinator worktree, verifies every", "task on the final candidate, then runs one two-round tree review.", "Only `NOT_RUN / scope-too-large` falls back to per-task two-round review;", "a substantive FAIL must be fixed. After PASS, advance writes a local", "receipt under the main checkout's Git common directory and calls finish.", "If the target moves, it retries the final gate once. An unresolved", "failure preserves worktrees and cannot be reported as finished.", "");

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

@@ -444,13 +444,11 @@ function blockingFindings(artifact) {
     return findings;
 }
 /**
- * Blocking findings of this task's most recent decided review, when that
- * review failed. NOT_RUN artifacts decide nothing and are skipped; a newer
- * PASS settles the earlier findings, so none are returned. Any unreadable
- * record is ignored: these are a hint for the next reviewer, and without them
- * the review simply runs as it always has.
+ * This task's decided reviews: PASS, or FAIL with a report. NOT_RUN artifacts
+ * decide nothing and are skipped, as is any unreadable record: callers use
+ * these as hints, and without them review simply runs as it always has.
  */
-export async function findPriorFailingFindings(root, taskId) {
+async function decidedTaskReviews(root, taskId) {
     const directory = join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"));
     let names;
     try {
@@ -460,7 +458,7 @@ export async function findPriorFailingFindings(root, taskId) {
         return [];
     }
     // ponytail: linear scan of every report; index by task if the directory grows large.
-    let latest;
+    const decided = [];
     for (const name of names) {
         // `<fingerprint>` or `<fingerprint>.<task id>`, then the suffix.
         const key = name.slice(0, -REVIEW_REPORT_ARTIFACT_SUFFIX.length);
@@ -475,23 +473,47 @@ export async function findPriorFailingFindings(root, taskId) {
                 continue;
             }
             const value = JSON.parse(source);
-            const decided = value.status === "PASS" ||
-                (value.status === "FAIL" && value.report !== undefined);
             if (![1, 2].includes(value?.schemaVersion) ||
                 value.sourceFingerprint !== fingerprint ||
                 value.taskId !== taskId ||
-                !decided ||
+                !(value.status === "PASS" || (value.status === "FAIL" && value.report !== undefined)) ||
                 !Number.isFinite(Date.parse(value.createdAt))) {
                 continue;
             }
-            if (latest === undefined || Date.parse(value.createdAt) > Date.parse(latest.createdAt)) {
-                latest = value;
-            }
+            decided.push(value);
         }
         catch {
             continue;
         }
     }
+    return decided;
+}
+/** After this many failed reviews of one contract, review stops and asks for a rethink. */
+export const REVIEW_ROUND_CAP = 3;
+/**
+ * Failed reviews of this task under its current contract since its latest
+ * PASS. Each source fingerprint keeps one report, so re-reviewing unchanged
+ * code does not add a round; a contract revision starts the count again.
+ */
+export async function countFailedReviewRounds(root, taskId, contractHash) {
+    const reviews = await decidedTaskReviews(root, taskId);
+    const lastPass = Math.max(-Infinity, ...reviews.filter(review => review.status === "PASS")
+        .map(review => Date.parse(review.createdAt)));
+    return reviews.filter(review => review.status === "FAIL" && review.taskContractHash === contractHash &&
+        Date.parse(review.createdAt) > lastPass).length;
+}
+/**
+ * Blocking findings of this task's most recent decided review, when that
+ * review failed. A newer PASS settles the earlier findings, so none are
+ * returned.
+ */
+export async function findPriorFailingFindings(root, taskId) {
+    let latest;
+    for (const value of await decidedTaskReviews(root, taskId)) {
+        if (latest === undefined || Date.parse(value.createdAt) > Date.parse(latest.createdAt)) {
+            latest = value;
+        }
+    }
     if (latest?.status !== "FAIL") {
         return [];
     }

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

@@ -74,13 +74,14 @@ async function readReport(path, root) {
     if (Buffer.byteLength(source) > 512 * 1024)
         throw new Error("Advisory artifact exceeds limit.");
     const value = JSON.parse(source);
-    if (!record(value) || Object.keys(value).some(key => !["kind", "taskId", "attemptId", "snapshotHash", "snapshot", "status", "code", "startedAt", "durationMs", "invocations", "ownerPid", "ownerIdentity", "target", "advice", "usage"].includes(key)) ||
+    if (!record(value) || Object.keys(value).some(key => !["kind", "taskId", "attemptId", "snapshotHash", "snapshot", "status", "code", "startedAt", "durationMs", "invocations", "ownerPid", "ownerIdentity", "target", "advice", "usage", "trigger"].includes(key)) ||
         value.kind !== "criteria-advisory" || !validText(value.taskId) || typeof value.attemptId !== "string" || !/^[a-f0-9-]{36}$/u.test(value.attemptId) ||
         !Number.isSafeInteger(value.ownerPid) || value.ownerPid < 1 ||
         (value.ownerIdentity !== null && !validText(value.ownerIdentity)) ||
         !validText(value.code) || !validText(value.startedAt) || !Number.isFinite(Date.parse(value.startedAt)) ||
         !Number.isSafeInteger(value.durationMs) || value.durationMs < 0 || ![0, 1].includes(value.invocations) ||
         (value.target !== undefined && !["agy", "claude", "codex"].includes(String(value.target))) ||
+        (value.trigger !== undefined && !["create", "rerun", "revise"].includes(String(value.trigger))) ||
         (value.usage !== undefined && (!record(value.usage) || Object.entries(value.usage).some(([key, n]) => !["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "costUsd"].includes(key) || typeof n !== "number" || !Number.isFinite(n) || n < 0))) ||
         typeof value.snapshotHash !== "string" || !/^[a-f0-9]{64}$/u.test(value.snapshotHash) || !record(value.snapshot) ||
         !["RUNNING", "COMPLETED", "NOT_RUN", "CANCELLED"].includes(String(value.status)) ||
@@ -101,12 +102,28 @@ async function ownerAlive(report) {
         return error.code !== "ESRCH";
     }
 }
+/**
+ * The surface audit is reviewed but is not what the advice is about: classifying
+ * one more discovery hit must not make the criteria look unreviewed. The stored
+ * snapshot is redacted, so the current one is redacted the same way.
+ */
+function criteriaCore(snapshot) {
+    const { surface: _surface, ...core } = snapshot;
+    return canonicalJson(core);
+}
+function coreChanged(report, snapshot) {
+    return criteriaCore(report.snapshot) !== criteriaCore(redactData(snapshot));
+}
+/** One automatic round after a substantive revise; after it only an explicit --rerun makes another due. */
+export function revisionReviewDue(view) {
+    return view !== null && view.stale && view.report.trigger !== "revise" && view.report.status !== "RUNNING";
+}
 export async function readCriteriaReview(root, task, parent) {
     try {
         const path = reportPath(root, task.id), report = await readReport(path, root);
         if (report === null || report.taskId !== task.id)
             return null;
-        return { report, reportPath: path, stale: report.snapshotHash !== sha256(canonicalJson(criteriaSnapshot(task, parent))), warnings: [] };
+        return { report, reportPath: path, stale: coreChanged(report, criteriaSnapshot(task, parent)), warnings: [] };
     }
     catch {
         return null;
@@ -119,7 +136,7 @@ export function renderCriteriaReview(view) {
         "Private report: " + view.reportPath, (report.advice === undefined ? undefined : safeTaskText(report.advice.summary)) ?? "No completed advice is available.",
         ...(report.advice?.recommendations ?? []).map(r => `[${safeTaskText(r.criterionId)}] ${safeTaskText(r.issue)}\nSuggestion: ${safeTaskText(r.recommendation)}\nWhy: ${safeTaskText(r.reason)}`),
         ...(report.advice?.limitations ?? []).map(s => "Limitation: " + safeTaskText(s)), ...view.warnings,
-        "Advisory only. Decide which suggestions to adopt; use task revise and record reasons, including rejections. Revision does not rerun this review. Final verification and two-round review are still required."
+        "Advisory only. Decide which suggestions to adopt; use task revise and record reasons, including rejections. The first revise that changes criteria, intent or goal reruns this review once; later ones need an explicit --rerun. Final verification and two-round review are still required."
     ].join("\n");
 }
 function cancelled(signal) {
@@ -134,10 +151,10 @@ export async function runCriteriaReview(options) {
     let report = { kind: "criteria-advisory", taskId: task.id, attemptId: randomUUID(), snapshotHash,
         snapshot: redactData(snapshot), status: "RUNNING", code: "CRITERIA_REVIEW_RUNNING",
         startedAt: new Date().toISOString(), durationMs: 0, invocations: 0, ownerPid: process.pid, ownerIdentity: await nativeProcessIdentity(process.pid),
-        ...(options.target === undefined ? {} : { target: options.target }) };
+        ...(options.target === undefined ? {} : { target: options.target }), trigger: options.trigger ?? (options.rerun ? "rerun" : "create") };
     const newAttempt = report;
     const warnings = [];
-    const view = () => ({ report, reportPath: path, stale: report.snapshotHash !== snapshotHash, warnings });
+    const view = () => ({ report, reportPath: path, stale: coreChanged(report, snapshot), warnings });
     let claimed = false;
     try {
         for (;;) {

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

@@ -64,7 +64,8 @@ function location(value, path, errors) {
 }
 function finding(value, path, errors) {
     if (!isRecord(value) || !exactFields(value, [
-        "severity", "blocking", "title", "details", "locations", "evidence", "recommendation", "criterionIds"
+        "severity", "blocking", "title", "details", "locations", "evidence", "recommendation", "criterionIds",
+        ...("origin" in value ? ["origin"] : [])
     ], path, errors)) {
         return undefined;
     }
@@ -73,8 +74,10 @@ function finding(value, path, errors) {
         !Array.isArray(value.locations) || value.locations.length > MAX_ARRAY ||
         !textArray(value.evidence) || value.evidence.length === 0 || !isText(value.recommendation) ||
         !textArray(value.criterionIds) || new Set(value.criterionIds).size !== value.criterionIds.length ||
-        (value.severity === "critical" && value.blocking !== true) ||
-        (value.severity === "minor" && value.blocking !== false)) {
+        (value.origin !== undefined && value.origin !== "introduced" && value.origin !== "pre-existing") ||
+        (value.origin === "pre-existing" ? value.blocking !== false :
+            (value.severity === "critical" && value.blocking !== true) ||
+                (value.severity === "minor" && value.blocking !== false))) {
         invalid(errors, path, "INVALID_FINDING", "Finding is invalid.");
         return undefined;
     }
@@ -90,7 +93,8 @@ function finding(value, path, errors) {
         locations: locations,
         evidence: [...value.evidence],
         recommendation: value.recommendation,
-        criterionIds: [...value.criterionIds]
+        criterionIds: [...value.criterionIds],
+        ...(value.origin === undefined ? {} : { origin: value.origin })
     };
 }
 export function validateReviewReport(value, requestedCriterionIds, changedFiles) {

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

@@ -22,6 +22,12 @@ const CONTRACT_INSTRUCTIONS = [
         "every changed path is still required and is checked on your reply.",
     "Report every blocking defect you find in this one reply, not only the " +
         "first: each defect left for a later round costs another full review.",
+    "A defect is pre-existing when it is present identically at the base and " +
+        "this change did not introduce, expose, worsen or depend on it. Report " +
+        "only pre-existing defects you meet while reading for this review; do not " +
+        "search for them. Give each one origin 'pre-existing' and blocking false, " +
+        "whatever its severity: it goes to followup, not to this change. Every " +
+        "other finding has origin 'introduced'.",
     "Every FAIL criterion must have at least one blocking finding whose " +
         "criterionIds includes it. Blocking findings may reference only FAIL " +
         "criteria.",
@@ -30,7 +36,8 @@ const CONTRACT_INSTRUCTIONS = [
         "summary:string,evidence:string[]}],findings:[{severity:'critical'|" +
         "'important'|'minor',blocking:boolean,title:string,details:string," +
         "locations:[{path:string,line?:integer}],evidence:string[]," +
-        "recommendation:string,criterionIds:string[]}],residualRisks:string[]," +
+        "recommendation:string,criterionIds:string[]," +
+        "origin?:'introduced'|'pre-existing'}],residualRisks:string[]," +
         "changedFilesInspected:string[],supportingFilesInspected:string[]}. " +
         "All descriptive strings and evidence arrays must be non-empty."
 ];
@@ -290,7 +297,8 @@ export function redactReviewReport(report) {
             })),
             evidence: finding.evidence.map((value) => safeTaskText(redactSecrets(value))),
             recommendation: safeTaskText(redactSecrets(finding.recommendation)),
-            criterionIds: finding.criterionIds.map((value) => safeTaskText(redactSecrets(value)))
+            criterionIds: finding.criterionIds.map((value) => safeTaskText(redactSecrets(value))),
+            ...(finding.origin === undefined ? {} : { origin: finding.origin })
         })),
         residualRisks: report.residualRisks.map((value) => safeTaskText(redactSecrets(value))),
         changedFilesInspected: report.changedFilesInspected.map((value) => safeTaskText(redactSecrets(value))),

package/docs/en/spec/review.md

@@ -5,14 +5,14 @@
 - Trigger: Production task criteria become ready before implementation.
 - Action: Await one scoped advisory and let the writer record adoption/rejection reasons.
 - Evidence: Private snapshot report plus safe local status/usage log; no completion attestation.
-- Positive: `A revised task shows historical advice and only an explicit rerun spends another round.`
-- Negative: `Automatically re-review every revise or treat advice as final PASS proof.`
+- Positive: `Adopting advice rewrites a criterion; that revise reruns the advisory once and shows the new advice.`
+- Negative: `Re-review every revise, including surface-only ones, or treat advice as final PASS proof.`
 
 Every production task creation (including DEBUG, replan children and native run root/child tasks) MUST wait for one independent criteria advisory before implementation. A fresh session uses one configured independent-review target, preferring a different target from the host. It receives only the original goal, assigned intent/covers, criteria and surface audit in an empty disposable workspace. It MUST NOT inspect repository files or run tests. Missing goals are insufficient information; child completeness is scoped to its assignment. Verification materials/import validity remain deferred until implementation; reasoned review-only acceptance is valid.
 
 The advisory has no agent-ops execution deadline, stall cutoff or token budget. Provider limitations, genuine launch/auth/output errors and explicit cancellation remain effective. Errors produce NOT_RUN and permit work; cancellation preserves the task and MUST stop implementation. Native review processes remain registered and stoppable. Normal verification and final two-round review retain their existing deadlines and gates.
 
-Task creation shows advice and a private report reference. The writer decides which recommendations to adopt and records acceptance/rejection reasons through task revise (a same-criteria revision may record rejected advice). Requirements that are ambiguous or expand scope require user clarification. Reports bind the original task/goal/criteria/surface snapshot; task status and revise show historical reports as stale when those inputs change. A revision MUST NOT automatically re-review. Repeated initial requests reuse the first attempt, including NOT_RUN; only explicit `agent-ops review --criteria --task <id> --rerun --yes` starts another fresh single round. Without --rerun the same command reads/waits for the current attempt.
+Task creation shows advice and a private report reference. The writer decides which recommendations to adopt and records acceptance/rejection reasons through task revise (a same-criteria revision may record rejected advice). Requirements that are ambiguous or expand scope require user clarification. Reports bind the original task/goal/criteria/surface snapshot and record their trigger (`create`, `rerun` or `revise`; absent on older reports). Task status and revise show a report as stale when the goal, intent, criteria or assigned scope change; a surface-only change leaves it current. The first saved revision that makes the current report stale, when that report was not itself revise-triggered, MUST wait for one automatic fresh round (trigger `revise`) and show its advice; the revision is kept whether that round completes, reports NOT_RUN or is cancelled. Further revisions MUST NOT automatically re-review until an explicit rerun. Repeated initial requests reuse the first attempt, including NOT_RUN; outside that one automatic round, only explicit `agent-ops review --criteria --task <id> --rerun --yes` starts another fresh single round. Without --rerun the same command reads/waits for the current attempt.
 
 Detailed redacted reports remain private in `.agent-ops/reviews/criteria-<task-id>*.json`; the local log contains only status, duration, counts, reported usage and report reference. CLI invocation counts are distinct from provider model calls, which may be unreported. Report/log failures MUST NOT roll back a task or fabricate evidence. These advisory artifacts MUST NOT satisfy verify, final review or finish.
 
@@ -112,6 +112,40 @@ successful refutation MUST make the run FAIL.
   replays the recorded queries and reads every listed `valueChanges` consumer;
   this is the only exception to "do not survey the repository".
 
+## REVIEW-ORIGIN-001
+
+A defect the change did not cause MUST NOT block the change; it MUST be
+reported as `origin: "pre-existing"` with `blocking: false` and flow to the
+followup ledger.
+
+- Trigger: A reviewer meets a defect while reading for the review.
+- Action: Mark it pre-existing only when it is present identically at the base
+  and the change did not introduce, expose, worsen or depend on it. Report only
+  defects met on the normal read path; do not search for old ones.
+- Evidence: The report validator rejects a pre-existing finding with
+  `blocking: true` at any severity, including critical. A finding without
+  `origin` means introduced and keeps the old severity rules, so stored reports
+  stay valid. Nonblocking findings of a delivered PASS reach followup as before.
+- Positive: `A critical injection in an untouched helper is reported as pre-existing, nonblocking, and collected into followup.`
+- Negative: `A caller in an unchanged file breaks because of this change and is marked pre-existing because its lines were not edited.`
+
+## REVIEW-ROUNDS-001
+
+Review MUST stop after three failed reviews of one task contract and ask for a
+new approach instead of another fix round.
+
+- Trigger: `review` (directly or through `batch`, `task advance` or a run) for a
+  task with three or more FAIL reports bound to its current task contract hash
+  and newer than its latest PASS.
+- Action: Return NOT_RUN `round-cap` before resolving scope or starting any
+  reviewer, printing the exact `task revise` command. Reconsider the approach and
+  revise the criteria or intent with a reason, or ask the user.
+- Evidence: NOT_RUN reports never count; each source fingerprint keeps one
+  report, so re-reviewing unchanged code adds nothing; a contract revision or a
+  newer PASS starts the count again. The cap is a constant, not configuration.
+- Positive: `Third FAIL on the same contract; the agent revises the intent to a different design and reviews again.`
+- Negative: `Keep committing one fix per finding through a fifth review of the same contract.`
+
 ## REVIEW-HOST-001
 
 A host that cannot provide network and loopback capability MUST fail closed

package/docs/zh-TW/spec/review.md

@@ -1,20 +1,20 @@
 # 審查
 
-English source version: 2026-10-23. Revalidate: when the English specification changes.
+English source version: 2026-10-27. Revalidate: when the English specification changes.
 
 ## REVIEW-CRITERIA-001
 
 - Trigger: 正式 task 的 criteria 就緒、尚未開始實作。
 - Action: 等待一輪限定範圍的 advisory，由 writer 記錄採納或拒絕理由。
 - Evidence: 私人快照報告與安全 local 狀態／用量 log；不產生完成證明。
-- Positive: `修訂後顯示歷史建議；只有明確 rerun 才再花一輪。`
-- Negative: `每次 revise 都自動重審，或把建議當正式 PASS 證明。`
+- Positive: `依建議改寫 criterion；該次 revise 自動重跑一輪 advisory 並顯示新建議。`
+- Negative: `每次 revise（包含只改 surface）都重審，或把建議當正式 PASS 證明。`
 
 每個正式 task 建立入口（含 DEBUG、replan 新子任務及 native run root/child）MUST 在首次實作前等待一輪獨立 criteria advisory。使用設定的 independent-review target 與全新 session，優先選擇不同於 host 的 target；只提供原始 goal、指派 intent/covers、criteria 與 surface audit，並在空白暫存工作區執行。MUST NOT 掃描 repository 或跑測試。缺 goal 須明示資訊不足；子任務只對指派範圍判完整性。材料是否存在、是否載入產品程式留待實作驗證；有理由的 review-only 條件合法。
 
 advisory 不設 agent-ops 執行 deadline、stall cutoff 或 token budget。provider 限制、真正啟動／認證／輸出錯誤與人工取消仍有效。錯誤回報 NOT_RUN 後可繼續；人工取消保留 task 並 MUST 停止實作。native 審查程序仍受註冊與停止機制管理。一般 verify 與正式雙輪 review 的既有時間限制及 gate 保持有效。
 
-task 建立回應呈現建議與私人報告位置。writer 自行判斷採納，透過 task revise 記錄採納及拒絕理由（可用相同 criteria 修訂記錄拒絕建議）。需求歧義或擴大範圍才向使用者澄清。報告綁定 task／goal／criteria／surface 快照；輸入改變後 status 與 revise 顯示歷史報告已過期。修訂 MUST NOT 自動重審。重複初審請求重用第一次嘗試，包含 NOT_RUN；只有明確執行 `agent-ops review --criteria --task <id> --rerun --yes` 才開始新的一輪。省略 --rerun 時讀取／等待目前嘗試。
+task 建立回應呈現建議與私人報告位置。writer 自行判斷採納，透過 task revise 記錄採納及拒絕理由（可用相同 criteria 修訂記錄拒絕建議）。需求歧義或擴大範圍才向使用者澄清。報告綁定 task／goal／criteria／surface 快照，並記錄觸發來源（`create`、`rerun` 或 `revise`；舊報告沒有此欄位）。goal、intent、criteria 或指派範圍改變後，status 與 revise 顯示報告已過期；只改 surface 時報告仍視為最新。第一次讓目前報告過期的已儲存修訂，若該報告本身不是 revise 觸發，MUST 等待一輪自動的新審查（觸發來源 `revise`）並顯示建議；不論該輪完成、回報 NOT_RUN 或被取消，修訂都會保留。之後的修訂 MUST NOT 自動重審，直到明確 rerun 為止。重複初審請求重用第一次嘗試，包含 NOT_RUN；除了那一輪自動審查，只有明確執行 `agent-ops review --criteria --task <id> --rerun --yes` 才開始新的一輪。省略 --rerun 時讀取／等待目前嘗試。
 
 詳細報告經遮蔽後私存於 `.agent-ops/reviews/criteria-<task-id>*.json`；local log 只記狀態、耗時、數量、可得用量及報告參照。CLI 呼叫數與 provider 模型呼叫數分開，後者可能未回報。報告／log 故障 MUST NOT 回滾 task 或偽造證據。advisory 產物 MUST NOT 滿足 verify、正式 review 或 finish。
 
@@ -100,6 +100,26 @@ PASS MUST 交給第二個規劃的 target 嘗試反駁，且反駁成立時 MUST
 - Note: 只有一個設定 target 時，會在全新 session 再呼叫同一 target。FAIL 已是終局，不再複查。
 - Note: 有 surface 的 task，第二輪也會在 `surface-coverage` 下搜尋未列出的 surface 與情境：檢查五個固定情境維度，每個軸向最多可新增 3 個 `git grep -F` 查詢。第一輪重放記錄的查詢並閱讀每個列出的 `valueChanges` consumer；這是「不要普查 repository」唯一的例外。
 
+## REVIEW-ORIGIN-001
+
+不是本次變更造成的缺陷 MUST NOT 擋下變更；MUST 以 `origin: "pre-existing"`、`blocking: false` 回報，並流入 followup ledger。
+
+- Trigger: reviewer 在審查閱讀過程中碰到缺陷。
+- Action: 只有當缺陷在 base 以相同形式存在，且本次變更沒有引入、暴露、加劇或依賴它時，才標為 pre-existing。只回報正常閱讀路徑上碰到的缺陷；不主動搜尋舊問題。
+- Evidence: report validator 拒絕任何 severity（包含 critical）的 pre-existing finding 帶 `blocking: true`。沒有 `origin` 的 finding 視為 introduced，沿用原本的 severity 規則，因此既有 report 仍然有效。已交付 PASS 的 nonblocking finding 照舊進入 followup。
+- Positive: `未改動 helper 裡的 critical injection 標為 pre-existing、nonblocking，並收進 followup。`
+- Negative: `未改動檔案中的 caller 因本次變更而壞掉，卻因為那幾行沒被修改就標為 pre-existing。`
+
+## REVIEW-ROUNDS-001
+
+同一份 task contract 的 review 失敗三次後 MUST 停止，要求換方案，而不是再修一輪。
+
+- Trigger: 對某 task 執行 `review`（直接執行，或經由 `batch`、`task advance`、run），且該 task 在目前 task contract hash 下、最近一次 PASS 之後已有三份以上 FAIL report。
+- Action: 在解析 scope 或啟動任何 reviewer 之前回傳 NOT_RUN `round-cap`，並印出完整的 `task revise` 指令。重新檢討做法，附上理由修訂 criteria 或 intent，或詢問使用者。
+- Evidence: NOT_RUN report 不計入；每個 source fingerprint 只保留一份 report，所以對未改動的程式碼重跑不會增加次數；contract 修訂或較新的 PASS 會讓計數歸零。上限是常數，不是設定項。
+- Positive: `同一份 contract 第三次 FAIL；agent 把 intent 改成另一種設計後再審。`
+- Negative: `同一份 contract 審到第五次，仍然每個 finding 修一個 commit。`
+
 ## REVIEW-HOST-001
 
 Host 缺少 network 或 loopback 能力時，MUST 在任何 reviewer invocation 前

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/schemas/review-report.schema.json

@@ -41,7 +41,8 @@
         "locations": { "type": "array", "items": { "$ref": "#/$defs/location" } },
         "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" } },
         "recommendation": { "$ref": "#/$defs/text" },
-        "criterionIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } }
+        "criterionIds": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/text" } },
+        "origin": { "enum": ["introduced", "pre-existing"] }
       }
     }
   }