@boyingliu01/xp-gate 0.31.4 → 0.32.1

package/plugins/dsh/src/tri-state.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @test REQ-DSH-011 tri-state gate rendering
+ * @intent Verify renderGateResult classifies every shell outcome into exactly one of
+ *         PASS / GATE FAILED / INDETERMINATE, following the documented decision order,
+ *         and that no ambiguous outcome can be read as a pass.
+ * @covers AC-DSH-011-01 AC-DSH-011-02 AC-DSH-011-03 AC-DSH-011-04 AC-DSH-011-05 AC-DSH-011-06
+ *
+ * Why the ordering matters: a timed-out process can still report exit 0 from its
+ * last state before the kill, so checking `exit === 0` first would turn a timeout
+ * into a green check. The same mistake in Gate 8 and Gate 10 is exactly what this
+ * project kept re-fixing — a gate that could not run must never report success.
+ */
+
+import { describe, it, expect } from "vitest"
+import type { ShellRunResult } from "@deepseek-ai/dsh-shell"
+import { renderGateResult } from "./gate-runner.js"
+
+/** The shell's convention for "command not found" — no verdict, no reason. */
+const COMMAND_NOT_FOUND = 127;
+
+/** A non-zero count a real gate prints when it finds violations. */
+const VIOLATIONS_FOUND = 3;
+
+function makeResult(over: Partial<ShellRunResult> = {}): ShellRunResult {
+  return {
+    exitCode: 0,
+    stdout: { text: "", truncated: false },
+    stderr: { text: "", truncated: false },
+    timedOut: false,
+    timeoutMs: 1000,
+    signal: null,
+    aborted: false,
+    ...over,
+  } as ShellRunResult
+}
+
+describe("renderGateResult tri-state", () => {
+  it("reports PASS on exit 0 with non-empty stdout", () => {
+    const out = renderGateResult(makeResult({ stdout: { text: "all gates ok", truncated: false } }))
+    expect(out).toContain("[XP-Gate] PASS")
+    expect(out).toContain("all gates ok")
+    expect(out).not.toContain("INDETERMINATE")
+    expect(out).not.toContain("GATE FAILED")
+  })
+
+  it("reports INDETERMINATE on exit 0 with empty stdout", () => {
+    // The command succeeded but said nothing — that is not a pass.
+    const out = renderGateResult(makeResult({ stdout: { text: "   \n", truncated: false } }))
+    expect(out).toContain("INDETERMINATE")
+    expect(out).toContain("NOT a pass")
+    expect(out).not.toContain("[XP-Gate] PASS")
+  })
+
+  it("reports GATE FAILED on nonzero exit with output", () => {
+    const out = renderGateResult(
+      makeResult({
+        exitCode: VIOLATIONS_FOUND,
+        stdout: { text: `${VIOLATIONS_FOUND} violations found`, truncated: false },
+      }),
+    )
+    expect(out).toContain("GATE FAILED")
+    expect(out).toContain(`exit code: ${VIOLATIONS_FOUND}`)
+    expect(out).toContain(`${VIOLATIONS_FOUND} violations found`)
+    expect(out).not.toContain("INDETERMINATE")
+  })
+
+  it("reports GATE FAILED on nonzero exit with only stderr", () => {
+    const out = renderGateResult(
+      makeResult({
+        exitCode: 1,
+        stderr: { text: "adapter crashed", truncated: false },
+      }),
+    )
+    expect(out).toContain("GATE FAILED")
+    expect(out).toContain("adapter crashed")
+  })
+
+  it("reports INDETERMINATE on nonzero exit with no output at all", () => {
+    // Typical command-not-found: neither a verdict nor a reason.
+    const out = renderGateResult(makeResult({ exitCode: COMMAND_NOT_FOUND }))
+    expect(out).toContain("INDETERMINATE")
+    expect(out).not.toContain("GATE FAILED")
+    expect(out).not.toContain("[XP-Gate] PASS")
+  })
+
+  it("reports INDETERMINATE on timeout even when exit code is 0", () => {
+    // The ordering trap: exit 0 must not win over timedOut.
+    const out = renderGateResult(
+      makeResult({
+        exitCode: 0,
+        timedOut: true,
+        stdout: { text: "partial output", truncated: false },
+      }),
+    )
+    expect(out).toContain("INDETERMINATE")
+    expect(out).toContain("timed out")
+    expect(out).not.toContain("[XP-Gate] PASS")
+  })
+
+  it("reports INDETERMINATE when stdout was truncated", () => {
+    const out = renderGateResult(
+      makeResult({
+        stdout: { text: "head of the report", truncated: true, spillPath: "/tmp/spill.log" },
+      }),
+    )
+    expect(out).toContain("INDETERMINATE")
+    expect(out).not.toContain("[XP-Gate] PASS")
+  })
+
+  it("never emits PASS anywhere in an ambiguous result", () => {
+    const ambiguous = [
+      makeResult({ exitCode: 0 }),
+      makeResult({ exitCode: COMMAND_NOT_FOUND }),
+      makeResult({ timedOut: true, exitCode: 0 }),
+      makeResult({ stdout: { text: "", truncated: true } }),
+    ]
+    for (const result of ambiguous) {
+      const out = renderGateResult(result)
+      // "NOT a pass" is allowed; a bare verdict line is not.
+      expect(out).not.toMatch(/\[XP-Gate\]\s+PASS/)
+    }
+  })
+})

