@holmes-lab/holmes-kit 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.3.9] - 2026-09-01
+
+Scope de-amplification and the push gate — the governance model stops taxing legitimate work
+(one test-class addition used to cost >=3 human interventions) and starts guarding the one
+moment nothing guarded: the push.
+
+### Added
+
+- **Tenure/admission scope model** (A-SPEC-508.1): a file already anchored on disk is IN its
+  specs' scope — editing it is free and silent (the double registration with `Files to Touch`
+  is gone). Only NEW claims (a new file's anchors, a re-anchor) pass admission: an FtT **glob**
+  (`src/core/**`, `test_*.py`), the **test-file dispensation** (a new test joining an approved
+  spec is coverage growth, which ART-4 asks for), or an out-of-band approval. All disk anchors
+  participate (first-match-only is dead), deleting an anchor line warns (RTM loss made audible)
+  but never blocks, and a re-anchor refusal names the transfer. Dogfooded: 96+ anchored files
+  in this repo, zero tenure regressions (pinned as a permanent sweep test).
+- **pre-push evidence gate** (A-SPEC-509.1): `npx holmes-kit install-push-gate` installs a
+  git pre-push hook (honoring `core.hooksPath`; a foreign hook is never overwritten) that
+  refuses a push unless the test-evidence ledger vouches for EXACTLY the pushed HEAD — green,
+  with real executions. Commit-message success claims never move the verdict; an unbacked claim
+  is surfaced as a warning. Collection failures allow (this safens the default; security stays
+  with the tool gates), `--no-verify` is respected, and doctor diagnoses a missing hook. Live
+  probe on this repo: a stale-ledger push was refused with both heads and the recovery command.
+
+### Fixed
+
+- **FtT parent-directory amplification**: a FILE token in Files-to-Touch silently covered its
+  whole sibling directory (`src/a/x.ts` admitted all of `src/a/`); a file token now names that
+  file only, and directory intent is written as a glob.
+
+<!-- @implements A-SPEC-209 -->
+## [0.3.8] - 2026-09-01
+
+Approval-UX slice pair (REQ-497 완결): the resident CLI surface decides on ONE raw keypress with
+an OS arrival ping, and the in-session dialog lane gets a one-choice form, a finite re-display
+and per-path deadlines.
+
+### Added
+
+- **`approve --watch` single-key TUI + OS notification** (A-SPEC-497.2): a pending item is
+  decided by one raw keypress — `a` approve / `d` deny / `q` one-line question / `s` skip — no
+  Enter, no deadline (a human terminal can wait forever). Unknown keys decide nothing
+  (fail-closed) and Ctrl-C leaves without deciding. Each NEW arrival fires one OS-native
+  notification (macOS `osascript`, Windows WinRT toast; flattened text, every failure swallowed —
+  a dead notifier changes nothing about the queue or the gates).
+- **Elicitation one-choice form, finite re-display, per-path deadlines** (A-SPEC-497.3): the
+  in-session approval dialog asks the DECISION alone (reason moves to a second dialog shown only
+  after deny/question — a question requires text, a deny stands without it); an expired dialog is
+  re-presented exactly once with a visible "재표시 2/2" counter (stale widgets survive on screen —
+  measured); and the deadline differs by path — lock-free `spec-approve` gets 240s, lock-holding
+  `review-resolve` keeps 120s with no re-display (starvation ceiling preserved). Decline, cancel
+  and any answer are never re-asked. Multi-cycle expiry measured end-to-end over the real MCP
+  protocol: two 240s presentations, summed 480s expired refusal, outer call alive.
+
+### Changed
+
+- The `--watch` input path replaces the readline line-reader with a raw-mode key stream; the
+  non-watch interactive surface is unchanged. The elicitation stage-1 form no longer carries a
+  `reason` field (moved to stage 2); silent-path refusal text stays byte-identical
+  (A-SPEC-263.1), and the expiry notice format is unchanged (summed seconds).
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.7] - 2026-09-01
 

