claude-spotter 1.4.20 → 1.4.22

package/CHANGELOG.md

@@ -1,11 +1,39 @@
 # Changelog
 
+## 1.4.22 — 2026-07-13
+
+- **default-on裁定の文書修正。** v1.4.21の実装どおりdefault-onは確定事項であり、7日・30 fresh resultの測定は精度改善にだけ使う。ON/OFFの再審査やdefault-off rollbackを選択肢としていた誤記をREADME、正典、SLO、計画、課題台帳から削除した。
+
+## 1.4.21 — 2026-07-13
+
+### Changed
+
+- **Throughline監査文脈をdefault-onへ変更。** `spotter install`がPATH上のThroughlineをabsolute pathへ解決できる場合、project markerへ既定設定する。marker v2の`origin:default|explicit`で旧既定disabledだけを移行し、明示OFFは再install後も維持する。POSIXはrealpath、Windows npm shimはabsolute `node.exe + throughline.mjs`を保存する。
+- **不在時は明示disabled。** Throughlineが見つからない場合は固定理由付きdisabledとし、current-only監査や別backendへfallbackしない。installerとdoctorが状態・OFF手順を表示する。
+- **実運用効果測定。** default-onはowner確定済み。7日以上・fresh 30件以上の過検出・見逃し・stale率・latencyは精度改善にだけ使い、ON/OFFを再審査しない。L2本文は評価ログへ保存しない。
+
+### 検証・公開
+
+478 tests（476 pass / 2 skip）、macOS/Linux/Windows × Node 22.5/22.xのCI 6/6、packの秘密・
+開発者固有path scan、隔離tarball installを通過。公開commitは`5026ace`。npm `claude-spotter@1.4.21`、
+tag / GitHub Release `v1.4.21`、registry由来global installを同期した。registry版の空projectへ
+`spotter install -y`を実行し、marker v2がThroughlineのglobal実体を`origin:default`で設定し、
+doctorがconnector availableを返すことを確認した。
+
 ## 1.4.20 — 2026-07-13
 
 ### Added
 
 - **Throughline監査文脈のopt-in配布。** 新規projectは既定`disabled`のまま、ownerがabsoluteなThroughline commandとrepeatableな先頭引数で有効化できる。freshな完了L2 user/assistant pairだけを`N=2`、body 600文字、total 4,000文字に制限し、Codex CLIへstdinで渡す。Haikuはこのcontext経路では呼ばず、fresh以外でもAIを呼ばない。connector障害は固定警告に限定する。親出力は安全なcatalog tool ID由来の固定・非命令形助言だけで、L2、reason、provider rawを反射しない。7日・30 fresh resultのproduction default昇格gateは未完了のため、配布後もproject opt-inを維持する。
 
+### 検証・公開
+
+Spotter 476 tests（474 pass / 2 skip）、Throughline 580 tests（全pass）、両CIのmacOS/Linux/Windows ×
+Node matrix各6/6、packの秘密・開発者固有path scan、隔離tarball installを通過。公開commitは`7cbc3a1`、
+npm `claude-spotter@1.4.20`、tag / GitHub Release `v1.4.20`、registry由来global installを同期した。
+`spotter doctor`は0 warnings、監査文脈connectorはavailable。Codex hook trustだけは仕様上機械検証不能のため、
+`/hooks`での人手確認を残す。
+
 ## 1.4.19
 
 親セッションの暴走を誘発できたHook出力の信頼境界を修正する。監査用AIは内部で構造化判定を返すだけとし、

package/README.ja.md

@@ -146,19 +146,18 @@ flowchart LR
 
 両者に共通するのは **「主体に頼らない仕組み」**。併用できます。
 
-### 任意の Throughline auditor context canary
+### Throughline auditor context（既定ON）
 
-新規の project install では auditor context は **disabled** が既定です。これは project が所有する
-opt-in であり、Spotter 全体の production 既定ではありません。現在の候補は Spotter リポジトリだけの
-canary です。auditor-context オプションなしで `spotter install` を再実行した場合、既存プロジェクトの
-設定は保持されます。無効化へ戻すには次を実行します。
+`spotter install`はPATH上のThroughlineを絶対パスへ解決できる場合、auditor contextを既定で有効化します。
+旧版の既定`disabled` markerも通常の再installで有効化されます。過去に明示的に無効化したprojectは
+`origin: explicit`として保持され、勝手に再有効化されません。無効化するには次を実行します。
 
 ```bash
 spotter install -y --auditor-context disabled
 ```
 
-project を opt-in するには、絶対パスの Throughline 実行ファイルと、必要なら繰り返し指定できる
-`--throughline-arg` を設定します。
+自動解決できない環境で手動設定する場合は、絶対パスのThroughline実行ファイルと、必要なら
+繰り返し指定できる`--throughline-arg`を設定します。
 
 ```bash
 spotter install -y --auditor-context throughline \
@@ -191,8 +190,7 @@ spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.js
   --recent-turns 2 --body-cap 600
 ```
 
