@holmes-lab/holmes-kit 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.7] - 2026-09-01
+
+Field-incident hardening: consistency warning lints over the code graph, and an approval queue
+that stops burying the one approval that matters.
+
+### Added
+
+- **Consistency lints, opt-in** (A-SPEC-506.1): `cpg_scan` accepts `lints: true` and adds a
+  warning-signal field (Python, with an honest `limits` envelope): `dynamicRef` — a literal
+  `getattr`/`hasattr` name absent from the scanned symbol census (field incident: 49
+  owner-approved deletions silently no-op'ed against a nonexistent method) — and
+  `asyncBlocking` — a known-blocking call inside an `async def`, unwrapped on its line (field
+  incident: scheduler starvation while the same file's other call sites used `to_thread`). No
+  gate consumes these; the default scan result is unchanged.
+- **Approval-queue staleness** (A-SPEC-507.1): the `approve` list sorts by latest activity and
+  folds entries whose last activity exceeded `--stale-hours` (default 24; `--all` unfolds,
+  `--stale-hours 0` disables) — measured: 51 pending rows, mostly week-old residue, buried the
+  one live approval at [32]. The ledger deletes nothing; a re-filed request revives itself; and
+  gate-path folds take no clock at all (value-identical without the view options).
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.6] - 2026-09-01
 

package/dist/.build-id

@@ -1 +1 @@
-c3e5866-mthi2ccn
+eb3164c-mthu5jwj

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

@@ -21,7 +21,19 @@ export declare function holdRequest(root: string, id: string, question: string,
  * when, and any standing question. Deliberately NO scope grammar anywhere — the moment the screen
  * teaches syntax, humans start typing it.
  */
-export declare function renderPending(state: QueueState): string;
+/**
+ * The list-view stale flags, parsed once: `--stale-hours <h>` (default 24; 0 disables folding —
+ * `--ttl` was already taken by the grant-lifetime flag) and `--all` to unfold. Returning null
+ * means "no clock": readQueue is then called without opts and the fold stays value-identical.
+ */
+export declare function staleView(flags: Record<string, unknown>): {
+    ttlMs: number;
+    showAll: boolean;
+} | null;
+export declare function renderPending(state: QueueState, view?: {
+    staleHours: number;
+    showAll: boolean;
+}): string;
 /**
  * @implements A-SPEC-262.1
  * What a decision line must say. Round-1: `✓ 승인 — <expires> 까지 유효` named NOTHING, so an index

package/dist/holmes/cli/approve.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.grantRequest = grantRequest;
 exports.denyRequest = denyRequest;
 exports.holdRequest = holdRequest;
+exports.staleView = staleView;
 exports.renderPending = renderPending;
 exports.subjectCells = subjectCells;
 exports.subjectRoom = subjectRoom;
@@ -236,7 +237,20 @@ function holdRequest(root, id, question, actor) {
  * when, and any standing question. Deliberately NO scope grammar anywhere — the moment the screen
  * teaches syntax, humans start typing it.
  */
-function renderPending(state) {
+// @implements A-SPEC-507.1
+/**
+ * The list-view stale flags, parsed once: `--stale-hours <h>` (default 24; 0 disables folding —
+ * `--ttl` was already taken by the grant-lifetime flag) and `--all` to unfold. Returning null
+ * means "no clock": readQueue is then called without opts and the fold stays value-identical.
+ */
+function staleView(flags) {
+    const raw = flags['stale-hours'];
+    const hours = typeof raw === 'string' ? Number(raw) : 24;
+    if (!Number.isFinite(hours) || hours <= 0)
+        return null;
+    return { ttlMs: hours * 3_600_000, showAll: flags.all === true };
+}
+function renderPending(state, view) {
     if (state.pending.length === 0) {
         // Round-7: this early return made the malformed-line row below UNREACHABLE in exactly the case
         // it exists for — a wholly corrupted queue printed "no requests waiting" and exited 0, which is
@@ -249,7 +263,13 @@ function renderPending(state) {
         return '승인 대기 중인 요청이 없습니다.';
     }
     const lines = [`◆ 승인 대기 ${state.pending.length}건`, ''];
-    state.pending.forEach((p, i) => {
+    // @implements A-SPEC-507.1 — the LIST VIEW sorts newest-activity-first and folds stale entries
+    // (C4: 51 rows, mostly week-old residue, buried the one live approval at [32]). Only when a view
+    // is passed: callers without one keep the legacy insertion order byte-for-byte.
+    const shown = view
+        ? [...state.pending].sort((a, b) => (Date.parse(b.lastTs) || 0) - (Date.parse(a.lastTs) || 0))
+        : state.pending;
+    shown.forEach((p, i) => {
         // @implements A-SPEC-262.1 — every field here is AGENT-CONTROLLED (the target is the command it
         // was blocked on). Round-1 forged two extra rows and hid the real ones behind an ANSI conceal,
         // and the operator granted a `curl … | sh` they never saw. The template owns the line structure.
@@ -266,6 +286,19 @@ function renderPending(state) {
         lines.push(`    id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
         lines.push('');
     });
+    if (view && state.expired.length > 0) {
+        if (view.showAll) {
+            // Folding is not concealment: --all shows every expired entry under a template-owned prefix.
+            for (const p of state.expired) {
+                lines.push(`[만료] ${subjectCells('[만료]  ', p)}`);
+                lines.push(`    마지막 활동: ${(0, screen_safe_1.rowField)(p.lastTs, 28)} · id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
+                lines.push('');
+            }
+        }
+        else {
+            lines.push(`⏳ 만료로 접힘 ${state.expired.length}건 (마지막 활동 ${view.staleHours}h 초과) — --all 로 표시`);
+        }
+    }
     if (state.malformedLines > 0)
         lines.push(`(큐에 읽을 수 없는 줄 ${state.malformedLines}건 — 손상 여부를 확인하십시오)`);
     return lines.join('\n');

package/dist/holmes/cli/index.js

@@ -787,8 +787,14 @@ async function main(argv) {
             process.stdout.write(r.ok ? `✓ 보류 — ${ref.subject('✓ 보류 — ')}\n${ref.detail('질문은 다음 거부 문면에')}\n` : `✗ ${r.reason}\n`);
             return r.ok ? 0 : 1;
         }
+        // @implements A-SPEC-507.1 — stale folding is a LIST-VIEW judgment: the clock enters only
+        // here, never on gate-path folds. `--stale-hours 0` disables it; `--all` unfolds.
+        const { staleView } = require('./approve');
+        const stale = staleView(flags);
+        const queueOpts = stale ? { now: Date.now(), ttlMs: stale.ttlMs } : undefined;
+        const listView = stale ? { staleHours: stale.ttlMs / 3_600_000, showAll: stale.showAll } : undefined;
         if (flags.list) {
-            process.stdout.write(renderPending(readQueue(root)) + '\n');
+            process.stdout.write(renderPending(readQueue(root, queueOpts), listView) + '\n');
             return 0;
         }
         // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
@@ -833,9 +839,9 @@ async function main(argv) {
         // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
         // with the real pending id filled in; the explicit --list above stays script-clean.
         if (!process.stdin.isTTY) {
-            const state = readQueue(root);
+            const state = readQueue(root, queueOpts);
             const hint = renderNonTtyHint(state);
-            process.stdout.write(renderPending(state) + (hint ? '\n\n' + hint : '') + '\n');
+            process.stdout.write(renderPending(state, listView) + (hint ? '\n\n' + hint : '') + '\n');
             return 0;
         }
         // @implements A-SPEC-262.1

package/dist/holmes/cpg/consistency-lints.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Consistency lints over what the repo already KNOWS — two field incidents, one gap:
+ *
+ * P-G  `getattr(mem, "delete_fact", None)` referenced a symbol no class defines; the optional
+ *      default hid the absence and 49 owner-approved deletions silently no-op'ed. The symbol
+ *      census (CPG scan) had the answer all along — nobody asked it.
+ * P-J  an `async def` body called sqlite directly and starved the scheduler, while the SAME
+ *      file's other call sites wrapped the call in `to_thread` — the correct convention was one
+ *      screen away.
+ *
+ * WARNING SIGNALS ONLY: no gate consumes these (association proposes, determinism judges — the
+ * standing principle). Text heuristics with honest limits (LINT_LIMITS): literal names only,
+ * same-line wrapping exemption only, Python only — both incidents were Python; extensions need
+ * their own field evidence, like every pattern list in this repository.
+ */
+export declare const LINT_LIMITS: readonly string[];
+/** P-G: literal getattr/hasattr names absent from the repo's symbol census. */
+export declare function dynamicRefFindings(code: string, defined: ReadonlySet<string>): Array<{
+    name: string;
+    line: number;
+}>;
+/** P-J: known-blocking calls inside an async def's indentation block, unwrapped on their line. */
+export declare function asyncBlockingFindings(code: string): Array<{
+    pattern: string;
+    line: number;
+}>;

package/dist/holmes/cpg/consistency-lints.js

@@ -0,0 +1,67 @@
+"use strict";
+// @implements A-SPEC-506.1
+/**
+ * Consistency lints over what the repo already KNOWS — two field incidents, one gap:
+ *
+ * P-G  `getattr(mem, "delete_fact", None)` referenced a symbol no class defines; the optional
+ *      default hid the absence and 49 owner-approved deletions silently no-op'ed. The symbol
+ *      census (CPG scan) had the answer all along — nobody asked it.
+ * P-J  an `async def` body called sqlite directly and starved the scheduler, while the SAME
+ *      file's other call sites wrapped the call in `to_thread` — the correct convention was one
+ *      screen away.
+ *
+ * WARNING SIGNALS ONLY: no gate consumes these (association proposes, determinism judges — the
+ * standing principle). Text heuristics with honest limits (LINT_LIMITS): literal names only,
+ * same-line wrapping exemption only, Python only — both incidents were Python; extensions need
+ * their own field evidence, like every pattern list in this repository.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINT_LIMITS = void 0;
+exports.dynamicRefFindings = dynamicRefFindings;
+exports.asyncBlockingFindings = asyncBlockingFindings;
+exports.LINT_LIMITS = [
+    '리터럴 이름 인자만 판정한다 — getattr(obj, 변수)는 판정 불가로 건너뛴다',
+    '차단 패턴 목록은 실사고·명백성 기반 최소 집합이다(time.sleep·requests.동사·sqlite3.·subprocess.run·urllib.request.urlopen) — 확장은 새 실측으로만',
+    'to_thread/run_in_executor 면제는 같은 행에서만 인식한다 — 여러 줄 래핑은 오탐될 수 있다',
+    '.py 텍스트 휴리스틱이다 — 비파이썬 언어와 문자열 속 코드는 보지 않는다',
+];
+const DYNAMIC_REF_RE = /\b(?:getattr|hasattr)\(\s*[^,()]+,\s*['"](\w+)['"]/g;
+/** P-G: literal getattr/hasattr names absent from the repo's symbol census. */
+function dynamicRefFindings(code, defined) {
+    const out = [];
+    for (const m of code.matchAll(DYNAMIC_REF_RE)) {
+        const name = m[1];
+        if (defined.has(name))
+            continue;
+        out.push({ name, line: code.slice(0, m.index).split('\n').length });
+    }
+    return out;
+}
+const BLOCKING = ['time.sleep(', 'requests.get(', 'requests.post(', 'requests.put(',
+    'requests.delete(', 'requests.request(', 'sqlite3.', 'subprocess.run(', 'urllib.request.urlopen'];
+const EXEMPT_RE = /to_thread|run_in_executor/;
+/** P-J: known-blocking calls inside an async def's indentation block, unwrapped on their line. */
+function asyncBlockingFindings(code) {
+    const out = [];
+    const lines = code.split('\n');
+    let asyncIndent = null; // indentation of the enclosing `async def`, when inside one
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const indent = line.length - line.trimStart().length;
+        const isBlank = line.trim() === '';
+        if (asyncIndent !== null && !isBlank && indent <= asyncIndent)
+            asyncIndent = null; // dedent ends the block
+        const def = /^(\s*)async\s+def\b/.exec(line);
+        if (def) {
+            asyncIndent = def[1].length;
+            continue;
+        }
+        if (asyncIndent === null || isBlank || EXEMPT_RE.test(line))
+            continue;
+        for (const pattern of BLOCKING) {
+            if (line.includes(pattern))
+                out.push({ pattern, line: i + 1 });
+        }
+    }
+    return out;
+}

package/dist/holmes/governance/approval-queue.d.ts

@@ -31,6 +31,14 @@ export interface PendingRequest {
 }
 export interface QueueState {
     pending: PendingRequest[];
+    /**
+     * @implements A-SPEC-507.1
+     * Pending entries whose last activity exceeded the caller's TTL — populated ONLY when the fold
+     * was given a clock ({now, ttlMs}), so gate-path folds never depend on when you look. C4
+     * measured the harm of agelessness: 51 entries, mostly week-old residue, buried the one live
+     * approval at [32]. Expiry is a display-layer judgment; the ledger keeps every event.
+     */
+    expired: PendingRequest[];
     /** Broken lines are counted, never swallowed: an empty-looking queue must be distinguishable from a corrupted one. */
     malformedLines: number;
     /**
@@ -64,7 +72,10 @@ export declare function approvalRequestId(kind: string, target: string): string;
  * entry's pending state: an old CLI reading a new queue must not silently mis-report what is
  * waiting.
  */
-export declare function foldQueue(lines: string[]): QueueState;
+export declare function foldQueue(lines: string[], opts?: {
+    now: number;
+    ttlMs: number;
+}): QueueState;
 /**
  * Append a request event. Fire-and-forget.
  *
@@ -79,7 +90,10 @@ export declare function enqueueApprovalRequest(root: string, req: {
     why: string;
 }): boolean;
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
-export declare function readQueue(root: string): QueueState;
+export declare function readQueue(root: string, opts?: {
+    now: number;
+    ttlMs: number;
+}): QueueState;
 /**
  * The refusal-message suffix pointing the operator at the review CLI.
  *

package/dist/holmes/governance/approval-queue.js

@@ -83,7 +83,7 @@ function approvalRequestId(kind, target) {
  * entry's pending state: an old CLI reading a new queue must not silently mis-report what is
  * waiting.
  */
-function foldQueue(lines) {
+function foldQueue(lines, opts) {
     const pending = new Map();
     const decisions = {};
     let malformedLines = 0;
@@ -155,7 +155,18 @@ function foldQueue(lines) {
                 break;
         }
     }
-    return { pending: [...pending.values()], malformedLines, decisions };
+    const all = [...pending.values()];
+    if (!opts)
+        return { pending: all, expired: [], malformedLines, decisions };
+    // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
+    // clockless entry must never be silently hidden by a clock it does not carry.
+    const expired = [];
+    const active = [];
+    for (const p of all) {
+        const last = Date.parse(p.lastTs);
+        (Number.isFinite(last) && last + opts.ttlMs < opts.now ? expired : active).push(p);
+    }
+    return { pending: active, expired, malformedLines, decisions };
 }
 /**
  * Append a request event. Fire-and-forget.
@@ -223,7 +234,7 @@ function isPlainFile(file) {
     }
 }
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
-function readQueue(root) {
+function readQueue(root, opts) {
     const file = path.join(root, exports.QUEUE_RELPATH);
     try {
         // TYPE BEFORE READ. `readFileSync` on a FIFO blocks inside open(2) forever — no throw, no
@@ -232,12 +243,12 @@ function readQueue(root) {
         // hook, the stop hook and the MCP handlers, not just the CLI. `approve-context.ts` has guarded
         // this since the 2026-08-24 hang; the queue reader, which far more code depends on, did not.
         if (!fs.lstatSync(file).isFile())
-            return { pending: [], malformedLines: 1, decisions: {} };
+            return { pending: [], expired: [], malformedLines: 1, decisions: {} };
         const raw = fs.readFileSync(file, 'utf8');
-        return foldQueue(raw.split('\n'));
+        return foldQueue(raw.split('\n'), opts);
     }
     catch {
-        return { pending: [], malformedLines: 0, decisions: {} };
+        return { pending: [], expired: [], malformedLines: 0, decisions: {} };
     }
 }
 /**

package/dist/holmes/mcp/handlers.d.ts

@@ -272,6 +272,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     }>;
     cpg_scan(a: {
         root: string;
+        lints?: boolean;
     }): Promise<{
         files: number;
         symbols: number;
@@ -280,6 +281,27 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             reason: string;
         }[];
         skippedCount: number;
+    } | {
+        lints: {
+            dynamicRef: {
+                file: string;
+                name: string;
+                line: number;
+            }[];
+            asyncBlocking: {
+                file: string;
+                pattern: string;
+                line: number;
+            }[];
+            limits: string[];
+        };
+        files: number;
+        symbols: number;
+        skipped: {
+            file: string;
+            reason: string;
+        }[];
+        skippedCount: number;
     }>;
     /**
      * @implements A-SPEC-138

package/dist/holmes/mcp/handlers.js

@@ -131,6 +131,7 @@ const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const elicit_approval_1 = require("./elicit-approval");
 const anchor_comment_1 = require("../rtm/anchor-comment");
+const consistency_lints_1 = require("../cpg/consistency-lints");
 const approval_queue_1 = require("../governance/approval-queue");
 const approval_grants_1 = require("../governance/approval-grants");
 const spec_digest_1 = require("../spec/spec-digest");
@@ -1633,7 +1634,37 @@ function makeRawHandlers(store, opts) {
             // with casualties" by counts alone. Bounded listing (50), complete count.
             const { scanned, skipped } = cachedScanWithReport(root);
             const symbols = scanned.reduce((n, f) => n + f.symbols.length, 0);
-            return { files: scanned.length, symbols, skipped: skipped.slice(0, 50), skippedCount: skipped.length };
+            const base = { files: scanned.length, symbols, skipped: skipped.slice(0, 50), skippedCount: skipped.length };
+            if (!a.lints)
+                return base;
+            // @implements A-SPEC-506.1 — opt-in consistency lints (P-G/P-J field incidents): WARNING
+            // signals only, additive field only, Python only; the default path above is byte-identical.
+            const defined = new Set();
+            for (const f of scanned)
+                for (const s of f.symbols) {
+                    defined.add(s.name);
+                    const last = s.name.split('.').pop();
+                    if (last)
+                        defined.add(last);
+                }
+            const dynamicRef = [];
+            const asyncBlocking = [];
+            for (const f of scanned) {
+                if (!f.sourcePath.endsWith('.py'))
+                    continue;
+                let code;
+                try {
+                    code = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                for (const hit of (0, consistency_lints_1.dynamicRefFindings)(code, defined))
+                    dynamicRef.push({ file: f.sourcePath, ...hit });
+                for (const hit of (0, consistency_lints_1.asyncBlockingFindings)(code))
+                    asyncBlocking.push({ file: f.sourcePath, ...hit });
+            }
+            return { ...base, lints: { dynamicRef, asyncBlocking, limits: [...consistency_lints_1.LINT_LIMITS] } };
         },
         /**
          * @implements A-SPEC-138

package/dist/holmes/mcp/tool-schemas.js

@@ -171,10 +171,10 @@ exports.TOOL_SCHEMAS = {
         },
     },
     cpg_scan: {
-        description: 'Scan the repository tree with tree-sitter across the 8 supported languages; returns { files, symbols } counts plus the skip report ({ skipped, skippedCount }) naming any claimed file the scan could not ingest — an empty report distinguishes a clean tree from one with casualties.',
+        description: 'Scan the repository tree with tree-sitter across the 8 supported languages; returns { files, symbols } counts plus the skip report ({ skipped, skippedCount }) naming any claimed file the scan could not ingest — an empty report distinguishes a clean tree from one with casualties. Pass lints:true to ALSO receive opt-in consistency WARNING signals (Python only, additive `lints` field with its own `limits`): dynamicRef (a literal getattr/hasattr name absent from the scanned symbol census) and asyncBlocking (a known-blocking call inside an async def, unwrapped on its line). Signals route a review; no gate consumes them.',
         inputSchema: {
             type: 'object',
-            properties: { root: ROOT },
+            properties: { root: ROOT, lints: { type: 'boolean', description: 'Include the consistency-lint warning signals (default false — the base result is unchanged without it).' } },
             required: ['root'],
         },
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",