@kylecheng3146/agent-ops 0.1.21 → 0.1.24

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

@@ -15,6 +15,14 @@ import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
  * review while looking like an unavailable target.
  */
 export const DEFAULT_REVIEW_TIMEOUT_MS = 900_000;
+export class ReviewInterruptedError extends Error {
+    signal;
+    constructor(signal) {
+        super("Independent review was interrupted.");
+        this.name = "ReviewInterruptedError";
+        this.signal = signal;
+    }
+}
 // USER is load-bearing, not cosmetic: a credential store keyed by account name
 // — the macOS keychain claude reads — cannot be opened without it, and its
 // absence surfaces as "Not logged in" on an install that is logged in.
@@ -81,8 +89,7 @@ const REQUIRED_HELP_FLAGS = {
  */
 const ADVANCING = new Set([
     "missing-executable",
-    "spawn-failed",
-    "timeout"
+    "spawn-failed"
 ]);
 const DIAGNOSTIC_MAX_CHARS = 200;
 /**
@@ -114,6 +121,16 @@ function rejectedCallReason(output) {
     }
     return "capability-unavailable";
 }
+function throwIfInterrupted(target, options, failureClass) {
+    if (failureClass !== "aborted" && options.signal?.aborted !== true) {
+        return;
+    }
+    const signal = typeof options.signal?.reason === "string"
+        ? options.signal.reason
+        : undefined;
+    options.onProgress?.(`${target}: review interrupted${signal === undefined ? "" : ` by ${signal}`}`);
+    throw new ReviewInterruptedError(signal);
+}
 async function snapshotRepository(request, destination, options) {
     const cloned = await runVerificationCommand({
         id: `review-snapshot-${request.label}`,
@@ -125,8 +142,10 @@ async function snapshotRepository(request, destination, options) {
         timeoutMs: Math.min(options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS, 60_000)
     }, {
         cwd: dirname(destination),
-        ...(options.runner === undefined ? {} : { runner: options.runner })
+        ...(options.runner === undefined ? {} : { runner: options.runner }),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
     });
+    throwIfInterrupted(request.target, options, cloned.failureClass);
     if (cloned.status !== "PASS") {
         return firstComplaint(cloned.stderr, cloned.stdout) ??
             `git clone failed (${cloned.failureClass})`;
@@ -184,6 +203,8 @@ async function attemptTarget(request, options) {
             return skip("capability-unavailable", "no read-only mode is available for this target", "skipping");
         }
         const environment = isolatedReviewEnvironment(target, attemptDirectory, options.env ?? process.env);
+        throwIfInterrupted(target, options);
+        options.onProgress?.(`${target}: checking reviewer capability`);
         const capability = await runVerificationCommand({
             id: `review-capability-${request.label}`,
             command: invocation.command,
@@ -196,8 +217,10 @@ async function attemptTarget(request, options) {
             cwd: attemptDirectory,
             ...(options.runner === undefined ? {} : { runner: options.runner }),
             env: environment,
-            replaceEnv: true
+            replaceEnv: true,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
         });
+        throwIfInterrupted(target, options, capability.failureClass);
         const help = `${capability.stdout}\n${capability.stderr}`;
         const missingFlags = (REQUIRED_HELP_FLAGS[target] ?? []).filter((flag) => !help.includes(flag));
         if (capability.status !== "PASS" ||
@@ -238,6 +261,8 @@ async function attemptTarget(request, options) {
         if (invocation === undefined) {
             return skip("capability-unavailable", "review invocation disappeared", "skipping");
         }
+        throwIfInterrupted(target, options);
+        options.onProgress?.(`${target}: review started (timeout: ${Math.ceil((options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS) / 1_000)}s)`);
         const spawned = await runVerificationCommand({
             id: `review-${request.label}`,
             command: invocation.command,
@@ -254,8 +279,13 @@ async function attemptTarget(request, options) {
                 : { outputLimitBytes: options.outputLimitBytes }),
             stdin: invocation.stdin,
             env: environment,
-            replaceEnv: true
+            replaceEnv: true,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
         });
+        throwIfInterrupted(target, options, spawned.failureClass);
+        if (spawned.failureClass === "timeout") {
+            return skip("timeout", "the reviewer exceeded its timeout");
+        }
         if (ADVANCING.has(spawned.failureClass)) {
             return {
                 ...skip("missing-cli", `the process did not complete: ${spawned.failureClass}`),
@@ -273,6 +303,9 @@ async function attemptTarget(request, options) {
             return skip(rejectedCallReason(output), firstComplaint(spawned.stderr, spawned.stdout) ??
                 `the call was rejected with exit ${spawned.exitCode ?? "unknown"} and no output`);
         }
+        if (spawned.failureClass === "signal-exit") {
+            return skip("capability-unavailable", `the reviewer exited after ${spawned.signal ?? "an unknown signal"}`);
+        }
         const payload = extractReviewObject(target, spawned.stdout);
         const parsed = payload === undefined
             ? undefined
@@ -343,8 +376,8 @@ export function createReviewExecutor(options) {
                     prompt: buildAdversarialPrompt({ ...request.invocation, harness: target }, primary)
                 }, options);
                 if (outcome.kind === "skip") {
-                    // Recorded, not just reported: progress is suppressed under --json,
-                    // and without this a PASS with no `adversarial` field cannot be told
+                    // Recorded, not just reported: stderr progress is transient, and
+                    // without this a PASS with no `adversarial` field cannot be told
                     // apart from a PASS that had no second target to challenge it.
                     attempts.push({
                         target,

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

@@ -7,9 +7,11 @@ function lineList(values) {
     return values.length === 0 ? ["- none"] : values.map((value) => `- ${safe(value)}`);
 }
 export function renderReviewResult(result) {
+    const plannedTargets = result.plannedTargets ?? [result.harness];
     const lines = [
         `Independent review: ${result.status}`,
-        `Reviewer: ${result.harness}; model: ${safe(result.model)}; effort: ${safe(result.effort)}.`
+        `Reviewer: ${result.harness}; model: ${safe(result.model)}; effort: ${safe(result.effort)}.`,
+        `Planned reviewers: ${plannedTargets.length === 0 ? "none" : plannedTargets.join(" → ")}.`
     ];
     if (result.scope !== undefined) {
         lines.push(result.scope.mode === "base"

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

@@ -160,6 +160,7 @@ function safeReport(report) {
 export async function runIndependentReview(options) {
     const base = {
         harness: options.invocation.harness,
+        plannedTargets: options.invocation.plannedTargets ?? [options.invocation.harness],
         model: options.invocation.model,
         effort: options.invocation.effort,
         prompt: buildReviewPrompt(options.invocation),

package/dist/runtime/src/security/trust.js

@@ -188,8 +188,7 @@ export class FileTrustStore {
         }
         await withPrivateFileLock(this.#path, this.#anchorDirectory, async () => {
             const store = await this.#read();
-            const records = store.records.filter((record) => record.binding.canonicalPath !== binding.canonicalPath &&
-                record.binding.remoteIdentity !== binding.remoteIdentity);
+            const records = store.records.filter((record) => record.binding.canonicalPath !== binding.canonicalPath);
             records.push({ binding: structuredClone(binding), grantedAt });
             await this.#write({ schemaVersion: 1, records });
         });

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

@@ -0,0 +1,62 @@
+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";
+export async function checkTaskCompletionEvidence(stored, options) {
+    const { root, config, sourceFingerprint, evidenceStore } = options;
+    if (stored.failureFingerprint !== null) {
+        return { status: "FAIL", code: "VERIFICATION_FAILED", remedy: "Resolve the latest verification failure before completing the task." };
+    }
+    const configHash = calculateConfigHash(config);
+    if (!validateTaskAgainstConfig(stored.task, config).ok || stored.policyConfigHash !== configHash) {
+        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) {
+            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) {
+            let latest;
+            for (const reference of stored.evidence[criterion.id] ?? []) {
+                if (reference.startsWith("review:"))
+                    continue;
+                const validation = validateEvidence(await evidenceStore.load(reference));
+                if (!validation.ok)
+                    continue;
+                const evidence = validation.value;
+                if (evidence.taskId === stored.task.id && evidence.criterionId === criterion.id &&
+                    evidence.commandId === command.id && evidence.configHash === configHash &&
+                    evidence.sourceFingerprint === sourceFingerprint &&
+                    (latest === undefined || Date.parse(evidence.finishedAt) > Date.parse(latest.finishedAt) ||
+                        (Date.parse(evidence.finishedAt) === Date.parse(latest.finishedAt) && !isPassingVerificationEvidence(command, evidence)))) {
+                    latest = evidence;
+                }
+            }
+            if (latest === undefined || !isPassingVerificationEvidence(command, latest)) {
+                return { status: "FAIL", code: "EVIDENCE_REQUIRED", remedy: "Run agent-ops verify and supply current PASS evidence for every required verifier." };
+            }
+        }
+    }
+    const attestation = await findReviewAttestation(root, sourceFingerprint);
+    if (attestation === null || attestation.taskId !== stored.task.id) {
+        return { status: "FAIL", code: "REVIEW_REQUIRED", remedy: "Run agent-ops review --yes for the whole task and current source." };
+    }
+    return null;
+}
+/** Include descendants so legacy completed children cannot hide unfinished work. */
+export function findIncompleteSubtask(records, taskId) {
+    const descendants = new Set([taskId]);
+    let previousSize = 0;
+    while (previousSize !== descendants.size) {
+        previousSize = descendants.size;
+        for (const record of records) {
+            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)
+                    return record;
+            }
+        }
+    }
+    return undefined;
+}

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