package/bin/holmes-pre-push.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// @implements A-SPEC-509.1
+// HOLMES-KIT PUSH GATE v1 — thin stdin adapter over dist/holmes/governance/push-gate-runner.js.
+// Fail-open by contract (H-SPEC-509): this gate safens the default, it is not a security
+// boundary, so any load or collection failure lets the push proceed.
+try {
+  const { runPrePush } = require('../dist/holmes/governance/push-gate-runner.js');
+  let text = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (c) => { text += c; });
+  process.stdin.on('end', () => {
+    let code = 0;
+    try {
+      code = runPrePush({ cwd: process.cwd(), stdinText: text, write: (s) => process.stderr.write(s) });
+    } catch { code = 0; }
+    process.exit(code);
+  });
+} catch {
+  process.exit(0);
+}

package/dist/.build-id

@@ -1 +1 @@
-eb3164c-mthu5jwj
+ab67afc-mti0dz4k

package/dist/holmes/cli/approve-watch.d.ts

@@ -1,4 +1,28 @@
+import { readQueue, PendingRequest } from '../governance/approval-queue';
 import { ApproveIO } from './approve';
+/** The raw-mode key source a single-key watch listens to (process.stdin in the shipped CLI). */
+export interface KeyStream {
+    setRawMode?: (raw: boolean) => unknown;
+    resume?: () => unknown;
+    pause?: () => unknown;
+    on(event: 'data', fn: (chunk: Buffer | string) => void): unknown;
+    removeListener(event: 'data', fn: (chunk: Buffer | string) => void): unknown;
+}
+/**
+ * ONE raw keypress decides an item — a/d/q/s; q collects one follow-up line (the question).
+ * Unknown keys decide NOTHING (a typo must not become an approval — fail-closed), and Ctrl-C
+ * rejects with AbortError: leaving is not deciding. No deadline anywhere: the MAIN LANE's whole
+ * point is that a human terminal can wait forever (H-SPEC-497).
+ */
+export declare function decideByKey(stream: KeyStream, _item: Pick<PendingRequest, 'id'>): Promise<'granted' | 'denied' | 'skipped' | {
+    question: string;
+}>;
+/**
+ * Present each pending item and apply the single-key decision. The item summary goes through the
+ * SAME escaped cells the list uses (agent-controlled text never owns a line), and a denial gets a
+ * canned-but-visible reason — the agent must still see that a human said no.
+ */
+export declare function presentByKey(root: string, io: ApproveIO, actor: string, stream: KeyStream, state: ReturnType<typeof readQueue>): Promise<void>;
 /** The idle line, printed once on entering idle (not on every poll — flood is the template's enemy). */
 export declare const WATCH_IDLE = "\u25C6 \uC2B9\uC778 \uB300\uAE30 \uC911\u2026 (Ctrl-C \uB85C \uC885\uB8CC)";
 /** Default idle poll cadence. The reaction DEADLINE is a tested judgment (T-SPEC), not this number. */
