@kylecheng3146/agent-ops 0.5.3 → 0.6.0

package/dist/runtime/src/verify/adapters/vitest.js

@@ -0,0 +1,218 @@
+import { makeAcceptanceCheck, makeAcceptanceRun, parseJsonDocument, parseJsonLines, stableCheckId } from "../acceptance-protocol.js";
+import { collectJestAcceptance } from "./jest.js";
+import { array, hasRetry, lower, number, object, result, run, string, terminalEvidence } from "./shared.js";
+function mapFramework(runValue, options) {
+    const results = runValue.results.map((item) => makeAcceptanceCheck({
+        executionId: options.executionId,
+        framework: "vitest",
+        frameworkVersion: options.frameworkVersion,
+        checkId: item.checkId,
+        phase: options.phase,
+        status: item.status,
+        failureClass: item.failureClass,
+        attempts: item.attempts,
+        evidence: item.evidence.map((reference) => reference.replace(/^jest:/u, "vitest:"))
+    }));
+    return makeAcceptanceRun({
+        executionId: options.executionId,
+        framework: "vitest",
+        frameworkVersion: options.frameworkVersion,
+        phase: options.phase,
+        results,
+        completed: runValue.completed,
+        completionEvidence: runValue.completionEvidence.map((reference) => reference.replace(/^jest:/u, "vitest:")),
+        diagnostics: runValue.diagnostics
+    });
+}
+function eventInput(input) {
+    if (Array.isArray(input))
+        return { events: input, diagnostics: [] };
+    if (typeof input !== "string")
+        return undefined;
+    const document = parseJsonDocument(input);
+    if (Array.isArray(document))
+        return { events: document, diagnostics: [] };
+    const lines = parseJsonLines(input);
+    const events = lines.values.length === 1 && Array.isArray(lines.values[0]) ? lines.values[0] : lines.values;
+    return events.length > 0 ? { events, diagnostics: lines.invalidLines.map(line => `invalid-json-line:${line}`) } : undefined;
+}
+function flattenTasks(tasks, file, ancestors, assertions, lifecycleErrors) {
+    for (const raw of tasks) {
+        const task = object(raw);
+        if (task === undefined) {
+            assertions.push(null);
+            continue;
+        }
+        const name = string(task.name ?? task.title);
+        const nextAncestors = name === undefined ? ancestors : [...ancestors, name];
+        const children = array(task.tasks ?? task.children);
+        const state = object(task.result) ?? object(task.state);
+        if (children !== undefined && children.length > 0) {
+            const errors = array(state?.errors);
+            const hooks = object(state?.hooks ?? task.hooks);
+            if (errors !== undefined && errors.length > 0)
+                lifecycleErrors.push(...errors);
+            if (task.hookErrors != null || state?.hookErrors != null ||
+                (hooks !== undefined && Object.values(hooks).some(value => value !== "pass" && value !== "passed"))) {
+                lifecycleErrors.push("suite-hook-error");
+            }
+            flattenTasks(children, file, nextAncestors, assertions, lifecycleErrors);
+            continue;
+        }
+        if (task.type === "suite")
+            continue;
+        const status = state === undefined ? task.status ?? task.state : state.state ?? state.status;
+        const retryValue = state === undefined ? task.retry ?? task.retries : state.retry ?? state.retries;
+        const retryCount = number(state?.retryCount);
+        const repeatCount = number(state?.repeatCount);
+        // Native errors and hooks omit fixture cleanup/onTestFinished provenance.
+        // Even AssertionError with passing hooks is ambiguous without classified
+        // collector metadata, just as in Jest-compatible JSON.
+        const assertion = task.assertion === true || state?.assertion === true || state?.failureClass === "assertion-failed";
+        assertions.push({
+            name,
+            ancestorTitles: ancestors,
+            status: task.fails === true ? "xfail" : status,
+            attempts: number(task.attempts) ?? (retryCount !== undefined && repeatCount !== undefined ? retryCount + repeatCount + 1 : null),
+            retry: hasRetry(task) || (state !== undefined && hasRetry(state)) || (typeof retryValue === "number" && retryValue > 0),
+            assertion,
+            hooks: state?.hooks ?? task.hooks,
+            hookErrors: state?.hookErrors ?? task.hookErrors,
+            location: task.location
+        });
+    }
+}
+function structuredReport(input) {
+    const value = typeof input === "string" ? parseJsonDocument(input) : input;
+    const report = object(value);
+    if (report === undefined)
+        return undefined;
+    if (array(report.testResults) !== undefined) {
+        return report;
+    }
+    const testFiles = array(report.testFiles);
+    if (testFiles !== undefined && testFiles.some((file) => {
+        const value = object(file);
+        return value !== undefined && array(value.assertionResults) !== undefined;
+    })) {
+        return { ...report, testResults: testFiles };
+    }
+    const files = array(report.files ?? report.testFiles);
+    if (files === undefined)
+        return undefined;
+    const suites = [];
+    for (const rawFile of files) {
+        const file = object(rawFile);
+        if (file === undefined) {
+            suites.push(null);
+            continue;
+        }
+        const assertions = [];
+        const lifecycleErrors = [];
+        const tasks = array(file.tasks ?? file.children);
+        if (tasks !== undefined) {
+            flattenTasks(tasks, string(file.filepath ?? file.file ?? file.name) ?? "<vitest-file>", [], assertions, lifecycleErrors);
+        }
+        suites.push({
+            testFilePath: string(file.filepath ?? file.file ?? file.name) ?? "<vitest-file>",
+            assertionResults: assertions,
+            testExecError: file.error ?? file.hookErrors ?? object(file.result)?.errors,
+            runtimeError: lifecycleErrors
+        });
+    }
+    return { ...report, testResults: suites };
+}
+function collectEvents(events, options, initialDiagnostics) {
+    const results = [];
+    const diagnostics = [...initialDiagnostics];
+    let completed = false;
+    let completionEvidence = [];
+    for (const raw of events) {
+        const value = object(raw);
+        if (value === undefined) {
+            diagnostics.push("malformed-event");
+            continue;
+        }
+        const type = lower(value.type ?? value.event ?? value.kind);
+        if ((type === "complete" || type === "completed" || type === "finished") &&
+            value.completed !== false && value.interrupted !== true) {
+            completed = true;
+            completionEvidence = [terminalEvidence(value, options.executionId)];
+            continue;
+        }
+        if (type !== "test-end" && type !== "test:pass" && type !== "test:fail" &&
+            type !== "test:skip" && type !== "test:todo" && type !== "test-result") {
+            diagnostics.push(`unsupported-event:${type ?? "unknown"}`);
+            continue;
+        }
+        const ancestors = array(value.ancestorTitles)?.filter((item) => typeof item === "string") ?? [];
+        const name = string(value.title ?? value.name) ??
+            (ancestors.length === 0 ? string(value.fullName) : undefined);
+        if (name === undefined) {
+            diagnostics.push("missing-check-id");
+            continue;
+        }
+        const file = string(value.file ?? value.filepath) ?? "<vitest>";
+        const location = object(value.location);
+        const line = number(location?.line);
+        const column = number(location?.column);
+        let id;
+        try {
+            id = stableCheckId([
+                file,
+                ...ancestors,
+                name,
+                ...(line === undefined || column === undefined ? [] : [`@${line}:${column}`])
+            ]);
+        }
+        catch {
+            diagnostics.push("missing-check-id");
+            continue;
+        }
+        const status = lower(value.status ?? value.state ?? (type === "test:pass" ? "passed" : type === "test:fail" ? "failed" : type === "test:skip" ? "skipped" : type === "test:todo" ? "todo" : undefined));
+        const refs = [`vitest:assertion:${id}`];
+        const observedAttempts = number(value.attempts);
+        const attemptCount = observedAttempts !== undefined && observedAttempts > 0 ? observedAttempts : null;
+        const hooks = object(value.hooks);
+        const hookFailure = value.hookErrors != null || (hooks !== undefined && Object.values(hooks).some(state => state !== "pass" && state !== "passed"));
+        if (hasRetry(value)) {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "retry", attemptCount));
+        }
+        else if (hookFailure) {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "hook-error", attemptCount));
+        }
+        else if (status === "passed" || status === "pass") {
+            results.push(result(options, "vitest", id, "PASS", refs, "none", attemptCount));
+        }
+        else if (status === "failed" || status === "fail") {
+            results.push(value.assertion === true || value.failureClass === "assertion-failed"
+                ? result(options, "vitest", id, "FAIL", refs, "assertion-failed", attemptCount)
+                : result(options, "vitest", id, "UNKNOWN", refs, "infrastructure-error", attemptCount));
+        }
+        else if (status === "skipped" || status === "pending") {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "skipped", attemptCount));
+        }
+        else if (status === "todo") {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "todo", attemptCount));
+        }
+        else {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "malformed-output", attemptCount));
+        }
+    }
+    return run(options, "vitest", results, completed, completionEvidence, diagnostics);
+}
+/** Collect Vitest reporter events or its Jest-compatible JSON output. */
+export function collectVitestAcceptance(input, options) {
+    const events = eventInput(input);
+    if (events !== undefined && events.events.some((event) => {
+        const value = object(event);
+        const type = value === undefined ? undefined : lower(value.type ?? value.event ?? value.kind);
+        return type !== undefined && type.startsWith("test");
+    })) {
+        return collectEvents(events.events, options, events.diagnostics);
+    }
+    const report = structuredReport(input);
+    if (report === undefined)
+        return run(options, "vitest", [], false, [], ["malformed-output"]);
+    return mapFramework(collectJestAcceptance(report, options), options);
+}

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