-評価結論は現在 N=2 / 600 です。ただし rollout 承認ではありません。Spotter リポジトリ canary の
-7 日・30 fresh result gate は未完了です。
+評価結論はN=2 / 600です。既定ONは確定済みで、7日・30 fresh resultの実運用測定は精度改善に使います。
 
 ## よく使うコマンド
 

package/README.md

@@ -146,19 +146,19 @@ The audited catalog is host-local: Claude uses `<project>/.spotter/tool-db.json`
 
 Both share the principle of **"don't rely on the primary agent to do it itself."** They compose well — you can run them together.
 
-### Optional Throughline auditor context canary
+### Throughline auditor context (default-on)
 
-Fresh project installs keep auditor context **disabled**. This is a project-owned
-opt-in, not a production-wide default: the current candidate is a canary in the
-Spotter repository only. Re-running `spotter install` without auditor-context
-options preserves the project's existing setting. Disable it again with:
+When `spotter install` can resolve Throughline on PATH to an absolute executable,
+auditor context is enabled by default. A normal reinstall migrates legacy markers
+whose disabled state came from the old default. An explicit project opt-out is
+stored with `origin: explicit` and is never silently re-enabled. Disable it with:
 
 ```bash
 spotter install -y --auditor-context disabled
 ```
 
-To opt a project in, configure a direct absolute Throughline executable and any
-leading arguments with repeatable `--throughline-arg`:
+When automatic discovery is unavailable, configure a direct absolute Throughline
+executable and any leading arguments with repeatable `--throughline-arg`:
 
 ```bash
 spotter install -y --auditor-context throughline \
@@ -195,8 +195,8 @@ spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.js
   --recent-turns 2 --body-cap 600
 ```
 
-Current evaluation conclusion is N=2 / 600. It is not a rollout approval: the
-Spotter-repository canary still lacks its 7-day and 30-fresh-result gates.
+The evaluated setting is N=2 / 600. Default-on is final; the 7-day,
+30-fresh-result sample is used only to identify precision improvements.
 
 ## Common commands
 

package/bin/spotter.mjs

@@ -25,6 +25,8 @@ Usage:
                                         [--throughline-command ABS] [--throughline-arg VALUE]
                                         register hooks in <cwd>/.claude/settings.json
                                         and create <cwd>/.spotter/marker.json