@@ -13,6 +37,14 @@ export interface WatchOpts {
      * Must resolve early if `signal` aborts, so an idle watch shuts down at once.
      */
     waitIdle?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * @implements A-SPEC-497.2
+     * When present, NEW items are presented via the single-key surface (presentByKey) instead of
+     * runInteractive — the shipped CLI passes raw-mode stdin here. Absent: legacy path, byte-for-byte.
+     */
+    keyStream?: KeyStream;
+    /** Called once per NEW pending item (lastPresented dedup) — a throwing notifier is swallowed. */
+    notify?: (item: PendingRequest) => void;
 }
 /** Exported for test: the shipped idle wait must resolve at once on abort, not after the timer. */
 export declare function defaultWaitIdle(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/holmes/cli/approve-watch.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_POLL_MS = exports.WATCH_IDLE = void 0;
+exports.decideByKey = decideByKey;
+exports.presentByKey = presentByKey;
 exports.defaultWaitIdle = defaultWaitIdle;
 exports.runWatch = runWatch;
 // @implements A-SPEC-262.2
@@ -14,6 +16,92 @@ exports.runWatch = runWatch;
 // existing runInteractive, and waits between polls when the queue is empty.
 const approval_queue_1 = require("../governance/approval-queue");
 const approve_1 = require("./approve");
+// @implements A-SPEC-497.2
+/**
+ * ONE raw keypress decides an item — a/d/q/s; q collects one follow-up line (the question).
+ * Unknown keys decide NOTHING (a typo must not become an approval — fail-closed), and Ctrl-C
+ * rejects with AbortError: leaving is not deciding. No deadline anywhere: the MAIN LANE's whole
+ * point is that a human terminal can wait forever (H-SPEC-497).
+ */
+function decideByKey(stream, _item) {
+    return new Promise((resolve, reject) => {
+        let questionMode = false;
+        let line = '';
+        const onData = (chunk) => {
+            const s = chunk.toString();
+            for (const ch of s) {
+                if (ch === '') {
+                    cleanup();
+                    const e = new Error('operator left');
+                    e.name = 'AbortError';
+                    reject(e);
+                    return;
+                }
+                if (questionMode) {
+                    if (ch === '\r' || ch === '\n') {
+                        cleanup();
+                        resolve({ question: line });
+                        return;
+                    }
+                    if (ch === '' || ch === '\b') {
+                        line = line.slice(0, -1);
+                        continue;
+                    }
+                    line += ch;
+                    continue;
+                }
+                if (ch === 'a') {
+                    cleanup();
+                    resolve('granted');
+                    return;
+                }
+                if (ch === 'd') {
+                    cleanup();
+                    resolve('denied');
+                    return;
+                }
+                if (ch === 's') {
+                    cleanup();
+                    resolve('skipped');
+                    return;
+                }
+                if (ch === 'q') {
+                    questionMode = true;
+                    continue;
+                }
+                // any other key: not a decision — keep listening
+            }
+        };
+        const cleanup = () => { stream.removeListener('data', onData); };
+        stream.on('data', onData);
+    });
+}
+// @implements A-SPEC-497.2
+/**
+ * Present each pending item and apply the single-key decision. The item summary goes through the
+ * SAME escaped cells the list uses (agent-controlled text never owns a line), and a denial gets a
+ * canned-but-visible reason — the agent must still see that a human said no.
+ */
+async function presentByKey(root, io, actor, stream, state) {
+    for (const p of state.pending) {
+        io.print(`\n─ ${(0, approve_1.subjectCells)('─  ', p)}`);
+        io.print('[a]승인  [d]거부  [q]질문  [s]건너뜀 > ');
+        const d = await decideByKey(stream, p);
+        if (d === 'granted') {
+            const r = (0, approve_1.grantRequest)(root, p.id, { actor });
+            io.print(r.ok ? `✓ 승인 — ${(0, approve_1.subjectCells)('✓ 승인 — ', p)}` : `✗ ${r.reason}`);
+        }
+        else if (d === 'denied') {
+            const r = (0, approve_1.denyRequest)(root, p.id, '운영자가 watch에서 단일 키로 거부(사유 즉답 생략)', actor);
+            io.print(r.ok ? `✗ 거부 — ${(0, approve_1.subjectCells)('✗ 거부 — ', p)}` : `✗ ${r.reason}`);
+        }
+        else if (typeof d === 'object') {
+            const r = (0, approve_1.holdRequest)(root, p.id, d.question, actor);
+            io.print(r.ok ? `? 보류 — 질문이 다음 거부 문면에 실립니다` : `✗ ${r.reason}`);
+        }
+        // skipped: leave it pending, silently
+    }
+}
 /** The idle line, printed once on entering idle (not on every poll — flood is the template's enemy). */
 exports.WATCH_IDLE = '◆ 승인 대기 중… (Ctrl-C 로 종료)';
 /** Default idle poll cadence. The reaction DEADLINE is a tested judgment (T-SPEC), not this number. */
@@ -60,9 +148,24 @@ async function runWatch(root, io, actor, opts = {}) {
         const hasNew = state.pending.some((p) => !lastPresented.has(p.id));
         if (state.pending.length > 0 && hasNew) {
             idleAnnounced = false;
+            // @implements A-SPEC-497.2 — one notification per NEW item, and never a lever: a throwing
+            // notifier is swallowed (the same doctrine as the queue writer's own failures).
+            if (opts.notify) {
+                for (const p of state.pending) {
+                    if (lastPresented.has(p.id))
+                        continue;
+                    try {
+                        opts.notify(p);
+                    }
+                    catch { /* fire-and-forget */ }
+                }
+            }
             const shown = new Set(state.pending.map((p) => p.id)); // what this pass presents
             try {
-                await (0, approve_1.runInteractive)(root, io, actor);
+                if (opts.keyStream)
+                    await presentByKey(root, io, actor, opts.keyStream, state);
+                else
+                    await (0, approve_1.runInteractive)(root, io, actor);
             }
             catch (e) {
                 // The operator leaving mid-decision (Ctrl-C / EOF) surfaces as AbortError through the

package/dist/holmes/cli/doctor.d.ts

@@ -102,6 +102,12 @@ export declare function runDoctor(packageRoot: string, target?: string, opts?: D
  * very first run against a healthy server).
  */
 export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform): Promise<Check>;
+/**
+ * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
+ * AND has git. Absence or a hook without our signature is a WARN carrying the install command —
+ * the same honest-diagnosis lineage as the codex-wiring WARN (never a gate).
+ */
+export declare function pushGateCheck(target: string): Check | null;
 export declare function formatChecks(checks: Check[]): string;
 /**
  * Prove that EVERY wired harness can actually start a server, not merely that its file parses.

package/dist/holmes/cli/doctor.js

@@ -40,6 +40,7 @@ exports.prefixVerdict = prefixVerdict;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
 exports.wiringSpawnCheck = wiringSpawnCheck;
+exports.pushGateCheck = pushGateCheck;
 exports.formatChecks = formatChecks;
 exports.wiringHandshakeChecks = wiringHandshakeChecks;
 exports.semanticTierVerdict = semanticTierVerdict;
@@ -972,6 +973,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         }
     }
     add('environment', 'PASS', present);
+    // @implements A-SPEC-509.1 — honest diagnosis, not a gate: a governed git repo without our
+    // pre-push evidence gate is told so once, with the one command that installs it.
+    {
+        const pg = pushGateCheck(target ?? process.cwd());
+        if (pg)
+            checks.push(pg);
+    }
     if (extraChecks) {
         checks.push(...extraChecks);
     }
@@ -1227,6 +1235,35 @@ function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
         send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } });
     });
 }
+// @implements A-SPEC-509.1
+/**
+ * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
+ * AND has git. Absence or a hook without our signature is a WARN carrying the install command —
+ * the same honest-diagnosis lineage as the codex-wiring WARN (never a gate).
+ */
+function pushGateCheck(target) {
+    try {
+        if (!fs.existsSync(path.join(target, '.ax')))
+            return null;
+        if (!fs.existsSync(path.join(target, '.git')))
+            return null;
+        const { PUSH_HOOK_SIGNATURE } = require('../governance/push-gate');
+        const { effectiveHooksDir } = require('../governance/push-gate-runner');
+        // core.hooksPath honored (live-probe finding): diagnose where git actually looks.
+        const hookPath = path.join(effectiveHooksDir(target), 'pre-push');
+        const installed = fs.existsSync(hookPath) && fs.readFileSync(hookPath, 'utf8').includes(PUSH_HOOK_SIGNATURE);
+        return installed
+            ? { name: 'push gate', level: 'PASS', detail: 'pre-push 증빙 게이트가 설치되어 있습니다 (test_run 원장 대조)' }
+            : {
+                name: 'push gate', level: 'WARN',
+                detail: 'pre-push 증빙 게이트가 설치되어 있지 않습니다 — 미검증 HEAD 가 다른 에이전트의 기준선이 될 수 있습니다',
+                fix: 'npx holmes-kit install-push-gate 를 실행하십시오 (기존 훅은 덮지 않습니다)',
+            };
+    }
+    catch {
+        return null;
+    } // diagnosis must never crash doctor
+}
 function formatChecks(checks) {
     const lines = checks.map((c) => {
         const head = `${c.level.padEnd(4)} ${c.name} — ${c.detail}`;

package/dist/holmes/cli/index.js

@@ -80,6 +80,8 @@ const KNOWN_FLAGS = {
     ledger: ['help', 'target', 'ref', 'dry-run'],
     // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
     'semantic-key': ['help'],
+    // @implements A-SPEC-509.1 — the explicit installation act for the pre-push evidence gate.
+    'install-push-gate': ['help', 'target'],
 };
 // @implements A-SPEC-171 — subcommands that render their OWN usage on `--help`. A-SPEC-171 governs
 // "help before any side effect"; a command whose usage lives past this handler (approve, whose
@@ -814,17 +816,27 @@ async function main(argv) {
                 process.stderr.write('✗ 대화형 상주 모드(--watch)는 TTY 가 필요합니다 — 스크립트에서는 --list 를 쓰십시오\n');
                 return 1;
             }
+            // @implements A-SPEC-497.2 — the resident surface decides on ONE raw keypress (a/d/q/s, no
+            // Enter, no deadline) and pings the OS on each new arrival. Raw mode is restored on the way
+            // out whatever happens; Ctrl-C arrives as \x03 through decideByKey and ends the loop.
             const { runWatch } = require('./approve-watch');
-            const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
+            const { notifyQueueArrival } = require('./os-notify');
             const ac = new AbortController();
-            rl.once('close', () => ac.abort());
             const onSig = () => ac.abort();
             process.once('SIGINT', onSig);
+            const stdin = process.stdin;
             try {
+                stdin.setRawMode?.(true);
+                stdin.resume();
                 await runWatch(root, {
                     print: (t) => process.stdout.write(t + '\n'),
-                    ask: (q) => rl.question(q, { signal: ac.signal }),
-                }, actor, { signal: ac.signal, ...(pollMs !== undefined ? { pollMs } : {}) });
+                    ask: async () => '', // unused on the key surface; kept for the ApproveIO shape
+                }, actor, {
+                    signal: ac.signal,
+                    keyStream: stdin,
+                    notify: (p) => notifyQueueArrival(p),
+                    ...(pollMs !== undefined ? { pollMs } : {}),
+                });
             }
             catch (e) {
                 if (e?.name !== 'AbortError')
@@ -832,7 +844,8 @@ async function main(argv) {
             }
             finally {
                 process.removeListener('SIGINT', onSig);
-                rl.close();
+                stdin.setRawMode?.(false);
+                stdin.pause();
             }
             return 0;
         }
@@ -886,6 +899,40 @@ async function main(argv) {
         await runServeCommand({ root: target, port });
         return 0;
     }
+    // @implements A-SPEC-509.1 — installing the pre-push evidence gate is an EXPLICIT operator act:
+    // holmes-kit never rewires a repository's git hooks as a side effect, and it never overwrites a
+    // hook it did not write (a foreign pre-push is refused byte-intact, with manual-merge guidance).
+    if (cmd === 'install-push-gate') {
+        const target = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
+        if (!fs.existsSync(path.join(target, '.git'))) {
+            process.stderr.write(`✗ ${target} 는 git 저장소가 아닙니다 — pre-push 게이트는 .git/hooks 에 설치됩니다\n`);
+            return 1;
+        }
+        const { PUSH_HOOK_SIGNATURE } = require('../governance/push-gate');
+        // Live-probe finding (2026-09-01, this repo): `core.hooksPath` redirects git away from
+        // `.git/hooks`, so installing there is a SILENT no-op — wiring presence is not enforcement.
+        // Install where git actually looks, honoring the operator's config instead of editing it.
+        const { effectiveHooksDir } = require('../governance/push-gate-runner');
+        const hookPath = path.join(effectiveHooksDir(target), 'pre-push');
+        // dist/holmes/cli → three up is the package root, the same derivation server.ts uses.
+        const runner = path.join(path.resolve(__dirname, '..', '..', '..'), 'bin', 'holmes-pre-push.js');
+        const script = `#!/usr/bin/env node\n// ${PUSH_HOOK_SIGNATURE} — \`npx holmes-kit install-push-gate\` 가 설치했습니다.\n`
+            + `// test-evidence 원장과 push HEAD 를 대조합니다. 로드 실패는 통과(fail-open) — 게이트 오류가 push 를 막지 않습니다.\n`
+            + `try { require(${JSON.stringify(runner)}); } catch { process.exit(0); }\n`;
+        if (fs.existsSync(hookPath)) {
+            const current = fs.readFileSync(hookPath, 'utf8');
+            if (!current.includes(PUSH_HOOK_SIGNATURE)) {
+                process.stderr.write(`✗ 기존 pre-push 훅이 있고 holmes-kit 이 쓴 것이 아닙니다 — 덮지 않습니다.\n`
+                    + `  수동 병합: 기존 훅 끝에 \`node ${runner} || exit 1\` 형태로 이 게이트를 이어 붙이십시오.\n`);
+                return 1;
+            }
+        }
+        fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+        fs.writeFileSync(hookPath, script);
+        fs.chmodSync(hookPath, 0o755);
+        process.stdout.write(`✓ pre-push 증빙 게이트 설치 — ${hookPath}\n  통과 조건: test_run 원장 head == push HEAD, 초록, 실행 > 0. 우회: git push --no-verify\n`);
+        return 0;
+    }
     if (cmd === 'init') {
         const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
         // @implements A-SPEC-251.1 — an unknown launch mode is refused, not defaulted: substituting a

package/dist/holmes/cli/os-notify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OS-native arrival notification for the approval queue — the MAIN LANE's "you are needed" ping.
+ * Fire-and-forget by doctrine: a notification failure must change NOTHING about the watch loop,
+ * the gate verdicts or the queue (the same swallow rule enqueueApprovalRequest lives by — the
+ * moment a dead notifier could change behavior, killing it becomes a lever).
+ *
+ * kind/target are AGENT-CONTROLLED text, so both are flattened before they reach a notification
+ * body: no control bytes, no forged lines in the notification center.
+ */
+import { ChildProcess } from 'node:child_process';
+import type { PendingRequest } from '../governance/approval-queue';
+export interface NotifyDeps {
+    platform: NodeJS.Platform;
+    spawn: (cmd: string, args: string[], opts?: {
+        stdio: 'ignore';
+        detached?: boolean;
+    }) => Pick<ChildProcess, 'unref' | 'on'>;
+}
+export declare function notifyQueueArrival(item: Pick<PendingRequest, 'kind' | 'target'>, deps?: NotifyDeps): void;

package/dist/holmes/cli/os-notify.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notifyQueueArrival = notifyQueueArrival;
+// @implements A-SPEC-497.2
+/**
+ * OS-native arrival notification for the approval queue — the MAIN LANE's "you are needed" ping.
+ * Fire-and-forget by doctrine: a notification failure must change NOTHING about the watch loop,
+ * the gate verdicts or the queue (the same swallow rule enqueueApprovalRequest lives by — the
+ * moment a dead notifier could change behavior, killing it becomes a lever).
+ *
+ * kind/target are AGENT-CONTROLLED text, so both are flattened before they reach a notification
+ * body: no control bytes, no forged lines in the notification center.
+ */
+const node_child_process_1 = require("node:child_process");
+const screen_safe_1 = require("./screen-safe");
+function notifyQueueArrival(item, deps = { platform: process.platform, spawn: (cmd, args) => (0, node_child_process_1.spawn)(cmd, args, { stdio: 'ignore', detached: false }) }) {
+    try {
+        const kind = (0, screen_safe_1.flattenField)(item.kind, 40);
+        const target = (0, screen_safe_1.flattenField)(item.target, 80);
+        const body = `${kind} — ${target} · 결정: holmes approve`;
+        let cmd;
+        let args;
+        if (deps.platform === 'darwin') {
+            // AppleScript strings escape only backslash and double-quote; flatten already removed the rest.
+            const esc = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            cmd = 'osascript';
+            args = ['-e', `display notification "${esc}" with title "Holmes-Kit 승인 요청"`];
+        }
+        else if (deps.platform === 'win32') {
+            // Toast via the WinRT bridge; single-quoted PowerShell literal with quotes doubled.
+            const esc = body.replace(/'/g, "''");
+            cmd = 'powershell.exe';
+            args = ['-NoProfile', '-Command',
+                `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; ` +
+                    `$x = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02); ` +
+                    `$t = $x.GetElementsByTagName('text'); $t.Item(0).AppendChild($x.CreateTextNode('Holmes-Kit 승인 요청')) > $null; ` +
+                    `$t.Item(1).AppendChild($x.CreateTextNode('${esc}')) > $null; ` +
+                    `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('holmes-kit').Show([Windows.UI.Notifications.ToastNotification]::new($x))`];
+        }
+        else {
+            return; // unsupported platform: silent pass-through, by contract
+        }
+        const child = deps.spawn(cmd, args, { stdio: 'ignore', detached: false });
+        child.on?.('error', () => { });
+        child.unref?.();
+    }
+    catch { /* a notification must never take the loop down with it */ }
+}

package/dist/holmes/governance/push-gate-runner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Where git ACTUALLY looks for hooks. Live probe (2026-09-01): this repo carries
+ * `core.hooksPath=.git/hooks-disabled`, so a hook written to `.git/hooks` never ran and the
+ * install success message was a lie — presence is not enforcement. A relative hooksPath is
+ * resolved against the repo root, matching git's own semantics.
+ */
+export declare function effectiveHooksDir(repoRoot: string): string;
+export interface PrePushIo {
+    cwd: string;
+    stdinText: string;
+    /** Refusals and notices land here (stderr in the shipped hook). */
+    write: (s: string) => void;
+}
+/** Exit code of the hook: 0 = push proceeds, 1 = refused. */
+export declare function runPrePush(io: PrePushIo): 0 | 1;

package/dist/holmes/governance/push-gate-runner.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveHooksDir = effectiveHooksDir;
+exports.runPrePush = runPrePush;
+// @implements A-SPEC-509.1
+/**
+ * The push gate's IMPURE half: collect (stdin lines, git facts, the evidence ledger) and hand
+ * everything to the pure judgePush. Any collection failure ALLOWS — this gate safens the default
+ * and must never be the thing that bricks a push (security stays with the tool gates).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const push_gate_1 = require("./push-gate");
+const test_evidence_1 = require("../review/test-evidence");
+/**
+ * Where git ACTUALLY looks for hooks. Live probe (2026-09-01): this repo carries
+ * `core.hooksPath=.git/hooks-disabled`, so a hook written to `.git/hooks` never ran and the
+ * install success message was a lie — presence is not enforcement. A relative hooksPath is
+ * resolved against the repo root, matching git's own semantics.
+ */
+function effectiveHooksDir(repoRoot) {
+    try {
+        const p = (0, node_child_process_1.execFileSync)('git', ['config', 'core.hooksPath'], { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (p)
+            return path.isAbsolute(p) ? p : path.join(repoRoot, p);
+    }
+    catch { /* unset config exits 1 — the default location applies */ }
+    return path.join(repoRoot, '.git', 'hooks');
+}
+/** Exit code of the hook: 0 = push proceeds, 1 = refused. */
+function runPrePush(io) {
+    try {
+        const lines = (0, push_gate_1.parsePushLines)(io.stdinText);
+        if (lines.length === 0)
+            return 0; // deletions / nothing to judge
+        const hasGovernance = fs.existsSync(path.join(io.cwd, '.ax'));
+        if (!hasGovernance)
+            return 0; // un-adopted: silent
+        const evidence = (0, test_evidence_1.readTestEvidence)(io.cwd) ?? null;
+        let refused = false;
+        for (const line of lines) {
+            let claimCommits = [];
+            try {
+                const range = /^0{40}$/.test(line.remoteSha)
+                    ? ['-n', '20', line.localSha] // new branch: a bounded recent window
+                    : [`${line.remoteSha}..${line.localSha}`];
+                claimCommits = (0, node_child_process_1.execFileSync)('git', ['log', '--format=%H%x09%s', ...range], { cwd: io.cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+                    .split('\n').filter(Boolean).map((l) => {
+                    const [sha, ...rest] = l.split('\t');
+                    return { sha, subject: rest.join('\t') };
+                });
+            }
+            catch { /* claim surfacing is optional — judgment inputs stay deterministic */ }
+            const v = (0, push_gate_1.judgePush)({ pushedHead: line.localSha, evidence, hasGovernance, claimCommits });
+            for (const n of v.notices)
+                io.write(n + '\n');
+            if (!v.allow) {
+                io.write((v.reason ?? '[Holmes-Kit push 게이트] 거부') + '\n');
+                refused = true;
+            }
+        }
+        return refused ? 1 : 0;
+    }
+    catch {
+        return 0; // fail-open by contract (H-SPEC-509)
+    }
+}

package/dist/holmes/governance/push-gate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The push gate's PURE judgment. A push is the moment a commit becomes other agents' baseline
+ * (field basis: a multi-agent regression reached production unguarded), so the default is made
+ * safe: the test-evidence ledger must vouch for EXACTLY the head being pushed, green, with real
+ * executions. Deterministic facts only — commit-message prose ("전체 스위트 초록") never moves
+ * the verdict; an unbacked claim is SURFACED as a notice so the dishonesty is audible.
+ *
+ * Deliberately NOT a security boundary: collection failures and un-adopted repos pass (the tool
+ * gates own security). And `git push --no-verify` is git's own escape hatch — respected, not
+ * re-litigated: this gate safens the default, it does not take the human's final say.
+ */
+import type { TestEvidence } from '../review/test-evidence';
+/** Identifies OUR installed hook — the single truth doctor and re-install both key on. */
+export declare const PUSH_HOOK_SIGNATURE = "HOLMES-KIT PUSH GATE v1";
+export interface PushJudgeInput {
+    pushedHead: string;
+    evidence: TestEvidence | null;
+    /** `.ax` exists — the repo opted into governance. */
+    hasGovernance: boolean;
+    /** Commits in the pushed range, for the claim cross-check (surfacing only). */
+    claimCommits: Array<{
+        sha: string;
+        subject: string;
+    }>;
+}
+export interface PushVerdict {
+    allow: boolean;
+    reason?: string;
+    notices: string[];
+}
+export declare function judgePush(input: PushJudgeInput): PushVerdict;
+/**
+ * The pre-push stdin format: `<local ref> <local sha> <remote ref> <remote sha>` per line.
+ * A deletion push (all-zero local sha) deletes a remote ref — there is nothing to vouch for.
+ */
+export declare function parsePushLines(stdinText: string): Array<{
+    localSha: string;
+    remoteSha: string;
+}>;