@kylecheng3146/agent-ops 0.8.6 → 0.9.0

package/dist/runtime/src/surface/discovery.js

@@ -0,0 +1,221 @@
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { appendLocalLog } from "../logging/local-log.js";
+import { localStatePaths, readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { globMatcher, isCovers, missingScenarios, parseSurface, SURFACE_AXES } from "./schema.js";
+/** Cheapest first: a budget overrun stops before the long tail of diff tokens. */
+export const DISCOVERY_SOURCES = ["agent", "hunk-header", "template-fragment", "diff-token"];
+export const SURFACE_LIMITS = {
+    agentQueryFiles: 200, derivedQueryFiles: 30, exclusionFiles: 10, budgetMs: 120_000, queryTimeoutMs: 30_000,
+    tokenLength: 6, fragmentLength: 4, derivedQueries: 400
+};
+/** argv only: queries are task text and must never meet a shell or a regex engine. */
+function git(root, args, timeoutMs) {
+    return new Promise(resolve => {
+        execFile("git", [...args], { cwd: root, encoding: "buffer", timeout: Math.max(1, timeoutMs), maxBuffer: 64 * 1024 * 1024, shell: false }, (error, stdout) => {
+            const failure = error;
+            resolve({ code: failure === null ? 0 : typeof failure.code === "number" ? failure.code : null,
+                stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.alloc(0), timedOut: failure?.killed === true });
+        });
+    });
+}
+const zList = (value) => value.toString("utf8").split("\0").filter(Boolean);
+// Language keywords long enough to pass the length floor carry no surface signal.
+const STOP = new Set(["return", "import", "export", "default", "function", "extends", "implements", "interface", "public",
+    "private", "protected", "static", "struct", "string", "number", "boolean", "object", "symbol", "typeof", "instanceof",
+    "delete", "select", "insert", "update", "values", "create", "require", "module", "exports", "global", "continue",
+    "switch", "package", "abstract", "unsigned", "virtual", "override", "readonly", "declare", "namespace", "undefined",
+    "nullptr", "lambda", "elseif", "except", "finally", "assert", "yield", "async", "await", "should", "expect",
+    "describe", "result", "props", "children", "className", "length", "constructor", "prototype", "console", "Promise"]);
+const SEPARATOR = /^[:._/#-]|[:._/#-]$/u;
+const LITERAL = /"((?:[^"\\\n]|\\.)*)"|'((?:[^'\\\n]|\\.)*)'|`((?:[^`\\\n]|\\.)*)`/gu;
+const COMPOUND = /[a-z0-9][A-Z]|[A-Za-z0-9][_$][A-Za-z0-9]|[A-Za-z][0-9]/u;
+const INTERPOLATION = /\$\{[^}]*\}|\{[^}]*\}|%[sdifjo]/u;
+function functionName(context) {
+    const match = /\b(?:function|def|func|fn|class|interface|struct|sub|procedure|type)\s+([A-Za-z_$][\w$]*)/u.exec(context) ??
+        /([A-Za-z_$][\w$]*)\s*[=:]\s*(?:async\s*)?(?:function\b|\()/u.exec(context) ?? /([A-Za-z_$][\w$]*)\s*\(/u.exec(context);
+    const name = match?.[1];
+    return name !== undefined && name.length >= SURFACE_LIMITS.fragmentLength && !STOP.has(name) ? name : undefined;
+}
+/** Fixed strings a change implies: literals and identifiers, template fragments, enclosing functions. */
+export function extractDiffQueries(diff) {
+    const tokens = new Set(), fragments = new Set(), functions = new Set();
+    for (const line of diff.split("\n")) {
+        const hunk = /^@@ [^@]* @@ ?(.*)$/u.exec(line);
+        if (hunk !== null) {
+            const name = functionName(hunk[1] ?? "");
+            if (name !== undefined)
+                functions.add(name);
+            continue;
+        }
+        if (!/^[+-]/u.test(line) || line.startsWith("+++") || line.startsWith("---"))
+            continue;
+        const body = line.slice(1);
+        for (const literal of body.matchAll(LITERAL)) {
+            const content = literal[1] ?? literal[2] ?? literal[3] ?? "";
+            for (const piece of content.split(new RegExp(INTERPOLATION.source, "gu")))
+                if (piece.length >= SURFACE_LIMITS.fragmentLength && SEPARATOR.test(piece) && piece.trim() === piece)
+                    fragments.add(piece);
+            if (!INTERPOLATION.test(content) && content.trim().length >= SURFACE_LIMITS.tokenLength)
+                tokens.add(content);
+        }
+        // ponytail: compound identifiers only (snake_case, camelCase, digits), so prose
+        // words in docs and comments are not queries; aliases are phase 2.
+        for (const identifier of body.replace(LITERAL, " ").matchAll(/[A-Za-z_$][A-Za-z0-9_$]*/gu))
+            if (identifier[0].length >= SURFACE_LIMITS.tokenLength && !STOP.has(identifier[0]) && COMPOUND.test(identifier[0]))
+                tokens.add(identifier[0]);
+    }
+    // ponytail: fixed caps on derived queries; the 120 s budget bounds the rest.
+    const cap = (values) => [...values].slice(0, SURFACE_LIMITS.derivedQueries);
+    return { tokens: cap(tokens), fragments: cap(fragments), functions: cap(functions) };
+}
+function notRun(code, message, details, discovery) {
+    return { status: "NOT_RUN", code, message, details: details.slice(0, 200), ...(discovery === undefined ? {} : { discovery }) };
+}
+/** Advisory metrics: fail-open, never evidence. */
+async function logMetrics(home, rows) {
+    try {
+        const state = localStatePaths(home);
+        for (const row of rows)
+            await appendLocalLog(join(state.logDirectory, "events.ndjson"), { type: "surface-metrics", ...row }, { anchorDirectory: state.anchorDirectory });
+    }
+    catch { /* advisory only */ }
+}
+export async function logSurfaceResidualRisks(count, home = process.env.AGENT_OPS_HOME ?? homedir()) {
+    await logMetrics(home, [{ source: "review", hits: 0, included: 0, excluded: 0, postBlockExclusions: 0, residualRisks: count }]);
+}
+/** EVIDENCE-SURFACE-001 gate run before any reviewer: every hit must be classified. */
+export async function runSurfaceGate(input) {
+    if (input.surface === undefined)
+        return input.required
+            ? notRun("SURFACE_MISSING", "This task requires a surface audit: task revise --surface-file <json>.", []) : { status: "PASS", discovery: null };
+    let surface;
+    try {
+        const parsed = parseSurface(input.surface);
+        if (isCovers(parsed))
+            return notRun("SURFACE_MISSING", "A covers-only surface needs a surfaced parent.", []);
+        surface = parsed;
+    }
+    catch (error) {
+        return notRun("SURFACE_MISSING", error instanceof Error ? error.message : "Unparseable surface.", []);
+    }
+    const scenarios = missingScenarios(surface);
+    if (scenarios.length > 0)
+        return notRun("SCENARIO_MISSING", "Every scenario dimension needs applies+behavior or n/a: reason.", scenarios);
+    if (input.children !== undefined && input.children.length > 0) {
+        const included = new Set(surface.included.map(row => row.id));
+        const covered = new Set(input.children.flatMap(child => child.covers));
+        const uncovered = [...included].filter(id => !covered.has(id));
+        const unknown = [...covered].filter(id => !included.has(id));
+        if (uncovered.length > 0 || unknown.length > 0)
+            return notRun("SURFACE_UNASSIGNED", "Children covers must equal the parent included surfaces.", [{ uncovered, unknown }]);
+    }
+    const now = input.now ?? Date.now;
+    const started = now();
+    const budget = input.budgetMs ?? SURFACE_LIMITS.budgetMs;
+    const remaining = () => budget - (now() - started);
+    const changed = new Set(input.changedFiles);
+    const tracked = await git(input.root, ["ls-files", "-z"], Math.min(SURFACE_LIMITS.queryTimeoutMs, Math.max(1, remaining())));
+    if (tracked.timedOut || remaining() <= 0)
+        return notRun("SURFACE_BUDGET_EXCEEDED", "Discovery budget exhausted listing files.", []);
+    const exclusions = surface.excluded.map(row => ({ ...row, match: globMatcher(row.glob) }));
+    for (const row of exclusions) {
+        const files = zList(tracked.stdout).filter(row.match);
+        const diffFiles = [...changed].filter(row.match);
+        if (files.length > SURFACE_LIMITS.exclusionFiles || diffFiles.length > 0)
+            return notRun("SURFACE_EXCLUSION_TOO_BROAD", diffFiles.length > 0 ? "Files in the diff cannot be excluded."
+                : `One exclusion may hide at most ${SURFACE_LIMITS.exclusionFiles} files.`, [{ glob: row.glob, files: files.length, diffFiles }]);
+    }
+    const head = (await git(input.root, ["rev-parse", "HEAD"], SURFACE_LIMITS.queryTimeoutMs)).stdout.toString("utf8").trim();
+    const diff = (await git(input.root, ["diff", "-U0", "--no-color", "--no-ext-diff", input.base ?? "HEAD", "--"], SURFACE_LIMITS.queryTimeoutMs)).stdout.toString("utf8");
+    const derived = extractDiffQueries(diff);
+    const agent = [...new Set(SURFACE_AXES.flatMap(name => { const axis = surface.axes[name]; return "queries" in axis ? axis.queries : []; }))];
+    const planned = [];
+    const seen = new Set();
+    for (const [source, queries] of [["agent", agent], ["hunk-header", derived.functions], ["template-fragment", derived.fragments],
+        ["diff-token", derived.tokens]])
+        for (const query of queries)
+            if (!seen.has(query)) {
+                seen.add(query);
+                planned.push({ source, query });
+            }
+    const key = sha256(canonicalJson({ head, base: input.base ?? null, diff: sha256(diff), queries: [...agent].sort(), config: input.configHash }));
+    const cachePath = join(input.root, ".agent-ops", "tasks", "surface", "cache", key + ".json");
+    let hits;
+    let cached = false;
+    try {
+        const stored = await readPrivateFile(cachePath, input.root);
+        if (stored !== null) {
+            hits = JSON.parse(stored);
+            cached = true;
+        }
+    }
+    catch {
+        hits = undefined;
+    }
+    if (hits === undefined) {
+        hits = [];
+        for (const { source, query } of planned) {
+            if (remaining() <= 0)
+                return notRun("SURFACE_BUDGET_EXCEEDED", `Discovery exceeded its ${budget} ms budget; narrow the diff or queries. Remaining queries were not skipped silently.`, [{ source, query, remaining: planned.length - hits.length }]);
+            const result = await git(input.root, ["grep", "-F", "-l", "-z", "-I", "--no-color", "-e", query, "--"], Math.min(SURFACE_LIMITS.queryTimeoutMs, remaining()));
+            if (result.timedOut)
+                return notRun("SURFACE_BUDGET_EXCEEDED", "A discovery query timed out.", [{ source, query }]);
+            hits.push({ source, query, files: result.code === 0 ? zList(result.stdout) : [] });
+        }
+        await writePrivateFile(cachePath, JSON.stringify(hits), input.root).catch(() => undefined);
+    }
+    const included = surface.included.map(row => globMatcher(row.path));
+    const unknownPaths = surface.unknown.flatMap(row => row.path === undefined ? [] : [globMatcher(row.path)]);
+    const blockPath = join(input.root, ".agent-ops", "tasks", "surface", input.taskId + ".blocks.json");
+    let blocked = [];
+    try {
+        blocked = JSON.parse(await readPrivateFile(blockPath, input.root) ?? "[]");
+    }
+    catch {
+        blocked = [];
+    }
+    const postBlockExclusions = blocked.flatMap(path => {
+        const row = exclusions.find(exclusion => exclusion.match(path));
+        return row === undefined ? [] : [{ path, glob: row.glob, reason: row.reason }];
+    });
+    const sources = Object.fromEntries(DISCOVERY_SOURCES.map(source => [source, { queries: 0, files: 0 }]));
+    const skipped = [];
+    const unclassified = new Map();
+    const metrics = new Map(DISCOVERY_SOURCES.map(source => [source, { hits: new Set(), included: new Set(), excluded: new Set() }]));
+    for (const hit of hits) {
+        sources[hit.source].queries += 1;
+        if (hit.source === "agent" && hit.files.length > SURFACE_LIMITS.agentQueryFiles)
+            return notRun("SURFACE_QUERY_TOO_BROAD", `Query hits more than ${SURFACE_LIMITS.agentQueryFiles} files; record a more specific fixed string.`, [{ query: hit.query, files: hit.files.length }]);
+        if (hit.source !== "agent" && hit.files.length > SURFACE_LIMITS.derivedQueryFiles) {
+            skipped.push({ source: hit.source, query: hit.query, files: hit.files.length });
+            continue;
+        }
+        const metric = metrics.get(hit.source);
+        for (const path of hit.files) {
+            metric.hits.add(path);
+            if (changed.has(path) || included.some(match => match(path)) || unknownPaths.some(match => match(path)))
+                metric.included.add(path);
+            else if (exclusions.some(row => row.match(path)))
+                metric.excluded.add(path);
+            else
+                unclassified.set(path, [...(unclassified.get(path) ?? []), { source: hit.source, query: hit.query }]);
+        }
+    }
+    for (const source of DISCOVERY_SOURCES)
+        sources[source].files = metrics.get(source).hits.size;
+    const discovery = { cached, sources, skipped: skipped.slice(0, 50), postBlockExclusions };
+    if (input.metrics === true)
+        await logMetrics(input.logHome ?? process.env.AGENT_OPS_HOME ?? homedir(), DISCOVERY_SOURCES.map(source => ({ source,
+            hits: metrics.get(source).hits.size, included: metrics.get(source).included.size, excluded: metrics.get(source).excluded.size,
+            postBlockExclusions: postBlockExclusions.length, residualRisks: 0 })));
+    if (unclassified.size > 0) {
+        const paths = [...unclassified.keys()].sort();
+        await writePrivateFile(blockPath, JSON.stringify([...new Set([...blocked, ...paths])].sort()), input.root).catch(() => undefined);
+        return notRun("SURFACE_UNCLASSIFIED", "Discovery found places outside the diff and the surface lists; include, exclude with a reason, or mark UNKNOWN.", paths.map(path => ({ path, hits: unclassified.get(path).slice(0, 5) })), discovery);
+    }
+    return { status: "PASS", discovery };
+}

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

@@ -0,0 +1,127 @@
+import { AgentOpsError } from "../fs/paths.js";
+/** EVIDENCE-SURFACE-001: where else the change lands, recorded before criteria. */
+export const SURFACE_AXES = ["dependents", "duplicates", "otherPaths", "sharedState"];
+export const SCENARIO_DIMENSIONS = ["initialState", "redo", "timeBoundary", "identitySwitch", "concurrency"];
+export const VALUE_CHANGE_KINDS = ["clear", "redact", "default", "normalize", "unit-format"];
+export const isCovers = (surface) => "covers" in surface;
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const text = (v, max = 2048) => typeof v === "string" && v.trim().length > 0 && v.length <= max && !v.includes("\0");
+const id = (v) => typeof v === "string" && /^[a-z][a-z0-9-]{0,63}$/u.test(v);
+const exact = (v, required, optional = []) => required.every(k => Object.hasOwn(v, k)) && Object.keys(v).every(k => required.includes(k) || optional.includes(k));
+// "out of scope" names where the work stops, not why the surface is unaffected.
+const reason = (v) => text(v) && !/^\s*(?:n\/?a|none|out[ -]of[ -]scope|unrelated|not relevant|irrelevant)\s*[.!]?\s*$/iu.test(v);
+const glob = (v) => text(v, 256) && !v.startsWith("/") && !v.includes("\\") &&
+    !/[\n\r]/u.test(v) && v.split("/").every(part => part !== "" && part !== "." && part !== "..");
+const list = (v, max) => Array.isArray(v) && v.length <= max;
+function invalid(message) {
+    throw new AgentOpsError("SURFACE_MISSING", message);
+}
+function axis(value, name) {
+    if (record(value) && exact(value, ["na"])) {
+        if (!reason(value.na))
+            invalid(`Axis ${name} n/a needs a reason the axis cannot apply.`);
+        return { na: value.na };
+    }
+    if (!record(value) || !exact(value, ["queries"]) || !list(value.queries, 32) || value.queries.length === 0 ||
+        !value.queries.every(q => text(q, 256) && !/[\n\r]/u.test(q)) || new Set(value.queries).size !== value.queries.length)
+        invalid(`Axis ${name} needs 1-32 unique single-line fixed-string queries or {na: reason}.`);
+    return { queries: [...value.queries] };
+}
+/** Strict parse of a stored or submitted surface; any defect is SURFACE_MISSING. */
+export function parseSurface(value) {
+    if (record(value) && exact(value, ["covers"])) {
+        if (!list(value.covers, 256) || value.covers.length === 0 || !value.covers.every(id) || new Set(value.covers).size !== value.covers.length)
+            invalid("covers must list unique parent surface IDs.");
+        return { covers: [...value.covers] };
+    }
+    if (!record(value) || !exact(value, ["axes", "included", "excluded", "unknown", "contracts", "valueChanges", "scenarios"]))
+        invalid("Surface file needs axes, included, excluded, unknown, contracts, valueChanges and scenarios (or covers for a child).");
+    const axes = value.axes;
+    if (!record(axes) || !exact(axes, [...SURFACE_AXES]))
+        invalid("axes must name dependents, duplicates, otherPaths and sharedState.");
+    const ids = new Set();
+    const unique = (v) => { if (ids.has(v))
+        invalid(`Duplicate surface ID ${v}.`); ids.add(v); return v; };
+    if (!list(value.included, 256) || value.included.length === 0)
+        invalid("included needs at least one surface (a single surface is fine).");
+    const included = value.included.map(row => {
+        if (!record(row) || !exact(row, ["id", "path", "behavior"]) || !id(row.id) || !glob(row.path) || !text(row.behavior))
+            invalid("Each included surface needs id, path glob and observable behavior.");
+        return { id: unique(row.id), path: row.path, behavior: row.behavior };
+    });
+    if (!list(value.excluded, 256))
+        invalid("excluded must be a list.");
+    const excluded = value.excluded.map(row => {
+        if (!record(row) || !exact(row, ["glob", "reason"]) || !glob(row.glob))
+            invalid("Each exclusion needs a path glob and a reason.");
+        if (!reason(row.reason))
+            invalid(`Exclusion ${row.glob}: say why the surface is unaffected; "out of scope" is not a reason.`);
+        return { glob: row.glob, reason: row.reason };
+    });
+    if (!list(value.unknown, 256))
+        invalid("unknown must be a list.");
+    const unknown = value.unknown.map(row => {
+        if (!record(row) || !exact(row, ["id", "reader", "behavior"], ["path"]) || !id(row.id) || !text(row.reader) ||
+            !text(row.behavior) || (row.path !== undefined && !glob(row.path)))
+            invalid("Each UNKNOWN surface needs id, reader, behavior and an optional path glob.");
+        return { id: unique(row.id), reader: row.reader, behavior: row.behavior, ...(row.path === undefined ? {} : { path: row.path }) };
+    });
+    if (!list(value.contracts, 256))
+        invalid("contracts must be a list.");
+    const contracts = value.contracts.map(row => {
+        if (!record(row) || !exact(row, ["id", "name", "change", "behavior"]) || !id(row.id) || !text(row.name) ||
+            (row.change !== "compatible" && row.change !== "breaking") || !text(row.behavior))
+            invalid("Each shared contract needs id, name, change compatible|breaking and behavior.");
+        return { id: unique(row.id), name: row.name, change: row.change, behavior: row.behavior };
+    });
+    if (!list(value.valueChanges, 128))
+        invalid("valueChanges must be a list.");
+    const valueChanges = value.valueChanges.map(row => {
+        if (!record(row) || !exact(row, ["producer", "kind", "change", "consumers", "indirectConsumers"]) || !text(row.producer) ||
+            !VALUE_CHANGE_KINDS.includes(row.kind) || !text(row.change) ||
+            !list(row.consumers, 64) || row.consumers.length === 0 || !row.consumers.every(c => text(c, 512)) ||
+            !list(row.indirectConsumers, 64) || !row.indirectConsumers.every(c => text(c, 512)))
+            invalid("Each value change needs producer, kind, change, consumers (first hop) and indirectConsumers (second hop).");
+        return { producer: row.producer, kind: row.kind, change: row.change,
+            consumers: [...row.consumers], indirectConsumers: [...row.indirectConsumers] };
+    });
+    const scenarios = value.scenarios;
+    if (!record(scenarios) || Object.keys(scenarios).some(k => !SCENARIO_DIMENSIONS.includes(k)))
+        invalid(`scenarios may name only ${SCENARIO_DIMENSIONS.join(", ")}.`);
+    const parsedScenarios = {};
+    for (const [key, row] of Object.entries(scenarios)) {
+        if (record(row) && exact(row, ["applies", "behavior"]) && row.applies === true && text(row.behavior))
+            parsedScenarios[key] = { applies: true, behavior: row.behavior };
+        else if (record(row) && exact(row, ["na"]) && reason(row.na))
+            parsedScenarios[key] = { na: row.na };
+        else
+            invalid(`Scenario ${key} needs {applies: true, behavior} or {na: reason}.`);
+    }
+    return {
+        axes: Object.fromEntries(SURFACE_AXES.map(name => [name, axis(axes[name], name)])),
+        included, excluded, unknown, contracts, valueChanges, scenarios: parsedScenarios
+    };
+}
+export function missingScenarios(surface) {
+    return SCENARIO_DIMENSIONS.filter(name => surface.scenarios[name] === undefined);
+}
+/** `**` crosses directories, `*` and `?` stay within one segment. */
+export function globMatcher(pattern) {
+    let source = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const c = pattern[i];
+        if (c === "*" && pattern[i + 1] === "*") {
+            const slash = pattern[i + 2] === "/";
+            source += slash ? "(?:.*/)?" : ".*";
+            i += slash ? 2 : 1;
+        }
+        else if (c === "*")
+            source += "[^/]*";
+        else if (c === "?")
+            source += "[^/]";
+        else
+            source += c.replace(/[.+^${}()|[\]\\]/gu, "\\$&");
+    }
+    const expression = new RegExp(`^${source}$`, "u");
+    return path => expression.test(path);
+}

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

@@ -9,7 +9,9 @@ export function criterionContractHash(criterion) {
 export function taskContractHash(task) {
     return sha256(canonicalJson({ goalHash: goalHash(task), title: task.title,
         intent: task.intent ?? null, revision: task.contractRevision ?? 0,
-        criteria: task.criteria.map(criterionContractHash), ...(task.debug === undefined ? {} : { debug: task.debug }) }));
+        criteria: task.criteria.map(criterionContractHash), ...(task.debug === undefined ? {} : { debug: task.debug }),
+        ...(task.surface === undefined ? {} : { surface: sha256(canonicalJson(task.surface)) }),
+        ...(task.surfaceRequired === undefined ? {} : { surfaceRequired: true }) }));
 }
 export function treeContractHash(tasks) {
     return sha256(canonicalJson(tasks.map(task => ({ id: task.id, hash: taskContractHash(task) }))

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

@@ -348,6 +348,9 @@ export class DebugService {
         if (root.debug.receipts.length >= 256)
             fail("TASK_DEBUG_HISTORY_LIMIT", "Execution history is full; retain it and report the blocker.");
         const productDigest = await this.#productDigest(root.debug);
+        // EVIDENCE-SURFACE-001: intake may start without a surface, the first repair may not.
+        if (kind === "verify" && task.task.surfaceRequired === true && task.task.surface === undefined && productDigest !== sha256(canonicalJson([])))
+            fail("SURFACE_MISSING", "Add the surface audit with task revise --surface-file before verifying the first repair.");
         const previousCandidate = root.debug.receipts.filter(r => r.kind === "verify" && (r.outcome === "PASS" || r.outcome === "FAIL")).at(-1)?.productDigest ?? sha256("[]");
         const cause = debugStopCause(root.debug);
         // Recovery reruns the original verifier; changed product content still needs fresh proof.

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

@@ -18,6 +18,7 @@ import { commitIdentity } from "../schema/acceptance.js";
 import { createDebugState, DEBUG_DEFAULTS } from "./debug-state.js";
 import { DebugService } from "./debug.js";
 import { sameDebugText } from "./debug-intake.js";
+import { isCovers, parseSurface } from "../surface/schema.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
     return `task-${randomUUID()}`;
@@ -123,9 +124,12 @@ export class TaskService {
         const criteria = structuredClone(input.criteria).map(criterion => ({ ...criterion,
             ...(criterion.acceptance === undefined ? {} : { acceptance: { ...criterion.acceptance,
                     baselineCommit: criterion.acceptance.baselineCommit ?? createdSourceCommit } }) }));
+        const surface = input.surface === undefined ? undefined : parseSurface(input.surface);
         const task = {
             schemaVersion: TASK_SCHEMA_VERSION,
             id: this.#generateId(),
+            ...(surface === undefined ? {} : { surface }),
+            ...(input.requireSurface === true ? { surfaceRequired: true } : {}),
             title: input.title,
             ...(input.intent === undefined ? {} : { intent: input.intent }),
             criteria,
@@ -186,6 +190,14 @@ export class TaskService {
                     validation.value.debug = structuredClone(parent.task.debug);
                 }
             }
+            if (input.requireSurface === true && validation.value.debug === undefined) {
+                const parentSurface = state.tasks.find(record => record.task.id === input.parentTaskId)?.task.surface;
+                const surfacedParent = parentSurface !== undefined && !isCovers(parentSurface);
+                if (surface === undefined || isCovers(surface) !== surfacedParent)
+                    throw taskError("SURFACE_MISSING", surfacedParent
+                        ? "A subtask of a surfaced parent declares --surface-file {\"covers\": [surface-id]}."
+                        : "A new task needs --surface-file with the four-axis surface audit (EVIDENCE-SURFACE-001).");
+            }
             const record = {
                 task: validation.value,
                 ...(input.debug === undefined ? {} : { debug: createDebugState(task.id, createdSourceCommit, debugSettings, this.#completion.root) }),
@@ -250,8 +262,11 @@ export class TaskService {
             throw taskError("TASK_NOT_ACTIVE", "Only active tasks can revise acceptance.");
         if (taskContractHash(previous.task) !== input.expectedContractHash)
             throw taskError("TASK_CONTRACT_CHANGED", "Task contract changed.");
+        if (input.criteria === undefined && input.surface === undefined)
+            throw taskError("TASK_REVISION_INVALID", "Revision requires criteria, a surface, or both.");
+        const surface = input.surface === undefined ? previous.task.surface : parseSurface(input.surface);
         const baseline = input.baseline ?? previous.createdSourceCommit;
-        const criteria = structuredClone(input.criteria).map(criterion => {
+        const criteria = input.criteria === undefined ? structuredClone(previous.task.criteria) : structuredClone(input.criteria).map(criterion => {
             if (criterion.acceptance === undefined)
                 return criterion;
             const sha = criterion.acceptance.baselineCommit ?? baseline;
@@ -263,7 +278,7 @@ export class TaskService {
             return { ...criterion, acceptance: { ...criterion.acceptance, baselineCommit: sha } };
         });
         const next = { ...previous.task, schemaVersion: TASK_SCHEMA_VERSION,
-            contractRevision: (previous.task.contractRevision ?? 0) + 1, criteria };
+            contractRevision: (previous.task.contractRevision ?? 0) + 1, criteria, ...(surface === undefined ? {} : { surface }) };
         const checked = validateTask(next);
         if (!checked.ok)
             throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid criterion revision.");

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

@@ -68,6 +68,60 @@ Each child worktree MUST record its modification intent before editing.
 - Positive: `A child records its planned API change, commits it, and the final receipt includes that intent and integrated verification.`
 - Negative: `A child edits first and supplies a retrospective one-line intent at delivery.`
 
+## EVIDENCE-SURFACE-001
+
+Every new task MUST record a surface audit of where else its change lands before writing criteria, and review MUST NOT run while discovery finds an unclassified place.
+
+- Trigger: Creating a task (`task create`, a run plan, or before a DEBUG task's first repair), revising its surface, or reviewing it.
+- Action: Search four axes with recorded fixed-string queries or `n/a: reason`, classify every hit as included, excluded (glob + reason) or UNKNOWN, give every surface row an observable `behavior`, and declare each shared contract compatible or breaking. Pass it with `task create|revise --surface-file <json>`.
+- Evidence: The surface is stored on the task, bound into its contract hash with revision history, replayed by `git grep -F` before review, and handed to both reviewers under the `surface-coverage` criterion.
+- Positive: `A diff token hits three copy-pasted sibling pages; the audit includes them with their behavior before review runs.`
+- Negative: `Exclude src/** because it is "out of scope", or list only the files the diff already touches.`
+
+- Axes: `dependents` (importers, callers, readers), `duplicates` (copied
+  markup, strings, logic that imports nothing), `otherPaths` (other routes,
+  modes, entry points or re-entries to the same concept) and `sharedState`
+  (storage, cache, messages, external APIs, client storage, issued URLs). The
+  design is stack-agnostic: the same axes cover frontend, backend, database,
+  cache and message flows.
+- `included` rows carry `id`, `path` glob and `behavior`; `excluded` rows carry
+  `glob` and a reason saying why the surface is unaffected ("out of scope" is
+  not a reason); `unknown` rows name a reader the repository cannot see.
+  `contracts` declare `compatible` or `breaking`. A single surface is allowed.
+- `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]`
+  list two hops whenever a value's semantics change (clear, redact, default,
+  normalize, unit/format).
+- `scenarios` cover five generic dimensions — `initialState` (empty vs
+  existing), `redo` (reload, retry, redelivery, idempotency), `timeBoundary`
+  (day, TTL, timezone), `identitySwitch` (store, role, tenant) and
+  `concurrency` — each `{applies: true, behavior}` or `{na: reason}`.
+- A parent holds the surface; its children declare `{"covers": [surface-id]}`
+  and their union must equal the parent's included list.
+- Before any reviewer runs, discovery replays with `git grep -F` through argv
+  (never a shell or a regex built from task text), cheapest source first:
+  recorded queries; enclosing function names from diff hunk headers;
+  template-literal fixed fragments (at least 4 characters, separator-bounded,
+  such as `order:`, `user_`, `menu.`); compound identifiers (snake_case,
+  camelCase or containing digits, so prose words are not queries) and string
+  literals from added and removed lines (at least 6 characters; skipped as too
+  generic above 30 file hits). Every hit outside the diff and the surface lists stops review.
+  Results are cached by HEAD, base, diff, query set and config hash.
+- Review returns NOT_RUN with: `SURFACE_MISSING` (no or unparseable surface;
+  also refused at create for non-DEBUG tasks), `SURFACE_UNCLASSIFIED`,
+  `SURFACE_QUERY_TOO_BROAD` (one recorded query over 200 files),
+  `SURFACE_EXCLUSION_TOO_BROAD` (one glob over 10 files, or any file in the
+  diff), `SCENARIO_MISSING`, `SURFACE_BUDGET_EXCEEDED` (120 s total, never
+  silently skipped) or `SURFACE_UNASSIGNED` (children's covers differ from the
+  parent's included list; checked by every review, including advance and batch).
+- A surface revision is a contract revision: fresh evidence and two fresh
+  reviews. Exclusions added after an `SURFACE_UNCLASSIFIED` block are flagged
+  to reviewers as post-block exclusions.
+- Tasks created before this rule shipped are grandfathered. Advisory local-log
+  metrics per discovery source are fail-open and never evidence.
+- Plain `worktree finish` writes the same local receipt as advance, including
+  both rounds' residual risks and non-blocking findings, references it in the
+  git note and prints the residual risks.
+
 ## EVIDENCE-AGGREGATE-001
 
 The verifier MUST return FAIL when a criterion is missing, duplicated, unknown, or has empty evidence.

package/docs/en/spec/judgment.md

@@ -10,6 +10,13 @@ The operator MUST stop when requirements, authorization, or a required decision
 - Positive: `Ask whether project or user scope is intended before applying installation.`
 - Negative: `Assume project scope because it is more convenient.`
 
+Surface audit triggers ([EVIDENCE-SURFACE-001](acceptance-and-evidence.md#evidence-surface-001)) also stop before editing:
+
+- A `breaking` change to a shared contract with any UNKNOWN reader.
+- A discovered surface excluded as "intentionally different": send the human
+  one consolidated behavior table (surface, current behavior, proposed
+  behavior, reason) and wait for the decision.
+
 ## JUDGMENT-RETRY-001
 
 The operator MUST change approach after the same failure repeats without new information.

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

@@ -53,10 +53,10 @@ This module defines the bounded loop used to plan, implement, verify, and hand o
 
 ## LOOP-START-001
 
-The operator MUST state acceptance criteria before editing and MUST stop when each criterion has evidence.
+The operator MUST audit the change's surfaces, then state acceptance criteria before editing, and MUST stop when each criterion has evidence.
 
 - Trigger: Starting a multi-step implementation or debugging loop.
-- Action: Record 2–5 observable criteria, then inspect only the files needed for the current step.
+- Action: Record the surface audit ([EVIDENCE-SURFACE-001](acceptance-and-evidence.md#evidence-surface-001)), then 2–5 observable criteria, then inspect only the files within the audited scope that the current step needs.
 - Evidence: The task record and final report link each criterion to a command or read-back.
 - Positive: `Criteria: tests pass; package builds; changed files are read back.`
 - Negative: `I changed the repository and will decide what success means afterward.`

package/docs/en/spec/review.md

@@ -84,6 +84,11 @@ successful refutation MUST make the run FAIL.
 - Negative: `Manufacture a refutation so the challenge looks effective.`
 - Note: With one configured target the same target is invoked again in a fresh
   session. A FAIL is already terminal and is never re-checked.
+- Note: For a surfaced task the second round also hunts unlisted surfaces and
+  scenarios under `surface-coverage`: it checks the five fixed scenario
+  dimensions and may run at most 3 new `git grep -F` queries per axis. Round 1
+  replays the recorded queries and reads every listed `valueChanges` consumer;
+  this is the only exception to "do not survey the repository".
 
 ## REVIEW-HOST-001
 

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

@@ -42,6 +42,54 @@ English source version: 2026-10-06. Revalidate: when the English specification c
 - Positive: `子 agent 先記錄預定 API 修改、提交程式碼，最後完成紀錄包含該意圖與整合後驗證。`
 - Negative: `先修改程式碼，交付時才補寫一行事後意圖。`
 
+## EVIDENCE-SURFACE-001
+
+每個新 task MUST 在寫驗收條件前記錄變更還會影響哪些位置（surface audit）；discovery 找到未分類位置時，review MUST NOT 執行。
+
+- Trigger: 建立 task（`task create`、run plan，或 DEBUG task 第一次修復之前）、修訂 surface，或審查 task。
+- Action: 以記錄下來的固定字串查詢或 `n/a: 理由` 搜尋四個軸向，把每個命中分類為 included、excluded（glob + 理由）或 UNKNOWN，每列 surface 都寫出可觀察的 `behavior`，並宣告每個共享契約為 compatible 或 breaking。以 `task create|revise --surface-file <json>` 提交。
+- Evidence: surface 存在 task 上、綁進 contract hash 並保留修訂歷史，review 前以 `git grep -F` 重放，並以 `surface-coverage` 條件交給兩位 reviewer。
+- Positive: `diff token 命中三個複製貼上的同類頁面；review 前 audit 已把它們連同行為列入 included。`
+- Negative: `以「out of scope」排除 src/**，或只列 diff 已修改的檔案。`
+
+- 軸向：`dependents`（import、呼叫者、讀取者）、`duplicates`（複製的 markup、
+  字串或不 import 任何東西的邏輯）、`otherPaths`（同一概念的其他路由、模式、
+  入口或重新進入點）、`sharedState`（storage、cache、訊息、外部 API、client
+  storage、已發出的 URL）。設計與技術棧無關：相同軸向涵蓋前端、後端、資料庫、
+  cache 與訊息流。
+- `included` 列含 `id`、`path` glob 與 `behavior`；`excluded` 列含 `glob` 與說明
+  該 surface 為何不受影響的理由（「out of scope」不是理由）；`unknown` 列記錄
+  repository 看不到的讀取者。`contracts` 宣告 `compatible` 或 `breaking`。只有單一
+  surface 也可以。
+- 值的語意改變（clear、redact、default、normalize、unit/format）時，
+  `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]` 列出兩層
+  consumer。
+- `scenarios` 涵蓋五個通用維度：`initialState`（空 vs 既有）、`redo`（重新載入、
+  重試、重送、冪等）、`timeBoundary`（日界、TTL、時區）、`identitySwitch`（門市、
+  角色、租戶）與 `concurrency`，每項為 `{applies: true, behavior}` 或 `{na: 理由}`。
+- 父 task 持有 surface；子 task 宣告 `{"covers": [surface-id]}`，聯集必須等於父
+  task 的 included 清單。
+- 任何 reviewer 執行前，discovery 以 argv 執行 `git grep -F`（絕不經過 shell，也
+  不以 task 文字組 regex），由便宜的來源先跑：記錄的查詢；diff hunk header 的外層
+  函式名；template literal 固定片段（至少 4 字元且以分隔符界定，例如 `order:`、
+  `user_`、`menu.`）；新增與刪除行的複合識別字（snake_case、camelCase 或含數字，
+  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元；命中超過 30 個檔案視為
+  太通用而略過）。diff 與 surface 清單之外的任何命中都會擋下 review。
+  結果以 HEAD、base、diff、查詢集合與 config hash 快取。
+- Review 以 NOT_RUN 回報：`SURFACE_MISSING`（沒有或無法解析的 surface；非 DEBUG
+  task 建立時也會拒絕）、`SURFACE_UNCLASSIFIED`、`SURFACE_QUERY_TOO_BROAD`（單一
+  記錄查詢超過 200 個檔案）、`SURFACE_EXCLUSION_TOO_BROAD`（單一 glob 超過 10 個
+  檔案，或包含 diff 內的檔案）、`SCENARIO_MISSING`、`SURFACE_BUDGET_EXCEEDED`
+  （總計 120 秒，絕不默默略過）或 `SURFACE_UNASSIGNED`（子 task covers 與父 task
+  included 不一致；每次 review 都檢查，包含 advance 與 batch）。
+- 修訂 surface 等同修訂 contract：需要新的證據與兩次新的 review。在
+  `SURFACE_UNCLASSIFIED` 阻擋之後才加入的排除，會以 post-block exclusion 標示給
+  reviewer。
+- 本規則上線前建立的 task 不受影響。每個 discovery 來源的 local-log 指標僅供參考、
+  fail-open，絕不作為證據。
+- 一般 `worktree finish` 也會寫入與 advance 相同的本機 receipt，包含兩輪的 residual
+  risks 與 non-blocking findings，在 git note 引用它並印出 residual risks。
+
 ## EVIDENCE-AGGREGATE-001
 
 驗證器 MUST 在條件缺少、重複、未知或證據為空時回傳 FAIL。

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

@@ -12,6 +12,12 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Positive: `套用安裝前詢問要 project 或 user scope。`
 - Negative: `因為方便就假設 project scope。`
 
+Surface audit 觸發條件（[EVIDENCE-SURFACE-001](acceptance-and-evidence.md#evidence-surface-001)）同樣要在編輯前停止：
+
+- 共享契約有 `breaking` 變更，且存在任何 UNKNOWN 讀取者。
+- 發現的 surface 以「刻意不同」為由排除：交給使用者一張整合的行為表（surface、
+  目前行為、提議行為、理由）並等待決定。
+
 ## JUDGMENT-RETRY-001
 
 相同失敗在沒有新資訊時重複發生，操作者 MUST 改變方法。

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

@@ -26,10 +26,10 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 
 ## LOOP-START-001
 
-操作者 MUST 在編輯前列出驗收條件，並在每項條件都有證據時停止。
+操作者 MUST 先盤點變更影響的 surface，再於編輯前列出驗收條件，並在每項條件都有證據時停止。
 
 - Trigger: 開始多步驟實作或除錯迴圈。
-- Action: 記錄 2–5 個可觀察條件，只檢查目前步驟所需檔案。
+- Action: 記錄 surface audit（[EVIDENCE-SURFACE-001](acceptance-and-evidence.md#evidence-surface-001)），再記錄 2–5 個可觀察條件，只檢查已盤點範圍內、目前步驟所需的檔案。
 - Evidence: 任務紀錄與最終報告把每項條件連到命令或讀回內容。
 - Positive: `條件：測試通過；套件建置；讀回變更檔案。`
 - Negative: `先修改，再決定成功標準。`

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

@@ -77,6 +77,7 @@ PASS MUST 交給第二個規劃的 target 嘗試反駁，且反駁成立時 MUST
 - Positive: `codex 判 PASS，claude 找到 blocking 缺陷，整體判定 FAIL。`
 - Negative: `為了讓複查看起來有效而編造反駁。`
 - Note: 只有一個設定 target 時，會在全新 session 再呼叫同一 target。FAIL 已是終局，不再複查。
+- Note: 有 surface 的 task，第二輪也會在 `surface-coverage` 下搜尋未列出的 surface 與情境：檢查五個固定情境維度，每個軸向最多可新增 3 個 `git grep -F` 查詢。第一輪重放記錄的查詢並閱讀每個列出的 `valueChanges` consumer；這是「不要普查 repository」唯一的例外。
 
 ## REVIEW-HOST-001