@@ -24,7 +24,9 @@ function validateBuiltEvidence(value) {
 }
 export function buildVerificationEvidence(input) {
     return validateBuiltEvidence({
-        schemaVersion: EVIDENCE_SCHEMA_VERSION,
+        schemaVersion: input.taskContractHash === undefined && input.acceptance === undefined ? 3 : EVIDENCE_SCHEMA_VERSION,
+        ...(input.taskContractHash === undefined ? {} : { taskContractHash: input.taskContractHash }),
+        ...(input.acceptance === undefined ? {} : { acceptance: input.acceptance }),
         taskId: input.taskId,
         criterionId: input.criterionId,
         commandId: input.command.id,
@@ -54,7 +56,7 @@ export function isPassingVerificationEvidence(command, evidence) {
         return false;
     }
     return command.evidence.kind !== "test-count" ||
-        (evidence.schemaVersion === EVIDENCE_SCHEMA_VERSION &&
+        (evidence.schemaVersion >= 3 &&
             evaluateTestCount(evidence.testCount, command.evidence.minimum).status === "PASS");
 }
 export class FileEvidenceStore {
@@ -64,6 +66,7 @@ export class FileEvidenceStore {
         this.#root = root;
         this.#anchorDirectory = anchorDirectory;
     }
+    get root() { return this.#root; }
     async save(value) {
         const evidence = validateBuiltEvidence(value);
         const content = `${JSON.stringify(evidence, null, 2)}\n`;

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

@@ -1,3 +1,5 @@
+import { taskContractHash } from "../task/contract.js";
+import { replayAcceptance } from "./acceptance-replay.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateTaskAgainstConfig } from "../schema/validate.js";
 import { collectChangeSurface } from "./change-surface.js";
@@ -23,7 +25,7 @@ function exitCategory(result) {
     return result.exitCode === 0 ? "exit-zero" : "nonzero-exit";
 }
 function relevantCriteria(task, commandId) {
-    return task.criteria.filter((criterion) => criterion.verifierIds.includes(commandId));
+    return task.criteria.filter((criterion) => criterion.verifierIds.includes(commandId) || criterion.acceptance !== undefined);
 }
 function commandById(config, commandId) {
     const command = config.verification.commands.find((candidate) => candidate.id === commandId);
@@ -59,6 +61,7 @@ export class VerificationService {
                 failureClass: result.failureClass,
                 sourceFingerprint,
                 toolVersions: this.#options.toolVersions ?? {},
+                ...(task.goal === undefined && (task.contractRevision ?? 0) === 0 && task.criteria.every(c => c.acceptance === undefined) ? {} : { taskContractHash: taskContractHash(task) }),
                 config: this.#options.config
             });
             references.push(await this.#options.evidenceStore.save(evidence));
@@ -113,13 +116,14 @@ export class VerificationService {
             throw verificationError("VERIFICATION_INPUT_INVALID", validation.errors[0]?.message ??
                 "Task and verification configuration are incompatible.");
         }
-        const missingCriteria = validation.value.criteria.filter((criterion) => !this.#options.config.verification.commands.some(({ id, required }) => required && criterion.verifierIds.includes(id)));
+        const missingCriteria = validation.value.criteria.filter((criterion) => criterion.acceptance === undefined && !this.#options.config.verification.commands.some(({ id, required }) => required && criterion.verifierIds.includes(id)));
         if (missingCriteria.length > 0) {
             throw verificationError("VERIFICATION_UNKNOWN", `Criteria without required coverage: ${missingCriteria.map(({ id }) => id).join(", ")}. Configure at least one required verifier for each criterion and recreate the task; no verifier commands were run.`);
         }
         const reviewScope = await resolveReviewScope({
             root: this.#options.root,
             runner: this.#options.gitRunner,
+            ...(this.#options.noChangePaths === undefined && stored.noChangePaths === undefined ? {} : { noChangePaths: this.#options.noChangePaths ?? stored.noChangePaths }),
             ...(this.#options.base === undefined ? {} : { base: this.#options.base })
         });
         const sourceFingerprint = await calculateSourceFingerprint(this.#options.root, reviewScope, this.#options.gitRunner);
@@ -133,29 +137,38 @@ export class VerificationService {
             ...mappedSelection,
             verifierIds: [...new Set([...mappedSelection.verifierIds,
                     ...this.#options.config.verification.commands
-                        .filter(({ id, required }) => required && taskVerifierIds.has(id))
+                        .filter(({ id, required }) => required && (validation.value.criteria.some(c => c.acceptance !== undefined) || 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)));
         }
-        let status = aggregateVerificationStatus(results);
+        const acceptance = validation.value.criteria.some(c => c.acceptance !== undefined && c.acceptance.mode !== "review-only")
+            ? await replayAcceptance({ ...this.#options, task: validation.value, sourceFingerprint }) : [];
+        let status = aggregateVerificationStatus([...results, ...acceptance.map(a => ({ required: true, status: a.status }))]);
         let sourceChanged = false;
         const postflightScope = await resolveReviewScope({
             root: this.#options.root,
             runner: this.#options.gitRunner,
+            ...(this.#options.noChangePaths === undefined && stored.noChangePaths === undefined ? {} : { noChangePaths: this.#options.noChangePaths ?? stored.noChangePaths }),
             ...(this.#options.base === undefined ? {} : { base: this.#options.base })
         });
         const postflightFingerprint = await calculateSourceFingerprint(this.#options.root, postflightScope, this.#options.gitRunner);
         if (reviewScopeSignature(reviewScope) !== reviewScopeSignature(postflightScope) ||
-            sourceFingerprint !== postflightFingerprint) {
+            sourceFingerprint !== postflightFingerprint ||
+            taskContractHash((await this.#options.taskService.status({ taskId })).task) !== taskContractHash(stored.task)) {
             status = "UNKNOWN";
             sourceChanged = true;
         }
+        const acceptanceEvidence = {};
+        for (const proof of acceptance)
+            acceptanceEvidence[proof.criterionId] = [...(acceptanceEvidence[proof.criterionId] ?? []), proof.reference];
+        if (status !== "PASS" && stored.status === "active" && acceptance.length > 0)
+            await this.#options.taskService.recordEvidence(taskId, acceptanceEvidence);
         let signal = null;
         if (status === "PASS") {
-            const taskEvidence = {};
+            const taskEvidence = { ...acceptanceEvidence };
             for (const [index, result] of results.entries()) {
                 const command = commandById(this.#options.config, result.commandId);
                 const references = await this.#persistEvidence(validation.value, command, result.startedAt, result.finishedAt, result, sourceFingerprint);
@@ -175,7 +188,9 @@ export class VerificationService {
             }
         }
         else {
-            const required = results.filter((result) => result.required);
+            const required = [...results.filter((result) => result.required), ...acceptance.map(a => ({ commandId: a.runnerId, required: true,
+                    status: a.status, failureClass: a.failureClass, exitCode: null, timedOut: false, testCount: null,
+                    diagnostic: a.criterionId + ":" + a.phase + ":" + a.failureClass, evidenceReferences: [a.reference], startedAt: "", finishedAt: "" }))];
             const gating = required;
             const failed = gating.find((result) => result.status !== "PASS");
             if (failed === undefined) {
@@ -189,7 +204,7 @@ export class VerificationService {
                     diagnostics: "source changed during verification"
                 }));
                 signal = advanced.signal;
-                return { taskId, status, surface, selection, results, signal, reviewScope, sourceFingerprint };
+                return { taskId, status, surface, selection, results, signal, reviewScope, sourceFingerprint, acceptance };
             }
             const advanced = await this.#options.taskService.recordFailure(taskId, createFailureFingerprint({
                 commandId: failed.commandId,
@@ -200,6 +215,7 @@ export class VerificationService {
             signal = advanced.signal;
         }
         return {
+            acceptance,
             taskId,
             status,
             surface,

package/dist/runtime/src/verify/source-fingerprint.js

@@ -8,7 +8,7 @@ export async function calculateSourceFingerprint(root, scope, runner) {
     if (scope.mode === "base") {
         return sha256(JSON.stringify({
             domain: "agent-ops-source-v1",
-            mode: "base",
+            mode: scope.noChange === true ? "goal-no-change" : "base",
             head,
             base: scope.resolvedBase,
             paths: [...scope.changedFiles]

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

@@ -146,16 +146,20 @@ async function defaultTerminateWindowsTree(processId, graceMs) {
 }
 export class NodeVerificationProcessRunner {
     #platform;
+    #processGroupId;
     #terminateWindowsTree;
     constructor(options = {}) {
         this.#platform = options.platform ?? process.platform;
+        this.#processGroupId = options.processGroupId;
+        if (this.#processGroupId !== undefined && (!Number.isSafeInteger(this.#processGroupId) || this.#processGroupId < 1 || this.#platform === "win32"))
+            throw new Error("Registered proof group must be a positive POSIX process group ID.");
         this.#terminateWindowsTree =
             options.terminateWindowsTree ?? defaultTerminateWindowsTree;
     }
     start(request) {
         const child = spawn(request.command, [...request.args], {
             cwd: request.cwd,
-            detached: this.#platform !== "win32",
+            detached: this.#platform !== "win32" && this.#processGroupId === undefined,
             env: {
                 ...(request.replaceEnv === true ? {} : process.env),
                 ...(request.env ?? {})
@@ -204,7 +208,7 @@ export class NodeVerificationProcessRunner {
                     await this.#terminateWindowsTree(processId, graceMs);
                     return;
                 }
-                await terminatePosixTree(processId, completion, graceMs);
+                await terminatePosixTree(this.#processGroupId ?? processId, completion, graceMs);
             }
         };
     }
@@ -375,3 +379,10 @@ export async function runVerificationCommand(command, options) {
         stderrTruncated: capturedStderr.truncated
     };
 }
+/** CLI-only opt-in. The dormant entry sets this after the supervisor records its PID. */
+export function registeredRunProofRunner() {
+    const value = process.env.AGENT_OPS_RUN_PROOF_PID;
+    if (value !== undefined && !/^[1-9][0-9]{0,9}$/u.test(value))
+        throw new Error("Invalid registered run proof PID.");
+    return new NodeVerificationProcessRunner(value === undefined ? {} : { processGroupId: Number(value) });
+}

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

@@ -1,5 +1,53 @@
 # Acceptance and Evidence
 
+## EVIDENCE-CONTRACT-001
+
+Executable acceptance MUST bind the current contract to immutable replay evidence.
+
+- Trigger: Verifying or completing a typed acceptance contract.
+- Action: Replay trusted checks against the immutable baseline and current candidate, then obtain fresh review.
+- Evidence: Digest-bound phase results and current contract coverage enter both reviewer packets.
+- Positive: Baseline assertion FAIL and candidate PASS prove a behavioral check.
+- Negative: A fixture error is counted as red, or an old review proves revised criteria.
+
+- `behavioral`: every designated red check fails by assertion on the baseline;
+  every required candidate check passes. `invariant`: required candidate checks
+  pass; baseline PASS is valid. `review-only`: two fresh reviewers discharge the
+  requirement against the original goal; no mechanical proof is claimed.
+- Trusted repository `verification.acceptanceRunners` define argv, setup, product
+  build and test build. Tasks provide stable check IDs and explicit committed
+  test/fixture/helper materials. Each checkout installs and builds its own version
+  before candidate materials are overlaid. Tasks cannot override runner commands.
+- Fixture, collection, build, timeout, cancellation, truncated output, missing or
+  duplicate IDs, retries and skips MUST NOT establish red or green. Complete raw
+  execution artifacts are digest-bound to the contract, materials and commits.
+- Native Jest JSON and Vitest task errors lack complete test-call versus
+  hook/fixture-cleanup provenance. Failed rows MUST remain UNKNOWN unless a
+  reviewed repository collector supplies explicit assertion classification;
+  AssertionError names, matcher details and passing hook states are insufficient.
+  Green requires explicit single-attempt evidence: attempts, Jest invocations,
+  or both Vitest retryCount and repeatCount. Native Vitest JSON omits these
+  counters and cannot supply mechanical proof by itself. Pytest requires one
+  ordered setup/call/teardown lifecycle per nodeid; the Rust protocol requires
+  explicit attempts. Missing metadata MUST NOT default to a successful attempt.
+- Baselines are immutable creation commits, or failed candidates for finding pins.
+  Revise/replan preserve the original goal, every mapped requirement and previous
+  contracts/evidence. New contracts require new proof and both fresh reviews.
+- `task pin-finding` validates saved report digest/index provenance. Recurrence
+  explicitly names an existing pin. A sixth criterion returns a replan obligation
+  without changing state; the mapped replan must retain the pin and all requirements.
+- Reviewer packets include original goal, revision history, coverage and verifier
+  materials. Review checks the assertions themselves and explicit fallback reasons.
+  Mechanical green never removes mandatory policy commands or either fresh review.
+
+Task state writes version 2 and reads version 1. Evidence version 4 reads earlier
+evidence; attestation version 3 binds contracts and coverage. Legacy criteria keep
+the verifier rules below; typed or revised contracts cannot reuse an old review.
+Coverage separates mechanical proof, review-only and legacy; a runner binding alone
+is not proof. Explicit no-change proof names existing committed regular source files
+at the frozen candidate; integration re-resolves them. Ordinary empty-diff review
+and empty-branch direct finish remain rejected.
+
 ## EVIDENCE-CRITERION-001
 
 Every acceptance criterion MUST map to observable evidence.

package/docs/en/spec/loop-engineering.md

@@ -1,5 +1,54 @@
 # Loop Engineering
 
+## LOOP-RUN-001
+
+`run` MUST preserve the original user goal and require current agent-ops proof.
+
+- Trigger: Starting, repairing or recovering a native goal run.
+- Action: Bind writers to current leases and require final verification, dual review and receipt proof.
+- Evidence: The run ledger and sealed receipt bind the current candidate and original goal.
+- Positive: Recovering interrupted cleanup preserves the target and saved final proof.
+- Negative: Native goal completion alone changes run state to complete.
+
+- The macOS supervisor registers Claude/Codex native identities before activating
+  goals. Same-host writers use isolated worktrees and current generation leases;
+  the coordinator counts toward the maximum two writers. Dependencies become
+  available only through frozen deliveries; child baselines follow those commits.
+- The default 60-minute budget counts the union of active intervals, including
+  setup, proof, review and integration. Resume keeps elapsed time and usage epochs.
+  Missing counters remain UNKNOWN; partial usage is not a complete cost estimate.
+- Questions pause work and require an explicit answer. Repair preserves the goal
+  and records failures; two identical rounds without progress stop that worker
+  and its dependents. Independent tasks remain eligible. Review findings require
+  regression pins or recorded review-only fallback before another final gate.
+- Native completion is observational. Finalization requires mandatory verification,
+  both fresh reviews, completed task state and a receipt bound to the target.
+  Integration seals the candidate before moving the target and records task,
+  receipt, note and cleanup progress. Recovery validates that seal and does not
+  repeat a successful target mutation. Inconsistent targets remain blocked.
+- Stop persists disabled continuation before confirming registered process-group
+  death. Crash recovery cannot replace a live or unidentified writer. Dirty
+  checkouts, version drift and restart storms preserve the scene for diagnosis.
+  Reboot/login changes require explicit resume; no global host policy is changed.
+  Startup process identities are saved before the native handshake; a stopped,
+  unopened Codex session may initialize afresh only after process death is proved.
+
+- Setup and native-issued local proof commands MUST register dormant process
+  groups before execution; Stop also reconciles their descendants. Interrupted
+  setup requires explicit resume and retains its checkout and failure artifact.
+- A coordinator may assess additional fixed non-dangerous capabilities only under
+  a run-scoped policy bound to the original repository trust, executable runtime
+  and remaining budget. Explicit native or organization denial cannot be bypassed.
+  Policy changes fence all writers, preserve frozen deliveries and journal contract
+  synchronization before new generations acquire leases. This never grants global
+  repository trust. Native decisions retain redacted command scope and rationale;
+  absent provider evidence remains UNKNOWN.
+  Explicit resume renews expired authorization from the remaining budget and
+  reconciles immutable renewal lineage before policy synchronization. An answer
+  uses the same recovery checks; neither action can revive an explicit denial.
+- Convergence compares actual per-check statuses and outstanding finding pins.
+  Source fingerprints, timing and diagnostics alone cannot establish progress.
+
 This module defines the bounded loop used to plan, implement, verify, and hand off work.
 
 ## LOOP-START-001

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

@@ -1,6 +1,26 @@
 # 驗收與證據
 
-English source version: 2026-09-27. Revalidate: when the English specification changes.
+## EVIDENCE-CONTRACT-001
+
+可執行驗收 MUST 將目前契約綁定到不可變的 replay 證據。
+
+- Trigger: 驗證或完成 typed 驗收契約。
+- Action: 在固定 baseline 與目前 candidate replay 授權 checks，再取得 fresh review。
+- Evidence: 綁定摘要的 phase results 與目前 coverage 進入兩輪 reviewer packet。
+- Positive: baseline 斷言 FAIL、candidate PASS 證明 behavioral check。
+- Negative: 把 fixture error 算 red，或用舊 review 證明修訂後 criteria。
+
+- `behavioral`：指定 red checks 在 baseline 都因斷言失敗，candidate 的必要 checks 全部通過。`invariant`：candidate 的必要 checks 通過，baseline 原本 PASS 有效。`review-only`：兩輪 fresh review 對照原始目標驗收，不宣稱機械證明。
+- repo 授權的 `verification.acceptanceRunners` 定義 argv、setup、產品與 test build。task 提供穩定 check IDs 與明列且已 commit 的 test／fixture／helper；兩側各自安裝並 build 其版本，再覆蓋 candidate 材料。task 不能改 runner 命令。
+- fixture、collection、build、timeout、取消、輸出截斷、缺少或重複 ID、retry、skip MUST NOT 算 red 或 green。完整 execution artifacts 以摘要綁定契約、材料與 commits。
+- 原生 Jest JSON 與 Vitest task errors 無法完整區分 test-call 斷言與 hook／fixture cleanup。除非已 review 的 repo collector 提供明確斷言分類，失敗列 MUST 保持 UNKNOWN；AssertionError 名稱、matcher 資料與 pass 的 hook 狀態都不足。green 需要明確的單次 attempt 證據：attempts、Jest invocations，或 Vitest retryCount 與 repeatCount 兩者。原生 Vitest JSON 省略這些 counters，不能單獨提供機械證明。pytest 每個 nodeid 必須有一組依序的 setup／call／teardown；Rust protocol 必須提供 attempts。缺 metadata MUST NOT 預設為一次成功。
+- baseline 固定為建立 commit；finding pin 使用被 FAIL 的 candidate。revise／replan 保留原始目標、全部映射要求與先前契約／證據。新契約必須重新取證並取得兩輪 fresh review。
+- `task pin-finding` 驗證已保存 report 的 digest／index 來源。recurrence 明確引用既有 pin。第六條回傳 replan 義務且不修改狀態；映射後必須保留 pin 與全部要求。
+- reviewer packet 包含原始目標、修訂歷史、coverage 與 verifier 材料，審查斷言本身與明確的 fallback 理由。機械 green 不會省略必要 policy commands 或任一 fresh review。
+
+task state 寫入 version 2、讀取 version 1；evidence version 4 讀取舊證據，attestation version 3 綁定契約與 coverage。legacy criteria 維持下列 verifier 規則；typed／revised 契約不能沿用舊 review。coverage 分列機械證明、review-only、legacy；runner 綁定本身不算證明。明確 no-change proof 列出固定 candidate 上已 commit 的 regular source files；整合時重新解析支持路徑。一般 empty-diff review 與 empty-branch direct finish 仍拒絕。
+
+English source version: 2026-10-06. Revalidate: when the English specification changes.
 
 ## EVIDENCE-CRITERION-001
 

package/docs/zh-TW/spec/loop-engineering.md

@@ -1,5 +1,27 @@
 # 迴圈工程
 
+## LOOP-RUN-001
+
+`run` MUST 保留原始使用者目標，並要求目前有效的 agent-ops 證據。
+
+- Trigger: 啟動、修復或恢復 native goal run。
+- Action: writer 綁定目前 lease，並要求最終 verify、雙 review 與 receipt 證據。
+- Evidence: run ledger 與封存 receipt 綁定目前 candidate 及原始目標。
+- Positive: 恢復未完成清理時，保留 target 與已保存的 final proof。
+- Negative: 只因 native goal completion 就把 run 標為 complete。
+
+- macOS supervisor 在啟動 goal 前保存 Claude／Codex native 身份。同 host writers 使用獨立 worktrees 與目前 generation lease；coordinator 計入最多兩個 writer。依賴以固定交付提供，child baseline 在依賴 commits 進入 checkout 後建立。
+- 預設 60 分鐘預算計算 active intervals 聯集，包含 setup、verify、review、整合。resume 保留時間與 usage epochs；缺少計數維持 UNKNOWN，partial usage 不算完整成本。
+- 實質疑問暫停並要求明確回答。修復保留目標與失敗紀錄；連續兩次相同失敗且無進展停止該 worker 及其依賴，獨立 task 仍可執行。review findings 在下次 final gate 前必須有回歸 pin 或記錄 review-only fallback。
+- native completion 僅是觀察。完成必須有必要驗證、兩輪 fresh review、完成的 task state、綁定 target 的 receipt。整合在移動 target 前封存 candidate，記錄 task、receipt、note、cleanup 進度；恢復驗證封存證據，不重做成功的 target mutation。不一致的 target 維持 blocked。
+- Stop 先保存禁止續跑，再確認受管 process group 死亡。crash recovery 不得取代仍存活或身份不明的 writer。dirty checkout、版本漂移、restart storm 保留現場。重開機／login 改變必須明確 resume；不修改全域 host policy。
+- Native handshake 前先保存啟動程序身份；尚未開啟的 Codex session 必須證明程序死亡，才可在新 lease 重新初始化。
+
+- Setup 與 native agent 發起的 local proof MUST 先登記 dormant process group 再執行；Stop 也要取消子程序。中斷的 setup 必須明確 resume，保留 checkout 與失敗 artifact。
+- Coordinator 只能在綁定原始 repository trust、可執行 runtime、剩餘預算的 run-scoped policy 下，評估新增固定且非危險的能力。不得繞過 native 或組織的明確拒絕。Policy 變更先停止所有 writer，保留固定交付，以 journal 記錄 contract 同步，再啟動新 generation；不授予永久 repository trust。Native decision 保存遮罩後的命令範圍與理由，provider 未提供的證據維持 UNKNOWN。
+- 明確 resume 從剩餘預算續期過期授權，並先核對不可變 renewal lineage，再同步 policy。回答問題也沿用相同恢復檢查；兩者皆不得復活已被明確拒絕的工作。
+- 收斂判斷比較實際 per-check 狀態及未解除的 finding pins；source fingerprint、時間或診斷文字本身不能算進展。
+
 English source version: 2026-07-23. Revalidate: when the English specification changes.
 
 ## LOOP-START-001

package/package.json

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