agent-roast 0.6.0 → 0.7.0

package/README.md

@@ -38,7 +38,7 @@ npx agent-roast check --baseline .agentroast-baseline.json
 npx agent-roast --staged
 
 # Audit pull request diffs (CI gate)
-npx agent-roast --base origin/main --head HEAD --format github
+npx agent-roast review --base origin/main --head HEAD --format github
 
 # Optional historical audit
 npx agent-roast --all --verbose
@@ -106,7 +106,7 @@ regressions) may appear in the report/summary rather than as an inline PR annota
 Use a separate SARIF category for introduced-findings review; it does not represent
 a full scan of all outstanding alerts.
 
-Install with `npx agent-roast@0.6.0 review --base origin/main`. For local development,
+Install 0.7.0: `npx agent-roast@0.7.0 review --base origin/main`. For local development,
 run `npm run build` and use `node dist/cli.js`.
 
 ### Baseline adoption
@@ -175,7 +175,6 @@ Configure custom ignore paths, rule severities, and CI thresholds with a `.agent
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/Nari-Ab/agent-roast/main/schema.json",
   "ignorePaths": [
     "**/*.min.js",
     "**/vendor/**",
@@ -183,11 +182,10 @@ Configure custom ignore paths, rule severities, and CI thresholds with a `.agent
     "**/fixtures/**"
   ],
   "rules": {
-    "hallucinated-package": "error",
-    "empty-catch": "warn",
+    "test-focus": "error",
+    "swallowed-error": "warn",
     "trivial-assert": "warn",
-    "stub-abandonment": "warn",
-    "mock-leak": "warn"
+    "stub-abandonment": "warn"
   },
   "scoreThreshold": 70
 }
@@ -203,9 +201,22 @@ npx agent-roast --staged
 npx agent-roast init --hook
 ```
 
-`--staged` audits exactly the Git index, including an initial commit without HEAD.
-Unstaged edits and untracked files are excluded. The generated hook uses the locally
-installed CLI (`--no-install`) and blocks on configured error rules instead of scoring
+Since 0.7.0, `--staged` (also `review --staged`) compares the **full source**
+of changed files in HEAD and the Git index. It detects deletion-only empty handlers
+and retains comment context. Existing findings do not block; additional occurrences
+do. Unstaged edits, untracked files and `git add -N` intent-to-add entries are excluded.
+The previous released 0.6.0 `--staged` command checks only added index lines.
+
+Policy comes from HEAD. Staged/unstaged config edits cannot weaken this check and
+are reported; adopt policy changes in a separately reviewed commit. With no HEAD,
+the first commit uses built-in defaults; use `--fail-on` for an explicit override.
+For example: `node dist/cli.js review --staged --fail-on test-skip,test-focus,swallowed-error`.
+Source is pinned by Git blob IDs. If HEAD or the staged inventory changes before the
+scan finishes, it exits 2 and asks for a rerun. The report's `source` is `index`;
+`headSha` is an `INDEX:` snapshot digest, not a commit SHA, and an unborn base is `EMPTY`.
+The JSON schema version for context reviews is now `1.1.0`.
+
+The generated hook uses the locally installed CLI (`--no-install`) and blocks on configured error rules instead of scoring
 old commits. It preserves an existing pre-commit hook.
 
 ### Configure what blocks a change
@@ -216,6 +227,7 @@ Create `.agentroastrc.json` (or run `npx agent-roast init`):
 {
   "rules": {
     "test-skip": "error",
+    "test-focus": "error",
     "trivial-assert": "error",
     "swallowed-error": "warn",
     "type-escape": "off"
@@ -227,7 +239,7 @@ Create `.agentroastrc.json` (or run `npx agent-roast init`):
 ```
 
 `off` removes findings and score penalties; `warn` reports without blocking a diff;
-`error` blocks PR/staged checks. An explicit `failOn` array overrides which enabled
+`error` blocks PR/staged checks, including `test-focus` by default in 0.7.0. An explicit `failOn` array overrides which enabled
 rules block (`[]` makes the audit advisory). CLI `--fail-on` takes precedence over
 that array. History and badge audits honor disabled rules and the panic-loop window.
 History exit status is controlled by `scoreThreshold` or `--fail-under`.
@@ -264,7 +276,6 @@ jobs:
       - name: Run agent-roast audit
         uses: Nari-Ab/agent-roast@v1
         with:
-          fail-on: test-skip,trivial-assert,stub-abandonment
           format: github
 ```
 
@@ -274,8 +285,12 @@ jobs:
 
 ### What it checks
 
-Only **added lines** (`+`) in source code files are scanned — deleted lines, file moves, and comments never trigger false alarms.
+`check` scans current source. `review` scans both full versions of changed source;
+the 0.7.0 `--staged` command does the same for HEAD and index. Legacy
+`--base` and history audits inspect added lines. Comment/literal masking reduces
+noise; these are heuristic checks and can have false positives and missed findings.
 
+- **Focused tests (`test-focus`):** Exclusive `test.only`, `it.only`, `describe.only`, `suite.only`, Playwright `test.describe.only` and common modifier chains in JS/TS-family sources. `fit` / `fdescribe` aliases are recognized in conventional test paths. Supports contiguous multiline chains and ignores literal/comment examples. Default blocking rule; an existing explicit `failOn` list must include it to block. This does not resolve imports or custom aliases; configure your runner's native forbid-only option too when available ([Playwright](https://playwright.dev/docs/api/class-testconfig#test-config-forbid-only), [Jest API](https://jestjs.io/docs/api#testonlyname-fn-timeout)).
 - **Skipped tests (`test-skip`):** `it.skip`, `describe.skip`, `xit`, `pytest.skip`, `test.todo` added to silence failing tests. (Default blocking gate).
 - **Trivial assertions (`trivial-assert`):** Tautological or dummy assertions added to fabricate test green checks (`expect(true).toBe(true)`, `expect(1).toBe(1)`, `assert True`, `self.assertTrue(True)`).
 - **Stub abandonment (`stub-abandonment`):** Dummy stubs left unimplemented in committed code (`throw new Error("Not implemented")`, `raise NotImplementedError`, Rust `todo!()` / `unimplemented!()`).
@@ -310,7 +325,8 @@ stubs, alongside a compiler, test runner and language-aware linter. Findings ide
 patterns, not proof of AI authorship or developer intent. Deliberate skips and abstract
 methods can be legitimate. Contiguous block comments, Python docstrings and multi-line empty handlers are
 recognized. Template interpolation, complex language syntax and context outside
-the added diff are not fully parsed. Panic loops are an observational history heuristic.
+the added diff in legacy audit modes are not fully parsed. Custom test API aliases,
+computed property calls and type/import resolution are not handled. Panic loops are an observational history heuristic.
 The discipline score summarizes added history; it does not certify current code quality.
 `check` reports actionable findings without assigning a personality or quality score.
 
@@ -323,7 +339,11 @@ npm test
 ```
 
 `npm test` builds the distribution first so CLI integration and bundle checks run
-against current code. Regression tests use disposable Git repositories.
+against current code. Regression tests use disposable Git repositories. The programmatic
+`auditPullRequest({ staged: true })` API retains the legacy added-lines contract;
+use `reviewStagedChanges()` for the new context comparison and `ReviewResult`.
+The composite Action installs exactly 0.7.0. For local development, use
+`node dist/cli.js --staged` after building.
 
 ### Author & Support
 

package/dist/{chunk-RU5OYHLR.js → chunk-YGHNTWHX.js}