@@ -1,8 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { TASK_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { validateTask } from "../schema/validate.js";
+import { validateEvidence, validateTask } from "../schema/validate.js";
 import { renderTaskMarkdown } from "./render.js";
+import { checkTaskCompletionEvidence, findIncompleteSubtask } from "./completion.js";
+import { calculateConfigHash, FileEvidenceStore } from "../verify/evidence.js";
+import { resolveReviewScope } from "../review/scope.js";
+import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 import { advanceFailureFingerprint } from "../verify/fingerprint.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
@@ -67,10 +71,12 @@ export class TaskService {
     #store;
     #generateId;
     #now;
+    #completion;
     constructor(store, options = {}) {
         this.#store = store;
         this.#generateId = options.generateId ?? defaultTaskId;
         this.#now = options.now ?? (() => new Date().toISOString());
+        this.#completion = options.completion;
     }
     async create(input) {
         if (input.policyConfigHash !== undefined &&
@@ -105,8 +111,8 @@ export class TaskService {
                 if (parent === undefined) {
                     throw taskError("TASK_PARENT_NOT_FOUND", `Parent task not found: ${input.parentTaskId}`);
                 }
-                if (parent.status === "archived") {
-                    throw taskError("TASK_PARENT_NOT_ACTIVE", "An archived task cannot take new subtasks.");
+                if (parent.status !== "active") {
+                    throw taskError("TASK_PARENT_NOT_ACTIVE", "Only an active task can take new subtasks.");
                 }
             }
             const record = {
@@ -196,12 +202,70 @@ export class TaskService {
     }
     async complete(taskId, evidenceInput) {
         const now = assertTimestamp(this.#now());
+        const snapshot = await this.#store.read();
+        const current = findTask(snapshot, taskId);
+        if (current.status === "archived") {
+            throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be completed.");
+        }
+        const submitted = normalizeEvidence(current.task, evidenceInput);
+        // A caller cannot hide a recorded failure by submitting only older PASS references.
+        const evidence = normalizeEvidence(current.task, Object.fromEntries(Object.entries(submitted).map(([criterionId, references]) => [criterionId,
+            [...new Set([...(current.evidence[criterionId] ?? []), ...references])]])));
+        const unfinished = findIncompleteSubtask(snapshot.tasks, taskId);
+        if (unfinished !== undefined) {
+            throw taskError("TASK_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent; archiving unfinished work does not satisfy completion.`);
+        }
+        const completion = this.#completion;
+        if (completion === undefined) {
+            throw taskError("TASK_COMPLETION_UNAVAILABLE", "Task completion requires repository config, source, verification evidence and review validation.");
+        }
+        const evidenceStore = new FileEvidenceStore(completion.root, completion.root);
+        for (const [criterionId, references] of Object.entries(evidence)) {
+            for (const reference of references) {
+                if (reference.startsWith("review:") && current.evidence[criterionId]?.includes(reference))
+                    continue;
+                const validation = validateEvidence(await evidenceStore.load(reference));
+                if (!validation.ok || validation.value.taskId !== taskId || validation.value.criterionId !== criterionId) {
+                    throw taskError("TASK_EVIDENCE_INVALID", `Criterion ${criterionId} requires resolvable evidence belonging to this task and criterion.`);
+                }
+            }
+        }
+        const fingerprint = async () => {
+            try {
+                const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
+                    ...(completion.base === undefined ? {} : { base: completion.base }) });
+                return await calculateSourceFingerprint(completion.root, scope, completion.gitRunner);
+            }
+            catch (error) {
+                if (error instanceof AgentOpsError && error.code === "REVIEW_NO_CHANGE_SURFACE") {
+                    throw taskError("TASK_COMPLETION_SCOPE_REQUIRED", completion.base === undefined
+                        ? "No changed worktree scope. For committed work, run verify, review and task complete with the same --base <git-ref>."
+                        : "The requested base range has no changed paths; choose a base that precedes the committed work.");
+                }
+                throw error;
+            }
+        };
+        const config = await completion.loadConfig();
+        const sourceFingerprint = await fingerprint();
+        const problem = await checkTaskCompletionEvidence({ ...current, evidence }, {
+            root: completion.root, config, sourceFingerprint,
+            evidenceStore
+        });
+        if (problem !== null) {
+            throw taskError(`TASK_COMPLETION_${problem.code}`, problem.remedy);
+        }
+        if (sourceFingerprint !== await fingerprint() ||
+            calculateConfigHash(config) !== calculateConfigHash(await completion.loadConfig())) {
+            throw taskError("TASK_COMPLETION_SOURCE_CHANGED", "Source or config changed during completion; verify and review again.");
+        }
         return await this.#store.mutate((state) => {
-            const current = findTask(state, taskId);
-            if (current.status === "archived") {
-                throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be completed.");
+            if (JSON.stringify(findTask(state, taskId)) !== JSON.stringify(current)) {
+                throw taskError("TASK_COMPLETION_STATE_CHANGED", "Task changed during completion; retry against its current evidence and status.");
+            }
+            const unfinished = findIncompleteSubtask(state.tasks, taskId);
+            if (unfinished !== undefined) {
+                throw taskError("TASK_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent; archiving unfinished work does not satisfy completion.`);
             }
-            const evidence = normalizeEvidence(current.task, evidenceInput);
             if (current.status === "complete") {
                 if (JSON.stringify(current.evidence) !== JSON.stringify(evidence)) {
                     throw taskError("TASK_ALREADY_COMPLETE", "Completed task evidence cannot be replaced.");

package/dist/runtime/src/verify/change-surface.js

@@ -60,6 +60,9 @@ async function collectPaths(runner, args) {
     return parseNulPaths(result.stdout);
 }
 export async function collectChangeSurface(runner) {
+    const trackedRuntime = await collectPaths(runner, [
+        "ls-files", "--cached", "-z", "--", ".agent-ops/tasks/", ".agent-ops/reviews/"
+    ]);
     const staged = await collectPaths(runner, [
         "diff",
         "--cached",
@@ -69,6 +72,9 @@ export async function collectChangeSurface(runner) {
         "--no-textconv",
         "-z"
     ]);
+    if (trackedRuntime.length > 0 || staged.some((path) => path.startsWith(".agent-ops/tasks/") || path.startsWith(".agent-ops/reviews/"))) {
+        throw new AgentOpsError("CHANGE_SURFACE_TRACKED_RUNTIME", "Runtime output is staged or tracked under .agent-ops/tasks/ or .agent-ops/reviews/. Move any source files out of these runtime directories, add ignore rules (agent-ops update), then remove runtime files from the Git index with git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/; keep local files, commit any staged runtime removals, then rerun verify/review.");
+    }
     const unstaged = await collectPaths(runner, [
         "diff",
         "--name-only",
@@ -77,12 +83,15 @@ export async function collectChangeSurface(runner) {
         "--no-textconv",
         "-z"
     ]);
-    const untracked = await collectPaths(runner, [
+    const untracked = (await collectPaths(runner, [
         "ls-files",
         "--others",
         "--exclude-standard",
         "-z"
-    ]);
+    ])).filter(
+    // Indexed runtime was rejected above; only generated, untracked output is excluded.
+    (path) => !path.startsWith(".agent-ops/tasks/") &&
+        !path.startsWith(".agent-ops/reviews/"));
     return {
         staged,
         unstaged,

package/dist/runtime/src/verify/evidence.js

@@ -47,6 +47,9 @@ export function isPassingVerificationEvidence(command, evidence) {
     if (evidence.status !== "PASS" ||
         evidence.exitCode !== 0 ||
         evidence.failureClass !== "none" ||
+        evidence.cwd !== command.cwd ||
+        JSON.stringify(evidence.argv) !==
+            JSON.stringify([command.command, ...command.args].map(redactSecrets)) ||
         command.evidence.kind === "file") {
         return false;
     }
@@ -96,7 +99,12 @@ export class FileEvidenceStore {
             return null;
         }
         try {
-            return JSON.parse(source);
+            const validation = validateEvidence(JSON.parse(source));
+            if (!validation.ok)
+                return null;
+            const evidence = validation.value;
+            const expected = `.agent-ops/tasks/evidence/${evidence.taskId}/${evidence.commandId}-${sha256(source).slice(0, 16)}.json`;
+            return reference === expected ? evidence : null;
         }
         catch {
             throw new AgentOpsError("EVIDENCE_INVALID", "Stored evidence is not valid JSON.");

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

@@ -123,7 +123,15 @@ export class VerificationService {
             ? await collectChangeSurface(this.#options.gitRunner)
             : { staged: [], unstaged: [], untracked: [], paths: reviewScope.changedFiles };
         const surface = worktreeSurface;
-        const selection = selectVerificationScope(surface.paths, this.#options.config);
+        const mappedSelection = selectVerificationScope(surface.paths, this.#options.config);
+        const taskVerifierIds = new Set(validation.value.criteria.flatMap((criterion) => criterion.verifierIds));
+        const selection = {
+            ...mappedSelection,
+            verifierIds: [...new Set([...mappedSelection.verifierIds,
+                    ...this.#options.config.verification.commands
+                        .filter(({ id, required }) => required && taskVerifierIds.has(id))
+                        .map(({ id }) => id)])]
+        };
         const results = [];
         for (const commandId of selection.verifierIds) {
             results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));

package/dist/runtime/src/verify/spawn.js

@@ -270,6 +270,9 @@ function hasAcknowledgedShell(command) {
 export async function runVerificationCommand(command, options) {
     const now = options.now ?? Date.now;
     const startedAt = now();
+    if (options.signal?.aborted === true) {
+        return emptyResult(command.id, "aborted", elapsedMilliseconds(startedAt, now()));
+    }
     if (!hasAcknowledgedShell(command)) {
         return emptyResult(command.id, "shell-risk-unacknowledged", elapsedMilliseconds(startedAt, now()));
     }
@@ -298,21 +301,35 @@ export async function runVerificationCommand(command, options) {
     const timeout = new Promise((resolve) => {
         timer = setTimeout(() => resolve({ kind: "timeout" }), timeoutMs);
     });
+    let removeAbortListener = () => { };
+    const aborted = new Promise((resolve) => {
+        const signal = options.signal;
+        if (signal === undefined) {
+            return;
+        }
+        const onAbort = () => resolve({ kind: "abort" });
+        signal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+    });
     const outcome = await Promise.race([
         running.completion.then((completion) => ({
             kind: "completion",
             completion
         })),
-        timeout
+        timeout,
+        aborted
     ]);
+    removeAbortListener();
     if (timer !== undefined) {
         clearTimeout(timer);
     }
     let completion;
     let timedOut = false;
+    let wasAborted = false;
     let terminationFailed = false;
-    if (outcome.kind === "timeout") {
-        timedOut = true;
+    if (outcome.kind === "timeout" || outcome.kind === "abort") {
+        timedOut = outcome.kind === "timeout";
+        wasAborted = outcome.kind === "abort";
         try {
             await running.terminateTree(terminationGrace);
         }
@@ -330,14 +347,19 @@ export async function runVerificationCommand(command, options) {
         settleCapturedOutput(stdout, terminationGrace),
         settleCapturedOutput(stderr, terminationGrace)
     ]);
-    const classified = timedOut
+    const classified = wasAborted
         ? {
             status: terminationFailed ? "UNKNOWN" : "FAIL",
-            failureClass: terminationFailed
-                ? "termination-failed"
-                : "timeout"
+            failureClass: "aborted"
         }
-        : classifyCompletion(completion, capturedStdout.failed || capturedStderr.failed);
+        : timedOut
+            ? {
+                status: terminationFailed ? "UNKNOWN" : "FAIL",
+                failureClass: terminationFailed
+                    ? "termination-failed"
+                    : "timeout"
+            }
+            : classifyCompletion(completion, capturedStdout.failed || capturedStderr.failed);
     return {
         commandId: command.id,
         status: classified.status,

package/docs/en/guides/configuration.md

@@ -55,6 +55,12 @@ A bare review uses the built-in `change-quality` criterion; `--task` uses the
 task criteria and requires fresh PASS evidence for required checks. The full
 report is printed, and PASS persists only a source-fingerprint attestation.
 
+`--review-target` belongs to `init` and configures that persistent chain.
+For one run, `review --harness <target>` narrows the chain to exactly one
+already-configured target; it never enables a target absent from project
+policy. The configured model, effort, and timeout still apply. Review JSON
+includes `plannedTargets` in the actual host-adjusted order.
+
 Every attempt starts from a fresh session and disposable repository clone with
 native read-only mode.
 Claude uses complete safe-mode isolation. Codex and Agy preserve their existing
@@ -88,6 +94,12 @@ failure, oversized output, or unparseable output. Every attempt and reason is
 preserved in human and JSON output. A `PASS` or `FAIL` verdict is **terminal**,
 so the chain cannot shop for a passing review.
 
+Capability checks and model starts are reported on stderr, including under
+`--json`; stdout remains one final JSON envelope and raw reviewer output is
+never streamed. SIGINT or SIGTERM terminates the active reviewer process tree,
+does not advance the fallback chain, and never writes an attestation. An
+exhausted timeout chain reports `timeout`, not `missing-cli`.
+
 If Claude Code is the host (`CLAUDECODE` is set), `claude` is moved to the end
 of the chain. It still runs when it is the only configured target, with a
 `reviewer == host` warning.

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

@@ -19,3 +19,28 @@ The verifier MUST return FAIL when a criterion is missing, duplicated, unknown,
 - Evidence: The aggregate lists the criterion IDs and their evidence references.
 - Positive: `tests PASS [report.json]; scope PASS [diff.txt]`.
 - Negative: `tests PASS; tests PASS; extra PASS`.
+
+## EVIDENCE-COMPLETION-001
+
+`agent-ops task complete` MUST validate completion independently of the host, active profiles, and Stop hooks.
+
+- Trigger: Completing a task, including repeated completion requests.
+- Action: Check required verifiers, current evidence, whole-task review, and subtask completion before writing state.
+- Evidence: `TASK_COMPLETED` is returned only after these checks pass; rejected requests preserve state.
+- Positive: Current verification evidence plus a task-bound review allows an otherwise complete task to finish.
+- Negative: Supplying `criterion=PASS`, an old review, or archiving an unfinished child to bypass completion.
+
+- Every criterion needs at least one required verifier and current PASS evidence for every required verifier it names. Verify always includes those task-required commands, even when path mappings select a narrower set. Supply the evidence file references produced by `agent-ops verify --task <id>`, not command strings or a written assertion of PASS.
+- The task's config baseline and evidence must match the current effective config and source fingerprint in the selected scope. Outstanding verification failures block completion. A newer failing result cannot be replaced by an older PASS; contradictory results at the same timestamp fail closed.
+- Run `agent-ops review --task <id> --yes` for the whole task. Completion requires its current, task-bound PASS attestation; generic reviews and partial-criterion reviews do not satisfy it.
+- Starting an authorized review invalidates the previous attestation for that source fingerprint. If the reviewer cannot run or does not pass, run a fresh successful whole-task review before completion.
+- All subtasks and descendants must have completed without an outstanding failure. Archiving unfinished work does not satisfy this requirement. A completed or archived parent cannot accept new subtasks. If a subtask is abandoned, recreate the parent task without that cancelled branch and verify/review the new task tree.
+- Evidence, source and config validation run outside the task store lock. After rechecking source and config, completion briefly locks state, rejects a changed task snapshot (`TASK_COMPLETION_STATE_CHANGED`), rechecks descendants, and writes completion atomically. Slow validation does not block task reads or other task mutations; a concurrent mutation remains intact when completion is rejected.
+
+Existing task files remain readable without migration. Legacy tasks without a config baseline, arbitrary evidence references, or unfinished archived children must be recreated and verified/reviewed before completion. Repeating completion also revalidates the evidence; an old completed status alone is insufficient. Runtime callers must supply `TaskServiceOptions.completion`; omitting this repository context fails closed for completion while leaving read-only task operations available.
+
+Before committing, use the default worktree scope for verify, review and completion. After committing, use the same `--base <git-ref>` on all three commands to produce fresh proof for that committed range; `TaskServiceOptions.completion.base` selects it for runtime callers. Base mode requires a clean worktree. Without a worktree change surface or an explicit base, completion returns `TASK_COMPLETION_SCOPE_REQUIRED`. The agy Stop gate still checks worktree-scoped proof: complete and stop before committing, or use its user-approved one-time permit after inspecting a completed base-scoped task.
+
+This enforces the toolkit's completion command, not a host's natural-language completion claim. It does not prevent a process with the same filesystem authority from editing task/evidence files directly, and it does not lock Git or external source writers.
+
+Project init/update installs `.agent-ops/.gitignore` for `/tasks/` and `/reviews/` on every harness and profile. An existing user-owned `.agent-ops/.gitignore` blocks init/update with `UNMANAGED_INSTALL_PATH`: first back it up outside that path and move its custom rules to the root `.gitignore` (prefix them with `/.agent-ops/`), then retry. Git collection fails with `CHANGE_SURFACE_TRACKED_RUNTIME` if these directories contain indexed files (even clean tracked files), or staged runtime removals. Move any real source files out of the runtime directories, install ignore rules, then use `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/` to keep local files while removing them from the index. Commit any staged removals before producing fresh verification/review evidence. The active completion Stop gate also blocks this condition with `COMPLETION_GATE_TRACKED_RUNTIME` and the recovery message. Run verify/review from the Git repository root; nested project roots are not supported by the current path/fingerprint collector. Uninstall removes the managed ignore file but preserves runtime output.

package/docs/en/spec/review.md

@@ -31,6 +31,12 @@ when an installation supports multiple harnesses.
 - Positive: `review --harness claude` resolves one target.
 - Negative: `Run one review invocation against every installed harness implicitly.`
 
+The explicit target MUST already exist in the configured independent-review
+role. It narrows the configured chain to one target while preserving model,
+effort, and timeout policy. Without `--harness`, host-aware ordering applies to
+the complete configured chain. Every result carries that order as
+`plannedTargets`.
+
 ## REVIEW-READONLY-001
 
 A review target MUST be launched with its own read-only mechanism, and a target
@@ -48,6 +54,11 @@ different CLI from the hosting CLI; when no other usable target exists,
 same-target fresh review is allowed but MUST render as `DEGRADED: isolated
 self-review`. A resumed development session is never an independent review.
 
+Capability and model-start progress goes to stderr even when stdout is JSON.
+Raw reviewer output remains bounded and unstreamed. SIGINT or SIGTERM aborts
+the active process tree without fallback or attestation; timeout remains a
+distinct NOT_RUN reason rather than being flattened to `missing-cli`.
+
 ## REVIEW-CHAIN-001
 
 Configured targets form an ordered fallback chain that MUST advance only when

package/docs/zh-TW/guides/configuration.md

@@ -49,6 +49,11 @@ Claude 與 Codex lifecycle support 為 `supported`，OpenCode 從 app initializa
 `--task` 使用 task criteria，並要求必要驗證的最新 PASS evidence。完整 report
 會顯示給人看，PASS 後只持久化 source-fingerprint attestation。
 
+`--review-target` 只屬於 `init`，用來設定持久 fallback chain。單次執行可用
+`review --harness <target>`，將 chain 縮窄為一個已在 project policy 啟用的
+target；它不會臨時啟用未設定的 reviewer。既有 model、effort 與 timeout 仍會
+沿用，review JSON 的 `plannedTargets` 會列出經 host 調整後的實際順序。
+
 每次嘗試都從全新 session、一次性 repository clone 與原生唯讀模式啟動。Claude 使用完整 safe-mode
 隔離；Codex 與 Agy 為了支援既有 OAuth 登入而保留登入環境，因此 context
 隔離較弱。Agy 會取得一次性 clone，即使 sandboxed plan mode 寫入 cwd，也無法
@@ -77,6 +82,11 @@ agent-ops 刻意不傳會繞過權限邊界的 `--dangerously-skip-permissions`
 都會保留每次 attempt 及原因。`PASS` 或 `FAIL` 判定是**終局**，因此不會產生
 自動化的 review shopping。
 
+Capability check 與模型啟動進度都寫到 stderr，包括 `--json` 模式；stdout
+仍只有最終 JSON envelope，且不會串流 reviewer 原始輸出。SIGINT 或 SIGTERM
+會終止目前 reviewer 的完整 process tree、不進入 fallback，也不寫入
+attestation。整條 chain 逾時時回報 `timeout`，不會誤報 `missing-cli`。
+
 若 host 是 Claude Code（`CLAUDECODE` 已設定），`claude` 會被移到鏈尾。
 當它是唯一設定的目標時仍會執行，並附上 `reviewer == host` 警告。
 

package/docs/zh-TW/spec/acceptance-and-evidence.md

@@ -1,6 +1,6 @@
 # 驗收與證據
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-07. Revalidate: when the English specification changes.
 
 ## EVIDENCE-CRITERION-001
 
@@ -21,3 +21,28 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: 聚合結果列出 criterion ID 與證據參照。
 - Positive: `tests PASS [report.json]；scope PASS [diff.txt]`。
 - Negative: `tests PASS；tests PASS；extra PASS`。
+
+## EVIDENCE-COMPLETION-001
+
+`agent-ops task complete` MUST 獨立於 host、啟用的 profile 與 Stop hook，驗證任務是否可完成。
+
+- Trigger: 完成任務，包括重複提交完成請求。
+- Action: 寫入狀態前檢查 required verifier、目前有效的證據、全任務審查與子任務完成狀態。
+- Evidence: 僅在檢查通過後回傳 `TASK_COMPLETED`；拒絕請求時保留原狀態。
+- Positive: 有目前有效的驗證證據與 task-bound review，且子任務已完成，才允許收口。
+- Negative: 填入 `criterion=PASS`、提供舊 review，或封存未完成子任務來繞過檢查。
+
+- 每項 criterion 至少需要一個 required verifier，且其列出的每個 required verifier 都要有目前有效的 PASS evidence。即使 path mapping 選出較小範圍，verify 也會包含 task 明列的 required 命令。請提供 `agent-ops verify --task <id>` 產生的證據檔參照，不能只填命令文字或自行宣稱 PASS。
+- 任務的 config baseline、evidence 必須符合目前有效設定與所選 scope 的來源指紋。尚未解決的驗證失敗會阻擋完成；舊 PASS 不能蓋過較新的失敗，同時間戳的矛盾結果也會阻擋。
+- 使用 `agent-ops review --task <id> --yes` 審查整個任務。完成時必須有目前有效且綁定該 task 的 PASS attestation；generic review 與只涵蓋部分 criterion 的 review 不算。
+- 開始一次已授權的 review 會撤銷該來源指紋先前的 attestation。若 reviewer 未能執行或未通過，完成前必須重新取得成功的全任務 review。
+- 所有子任務與後代任務都必須已完成，且沒有尚未解決的失敗。封存未完成工作不算完成；已完成或封存的 parent 不能新增子任務。若放棄某個 subtask，請重建不含該取消分支的 parent task，並重新驗證與審查新的 task tree。
+- 證據、來源與設定檢查在 task store 鎖外執行。再次確認來源與設定後，完成操作才短暫鎖住狀態，比對 task 快照（改變時回傳 `TASK_COMPLETION_STATE_CHANGED`）、重查後代任務並原子寫入。慢速檢查不會阻擋 task 讀取或其他修改；完成被拒絕時，併發修改仍會保留。
+
+既有 task 檔案仍可直接讀取，不需資料格式遷移。缺少 config baseline、使用任意文字證據，或含有未完成但已封存子任務的舊任務，必須重建並完成驗證與審查。重複執行 complete 也會重新驗證證據；舊的 completed 狀態本身不夠。Runtime 呼叫端必須提供 `TaskServiceOptions.completion`；缺少此 repository context 時，complete 會拒絕執行，但仍可讀取任務。
+
+Commit 前，verify、review、complete 使用預設 worktree scope。Commit 後，三個命令都使用相同的 `--base <git-ref>`，為已提交範圍重新產生證據；runtime 呼叫端使用 `TaskServiceOptions.completion.base`。Base 模式要求 worktree 乾淨。沒有 worktree 變更又未指定 base 時，complete 會回傳 `TASK_COMPLETION_SCOPE_REQUIRED`。agy Stop gate 仍檢查 worktree scope 的證據：請在 commit 前完成並停止，或由使用者檢查已完成的 base-scope 任務後，核准一次性的 Stop permit。
+
+這項機制強制的是 toolkit 的完成命令，無法阻止 host 直接用自然語言宣稱完成，也無法阻止具有相同檔案權限的 process 直接改寫 task／evidence 檔案；它不會鎖住 Git 或其他來源檔案寫入者。
+
+Project init/update 在所有 harness 與 profile 安裝 `.agent-ops/.gitignore`，忽略 `/tasks/` 與 `/reviews/`；若已有使用者自建的 `.agent-ops/.gitignore`，init/update 會回傳 `UNMANAGED_INSTALL_PATH`：先將原檔備份到其他位置，並將自訂規則移到根目錄 `.gitignore`（加上 `/.agent-ops/` 前綴），再重試。這些目錄若包含 index 中的檔案（即使 tracked 且未修改）或 staged 的 runtime 刪除，Git 範圍收集會回傳 `CHANGE_SURFACE_TRACKED_RUNTIME`。請先移出真正的程式來源、安裝 ignore 規則，再執行 `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/`，保留本機檔案並解除追蹤。若有 staged 刪除，先提交清理 commit，再重新產生 verify/review 證據。啟用的 completion Stop gate 也會以 `COMPLETION_GATE_TRACKED_RUNTIME` 阻擋此狀況並提供修復訊息。請從 Git repository 根目錄執行 verify/review；目前路徑與指紋收集不支援巢狀 project root。Uninstall 會移除 managed ignore 檔，但保留 runtime 輸出。