+                                        (Throughline on PATH enables context by default;
+                                         pass disabled for a persistent project opt-out)
                                         (run inside each project you want audited)
   spotter install --user [-y]           legacy: register globally in ~/.claude/settings.json
                                         (NOT RECOMMENDED — fires for every Claude Code session
@@ -175,8 +177,8 @@ function parseInstallArgs(argv) {
   if (mode === 'disabled' && (command !== null || args.length > 0)) throw invalidInstallArgs();
   if (mode === 'throughline' && (command === null || !isAbsoluteCommand(command) || isShellWrapper(command))) throw invalidInstallArgs();
   const auditorContext = mode === null ? undefined : mode === 'disabled'
-    ? { mode: 'disabled' }
-    : { mode: 'throughline', command, args };
+    ? { mode: 'disabled', origin: 'explicit' }
+    : { mode: 'throughline', command, args, origin: 'explicit' };
   return { target, autoYes, auditorContext };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "1.4.20",
+  "version": "1.4.22",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {

package/src/cli/doctor.mjs

@@ -152,7 +152,14 @@ export async function inspectAuditorContextConfiguration({
   }
 
   const config = marker?.auditorContext;
-  if (config === undefined || config?.mode === 'disabled') return disabled;
+  if (config === undefined) return disabled;
+  if (config?.mode === 'disabled') {
+    if (config.origin === 'explicit') return { ok: true, mode: 'disabled', detail: 'explicit project opt-out' };
+    if (config.reason === 'throughline_unavailable') {
+      return { ok: true, mode: 'disabled', detail: 'default disabled: Throughline unavailable' };
+    }
+    return disabled;
+  }
   if (config?.mode !== 'throughline') {
     return { ok: false, mode: 'unknown', detail: 'invalid configuration' };
   }

package/src/cli/install.mjs

@@ -12,10 +12,11 @@
 // Install seeds the DB automatically via `refresh` (project-mode only — user-mode
 // has no projectRoot so DB seeding is skipped there).
 
-import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
+import { mkdir, writeFile, readFile, access, realpath } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, delimiter, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { version as SPOTTER_VERSION } from '../version.mjs';
@@ -29,7 +30,7 @@ const SPOTTER_BIN = join(PACKAGE_ROOT, 'bin', 'spotter.mjs');
 
 const SPOTTER_HOME = join(homedir(), '.spotter');
 
-const MARKER_VERSION = '1';
+const MARKER_VERSION = '2';
 
 // v1.3.0: UserPromptSubmit / Stop を 60s に統一。理由:
 // - daemon 側 Haiku timeout は 45s (DEFAULT_HAIKU_TIMEOUT_MS @ daemon.mjs)
@@ -58,6 +59,7 @@ export async function runInstall({
   codexCliPresentFn = isCodexCliPresent,
   installCodexHooksFn = installCodexHooks,
   auditorContext,
+  resolveDefaultAuditorContextFn = resolveDefaultAuditorContext,
 } = {}) {
   const settingsPath = target === 'user'
     ? join(homedir(), '.claude', 'settings.json')
@@ -86,8 +88,8 @@ export async function runInstall({
     const markerPath = join(markerDir, 'marker.json');
     await mkdir(markerDir, { recursive: true });
     const preservedAuditorContext = auditorContext === undefined
-      ? await readExistingAuditorContext(markerPath)
-      : auditorContext;
+      ? await readExistingAuditorContext(markerPath, resolveDefaultAuditorContextFn)
+      : { ...auditorContext, origin: 'explicit' };
     const marker = {
       markerVersion: MARKER_VERSION,
       spotterVersion: SPOTTER_VERSION,
@@ -96,6 +98,13 @@ export async function runInstall({
     };
     await writeFile(markerPath, JSON.stringify(marker, null, 2) + '\n', 'utf8');
     console.log(`  wrote ${markerPath}`);
+    console.log(`  auditor context: ${preservedAuditorContext.mode} (${preservedAuditorContext.origin})`);
+    if (preservedAuditorContext.mode === 'throughline') {
+      console.log('  sends bounded completed user/assistant text to the selected Codex auditor; disable with:');
+      console.log('    spotter install -y --auditor-context disabled');
+    } else if (preservedAuditorContext.reason === 'throughline_unavailable') {
+      console.log('  Throughline was not found; context auditing remains disabled (no current-only fallback)');
+    }
   }
 
   // 4. compute desired settings.json with hooks
@@ -176,16 +185,75 @@ export async function runInstall({
   }
 }
 
-async function readExistingAuditorContext(markerPath) {
+async function readExistingAuditorContext(markerPath, resolveDefaultAuditorContextFn) {
   try {
     const marker = JSON.parse(await readFile(markerPath, 'utf8'));
-    return marker?.auditorContext ?? { mode: 'disabled' };
+    const existing = marker?.auditorContext;
+    if (existing?.mode === 'throughline') {
+      return { ...existing, origin: existing.origin ?? 'explicit' };
+    }
+    if (existing?.mode === 'disabled' && existing.origin === 'explicit') {
+      return existing;
+    }
+    return resolveDefaultAuditorContextFn();
   } catch (err) {
-    if (err?.code === 'ENOENT') return { mode: 'disabled' };
+    if (err?.code === 'ENOENT') return resolveDefaultAuditorContextFn();
     throw err;
   }
 }
 
+export async function resolveDefaultAuditorContext({
+  env = process.env,
+  platform = process.platform,
+  nodePath = process.execPath,
+  accessFn = access,
+  realpathFn = realpath,
+} = {}) {
+  const pathValue = platform === 'win32' ? (env.Path ?? env.PATH ?? '') : (env.PATH ?? '');
+  const pathSeparator = platform === 'win32' ? ';' : delimiter;
+  const names = platform === 'win32'
+    ? ['throughline.exe', 'throughline.cmd', 'throughline.bat', 'throughline']
+    : ['throughline'];
+
+  for (const directory of pathValue.split(pathSeparator).filter(Boolean)) {
+    for (const name of names) {
+      const candidate = join(directory, name);
+      if (!await canExecute(candidate, accessFn)) continue;
+      const extension = extname(candidate).toLowerCase();
+      if (extension === '.cmd' || extension === '.bat') {
+        const script = join(directory, 'node_modules', 'throughline', 'bin', 'throughline.mjs');
+        if (!await canRead(script, accessFn)) continue;
+        return { mode: 'throughline', command: nodePath, args: [script], origin: 'default' };
+      }
+      return {
+        mode: 'throughline',
+        command: await realpathFn(candidate),
+        args: [],
+        origin: 'default',
+      };
+    }
+  }
+  return { mode: 'disabled', origin: 'default', reason: 'throughline_unavailable' };
+}
+
+async function canExecute(path, accessFn) {
+  try {
+    await accessFn(path, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function canRead(path, accessFn) {
+  try {
+    await accessFn(path, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function codexInstallNextSteps(projectRoot) {
   return [
     'review the three Spotter hooks with Codex /hooks',