@@ -640,6 +640,12 @@ var SourceMasker = class {
 
 // src/rules.ts
 var RULE_GUIDES = {
+  "test-focus": {
+    title: "Focused test narrows the test run",
+    why: "An exclusive test or suite can leave other tests unexecuted while the selected tests pass.",
+    suggestion: "Remove .only (or replace fit/fdescribe with it/describe) and run the full suite. Enable your test runner's forbid-only setting in CI when available.",
+    example: 'test.only("auth", ...) \u2192 test("auth", ...), then run the full suite'
+  },
   "test-skip": {
     title: "Skipped or disabled test",
     why: "The test runner may report success without executing this behavior check.",
@@ -689,12 +695,13 @@ var VALID_DETECTORS = [
   "swallowed-error",
   "panic-loop",
   "trivial-assert",
-  "stub-abandonment"
+  "stub-abandonment",
+  "test-focus"
 ];
 
 // src/config.ts
 var DEFAULT_CONFIG = {
-  failOn: ["test-skip", "trivial-assert"],
+  failOn: ["test-skip", "trivial-assert", "test-focus"],
   ignorePaths: [
     "**/fixtures/**",
     "**/__fixtures__/**",
@@ -709,6 +716,7 @@ var DEFAULT_CONFIG = {
   rules: {
     "test-skip": "error",
     "trivial-assert": "error",
+    "test-focus": "error",
     "swallowed-error": "warn",
     "stub-abandonment": "warn",
     "type-escape": "warn"
@@ -840,6 +848,7 @@ var TEST_SKIP_PATTERNS = [
   { regex: /\bpytest\.skip\(/, name: "imperative pytest skip (pytest.skip)" },
   { regex: /\btest\.todo\(/, name: "todo placeholder test" }
 ];
+var FOCUSED_TEST = /(?<![\w$.])(?:it|test|describe|suite)(?:\s*\.\s*(?:concurrent|serial|parallel|describe))*\s*\.\s*only\b(?=\s*(?:\(|\.\s*(?:each|failing|concurrent|serial|parallel)\b))|(?<![\w$.])(?:fit|fdescribe)\b(?=\s*(?:\(|\.\s*each\b))/g;
 var COMMENT_DIRECTIVE_PATTERNS = [
   { regex: /^\s*\/\/\s*@ts-ignore\b/, name: "compiler ignore (@ts-ignore)" },
   { regex: /^\s*\/\/\s*@ts-expect-error\b/, name: "compiler suppression (@ts-expect-error)" },
@@ -879,6 +888,8 @@ var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".jsx",
   ".mjs",
   ".cjs",
+  ".mts",
+  ".cts",
   ".py",
   ".go",
   ".rs",
@@ -1024,6 +1035,35 @@ function auditFileDiffs(files, commitHash = "HEAD", commitDate = (/* @__PURE__ *
         }
       }
     }
+    if (/\.(?:[cm]?[jt]sx?|vue|svelte)$/i.test(file.path)) {
+      let source = "";
+      const offsets = [];
+      for (let i = 0; i < maskedLines.length; i++) {
+        if (i) source += maskedLines[i].number === maskedLines[i - 1].number + 1 ? "\n" : "\0";
+        offsets.push(source.length);
+        source += maskedLines[i].code;
+      }
+      let row = 0;
+      for (const match of source.matchAll(FOCUSED_TEST)) {
+        let previous = match.index - 1;
+        while (previous >= 0 && /\s/.test(source[previous])) previous--;
+        if (source[previous] === ".") continue;
+        if (/^(?:fit|fdescribe)$/.test(match[0]) && !isTestFile(file.path)) continue;
+        if (/\bfunction$/.test(source.slice(Math.max(0, previous - 8), previous + 1))) continue;
+        while (row + 1 < offsets.length && offsets[row + 1] <= match.index) row++;
+        let end = row;
+        while (end + 1 < offsets.length && offsets[end + 1] < match.index + match[0].length) end++;
+        infractions.push({
+          type: "test-focus",
+          file: file.path,
+          lineNumber: maskedLines[row].number,
+          lineSnippet: maskedLines.slice(row, end + 1).map((line) => line.raw.trim()).join(" "),
+          commitHash,
+          commitDate,
+          reason: "focused test or suite excludes other tests from the run"
+        });
+      }
+    }
     for (let index = 0; index < maskedLines.length; index++) {
       const start = maskedLines[index];
       const isCatch = /\bcatch\s*(?:\([^)]*\))?\s*\{\s*$/.test(start.code);
@@ -1067,6 +1107,7 @@ var MetricsCollector = class {
   totalCommits = 0;
   aiCommits = 0;
   testSkips = [];
+  focusedTests = [];
   typeEscapes = [];
   swallowedErrors = [];
   panicLoops = [];
@@ -1173,6 +1214,7 @@ var MetricsCollector = class {
     });
     const buckets = {
       "test-skip": this.testSkips,
+      "test-focus": this.focusedTests,
       "type-escape": this.typeEscapes,
       "swallowed-error": this.swallowedErrors,
       "trivial-assert": this.trivialAsserts,
@@ -1190,7 +1232,7 @@ var MetricsCollector = class {
     this.flushPanicChain();
     const linesSample = this.includeAll ? this.totalLinesAdded : this.aiLinesAdded;
     const isSufficientData = linesSample >= MIN_SAMPLE_LOC;
-    const codeInfractionPoints = this.testSkips.length * 15 + this.trivialAsserts.length * 15 + this.swallowedErrors.length * 10 + this.stubAbandonments.length * 8 + this.typeEscapes.length * 3;
+    const codeInfractionPoints = this.testSkips.length * 15 + this.focusedTests.length * 15 + this.trivialAsserts.length * 15 + this.swallowedErrors.length * 10 + this.stubAbandonments.length * 8 + this.typeEscapes.length * 3;
     let panicInfractionPoints = 0;
     for (const loop of this.panicLoops) {
       const countMatch = loop.reason.match(/chain of (\d+) quick fixes/);
@@ -1259,6 +1301,7 @@ var MetricsCollector = class {
       totalCommits: this.totalCommits,
       aiCommits: this.aiCommits,
       testSkips: this.testSkips,
+      focusedTests: this.focusedTests,
       typeEscapes: this.typeEscapes,
       swallowedErrors: this.swallowedErrors,
       panicLoops: this.panicLoops,
@@ -1315,7 +1358,7 @@ function formatTerminalCard(summary, options) {
     lines.push(`  ${pc.dim(summary.archetypeDescription)}`);
     lines.push("");
   }
-  const totalInfractions = (summary.testSkips?.length || 0) + (summary.typeEscapes?.length || 0) + (summary.swallowedErrors?.length || 0) + (summary.panicLoops?.length || 0) + (summary.trivialAsserts?.length || 0) + (summary.stubAbandonments?.length || 0);
+  const totalInfractions = (summary.testSkips?.length || 0) + (summary.focusedTests?.length || 0) + (summary.typeEscapes?.length || 0) + (summary.swallowedErrors?.length || 0) + (summary.panicLoops?.length || 0) + (summary.trivialAsserts?.length || 0) + (summary.stubAbandonments?.length || 0);
   lines.push(pc.bold(`  INFRACTIONS (${totalInfractions})`));
   lines.push(pc.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   if (summary.panicLoops && summary.panicLoops.length > 0) {
@@ -1334,6 +1377,11 @@ function formatTerminalCard(summary, options) {
       lines.push(`      ${pc.dim(`${sample.file}: ${sample.lineSnippet || ""}`)}`);
     }
   }
+  if (summary.focusedTests?.length) {
+    lines.push(`  ${pc.red("\u25CF")} ${pc.bold("test-focus")} (${summary.focusedTests.length})  ${pc.dim("exclusive tests narrow the test run")}`);
+    const sample = summary.focusedTests[0];
+    if (sample.file) lines.push(`      ${pc.dim(`${terminalText(sample.file)}: ${terminalText(sample.lineSnippet || "")}`)}`);
+  }
   if (summary.testSkips && summary.testSkips.length > 0) {
     lines.push(
       `  ${pc.red("\u25CF")} ${pc.bold("test-skip")} (${summary.testSkips.length})  ${pc.dim("skipped or disabled tests")}`
@@ -1388,6 +1436,7 @@ function formatTerminalCard(summary, options) {
     }
     const allInfractions = [
       ...summary.testSkips || [],
+      ...summary.focusedTests || [],
       ...summary.trivialAsserts || [],
       ...summary.swallowedErrors || [],
       ...summary.stubAbandonments || [],
@@ -1631,8 +1680,8 @@ function formatReviewTerminal(result) {
   const status = !result.complete ? "INCOMPLETE" : result.passed ? "PASSED" : "BLOCKED";
   const lines = [
     "",
-    pc.bold(`agent-roast \u2014 context review: ${status}`),
-    `  ${result.mergeBaseSha.slice(0, 7)} \u2192 ${result.headSha.slice(0, 7)} \xB7 policy from base ${result.policySha.slice(0, 7)}`,
+    pc.bold(`agent-roast \u2014 ${result.source === "index" ? "staged context review" : "context review"}: ${status}`),
+    `  ${result.mergeBaseSha.slice(0, 7)} \u2192 ${result.headSha.slice(0, result.source === "index" ? 18 : 7)} \xB7 policy: ${result.policySha === "EMPTY" ? "built-in first-commit defaults" : "base " + result.policySha.slice(0, 7)}`,
     `  ${result.filesInspected} changed files compared \xB7 ${result.linesInspected} source lines inspected across both versions`,
     `  ${result.infractions.length} new \xB7 ${result.unchangedCount} existing \xB7 ${result.removedFindings.length} no longer detected`
   ];
@@ -1655,9 +1704,9 @@ function formatReviewTerminal(result) {
 function formatReviewMarkdown(result) {
   const status = !result.complete ? "INCOMPLETE" : result.passed ? "PASSED" : "BLOCKED";
   const lines = [
-    `## agent-roast context review: ${status}`,
+    `## agent-roast ${result.source === "index" ? "staged context review" : "context review"}: ${status}`,
     "",
-    `Compared ${result.filesInspected} changed files at \`${result.mergeBaseSha.slice(0, 7)}\` \u2192 \`${result.headSha.slice(0, 7)}\`. Policy: \`${result.policySha.slice(0, 7)}\`.`,
+    `Compared ${result.filesInspected} changed files at \`${result.mergeBaseSha.slice(0, 7)}\` \u2192 \`${result.headSha.slice(0, result.source === "index" ? 18 : 7)}\`. Policy: \`${result.policySha === "EMPTY" ? "built-in first-commit defaults" : result.policySha.slice(0, 7)}\`.`,
     "",
     `**${result.infractions.length} new** \xB7 ${result.unchangedCount} existing \xB7 ${result.removedFindings.length} no longer detected.`,
     ""
@@ -1985,6 +2034,7 @@ Example: ${RULE_GUIDES[rule].example}` },
       results,
       properties: report.mode === "review" ? {
         scope: "introduced findings in changed files",
+        source: report.source ?? "commits",
         baseSha: report.baseSha,
         headSha: report.headSha,
         mergeBaseSha: report.mergeBaseSha,
@@ -2063,7 +2113,7 @@ async function checkProject(options = {}) {
   const cwd = path4.resolve(options.cwd || process.cwd());
   const root = await fs4.realpath(git(cwd, ["rev-parse", "--show-toplevel"]).trim());
   const config = loadConfig(root);
-  const failOn = options.failOn ?? config.failOn ?? ["test-skip", "trivial-assert"];
+  const failOn = options.failOn ?? config.failOn ?? ["test-skip", "trivial-assert", "test-focus"];
   for (const rule of failOn) if (!VALID_DETECTORS.includes(rule)) throw new ConfigError(`Unknown rule '${rule}'.`);
   const format = options.format || "terminal";
   if (!["terminal", "json", "github", "markdown", "sarif"].includes(format)) throw new ConfigError("Unsupported check output format.");
@@ -2131,6 +2181,7 @@ async function checkProject(options = {}) {
 import path5 from "path";
 
 // src/snapshot.ts
+import { createHash as createHash2 } from "crypto";
 import { spawn as spawn2 } from "child_process";
 function assertNotAborted(signal) {
   if (signal?.aborted) throw new ConfigError("Review cancelled; no complete result was produced.");
@@ -2177,6 +2228,16 @@ async function readGit(cwd, args, signal, limit = 8 * 1024 * 1024) {
     if (signal?.aborted) abort();
   });
 }
+async function requireLocalObjects(cwd, signal) {
+  try {
+    const promises = (await readGit(cwd, ["config", "--type=bool", "--get-regexp", "^remote\\..*\\.promisor$"], signal, 64 * 1024)).toString();
+    if (promises.split("\n").some((line) => /\s+(?:true|yes|on|1)\s*$/i.test(line))) {
+      throw new ConfigError("Offline review requires a non-partial clone with local objects; promisor remotes are unsupported.");
+    }
+  } catch (error) {
+    if (!(error instanceof GitError && error.code === 1)) throw error;
+  }
+}
 async function reviewRefs(cwd, base, head, signal) {
   const resolve2 = async (ref) => {
     if (!ref.trim()) throw new ConfigError("Review refs must not be empty.");
@@ -2187,14 +2248,7 @@ async function reviewRefs(cwd, base, head, signal) {
       throw new ConfigError(`Cannot resolve review ref '${ref}'. Use valid commits and fetch complete history (actions/checkout fetch-depth: 0). ${error instanceof Error ? error.message : String(error)}`);
     }
   };
-  try {
-    const promises = (await readGit(cwd, ["config", "--type=bool", "--get-regexp", "^remote\\..*\\.promisor$"], signal, 64 * 1024)).toString();
-    if (promises.split("\n").some((line) => /\s+(?:true|yes|on|1)\s*$/i.test(line))) {
-      throw new ConfigError("Offline review requires a non-partial clone with local objects; promisor remotes are unsupported.");
-    }
-  } catch (error) {
-    if (!(error instanceof GitError && error.code === 1)) throw error;
-  }
+  await requireLocalObjects(cwd, signal);
   const baseSha = await resolve2(base);
   const headSha = await resolve2(head);
   let ancestors;
@@ -2209,6 +2263,9 @@ async function reviewRefs(cwd, base, head, signal) {
 }
 async function changedTreeFiles(cwd, before, after, signal) {
   const buffer = await readGit(cwd, ["diff", "--raw", "-z", "--no-relative", "--no-abbrev", "--no-ext-diff", "--no-textconv", "--find-renames=50%", "-l1000", "--end-of-options", before, after, "--"], signal);
+  return parseTreeChanges(buffer);
+}
+function parseTreeChanges(buffer) {
   const tokens = new TextDecoder("utf-8", { fatal: true }).decode(buffer).split("\0");
   if (tokens.pop() !== "") throw new ConfigError("Truncated Git change inventory.");
   const changes = [];
@@ -2245,6 +2302,59 @@ async function reviewPolicy(cwd, baseSha, signal) {
   }
   return { config: configFromText("{}", "default review policy"), filename: null };
 }
+async function stagedSnapshot(cwd, signal) {
+  await requireLocalObjects(cwd, signal);
+  const head = async () => {
+    try {
+      return (await readGit(cwd, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], signal, 1024)).toString().trim();
+    } catch (error) {
+      if (!(error instanceof GitError && error.code === 1)) throw error;
+      const ref = (await readGit(cwd, ["symbolic-ref", "--quiet", "HEAD"], signal, 1024)).toString().trim();
+      try {
+        await readGit(cwd, ["show-ref", "--verify", "--quiet", ref], signal, 1024);
+      } catch (missing) {
+        if (missing instanceof GitError && missing.code === 1) return "EMPTY";
+        throw missing;
+      }
+      throw new ConfigError("HEAD exists but cannot be resolved to a commit.");
+    }
+  };
+  const baseSha = await head();
+  const inventory = () => readGit(cwd, [
+    "diff",
+    "--cached",
+    "--raw",
+    "-z",
+    "--no-relative",
+    "--no-abbrev",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--ignore-submodules=none",
+    "--ita-invisible-in-index",
+    "--find-renames=50%",
+    "-l1000",
+    "--end-of-options",
+    ...baseSha === "EMPTY" ? [] : [baseSha],
+    "--"
+  ], signal);
+  const conflicts = await readGit(cwd, ["ls-files", "--unmerged", "-z", "--full-name"], signal);
+  if (conflicts.length) throw new ConfigError("Resolve unmerged index entries before reviewing staged changes.");
+  const pinned = await inventory();
+  const changes = parseTreeChanges(pinned);
+  const headSha = "INDEX:" + createHash2("sha256").update(baseSha).update(pinned).digest("hex");
+  return {
+    baseSha,
+    headSha,
+    mergeBaseSha: baseSha,
+    changes,
+    verify: async () => {
+      assertNotAborted(signal);
+      if (await head() !== baseSha || !(await inventory()).equals(pinned)) {
+        throw new ConfigError("HEAD or staged changes changed during review; rerun before committing. No complete result was produced.");
+      }
+    }
+  };
+}
 
 // src/review.ts
 var GENERATED_PATHS2 = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.min.js", "**/*.map"];
@@ -2268,21 +2378,29 @@ function compareFindings(before, after, newPath) {
   }
   return { introduced, removed: [...old.values()].flatMap((bucket) => bucket.findings.slice(bucket.matched)), unchanged };
 }
-async function reviewChanges(options) {
+function reviewChanges(options) {
+  return compareSourceChanges({ ...options, staged: false });
+}
+function reviewStagedChanges(options = {}) {
+  return compareSourceChanges({ ...options, staged: true });
+}
+async function compareSourceChanges(options) {
   assertNotAborted(options.signal);
   const cwd = path5.resolve(options.cwd || process.cwd());
-  const refs = await reviewRefs(cwd, options.base, options.head ?? "HEAD", options.signal);
-  const policy = await reviewPolicy(cwd, refs.baseSha, options.signal);
+  const staged = options.staged ? await stagedSnapshot(cwd, options.signal) : void 0;
+  const refs = options.staged ? { baseSha: staged.baseSha, headSha: staged.headSha, mergeBaseSha: staged.mergeBaseSha } : await reviewRefs(cwd, options.base, options.head ?? "HEAD", options.signal);
+  const policy = refs.baseSha === "EMPTY" ? { config: configFromText("{}", "default first-commit policy"), filename: null } : await reviewPolicy(cwd, refs.baseSha, options.signal);
   const format = options.format ?? "terminal";
   if (!["terminal", "json", "github", "markdown", "sarif"].includes(format)) throw new ConfigError("Unsupported review format.");
-  const failOn = options.failOn ?? policy.config.failOn ?? ["test-skip", "trivial-assert"];
+  const failOn = options.failOn ?? policy.config.failOn ?? ["test-skip", "trivial-assert", "test-focus"];
   for (const rule of failOn) if (!VALID_DETECTORS.includes(rule)) throw new ConfigError(`Unknown review rule '${rule}'.`);
-  const changes = await changedTreeFiles(cwd, refs.mergeBaseSha, refs.headSha, options.signal);
+  const changes = staged?.changes ?? await changedTreeFiles(cwd, refs.mergeBaseSha, refs.headSha, options.signal);
   const policyChanges = changes.filter((change) => CONFIG_FILENAMES.includes(change.oldPath) || CONFIG_FILENAMES.includes(change.newPath)).map((change) => change.newPath);
   const ignores = [...GENERATED_PATHS2, ...policy.config.ignorePaths || []];
   const result = {
-    schemaVersion: "1.0.0",
+    schemaVersion: "1.1.0",
     mode: "review",
+    source: staged ? "index" : "commits",
     ...refs,
     policySha: refs.baseSha,
     policyFile: policy.filename,
@@ -2355,6 +2473,7 @@ async function reviewChanges(options) {
     }
   }
   assertNotAborted(options.signal);
+  await staged?.verify();
   result.complete = result.skippedFiles.length === 0;
   result.failedRules = [...new Set(result.infractions.filter((finding) => failOn.includes(finding.type)).map((finding) => finding.type))];
   result.passed = result.complete && result.failedRules.length === 0;
@@ -2514,6 +2633,7 @@ export {
   checkProject,
   compareFindings,
   reviewChanges,
+  reviewStagedChanges,
   InvalidDetectorError,
   roastRepository,
   auditPullRequest

package/dist/cli.js

@@ -16,9 +16,10 @@ import {
   initProject,
   loadConfig,
   reviewChanges,
+  reviewStagedChanges,
   roastRepository,
   writeBaseline
-} from "./chunk-RU5OYHLR.js";
+} from "./chunk-YGHNTWHX.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -27,8 +28,39 @@ import * as fs from "fs";
 import * as path from "path";
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
+async function runContextReview(repoPath, options, staged) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  try {
+    const common = {
+      cwd: repoPath,
+      failOn: options.failOn !== void 0 ? options.failOn.split(",").map((rule) => rule.trim()).filter(Boolean) : void 0,
+      format: options.json ? "json" : options.format,
+      signal: controller.signal
+    };
+    const result = staged ? await reviewStagedChanges(common) : await reviewChanges({ ...common, base: options.base, head: options.head });
+    if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, formatReviewMarkdown(result) + "\n");
+    if (process.env.GITHUB_OUTPUT) fs.appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `passed=${result.passed}
+infractions-count=${result.infractions.length}
+has-supported-changes=${result.filesInspected > 0}
+complete=${result.complete}
+existing-count=${result.unchangedCount}
+removed-count=${result.removedFindings.length}
+`
+    );
+    console.log(result.output);
+    process.exitCode = result.exitCode;
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+}
 var program = new Command();
-program.name("agent-roast").description("Audit your git history or PR diffs for AI coding shortcuts and panic loops").version(pkg.version || "0.4.0").argument("[path]", "Path to git repository (default: current directory)", ".").option("-a, --all", "Audit ALL commits regardless of AI attribution tags", false).option("-s, --since <time>", "Time window for git analysis", "90 days ago").option("-v, --verbose", "Show commit SHAs and line snippets for all infractions", false).option("--json", "Output results as raw JSON", false).option("--staged", "Audit staged changes before committing (including the first commit)", false).option("--base <ref>", "Base git ref/branch for PR mode audit (e.g. origin/main)").option("--head <ref>", "Head git ref/SHA for PR mode audit (default: HEAD)", "HEAD").option("--fail-on <rules>", "Comma-separated detectors that trigger CI failure").option("--fail-under <score>", "Fail CI if agent score is below threshold (0-100)").option("--format <format>", "Output format: terminal, json, github, markdown (check/review also support sarif)", "terminal").option("--authors", "Display author names and emails in report", false).action(async (repoPath, options) => {
+program.name("agent-roast").description("Audit your git history or PR diffs for AI coding shortcuts and panic loops").version(pkg.version || "0.4.0").argument("[path]", "Path to git repository (default: current directory)", ".").option("-a, --all", "Audit ALL commits regardless of AI attribution tags", false).option("-s, --since <time>", "Time window for git analysis", "90 days ago").option("-v, --verbose", "Show commit SHAs and line snippets for all infractions", false).option("--json", "Output results as raw JSON", false).option("--staged", "Compare full HEAD/index source and gate new staged findings (including the first commit)", false).option("--base <ref>", "Base git ref/branch for PR mode audit (e.g. origin/main)").option("--head <ref>", "Head git ref/SHA for PR mode audit (default: HEAD)", "HEAD").option("--fail-on <rules>", "Comma-separated detectors that trigger CI failure").option("--fail-under <score>", "Fail CI if agent score is below threshold (0-100)").option("--format <format>", "Output format: terminal, json, github, markdown (check/review also support sarif)", "terminal").option("--authors", "Display author names and emails in report", false).action(async (repoPath, options) => {
   try {
     if (process.env.GITHUB_EVENT_NAME === "pull_request_target") {
       console.warn(
@@ -36,6 +68,13 @@ program.name("agent-roast").description("Audit your git history or PR diffs for
       );
     }
     if (options.staged && options.base) throw new ConfigError("--staged cannot be combined with --base.");
+    if (options.staged) {
+      if (options.all || options.failUnder !== void 0 || program.getOptionValueSource("since") === "cli" || program.getOptionValueSource("head") === "cli") {
+        throw new ConfigError("--staged compares HEAD and index; --all, --since, --head and --fail-under do not apply.");
+      }
+      await runContextReview(repoPath, options, true);
+      return;
+    }
     if (!["terminal", "json", "github", "markdown"].includes(options.format)) {
       throw new ConfigError("--format must be terminal, json, github, or markdown.");
     }
@@ -122,43 +161,16 @@ has-supported-changes=${prResult.hasSupportedChanges}
     }
   }
 });
-program.command("review").description("Compare full changed source at merge-base and head; gate only new findings").argument("[path]", "Path to the Git repository", ".").addHelpText("after", "\nRequired: --base <trusted-ref>  Optional: --head <ref> (default HEAD)\nOutput: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>\nExample: agent-roast review --base origin/main --format markdown").action(async (repoPath) => {
+program.command("review").description("Compare full changed source at merge-base and head; gate only new findings").argument("[path]", "Path to the Git repository", ".").addHelpText("after", "\nRequired: --base <trusted-ref>  Optional: --head <ref> (default HEAD), or use --staged for HEAD/index\nOutput: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>\nExample: agent-roast review --base origin/main --format markdown").action(async (repoPath) => {
   try {
     const options = program.opts();
-    if (!options.base) throw new ConfigError("review requires --base <trusted-ref>.");
-    if (options.staged || options.all || options.failUnder !== void 0 || program.getOptionValueSource("since") === "cli") {
-      throw new ConfigError("review compares committed refs; --staged, --all, --since and --fail-under do not apply.");
+    if (options.staged ? options.base || program.getOptionValueSource("head") === "cli" : !options.base) {
+      throw new ConfigError("Use review --base <trusted-ref> or review --staged; --base/--head cannot be combined with --staged.");
     }
-    const controller = new AbortController();
-    const abort = () => controller.abort();
-    process.once("SIGINT", abort);
-    process.once("SIGTERM", abort);
-    try {
-      const result = await reviewChanges({
-        cwd: repoPath,
-        base: options.base,
-        head: options.head,
-        failOn: options.failOn !== void 0 ? options.failOn.split(",").map((rule) => rule.trim()).filter(Boolean) : void 0,
-        format: options.json ? "json" : options.format,
-        signal: controller.signal
-      });
-      if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, formatReviewMarkdown(result) + "\n");
-      if (process.env.GITHUB_OUTPUT) fs.appendFileSync(
-        process.env.GITHUB_OUTPUT,
-        `passed=${result.passed}
-infractions-count=${result.infractions.length}
-has-supported-changes=${result.filesInspected > 0}
-complete=${result.complete}
-existing-count=${result.unchangedCount}
-removed-count=${result.removedFindings.length}
-`
-      );
-      console.log(result.output);
-      process.exitCode = result.exitCode;
-    } finally {
-      process.removeListener("SIGINT", abort);
-      process.removeListener("SIGTERM", abort);
+    if (options.all || options.failUnder !== void 0 || program.getOptionValueSource("since") === "cli") {
+      throw new ConfigError("review compares source snapshots; --all, --since and --fail-under do not apply.");
     }
+    await runContextReview(repoPath, options, options.staged);
   } catch (error) {
     console.error(`agent-roast review error: ${error instanceof Error ? error.message : String(error)}`);
     process.exitCode = 2;

package/dist/index.d.ts

@@ -9,7 +9,7 @@ interface CommitInfo {
     isAiAttributed: boolean;
     aiSignatures: string[];
 }
-type DetectorType = "test-skip" | "type-escape" | "swallowed-error" | "panic-loop" | "trivial-assert" | "stub-abandonment";
+type DetectorType = "test-skip" | "type-escape" | "swallowed-error" | "panic-loop" | "trivial-assert" | "stub-abandonment" | "test-focus";
 declare const VALID_DETECTORS: readonly DetectorType[];
 interface Infraction {
     type: DetectorType;
@@ -28,6 +28,7 @@ interface MetricSummary {
     totalCommits: number;
     aiCommits: number;
     testSkips: Infraction[];
+    focusedTests?: Infraction[];
     typeEscapes: Infraction[];
     swallowedErrors: Infraction[];
     panicLoops: Infraction[];
@@ -118,9 +119,11 @@ interface ReviewOptions {
     format?: ReviewFormat;
     signal?: AbortSignal;
 }
+type StagedReviewOptions = Omit<ReviewOptions, "base" | "head">;
 interface ReviewResult {
     schemaVersion: string;
     mode: "review";
+    source?: "commits" | "index";
     baseSha: string;
     headSha: string;
     mergeBaseSha: string;
@@ -240,6 +243,7 @@ declare class MetricsCollector {
     private totalCommits;
     private aiCommits;
     private testSkips;
+    private focusedTests;
     private typeEscapes;
     private swallowedErrors;
     private panicLoops;
@@ -361,6 +365,7 @@ declare function compareFindings(before: Infraction[], after: Infraction[], newP
 };
 /** Compare full source blobs in changed files without executing or checking out the candidate. */
 declare function reviewChanges(options: ReviewOptions): Promise<ReviewResult>;
+declare function reviewStagedChanges(options?: StagedReviewOptions): Promise<ReviewResult>;
 
 /** Offline SARIF 2.1.0, with relative URIs and explicit incomplete-run status.
  * Snippets are omitted to avoid embedding source code in integration artifacts. */
@@ -404,4 +409,4 @@ declare function roastRepository(options?: RoastOptions): Promise<{
 }>;
 declare function auditPullRequest(options: PrAuditOptions): Promise<PrAuditResult>;
 
-export { type AgentRoastConfig, type AiAttributionResult, CONFIG_FILENAMES, type CheckOptions, type CheckResult, type CommitInfo, ConfigError, DEFAULT_CONFIG, DEFAULT_CONFIG_TEMPLATE, type DetectorType, FIELD_SEPARATOR, type FindingBaseline, GITHUB_WORKFLOW_TEMPLATE, GitError, GitResolutionError, HERMETIC_GIT_FLAGS, type Infraction, type InitOptions, type InitResult, InvalidDetectorError, type MetricSummary, MetricsCollector, PRE_COMMIT_HOOK_TEMPLATE, type ParseDiffResult, type ParsedCommit, type ParsedDiffLine, type ParsedFileDiff, type PrAuditOptions, type PrAuditResult, RECORD_SEPARATOR, RULE_GUIDES, type ReviewFormat, type ReviewOptions, type ReviewResult, type RoastOptions, type RuleGuide, type ShieldsEndpointResponse, VALID_DETECTORS, applyBaseline, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, detectAiAttribution, findMergeBase, findingFingerprint, formatCheckMarkdown, formatCheckTerminal, formatGithubAnnotations, formatGithubStepSummary, formatPrMarkdownComment, formatPrTerminalCard, formatReviewMarkdown, formatReviewTerminal, formatSarif, formatTerminalCard, generateShareUrl, generateShieldsJson, generateShieldsMarkdown, generateSvgBadge, getHermeticGitEnv, getScoreColor, initProject, isCodeFile, isTestFile, loadBaseline, loadConfig, matchIgnorePath, parseDiff, parseGitLogStream, resolveCommitSha, reviewChanges, roastRepository, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, unquoteGitPath, writeBaseline };
+export { type AgentRoastConfig, type AiAttributionResult, CONFIG_FILENAMES, type CheckOptions, type CheckResult, type CommitInfo, ConfigError, DEFAULT_CONFIG, DEFAULT_CONFIG_TEMPLATE, type DetectorType, FIELD_SEPARATOR, type FindingBaseline, GITHUB_WORKFLOW_TEMPLATE, GitError, GitResolutionError, HERMETIC_GIT_FLAGS, type Infraction, type InitOptions, type InitResult, InvalidDetectorError, type MetricSummary, MetricsCollector, PRE_COMMIT_HOOK_TEMPLATE, type ParseDiffResult, type ParsedCommit, type ParsedDiffLine, type ParsedFileDiff, type PrAuditOptions, type PrAuditResult, RECORD_SEPARATOR, RULE_GUIDES, type ReviewFormat, type ReviewOptions, type ReviewResult, type RoastOptions, type RuleGuide, type ShieldsEndpointResponse, type StagedReviewOptions, VALID_DETECTORS, applyBaseline, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, detectAiAttribution, findMergeBase, findingFingerprint, formatCheckMarkdown, formatCheckTerminal, formatGithubAnnotations, formatGithubStepSummary, formatPrMarkdownComment, formatPrTerminalCard, formatReviewMarkdown, formatReviewTerminal, formatSarif, formatTerminalCard, generateShareUrl, generateShieldsJson, generateShieldsMarkdown, generateSvgBadge, getHermeticGitEnv, getScoreColor, initProject, isCodeFile, isTestFile, loadBaseline, loadConfig, matchIgnorePath, parseDiff, parseGitLogStream, resolveCommitSha, reviewChanges, reviewStagedChanges, roastRepository, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, unquoteGitPath, writeBaseline };

package/dist/index.js

@@ -51,13 +51,14 @@ import {
   parseGitLogStream,
   resolveCommitSha,
   reviewChanges,
+  reviewStagedChanges,
   roastRepository,
   streamGitDiff,
   streamGitLog,
   stripStringAndRegexLiterals,
   unquoteGitPath,
   writeBaseline
-} from "./chunk-RU5OYHLR.js";
+} from "./chunk-YGHNTWHX.js";
 export {
   CONFIG_FILENAMES,
   ConfigError,
@@ -110,6 +111,7 @@ export {
   parseGitLogStream,
   resolveCommitSha,
   reviewChanges,
+  reviewStagedChanges,
   roastRepository,
   streamGitDiff,
   streamGitLog,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-roast",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Offline code checks for skipped tests, swallowed errors, unfinished stubs and AI coding shortcuts",
   "type": "module",
   "main": "./dist/index.js",