@kylecheng3146/agent-ops 0.1.22 → 0.1.24

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

@@ -336,8 +336,9 @@ export function parseArgs(argv) {
     if (command !== "update" && targetVersion !== undefined) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--target-version may be used only with update.");
     }
-    if (base !== undefined && command !== "verify" && command !== "review") {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--base may be used only with verify or review.");
+    if (base !== undefined && command !== "verify" && command !== "review" &&
+        !(command === "task" && action === "complete")) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--base may be used only with verify, review or task complete.");
     }
     if (hookTargets.length > 0 &&
         command !== "init" &&
@@ -401,9 +402,8 @@ export function parseArgs(argv) {
             evidence.length > 0 ||
             dryRun ||
             yes ||
-            base !== undefined ||
             (taskId !== undefined && sessionId !== undefined))) {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Verify accepts only scope, task or session, and json options.");
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Verify accepts only scope, task or session, base, and json options.");
     }
     if (command === "review" &&
         (title !== undefined || sessionId !== undefined)) {

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

@@ -353,7 +353,12 @@ else {
                             : { targetVersion: updateArgs.targetVersion })
                     });
                 }
-                const taskService = new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root));
+                const taskService = new TaskService(new FileTaskStore(join(root, ".agent-ops", "tasks", "state.json"), root), { completion: {
+                        root,
+                        gitRunner: gitRunner(root),
+                        ...(args.base === undefined ? {} : { base: args.base }),
+                        loadConfig: async () => (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config
+                    } });
                 if (args.command === "allow-stop") {
                     const config = (await loadEffectiveConfig(root, "project")).config;
                     return await runAllowStopCommand({

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

@@ -48,7 +48,7 @@ Options:
   --criterion <json>                    Repeatable
   --evidence <criterion-id=reference>   Repeatable
   --session <id>
-  --base <git-ref>                    Verify/review a clean committed range
+  --base <git-ref>                    Verify/review/complete a clean committed range
   --dry-run
   --json
   --yes

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

@@ -20,25 +20,20 @@ export function normalizeHookInput(harness, input) {
     }
 }
 /**
- * Hooks are advisory infrastructure: every failure path stays fail-open with
- * exit code 0 so a broken toolkit can never wedge the harness.
+ * Advisory failures stay fail-open; an enabled completion Stop fails closed
+ * through the host's native decision protocol (still exit code 0).
  */
 export async function runHookCommand(options) {
     try {
         const { capabilities } = options.config.profiles.length === 0
             ? { capabilities: [] }
             : resolveCapabilities(options.config);
-        let input;
-        try {
-            input = JSON.parse(options.stdin);
-        }
-        catch {
-            return { exitCode: 0, stdout: "", stderr: "" };
-        }
+        const input = JSON.parse(options.stdin);
         const descriptor = harnessDescriptor(options.harness);
         const normalized = normalizeHookInput(options.harness, input);
-        if (normalized === null) {
-            return { exitCode: 0, stdout: "", stderr: "" };
+        if (normalized === null ||
+            (options.completionGate !== undefined && options.event === "Stop" && normalized.event !== "stop")) {
+            throw new Error("Invalid hook input.");
         }
         const stopRegistration = descriptor.control.registrations.find(({ capability }) => capability === "optional-stop-verify");
         const stopVerification = options.stopVerification !== undefined &&
@@ -57,7 +52,7 @@ export async function runHookCommand(options) {
         return descriptor.runtime.formatOutput(options.event, result);
     }
     catch {
-        if (options.harness === "agy" && options.completionGate !== undefined) {
+        if (options.harness === "agy" && options.event === "Stop" && options.completionGate !== undefined) {
             return harnessDescriptor("agy").runtime.formatOutput(options.event, {
                 action: "block",
                 status: "UNKNOWN",

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

@@ -1,7 +1,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 { saveReviewAttestation } from "../../../../runtime/src/review/attestation.js";
+import { invalidateReviewAttestation, saveReviewAttestation } from "../../../../runtime/src/review/attestation.js";
 import { resolveReviewRole } from "../../../../runtime/src/review/roles.js";
 import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
 import { assertSafeSupportingPaths, isReviewerPolicyPath, resolveReviewScope, reviewScopeSignature } from "../../../../runtime/src/review/scope.js";
@@ -75,7 +75,8 @@ async function taskContext(options) {
         policyConfigHash: record.policyConfigHash,
         evidence: record.evidence,
         failureFingerprint: record.failureFingerprint,
-        criteria
+        criteria,
+        allCriteriaReviewed: criteria.length === record.task.criteria.length
     };
 }
 function newestEvidence(values) {
@@ -287,6 +288,9 @@ export async function runReviewCommand(options) {
             });
         }
         sourceFingerprint = await calculateSourceFingerprint(options.root, scope, options.gitRunner);
+        if (options.authorized) {
+            await invalidateReviewAttestation(options.root, sourceFingerprint);
+        }
         if (context !== undefined && options.policyConfigHash !== undefined) {
             if (context.policyConfigHash === null) {
                 return notRunEnvelope({
@@ -422,7 +426,8 @@ export async function runReviewCommand(options) {
     // changes again.
     if (options.root !== undefined &&
         result.status === "PASS" &&
-        sourceFingerprint !== undefined) {
+        sourceFingerprint !== undefined &&
+        (context === undefined || context.allCriteriaReviewed)) {
         await saveReviewAttestation(options.root, {
             schemaVersion: 1,
             ...(context === undefined ? {} : { taskId: context.taskId }),

package/dist/packages/cli/src/hook-process.js

@@ -267,6 +267,15 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
             return 0;
         }
         const config = configOutcome.config;
+        if (completionGateInstalled && !config.features.completionGate.enabled) {
+            writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                action: "block",
+                status: "UNKNOWN",
+                code: "COMPLETION_GATE_CONFIG_DISABLED",
+                remedy: "Restore completionGate.enabled or explicitly uninstall the completion gate."
+            }));
+            return 0;
+        }
         const trustStatus = dependencies.trust === undefined
             ? await repositoryTrust(root, config, cliVersion)
             : await dependencies.trust(root, config, cliVersion);

package/dist/runtime/src/hooks/completion-gate.js

@@ -1,11 +1,8 @@
 import { join } from "node:path";
-import { calculateConfigHash } from "../config/hash.js";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { findReviewAttestation } from "../review/attestation.js";
-import { validateEvidence, validateTaskAgainstConfig } from "../schema/validate.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
-import { isPassingVerificationEvidence } from "../verify/evidence.js";
+import { checkTaskCompletionEvidence, findIncompleteSubtask } from "../task/completion.js";
 import { collectChangeSurface } from "../verify/change-surface.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 const FINGERPRINT = /^[a-f0-9]{64}$/u;
@@ -101,34 +98,10 @@ export class CompletionGateService {
             return { ...state, permitFingerprint: fingerprint };
         });
     }
-    #isPermitCommand(event, sessionId) {
-        if (event.event !== "command")
-            return false;
-        const tokens = [event.command, ...event.args];
-        const commandIndex = tokens.indexOf("allow-stop");
-        return commandIndex >= 0 &&
-            tokens[commandIndex + 1] === "--session" &&
-            (tokens[commandIndex + 2] === sessionId ||
-                tokens[commandIndex + 2] === "$AGENT_OPS_SESSION_ID");
-    }
-    async #hasCurrentEvidence(taskId, criterionId, command, references, configHash, sourceFingerprint) {
-        for (const reference of references) {
-            if (reference.startsWith("review:"))
-                continue;
-            const validation = validateEvidence(await this.#options.evidenceStore.load(reference));
-            if (!validation.ok)
-                continue;
-            const evidence = validation.value;
-            if (evidence.taskId === taskId &&
-                evidence.criterionId === criterionId &&
-                evidence.commandId === command.id &&
-                evidence.configHash === configHash &&
-                evidence.sourceFingerprint === sourceFingerprint &&
-                isPassingVerificationEvidence(command, evidence)) {
-                return true;
-            }
-        }
-        return false;
+    #isPermitCommand(event) {
+        const commands = event.event === "command" ? [event] :
+            event.event === "command-batch" ? event.commands : [];
+        return commands.some(({ command, args }) => [command, ...args].includes("allow-stop"));
     }
     async #validateTask(sessionId, sourceFingerprint) {
         let stored;
@@ -143,30 +116,20 @@ export class CompletionGateService {
         if (stored.status !== "complete") {
             return gateResult("block", "FAIL", "COMPLETION_GATE_TASK_INCOMPLETE", "Complete the attached task after verification and review.");
         }
-        const taskValidation = validateTaskAgainstConfig(stored.task, this.#options.config);
-        const configHash = calculateConfigHash(this.#options.config);
-        if (!taskValidation.ok || stored.policyConfigHash !== configHash) {
-            return gateResult("block", "FAIL", "COMPLETION_GATE_TASK_STALE", "Recreate or re-verify the task against the current config.");
-        }
-        for (const criterion of stored.task.criteria) {
-            for (const commandId of criterion.verifierIds) {
-                const command = this.#options.config.verification.commands.find(({ id }) => id === commandId);
-                if (command === undefined) {
-                    return gateResult("block", "UNKNOWN", "COMPLETION_GATE_EVIDENCE_UNAVAILABLE", "Configured task evidence cannot be resolved.");
-                }
-                if (command.required &&
-                    !(await this.#hasCurrentEvidence(stored.task.id, criterion.id, command, stored.evidence[criterion.id] ?? [], configHash, sourceFingerprint))) {
-                    return gateResult("block", "FAIL", "COMPLETION_GATE_EVIDENCE_REQUIRED", "Run agent-ops verify and complete the task with current PASS evidence.");
-                }
-            }
+        const unfinished = findIncompleteSubtask(await this.#options.taskService.list(), stored.task.id);
+        if (unfinished !== undefined) {
+            return gateResult("block", "FAIL", "COMPLETION_GATE_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent.`);
         }
-        const attestation = await findReviewAttestation(this.#options.root, sourceFingerprint);
-        if (attestation === null || attestation.taskId !== stored.task.id) {
-            return gateResult("block", "FAIL", "COMPLETION_GATE_REVIEW_REQUIRED", "Run agent-ops review --yes for the attached task and current source.");
+        const problem = await checkTaskCompletionEvidence(stored, { ...this.#options, sourceFingerprint });
+        if (problem !== null) {
+            return gateResult("block", problem.status, `COMPLETION_GATE_${problem.code}`, problem.remedy);
         }
         return null;
     }
     async handle(event) {
+        if (this.#isPermitCommand(event)) {
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_PERMIT_CONFIRMATION", "Allow this command only to grant one Stop for the current source fingerprint.");
+        }
         const sessionId = event.sessionId;
         if (sessionId === undefined) {
             return event.event === "stop"
@@ -176,11 +139,12 @@ export class CompletionGateService {
         if (event.event === "session-start") {
             return await this.initialize(sessionId);
         }
-        if (this.#isPermitCommand(event, sessionId)) {
-            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_PERMIT_CONFIRMATION", "Allow this command only to grant one Stop for the current source fingerprint.");
-        }
         if (event.event !== "stop")
             return null;
+        if (event.terminationReason === undefined ||
+            (event.terminationReason === "model_stop" && event.fullyIdle === undefined)) {
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_STOP_INPUT_INVALID", "Restore the Stop termination reason and fullyIdle metadata before stopping.");
+        }
         if (event.terminationReason !== "model_stop" || event.fullyIdle !== true) {
             return gateResult("continue", "PASS", "COMPLETION_GATE_NON_FINAL_STOP");
         }

package/dist/runtime/src/hooks/dispatch.js

@@ -1,3 +1,4 @@
+import { AgentOpsError } from "../fs/paths.js";
 import { evaluateGuardrail } from "../guardrails/evaluate.js";
 import { runStopVerification } from "./stop-verify.js";
 function continueWith(status, code) {
@@ -36,9 +37,16 @@ function evaluateCommands(commands, scope) {
 }
 export async function dispatchHookEvent(event, options) {
     if (options.completionGate !== undefined) {
-        const result = await options.completionGate.handle(event);
-        if (result !== null) {
-            return result;
+        try {
+            const result = await options.completionGate.handle(event);
+            if (result !== null)
+                return result;
+        }
+        catch (error) {
+            if (error instanceof AgentOpsError && error.code === "CHANGE_SURFACE_TRACKED_RUNTIME") {
+                return { action: "block", status: "FAIL", code: "COMPLETION_GATE_TRACKED_RUNTIME", remedy: error.message };
+            }
+            throw error;
         }
     }
     if (event.event === "unsupported") {

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

@@ -86,6 +86,13 @@ export function assertSupportedManifestOwnership(manifest, root) {
         pathKey(".agent-ops/config.json")
     ]);
     const optionalArtifactPaths = new Set();
+    // Optional for manifests installed before runtime output was ignored.
+    if (manifest.scope === "project") {
+        expectedArtifactPaths.set(".agent-ops/.gitignore", {
+            path: ".agent-ops/.gitignore", ids: new Set(["runtime-ignore"])
+        });
+        optionalArtifactPaths.add(".agent-ops/.gitignore");
+    }
     const expectedMarkers = new Map();
     const expectedMarkerPaths = new Set();
     const loopHarnesses = selectedLoopHarnesses(harnesses);

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

@@ -435,6 +435,7 @@ export async function createInstallPlan(options) {
     });
     const contribution = {
         artifacts: [
+            ...(options.scope === "project" ? [{ id: "runtime-ignore", path: ".agent-ops/.gitignore", content: "/tasks/\n/reviews/\n" }] : []),
             ...baseContribution.artifacts,
             ...loopContribution.artifacts
         ],

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

@@ -22,6 +22,8 @@ function selectedSet(harnesses) {
 function artifactOwners(manifest, artifact) {
     if (artifact.id === "config")
         return [];
+    if (artifact.id === "runtime-ignore")
+        return manifest.harness;
     if (artifact.id === "opencode-plugin")
         return ["opencode"];
     if (artifact.id === "claude-loop-launcher" ||

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

@@ -57,9 +57,20 @@ export async function findReviewAttestation(root, sourceFingerprint) {
         return null;
     }
     try {
-        return parseAttestation(JSON.parse(source));
+        const attestation = parseAttestation(JSON.parse(source));
+        return attestation?.sourceFingerprint === sourceFingerprint ? attestation : null;
     }
     catch {
         return null;
     }
 }
+/** A new authorized attempt supersedes any earlier PASS for this source. */
+export async function invalidateReviewAttestation(root, sourceFingerprint) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
+        throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Invalid source fingerprint.");
+    }
+    const path = attestationPath(root, sourceFingerprint);
+    if (await readPrivateFile(path, root) !== null) {
+        await writePrivateFile(path, "null\n", root);
+    }
+}

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/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/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 輸出。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",