@kylecheng3146/agent-ops 0.11.4 → 0.11.5

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

@@ -317,6 +317,7 @@ const SURFACE_REASONS = {
     SURFACE_UNCLASSIFIED: "surface-unclassified",
     SURFACE_QUERY_TOO_BROAD: "surface-query-too-broad",
     SURFACE_EXCLUSION_TOO_BROAD: "surface-exclusion-too-broad",
+    SURFACE_INCLUSION_TOO_BROAD: "surface-inclusion-too-broad",
     SCENARIO_MISSING: "scenario-missing",
     SURFACE_BUDGET_EXCEEDED: "surface-budget-exceeded",
     SURFACE_UNASSIGNED: "surface-unassigned",

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

@@ -108,6 +108,8 @@ function taskDataBlock(invocation) {
 function surfaceBlock(invocation, round) {
     if (invocation.packet.surface === undefined)
         return [];
+    const discovery = invocation.packet.surface.discovery;
+    const skipped = round === "adversarial" ? discovery?.skipped ?? [] : [];
     return [
         "",
         "Surface coverage (narrow exception to \"Do not survey\"): task data carries the surface audit, its revision " +
@@ -121,7 +123,10 @@ function surfaceBlock(invocation, round) {
                 "and indirect consumer. Do not run other searches beyond callers a specific question needs."
             : "Round 2: check the five fixed scenarios (initialState, redo, timeBoundary, identitySwitch, concurrency) against " +
                 "the code, and hunt unlisted surfaces with at most 3 new `git grep -F` queries per axis (dependents, duplicates, " +
-                "otherPaths, sharedState); cite each query you ran in evidence."
+                "otherPaths, sharedState); cite each query you ran in evidence.",
+        ...(skipped.length === 0 ? [] : ["Skipped derived queries (over 10 files outside the diff, so discovery never gated them; " +
+                `fewest first): ${skipped.map(row => `\`${row.query}\` (${row.files})`).join(", ")}. Beyond the per-axis budget, run at most 3 ` +
+                "extra `git grep -F` queries in total over these to find copied siblings the change missed; cite each in evidence."])
     ];
 }
 /** Escape Loop: both rounds adjudicate the earliest-gate label of each declared escape. */

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

@@ -11,8 +11,8 @@ import { globMatcher, isCovers, missingScenarios, parseSurface, SURFACE_AXES } f
 /** 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 = {
-    // ponytail: derived queries over 10 files are skipped as generic; incidental ones under that are dismissed by query.
-    agentQueryFiles: 200, derivedQueryFiles: 10, exclusionFiles: 10, dismissals: 128, dismissMinFiles: 4, budgetMs: 120_000, queryTimeoutMs: 30_000,
+    // ponytail: derived queries over 10 files outside the diff are skipped as generic; incidental ones under that are dismissed by query.
+    agentQueryFiles: 200, derivedQueryFiles: 10, exclusionFiles: 10, inclusionFiles: 10, dismissals: 128, dismissMinFiles: 4, 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. */
@@ -142,14 +142,23 @@ export async function runSurfaceGate(input) {
     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 trackedFiles = zList(tracked.stdout);
     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 files = trackedFiles.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 }]);
     }
+    // An included or UNKNOWN glob classifies every hit it matches, so it is capped like an exclusion.
+    for (const glob of [...surface.included.map(row => row.path), ...surface.unknown.flatMap(row => row.path === undefined ? [] : [row.path])]) {
+        const match = globMatcher(glob);
+        const files = trackedFiles.filter(path => match(path) && !changed.has(path)).length;
+        if (files > SURFACE_LIMITS.inclusionFiles)
+            return notRun("SURFACE_INCLUSION_TOO_BROAD", `One included or UNKNOWN glob may cover at most ${SURFACE_LIMITS.inclusionFiles} ` +
+                "files outside the diff; list narrower paths, each with its own behavior.", [{ glob, files }]);
+    }
     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);
@@ -217,7 +226,7 @@ export async function runSurfaceGate(input) {
             return notRun("SURFACE_DISMISSAL_INVALID", "A recorded axis query cannot be dismissed; classify its hits.", [{ query }]);
         const hit = hits.find(row => row.query === query && row.source !== "agent");
         const outside = hit === undefined ? [] : hit.files.filter(path => !changed.has(path));
-        if (hit !== undefined && outside.length < SURFACE_LIMITS.dismissMinFiles && hit.files.length <= SURFACE_LIMITS.derivedQueryFiles)
+        if (hit !== undefined && outside.length < SURFACE_LIMITS.dismissMinFiles)
             return notRun("SURFACE_DISMISSAL_INVALID", `A query reaching fewer than ${SURFACE_LIMITS.dismissMinFiles} files outside the diff ` +
                 "is the likeliest sibling signal and cannot be dismissed; classify its files.", [{ query, files: outside }]);
         if (hit !== undefined)
@@ -227,8 +236,9 @@ export async function runSurfaceGate(input) {
         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 });
+        const outside = hit.files.filter(path => !changed.has(path)).length;
+        if (hit.source !== "agent" && outside > SURFACE_LIMITS.derivedQueryFiles) {
+            skipped.push({ source: hit.source, query: hit.query, files: outside });
             continue;
         }
         if (hit.source !== "agent" && dismissals.has(hit.query))
@@ -284,7 +294,8 @@ export async function runSurfaceGate(input) {
         return notRun("ESCAPE_RULE_NO_EXCLUDE", "A learned escape rule marks these places noExclude: include them or mark them UNKNOWN.", noExclude);
     for (const source of DISCOVERY_SOURCES)
         sources[source].files = metrics.get(source).hits.size;
-    const discovery = { cached, sources, skipped: skipped.slice(0, 50), postBlockExclusions, dismissed };
+    const discovery = { cached, sources, skipped: skipped
+            .sort((a, b) => a.files - b.files || (a.query < b.query ? -1 : a.query > b.query ? 1 : 0)).slice(0, 50), postBlockExclusions, dismissed };
     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,

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

@@ -99,6 +99,9 @@ Every new task MUST record a surface audit of where else its change lands before
   `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.
+  An `included` or `unknown` path glob may cover at most 10 tracked files
+  outside the diff, like an exclusion; list narrower paths, each with its own
+  behavior.
 - `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]`
   list two hops whenever a value's semantics change (clear, redact, default,
   normalize, unit/format).
@@ -114,8 +117,9 @@ Every new task MUST record a surface audit of where else its change lands before
   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 10 file hits, changed files included). Every hit outside the diff and the surface lists stops review.
+  literals from added and removed lines (at least 6 characters). A derived
+  query is skipped as too generic above 10 hit files outside the diff; skipped
+  queries, fewest hits first, go to the second reviewer. Every hit outside the diff and the surface lists stops review.
 - A derived query (diff token, template fragment or hunk-header name) whose hits
   are incidental may be dismissed once in the surface's optional `dismissed`
   list (`{query, reason}`, reason at most 256 characters, "out of scope" is
@@ -132,7 +136,8 @@ Every new task MUST record a surface audit of where else its change lands before
   also refused at create), `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), `SURFACE_DISMISSAL_TOO_BROAD` (over 128 dismissals),
+  diff), `SURFACE_INCLUSION_TOO_BROAD` (one included or UNKNOWN glob over 10
+  files outside the diff), `SURFACE_DISMISSAL_TOO_BROAD` (over 128 dismissals),
   `SURFACE_DISMISSAL_INVALID` (a recorded or rare query), `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).

package/docs/en/spec/review.md

@@ -108,7 +108,9 @@ successful refutation MUST make the run FAIL.
   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
+  dimensions and may run at most 3 new `git grep -F` queries per axis, plus at
+  most 3 in total over the derived queries discovery skipped as too generic,
+  which the prompt names with their hit counts. Round 1
   replays the recorded queries and reads every listed `valueChanges` consumer;
   this is the only exception to "do not survey the repository".
 

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

@@ -62,7 +62,8 @@ English source version: 2026-10-20. Revalidate: when the English specification c
 - `included` 列含 `id`、`path` glob 與 `behavior`；`excluded` 列含 `glob` 與說明
   該 surface 為何不受影響的理由（「out of scope」不是理由）；`unknown` 列記錄
   repository 看不到的讀取者。`contracts` 宣告 `compatible` 或 `breaking`。只有單一
-  surface 也可以。
+  surface 也可以。`included` 或 `unknown` 的 path glob 與排除一樣，至多涵蓋 diff
+  以外 10 個 tracked 檔案；請改列更窄的路徑，各自寫出 behavior。
 - 值的語意改變（clear、redact、default、normalize、unit/format）時，
   `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]` 列出兩層
   consumer。
@@ -75,8 +76,8 @@ English source version: 2026-10-20. Revalidate: when the English specification c
   不以 task 文字組 regex），由便宜的來源先跑：記錄的查詢；diff hunk header 的外層
   函式名；template literal 固定片段（至少 4 字元且以分隔符界定，例如 `order:`、
   `user_`、`menu.`）；新增與刪除行的複合識別字（snake_case、camelCase 或含數字，
-  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元；命中超過 10 個檔案〈含
-  變更檔案〉視為太通用而略過）。diff 與 surface 清單之外的任何命中都會擋下 review。
+  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元）。衍生查詢在 diff 以外命中
+  超過 10 個檔案時視為太通用而略過；略過的查詢依命中數由少到多交給第二輪 reviewer。diff 與 surface 清單之外的任何命中都會擋下 review。
 - 衍生查詢（diff 字詞、template 片段或 hunk header 函式名）的命中若只是巧合，可在
   surface 選用的 `dismissed` 清單中以一筆 `{query, reason}` 排除（理由至多 256
   字元，「out of scope」不是理由），不必逐檔排除。記錄的軸查詢與 escape rule 命中
@@ -88,7 +89,8 @@ English source version: 2026-10-20. Revalidate: when the English specification c
 - Review 以 NOT_RUN 回報：`SURFACE_MISSING`（沒有或無法解析的 surface；
   task 建立時也會拒絕）、`SURFACE_UNCLASSIFIED`、`SURFACE_QUERY_TOO_BROAD`（單一
   記錄查詢超過 200 個檔案）、`SURFACE_EXCLUSION_TOO_BROAD`（單一 glob 超過 10 個
-  檔案，或包含 diff 內的檔案）、`SURFACE_DISMISSAL_TOO_BROAD`（超過 128 筆排除）、
+  檔案，或包含 diff 內的檔案）、`SURFACE_INCLUSION_TOO_BROAD`（單一 included 或
+  UNKNOWN glob 涵蓋 diff 以外超過 10 個檔案）、`SURFACE_DISMISSAL_TOO_BROAD`（超過 128 筆排除）、
   `SURFACE_DISMISSAL_INVALID`（記錄的查詢或稀有查詢）、`SCENARIO_MISSING`、`SURFACE_BUDGET_EXCEEDED`
   （總計 120 秒，絕不默默略過）或 `SURFACE_UNASSIGNED`（子 task covers 與父 task
   included 不一致；每次 review 都檢查，包含 advance 與 batch）。

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

@@ -98,7 +98,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」唯一的例外。
+- Note: 有 surface 的 task，第二輪也會在 `surface-coverage` 下搜尋未列出的 surface 與情境：檢查五個固定情境維度，每個軸向最多可新增 3 個 `git grep -F` 查詢，另外可針對 discovery 因太通用而略過的衍生查詢（prompt 會列出它們與命中數）總計最多再跑 3 個。第一輪重放記錄的查詢並閱讀每個列出的 `valueChanges` consumer；這是「不要普查 repository」唯一的例外。
 
 ## REVIEW-ORIGIN-001
 

package/package.json

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