package/plugins/opencode/index.ts

@@ -98,51 +98,113 @@ function getLocalXpGateVersion(): string | null {
   }
 }
 
-async function checkXpGateUpdate(): Promise<UpgradeResult> {
-  const cached = readCache(XP_GATE_CACHE_FILE)
+/**
+ * Decide whether an upgrade is worth attempting, without performing one.
+ *
+ * Split out of `checkXpGateUpdate` (CCN 14). That function interleaved five
+ * "return noop for this reason" branches with the install itself, so the
+ * conditions that STOP an upgrade and the act of upgrading were one readable
+ * blob. Separating them means the decision can be read (and tested) on its own.
+ */
+type UpgradeDecision =
+  | { kind: "noop"; localVersion: string | null; remoteVersion: string | null }
+  | { kind: "install"; localVersion: string; remoteVersion: string }
+
+/**
+ * Is the cached answer still a truthful description of this install?
+ *
+ * A cache records the version it was computed FOR. After a manual upgrade the
+ * local version differs, so the cache describes a different install and must be
+ * re-derived -- otherwise a user who upgrades by hand is never checked again.
+ */
+function cacheStillDescribes(
+  cached: { remoteVersion: string; localVersion?: string; status?: string } | null,
+  localVersion: string | null,
+): cached is { remoteVersion: string; localVersion: string; status: "current" } {
+  if (!cached) return false
+  if (cached.status !== "current") return false
+  if (!cached.remoteVersion || !localVersion) return false
+  return cached.localVersion === localVersion
+}
+
+async function decideUpgrade(): Promise<UpgradeDecision> {
   const localVersion = getLocalXpGateVersion()
+  const cached = readCache(XP_GATE_CACHE_FILE)
 
-  // If cache exists and local version hasn't changed AND status is "current",
-  // the cache is still valid — skip network check
-  if (cached?.status === "current" && cached.remoteVersion && localVersion && cached.localVersion === localVersion) {
-    return { action: "noop", localVersion, remoteVersion: cached.remoteVersion }
+  if (cacheStillDescribes(cached, localVersion)) {
+    return { kind: "noop", localVersion, remoteVersion: cached.remoteVersion }
   }
 
-  // If we have a valid cache but local version changed (e.g., manual upgrade)
-  // or cache has no "current" status, we need to re-check remote
-  if (!localVersion) return { action: "noop", localVersion: null, remoteVersion: null }
+  if (!localVersion) return { kind: "noop", localVersion: null, remoteVersion: null }
 
   const remoteVersion = await fetchNpmLatestVersion(XP_GATE_REGISTRY_URL)
-  if (!remoteVersion) return { action: "noop", localVersion, remoteVersion: null }
-
-  if (!semverLt(localVersion, remoteVersion)) {
+  if (!remoteVersion) return { kind: "noop", localVersion, remoteVersion: null }
+
+  const upToDate = !semverLt(localVersion, remoteVersion)
+  // The opt-out is checked AFTER the version comparison so that recording
+  // "current" is still correct for an opted-out user; skipping it would make the
+  // next run re-query the registry every time.
+  const optedOut = readXpGateConfig()?.autoUpgrade === false
+  if (upToDate || optedOut) {
     writeCache(XP_GATE_CACHE_FILE, { ts: Date.now(), localVersion, remoteVersion, status: "current" })
-    return { action: "noop", localVersion, remoteVersion }
+    return { kind: "noop", localVersion, remoteVersion }
   }
 
-  // Check opt-out config
-  const config = readXpGateConfig()
-  if (config?.autoUpgrade === false) {
-    writeCache(XP_GATE_CACHE_FILE, { ts: Date.now(), localVersion, remoteVersion, status: "current" })
-    return { action: "noop", localVersion, remoteVersion }
-  }
+  return { kind: "install", localVersion, remoteVersion }
+}
 
-  writeCache(XP_GATE_CACHE_FILE, { ts: Date.now(), localVersion, remoteVersion })
-  try {
-    const exitCode = await new Promise<number | null>((resolve, reject) => {
-      const child = spawn("npm", ["install", "-g", `${XP_GATE_NPM_PKG}@${remoteVersion}`], {
+/**
+ * Run `npm install -g` for one version.
+ *
+ * Resolves with the exit code rather than throwing on a non-zero exit: a failed
+ * install is a reported condition ("error"), not an exception the caller has to
+ * guess the meaning of. A spawn that could not start at all still rejects -- that
+ * is a different failure (no npm on PATH) and the caller must see it.
+ *
+ * The spawn call is guarded as well as listening for the 'error' event: both are
+ * reachable (the event covers an async ENOENT, the guard covers a synchronous
+ * throw such as an invalid argument), and an unhandled one here would escape into
+ * the host's chat loop.
+ */
+function installGlobally(version: string): Promise<number | null> {
+  return new Promise<number | null>((resolve, reject) => {
+    let child;
+    try {
+      child = spawn("npm", ["install", "-g", `${XP_GATE_NPM_PKG}@${version}`], {
         stdio: "pipe",
         shell: true,  // Required on Windows: npm is a .cmd file
         timeout: 120_000,
       })
-      child.on("close", (code) => resolve(code))
-      child.on("error", (err) => reject(err))
-    })
-    if (exitCode === 0) {
-      writeCache(XP_GATE_CACHE_FILE, { ts: Date.now(), localVersion: remoteVersion, remoteVersion, status: "current" })
-      return { action: "upgraded", localVersion, remoteVersion }
+    } catch (err) {
+      reject(err)
+      return
+    }
+    child.on("close", (code) => resolve(code))
+    child.on("error", (err) => reject(err))
+  })
+}
+
+async function checkXpGateUpdate(): Promise<UpgradeResult> {
+  const decision = await decideUpgrade()
+  if (decision.kind === "noop") {
+    return {
+      action: "noop",
+      localVersion: decision.localVersion,
+      remoteVersion: decision.remoteVersion,
+    }
+  }
+
+  const { localVersion, remoteVersion } = decision
+  writeCache(XP_GATE_CACHE_FILE, { ts: Date.now(), localVersion, remoteVersion })
+  try {
+    const exitCode = await installGlobally(remoteVersion)
+    if (exitCode !== 0) {
+      return { action: "error", localVersion, remoteVersion, error: `npm install exited with code ${exitCode}` }
     }
-    return { action: "error", localVersion, remoteVersion, error: `npm install exited with code ${exitCode}` }
+    // Record the NEW version as local: the install succeeded, so the next run
+    // must not offer the same upgrade again.
+    writeCache(XP_GATE_CACHE_FILE, { ts: Date.now(), localVersion: remoteVersion, remoteVersion, status: "current" })
+    return { action: "upgraded", localVersion, remoteVersion }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     return { action: "error", localVersion, remoteVersion, error: msg }
@@ -160,26 +222,36 @@ function readXpGateConfig(): { autoUpgrade?: boolean } | null {
 }
 // ── OpenCode plugin version check (notification only) ──
 
-async function checkPluginUpdate(pluginDir: string): Promise<void> {
-  const cached = readCache(OPENCODE_CACHE_FILE)
-  if (cached?.status === "current" && cached.remoteVersion) return
-
-  let localVersion = ""
+/** The plugin's own installed version, or null when it cannot be read. */
+function readInstalledPluginVersion(pluginDir: string): string | null {
   try {
     const pkg = JSON.parse(readFileSync(join(pluginDir, "package.json"), "utf8"))
-    localVersion = pkg.version || ""
+    return pkg.version || null
   } catch {
-    return
+    return null
   }
+}
+
+async function checkPluginUpdate(pluginDir: string): Promise<void> {
+  const cached = readCache(OPENCODE_CACHE_FILE)
+  if (cached?.status === "current" && cached.remoteVersion) return
+
+  const localVersion = readInstalledPluginVersion(pluginDir)
+  if (!localVersion) return
 
   const remoteVersion = await fetchNpmLatestVersion(OPENCODE_PLUGIN_REGISTRY)
   if (!remoteVersion) return
 
-  if (remoteVersion && localVersion && semverLt(localVersion, remoteVersion)) {
-    writeCache(OPENCODE_CACHE_FILE, { ts: Date.now(), localVersion, remoteVersion })
-  } else if (remoteVersion && localVersion) {
-    writeCache(OPENCODE_CACHE_FILE, { ts: Date.now(), localVersion, remoteVersion, status: "current" })
+  // The presence or absence of `status: "current"` is the whole message: with it
+  // the caller stays quiet, without it a notice is owed. It used to be expressed
+  // as an if/else-if that re-tested `remoteVersion && localVersion` in both arms,
+  // even though both were already known non-empty by this point.
+  const upToDate = !semverLt(localVersion, remoteVersion)
+  const entry: { ts: number; localVersion: string; remoteVersion: string; status?: string } = {
+    ts: Date.now(), localVersion, remoteVersion,
   }
+  if (upToDate) entry.status = "current"
+  writeCache(OPENCODE_CACHE_FILE, entry)
 }
 
 // ── TUI upgrade notice ──
@@ -432,39 +504,75 @@ function writeSessionModel(dbPath: string, sessionId: string, modelJson: string)
 // Boy Scout (#447): the tool's execute() body inlined 40+ lines at 5 brace
 // levels (tool → execute → try → JSON.stringify options). The logic lives at
 // module scope; execute() is pure wiring.
-function reloadSessionModel(sessionId: string): string {
+/**
+ * The config a session-model reload needs, or the reason it cannot proceed.
+ *
+ * Split out of `reloadSessionModel` (CCN 14): the function was six preconditions
+ * plus one action, and each precondition owns a distinct diagnostic. Keeping them
+ * as one linear chain made the failure paths hard to read and impossible to test
+ * individually; returning a discriminated result lets the caller stay flat.
+ */
+type ReloadInputs =
+  | { ok: true; dbPath: string; providerID: string; modelID: string }
+  | { ok: false; reason: string }
+
+function readReloadInputs(): ReloadInputs {
   const dbPath = join(homedir(), ".local", "share", "opencode", "opencode.db")
-  const configDir = join(homedir(), ".config", "opencode")
-  const omoConfigPath = join(configDir, "oh-my-openagent.json")
-
   if (!existsSync(dbPath)) {
-    return "Session reload failed: OpenCode database not found at " + dbPath
+    return { ok: false, reason: "Session reload failed: OpenCode database not found at " + dbPath }
   }
+
+  const omoConfigPath = join(homedir(), ".config", "opencode", "oh-my-openagent.json")
   if (!existsSync(omoConfigPath)) {
-    return "Session reload failed: oh-my-openagent.json not found at " + omoConfigPath
+    return { ok: false, reason: "Session reload failed: oh-my-openagent.json not found at " + omoConfigPath }
   }
 
-  let omoConfig: Record<string, unknown>
+  const parsed = parseOmoConfig(omoConfigPath)
+  if (typeof parsed === "string") return { ok: false, reason: parsed }
+
+  const model = readSisyphusModel(parsed)
+  if (typeof model === "string" && model.startsWith("Session reload failed")) {
+    return { ok: false, reason: model }
+  }
+
+  const slashIdx = (model as string).indexOf("/")
+  if (slashIdx === -1) {
+    return { ok: false, reason: `Session reload failed: model "${model}" is not in provider/model format` }
+  }
+
+  return {
+    ok: true,
+    dbPath,
+    providerID: (model as string).substring(0, slashIdx),
+    modelID: (model as string).substring(slashIdx + 1),
+  }
+}
+
+/** The parsed config object, or the failure message. */
+function parseOmoConfig(path: string): Record<string, unknown> | string {
   try {
-    omoConfig = JSON.parse(readFileSync(omoConfigPath, "utf8"))
+    return JSON.parse(readFileSync(path, "utf8"))
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     return "Session reload failed: could not parse oh-my-openagent.json: " + msg
   }
+}
 
-  const agents = omoConfig?.["agents"] as Record<string, { model?: string }> | undefined
-  const sisyphusModel = agents?.["sisyphus"]?.["model"]
-  if (!sisyphusModel || typeof sisyphusModel !== "string") {
+/** The configured sisyphus model id, or the failure message. */
+function readSisyphusModel(config: Record<string, unknown>): string {
+  const agents = config?.["agents"] as Record<string, { model?: string }> | undefined
+  const model = agents?.["sisyphus"]?.["model"]
+  if (!model || typeof model !== "string") {
     return "Session reload failed: could not find sisyphus.model in oh-my-openagent.json"
   }
+  return model
+}
 
-  const slashIdx = sisyphusModel.indexOf("/")
-  if (slashIdx === -1) {
-    return `Session reload failed: model "${sisyphusModel}" is not in provider/model format`
-  }
-  const providerID = sisyphusModel.substring(0, slashIdx)
-  const modelID = sisyphusModel.substring(slashIdx + 1)
+function reloadSessionModel(sessionId: string): string {
+  const inputs = readReloadInputs()
+  if (!inputs.ok) return inputs.reason
 
+  const { dbPath, providerID, modelID } = inputs
   const oldModel = readCurrentSessionModel(dbPath, sessionId)
   try {
     writeSessionModel(dbPath, sessionId, JSON.stringify({ id: modelID, providerID }))
@@ -557,4 +665,30 @@ const pluginModule = {
   server: XpGatePlugin,
 }
 
+/**
+ * Internals exposed for the test suite.
+ *
+ * This module had 560 lines and 27 functions with no tests at all, so nothing
+ * could be changed safely -- including the CCN=48 update callback. The pure
+ * helpers are re-exported here so their behaviour can be pinned (REQ-625)
+ * before and after the refactor that brings the complexity down.
+ *
+ * Not part of the plugin's public surface: the host loads `default`, and nothing
+ * here is a tool or a hook.
+ */
+export const __test = {
+  semverLt,
+  readCache,
+  writeCache,
+  extractTitleFromText,
+  getLocalXpGateVersion,
+  checkXpGateUpdate,
+  checkPluginUpdate,
+  runBackgroundUpdates,
+  reloadSessionModel,
+  renameSession,
+  XP_GATE_CACHE_FILE,
+  OPENCODE_CACHE_FILE,
+}
+
 export default pluginModule

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.31.4",
+  "version": "0.32.1",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.31.4",
+  "version": "0.32.1",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-10-26
-**Commit:** dfe3bf53
+**Generated:** 2026-10-29
+**Commit:** 101a0ff3
 **Branch:** main
-**Version:** 0.31.4.0
+**Version:** 0.32.1.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/principles/__tests__/analyze-read-failure.test.ts

@@ -0,0 +1,70 @@
+/**
+ * @test REQ-623
+ * @intent A file the checker could not read must not be silently rounded down to
+ *         "no violations". Before this, `analyze` caught the read failure into
+ *         `result.errors` and `main()` never looked at that array, so the run
+ *         exited 0 with a clean report. That is how CI's SARIF step archived a
+ *         successful-looking report while its log said
+ *         `Analysis failed: Could not read file: <blob>` -- a report about fewer
+ *         files than were asked for, presented as a report about all of them.
+ *
+ *         The contract kept here: an unreadable file is RECORDED (one entry, not
+ *         one per rule) and `main()` refuses to call the run clean.
+ * @covers AC-623-04, AC-623-05
+ */
+
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { analyze, getAdapterForFile } from '../analyzer';
+import { getAllRules } from '../index';
+
+/** A directory named `*.ts`: resolves a TS adapter, then cannot be read. */
+function unreadableTsPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-analyze-'));
+  const asDir = path.join(dir, 'broken.ts');
+  fs.mkdirSync(asDir);
+  return asDir;
+}
+
+describe('AC-623-04: an unreadable file is recorded, not swallowed', () => {
+  it('puts the read failure in result.errors', async () => {
+    const result = await analyze([unreadableTsPath()], getAllRules(), getAdapterForFile);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('names the file that could not be read', async () => {
+    const target = unreadableTsPath();
+    const result = await analyze([target], getAllRules(), getAdapterForFile);
+    expect(result.errors.join('\n')).toContain('broken.ts');
+  });
+
+  it('records one entry per file, not one per rule', async () => {
+    // The unreadable file is touched by every enabled rule; the failure is a
+    // property of the file, so the operator must not see it repeated per rule.
+    const result = await analyze([unreadableTsPath()], getAllRules(), getAdapterForFile);
+    expect(result.errors.length).toBe(1);
+  });
+
+  it('does not report the unreadable file as examined-and-clean', async () => {
+    const result = await analyze([unreadableTsPath()], getAllRules(), getAdapterForFile);
+    // No violations could have been found in a file that was never read.
+    expect(result.violations).toHaveLength(0);
+    // ...so the only honest signal is the error, and it must be present.
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+});
+
+describe('AC-623-05: a healthy run records no errors', () => {
+  it('leaves errors empty when every file reads', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-analyze-ok-'));
+    const good = path.join(dir, 'good.ts');
+    fs.writeFileSync(good, 'export const value = 1;\n', 'utf8');
+
+    const result = await analyze([good], getAllRules(), getAdapterForFile);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.summary.filesChecked).toBe(1);
+  });
+});