@holmes-lab/holmes-kit 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -5,6 +5,91 @@ 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.21.0] - 2026-09-17
+
+The backlog-hardening cycle: the RTM stops claiming coverage it cannot see, sealing reports what a
+spec's Files to Touch left behind, and a known defect pinned by a test now carries a marker with an
+expiry — reported as debt, never a block, until the grace runs out.
+
+### Added
+- **Code-link census with reasons** (A-SPEC-655). `rtm_dashboard` and `/api/rtm` report `codeLinkedPct`,
+  `unlinkedCount` and `unlinkedByReason` (`test-only`, `file-anchor`, `test-and-file`, `weak-anchor`, `none`)
+  next to the old `coveragePct`, which still reads 100 while 11.4% of approved specs have no `implements`
+  edge. The scanner now reads every anchor the injector can write (`.sh/.yml/.toml/...` file anchors were
+  planted and never indexed). Measured here: 636 approved, 563 linked, 73 unlinked — 72 test-only.
+- **Files-to-Touch fulfilment advisory** (A-SPEC-656). At `spec_approve` and in `approval_status`, a sealed
+  A-SPEC whose declared paths do not exist is reported as `missing`, `moved` (same basename elsewhere) or
+  `alternatives`; the verdict is appended to `.ax/ledger/ftt-fulfilment.<replica>.jsonl`. Never blocks.
+  Four genuinely unfulfilled paths on three sealed specs were found on the first run.
+- **Trace gaps** (A-SPEC-658). `rtm_impact` returns `traceGaps` — approved specs that declare a scanned
+  production file in Files to Touch yet anchor only tests — and `impact_gate_check` answers `trace-gap`
+  with remediation instead of silently widening. Measured here: 21 specs, 29 spec/file pairs.
+- **`@known-defect(reason, expires=YYYY-MM-DD)`** (A-SPEC-660) and constitution article **ART-9**. A test
+  that pins a known defect as its expected value carries the marker on a comment line; the Stop hook walks
+  test files, lists unexpired markers on the `tracked` channel as `known-defect debt`, and blocks only when
+  a marker has expired or cannot be read (`no-reason`, `no-expires`, `bad-date`). String literals are
+  stripped first, the expiry day itself counts as expired (UTC), and a walk that cannot start is no signal.
+  Walk cost ≈61 ms per Stop on this tree; zero markers exist yet.
+- **`[observability]` obligation in the authoring playbooks** (A-SPEC-659). A slice that creates a record
+  must declare the obligation in its H-SPEC and carry a record→read round-trip case in its T-SPEC; the
+  existing tag-correspondence check reports the gap. Pinned so the prose cannot claim the gate blocks.
+
+### Fixed
+- **Windows-spelled in-project `.ax` paths are judged by location, not spelling** (A-SPEC-657). A Bash
+  write to `C:\proj\.ax\...`, `/c/proj/.ax/...` or `C:/proj/.ax/...` reached the protected-path check
+  as an outside-project path and was masked out of it; drive, MSYS and backslash spellings now normalise
+  to the project root first. Found by the Windows agent's residual-red evidence, reproduced on macOS.
+
+### Measured
+- macOS: 515 suites / 6,534 passed / 11 skipped; every slice recorded red-assertion → green; official
+  `test_run` green at b18ff0bf, last-green recorded.
+- `kills` mutation testing: all 22 existing entries write `where` as a file path and `mutate` as prose,
+  so the literal-replacement engine applies none of them and `--mutate` reports `survivors: []`. Making
+  `kills` mandatory is deferred behind a `where`-validation slice (`docs/goals/EVIDENCE-kills-cost-2026-09-17.md`).
+- Linux (OrbStack Ubuntu 24.04 arm64, Node 24): 514 / 515 suites green; the one red is the documented
+  `tree-sitter@0.21.1` source-compile failure against Node 24 headers on ARM Linux (README, unchanged since
+  0.19.4) — the npx wiring case installs the packed tarball and that install fails there. On Node 22 the
+  same tarball installs, the MCP handshake answers with the package version, and the suite is green.
+- Windows: not re-run for this release; the only Windows-relevant change is A-SPEC-657, reproduced and
+  pinned on macOS from the Windows agent's evidence.
+
+## [0.20.2] - 2026-09-16
+
+Two findings the Windows cycle recorded and could not close, closed — without giving autonomy or the
+drift check one inch of slack.
+
+### Fixed
+- **A sealed spec can now admit a root-level file** (A-SPEC-654). `Files to Touch` tokens had to contain
+  a slash, so a spec listing `- jest.config.js` produced no token at all and its own anchored write was
+  refused as "outside its Files to Touch scope" — measured 2026-09-15 on Windows, where A-SPEC-652.4 had
+  to be redesigned around it. A list item whose first word is a filename with an extension is now a token;
+  a filename mentioned inside prose, a version-like item (`- 0.20.1`) and a bare word still yield nothing,
+  and the enforcer still admits exactly that one path.
+- **A CRLF checkout is no longer reported as skill drift.** Under `core.autocrlf=true`, git rewrote the
+  skill files the installer writes with LF, so `doctor` reported three untouched skills as `drifted` and
+  advised a refresh that produced LF for the next checkout to convert straight back (measured 2026-09-16,
+  Windows). `init`'s `.gitattributes` block now declares `.claude/skills/**/SKILL.md` and
+  `.agents/skills/**/SKILL.md` as `text eol=lf`, so checkout stops re-creating the difference. One
+  `holmes-kit skills refresh` converges an existing CRLF working tree.
+
+### Unchanged on purpose
+- **Autonomy did not widen with the new tokens.** Measured before the change: 36 A-SPECs in this
+  repository have prose-only Files to Touch and 8 of them would have gained tokens — one mentioning
+  `handlers.ts` in a sentence would have flipped from human approval to self-approval. The grader now
+  requires at least one directory-scoped token, so a spec whose tokens are all root-level files still asks
+  a human: a root-level file is project-wide configuration. A test walks every A-SPEC in the store and
+  asserts each verdict equals the pre-change verdict.
+- **The drift comparison is still byte-exact.** Folding CRLF into it was implemented, measured against
+  A-SPEC-190 §9a — whitespace-touched files are `drifted` *and a refresh reclaims them* — and reverted:
+  it would have made the first of those three mutations invisible rather than recoverable. That refusal
+  is pinned in the new suite.
+
+### Measured
+- macOS: 503 suites / 6,461 passed / 11 skipped; official `test_run` green, last-green recorded.
+- Still open: the Windows residual single-assertion reds. They need the failure text from the Windows box
+  (`npx jest --json`); nothing in this repository names why they fail, and guessing from a macOS run would
+  be inventing evidence.
+
 ## [0.20.1] - 2026-09-16
 
 The Windows release. 0.20.0's external matrix was run natively on Windows 11 (Node 24, npm 12, pytest 9)

package/dist/.build-id

@@ -1 +1 @@
-37e99456-mu2vxydy
+bdbd4f85-mu4ywfad

package/dist/holmes/cli/gitignore-merge.js

@@ -61,6 +61,16 @@ exports.ATTRIBUTE_LINES = [
     '# 남는 체인 이음새는 `holmes-kit ledger rechain`의 일이다.',
     '.ax/ledger/*.jsonl merge=union',
     '.ax/approvals/queue.jsonl merge=union',
+    // @implements A-SPEC-654
+    // The installer writes these with LF and doctor compares them byte for byte (A-SPEC-190 §9a: a
+    // whitespace-touched file is `drifted` so a refresh can reclaim it). Under `core.autocrlf=true`
+    // checkout rewrote them to CRLF, so three untouched skills read `drifted` and the advised refresh
+    // produced LF for the next checkout to convert straight back — measured 2026-09-16 on Windows.
+    // Declaring the files settles it where the disagreement is, instead of teaching the drift check to
+    // ignore a difference it exists to catch.
+    '# @implements A-SPEC-654 — 설치기가 LF 로 쓰는 파일은 체크아웃에서 CRLF 로 바뀌지 않는다.',
+    '.claude/skills/**/SKILL.md text eol=lf',
+    '.agents/skills/**/SKILL.md text eol=lf',
 ];
 /** As `mergeGitignore`, over `.gitattributes` — the same marker block machinery, so idempotence
  *  and user-content preservation are inherited rather than re-implemented. */

package/dist/holmes/governance/autonomy.js

@@ -178,6 +178,12 @@ function specApprovalAutonomy(spec, resolveParent, descendants) {
                 return 'hitl';
             if (paths.some(isHighRiskPath))
                 return 'hitl'; // gate/governance/taint file
+            // @implements A-SPEC-654 — a ROOT-level file is project-wide configuration (the test runner, the
+            // manifest, the ignore policy): admitting it at the gate was the point of that slice, but grading
+            // it auto would be a widening nobody asked for. A spec earns self-approval only when it also names
+            // a directory-scoped surface — the same doubt `paths.length === 0` already encodes.
+            if (!paths.some((p) => p.includes('/')))
+                return 'hitl';
             return 'auto';
         }
         default:

package/dist/holmes/governance/constitution.d.ts

@@ -1,5 +1,6 @@
 import { Spec } from '../spec/spec-parser';
 import type { TestOutcome } from '../review/test-runner';
+import type { KnownDefect, MalformedMarker } from '../rtm/known-defects';
 /**
  * L1 — Governance CONSTITUTION (target-architecture §7 L1).
  *
@@ -26,6 +27,16 @@ export interface ConstitutionViolation {
 }
 export interface ConstitutionContext {
     specs: Spec[];
+    /**
+     * @implements A-SPEC-660
+     * `@known-defect` markers the hook judged EXPIRED or could not read — ART-9's evidence. Supplied by
+     * the hook like every other article's evidence; absent means silent (no signal, not clean).
+     * Unexpired markers never reach the constitution: they are debt on the tracked channel.
+     */
+    knownDefects?: {
+        expired: KnownDefect[];
+        malformed: MalformedMarker[];
+    };
     /**
      * @implements A-SPEC-160
      * Recorded review findings, for ART-6. Supplied by the hook, like ART-4's evidence — the

package/dist/holmes/governance/constitution.js

@@ -42,13 +42,18 @@ exports.ARTICLES = {
     'ART-4': 'Coverage honesty — declared coverage must be backed by real anchored test cases, not prose',
     'ART-5': 'Approval is out-of-band — a spec cannot self-approve; governance config cannot be self-written',
     'ART-8': 'Test-first is observed — a changed A-SPEC must show a recorded red-assertion→green sequence before it is done (a red-error is not a valid RED)',
+    // @implements A-SPEC-660
+    'ART-9': '알려진 결함을 기대값으로 고정한 단언은 표식(@known-defect)과 만료일을 가진다 — 만료가 지났거나 표식이 깨진 단언은 미완이다 (미만료 표식은 tracked 로 보고만 된다: 우회는 때로 옳은 선택이다)',
 };
 function verifyConstitution(ctx) {
     const governed = (0, spec_types_1.filterGoverned)(ctx.specs);
     // @implements A-SPEC-191 (§4b) — the early return may NOT swallow recorded findings: a project
     // that reviews before authoring specs (measured: adopt flow, reverse_scan first) held an open
     // critical while Stop passed, because ART-7 was accidentally coupled to spec-graph existence.
-    if (governed.length === 0 && (ctx.findings ?? []).length === 0)
+    // @implements A-SPEC-660 — nor may it swallow judged @known-defect markers: an expired bypass in a
+    // spec-less project is still an expired bypass.
+    const knownDefectEvidence = (ctx.knownDefects?.expired.length ?? 0) + (ctx.knownDefects?.malformed.length ?? 0) > 0;
+    if (governed.length === 0 && (ctx.findings ?? []).length === 0 && !knownDefectEvidence)
         return []; // rows 가 아니라 원본 기준 — 오염 행만 있는 원장도 감식 대상이다
     const resolve = (id) => ctx.specs.find((s) => s.id === id) ?? null;
     const v = [];
@@ -175,5 +180,14 @@ function verifyConstitution(ctx) {
             v.push({ article: 'ART-7', detail: `finding ${f.id}${gist}: 해소가 갈라진 빌드에서 봉인되었습니다 (basis ${f.basis}) — 현재 빌드로 재검증해 다시 기록하십시오` });
         }
     }
+    // @implements A-SPEC-660 — ART-9. An expired marker is a bypass whose grace ran out; an unreadable
+    // one is a debt nobody can see. Unexpired markers never reach here (tracked channel). Absent input
+    // is silence, not a clean verdict — the hook decides whether it could look.
+    for (const k of ctx.knownDefects?.expired ?? []) {
+        v.push({ article: 'ART-9', detail: `${k.file}:${k.line}: known defect "${k.reason}" expired ${k.expires} — fix the root cause or renew the marker with a reason (ART-9)` });
+    }
+    for (const m of ctx.knownDefects?.malformed ?? []) {
+        v.push({ article: 'ART-9', detail: `${m.file}:${m.line}: @known-defect marker is ${m.why} — a marker that cannot be read is a debt nobody can see (ART-9)` });
+    }
     return v;
 }

package/dist/holmes/guardrail/impact-gate.d.ts

@@ -13,7 +13,7 @@ import type { EvidenceArtifact } from '../mcp/maintenance-evidence';
  */
 export type EditDecision = 'allow' | 'widen' | 'refuse';
 export interface EditEvidenceReason {
-    code: 'no-analysis' | 'basis-drift' | 'target-out-of-scope' | 'contract-untested' | 'unproven-absence' | 'architecture-unchecked' | 'target-drift' | 'basis-unverifiable' | 'security-unchecked' | 'compatibility-unchecked';
+    code: 'no-analysis' | 'basis-drift' | 'target-out-of-scope' | 'contract-untested' | 'unproven-absence' | 'architecture-unchecked' | 'target-drift' | 'basis-unverifiable' | 'security-unchecked' | 'compatibility-unchecked' | 'trace-gap';
     detail: string;
 }
 export interface EditEvidenceInput {
@@ -30,6 +30,15 @@ export interface EditEvidenceInput {
      * is caught even while HEAD sits still.
      */
     currentTargetDigest?: string | null;
+    /**
+     * @implements A-SPEC-658
+     * Approved A-SPECs that declare `target` in their Files to Touch but are anchored by no source —
+     * computed by the caller (the handler owns the spec store and the scan; this module stays pure).
+     */
+    traceGaps?: Array<{
+        id: string;
+        file: string;
+    }>;
 }
 export interface EditEvidenceVerdict {
     decision: EditDecision;

package/dist/holmes/guardrail/impact-gate.js

@@ -80,6 +80,8 @@ const REMEDIATION = {
     'security-unchecked': 'The security axis was never examined — re-run maintenance_analyze against a tree it can actually scan so data-flow reachability is walked.',
     'compatibility-unchecked': 'The compatibility axis was never examined — re-run maintenance_analyze where the spec store is readable so breaking-change declarations can be read.',
     'basis-unverifiable': 'The analysis recorded no digest for this file, or the file cannot be read now, so drift cannot be ruled out — re-run maintenance_analyze with persist: true to take a verifiable basis.',
+    // @implements A-SPEC-658
+    'trace-gap': 'The target is declared in the Files to Touch of approved A-SPEC(s) that no source file anchors, so the graph cannot see their impact — anchor the implementing source (spec_remediate) or include those specs in the analysis request and re-run maintenance_analyze.',
 };
 const RANK = { allow: 0, widen: 1, refuse: 2 };
 function evaluateEditEvidence(inputArgs) {
@@ -89,6 +91,21 @@ function evaluateEditEvidence(inputArgs) {
     let decision = 'allow';
     const escalate = (next) => { if (RANK[next] > RANK[decision])
         decision = next; };
+    // @implements A-SPEC-658 — a trace gap is "we could not look" wearing a file's name: the target is
+    // declared by an approved A-SPEC no source anchors, so the graph's silence about that spec is
+    // ignorance, not absence. It widens, never lowers a refusal, and never speaks for one (the
+    // primary remediation below stays the refusal's). The caller computes the list; this stays pure.
+    const traceGapReason = () => {
+        const gaps = inputArgs.traceGaps ?? [];
+        if (gaps.length === 0)
+            return;
+        const ids = [...new Set(gaps.map((g) => g.id))].sort();
+        reasons.push({
+            code: 'trace-gap',
+            detail: `${target} is declared by approved ${ids.join(', ')} that no source anchors — the graph cannot see their impact.`,
+        });
+        escalate('widen');
+    };
     const artifact = inputArgs.artifact;
     if (!artifact) {
         // The proportional path: ordinary prose needs no graph evidence. A governing document does, and
@@ -96,6 +113,7 @@ function evaluateEditEvidence(inputArgs) {
         if (lowRisk)
             return { decision: 'allow', reasons: [], remediation: '', lowRisk: true };
         reasons.push({ code: 'no-analysis', detail: `No impact analysis backs an edit to ${target}.` });
+        traceGapReason(); // two reasons, both stated; the remediation stays the refusal's
         return { decision: 'refuse', reasons, remediation: REMEDIATION['no-analysis'], lowRisk };
     }
     // (2) An analysis describes one commit. Once HEAD moves, its claims are about a tree that no
@@ -183,6 +201,7 @@ function evaluateEditEvidence(inputArgs) {
         });
         escalate('widen');
     }
+    traceGapReason();
     // Lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal.
     const primary = reasons.find((r) => r.code === 'basis-drift')
         ?? reasons.find((r) => r.code === 'target-drift')

package/dist/holmes/guardrail/risk-classifier.d.ts

@@ -13,6 +13,7 @@ export declare function rmCommandTargets(cmd: string): string[];
  * project and stays protected, so nothing is weakened for the case the rule exists to cover. With no
  * projectRoot supplied the command is returned unchanged — unknown scope stays conservative.
  */
+export declare function normalizeWindowsPathSpellings(cmd: string): string;
 export declare function scopeAxToProject(cmd: string, projectRoot?: string): string;
 /**
  * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so

package/dist/holmes/guardrail/risk-classifier.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rmCommandTargets = rmCommandTargets;
+exports.normalizeWindowsPathSpellings = normalizeWindowsPathSpellings;
 exports.scopeAxToProject = scopeAxToProject;
 exports.normalizeCommandPaths = normalizeCommandPaths;
 exports.classifyReversibility = classifyReversibility;
@@ -248,11 +249,33 @@ const DESTRUCTIVE_CMD_CHECKS = [
  * project and stays protected, so nothing is weakened for the case the rule exists to cover. With no
  * projectRoot supplied the command is returned unchanged — unknown scope stays conservative.
  */
+// @implements A-SPEC-657 — Windows spellings (drive `C:/…`, `C:\…`, MSYS `/c/…`) of a path INSIDE
+// the project were masked as another project's, and the backslash spelling matched no `.ax/` rule at
+// all (measured on Windows 2026-09-17, reproduced on macOS 4/4). The five `.ax` rules below consume
+// the string this function hands them, so one normalisation closes every spelling at once. Pure
+// string logic: no process.platform, no filesystem — a POSIX suite verifies the Windows verdicts.
+function normalizeWindowsPathSpellings(cmd) {
+    return cmd
+        // `C:\a\b`, `C:/a/b` → `c:/a/b` — a drive is one letter, a colon and a separator, at a token
+        // boundary; `http://` and `a:b` never match.
+        .replace(/(^|[\s'"=(])([A-Za-z]):[\\/]([^\s'"()]*)/g, (_m, pre, d, rest) => `${pre}${d.toLowerCase()}:/${rest.replace(/\\/g, '/')}`)
+        // MSYS/Git-Bash `/c/a/b` → `c:/a/b`.
+        .replace(/(^|[\s'"=(])\/([A-Za-z])\/(?=[^\s'"()/])/g, (_m, pre, d) => `${pre}${d.toLowerCase()}:/`);
+}
 function scopeAxToProject(cmd, projectRoot) {
+    const spelled = normalizeWindowsPathSpellings(cmd);
     if (!projectRoot)
-        return cmd;
-    const root = projectRoot.replace(/\\/g, '/').replace(/\/+$/, '');
-    return cmd.replace(/(^|[\s'"=(:])(\/[^\s'"()]*\/\.ax\/[^\s'"()]*)/g, (m, pre, abs) => (abs === root || abs.startsWith(`${root}/`) ? m : `${pre}<other-project-path>`));
+        return spelled;
+    const root = normalizeWindowsPathSpellings(projectRoot.replace(/\\/g, '/')).replace(/\/+$/, '');
+    // NTFS folds case (foldsCaseBySyntax says the same of a drive letter); POSIX does not.
+    const drive = /^[a-z]:\//.test(root);
+    const inside = (abs) => {
+        const a = drive ? abs.toLowerCase() : abs;
+        const r = drive ? root.toLowerCase() : root;
+        return a === r || a.startsWith(`${r}/`);
+    };
+    // The pre-class no longer admits `:` — that is what cut `C:/proj/.ax/x` down to `/proj/.ax/x`.
+    return spelled.replace(/(^|[\s'"=(])((?:[a-z]:)?\/[^\s'"()]*\/\.ax\/[^\s'"()]*)/g, (m, pre, abs) => (inside(abs) ? m : `${pre}<other-project-path>`));
 }
 // `state` joined the protected set with P3 (REQ-134): it holds the constitution-debt and the
 // last-green baseline, so a single-file `rm` there would bypass the WRITE_CODE debt gate — measured

package/dist/holmes/guardrail/scope-judgment.d.ts

@@ -29,7 +29,18 @@ export declare function isTestPath(relPath: string): boolean;
  * one bounded fragment, so no ReDoS surface.
  */
 export declare function matchesFtt(token: string, relPath: string): boolean;
-/** Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none. */
+export declare function isRootFileToken(token: string): boolean;
+/**
+ * Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none.
+ *
+ * @implements A-SPEC-654
+ * The slashed match alone could not see a ROOT-level file, so a sealed spec listing `- jest.config.js`
+ * admitted nothing at all and its own anchored write was refused as out of scope (measured 2026-09-15 on
+ * Windows; A-SPEC-652.4 was redesigned around it). A bare filename counts only as a LIST ITEM's first
+ * word: `- \`tsconfig.test.json\` (신규)` is a token, while `\`cfg.ts\`, \`ddg.ts\` 를 고친다` — prose, and a
+ * word carrying a comma — stays what it always was, nothing. The enforcer is unchanged: a root token
+ * admits that exact path (`matchesFtt`), and the grader requires a directory-scoped token of its own.
+ */
 export declare function fttPathTokens(fttText: string): string[];
 export interface ScopeInput {
     relPath: string;

package/dist/holmes/guardrail/scope-judgment.js

@@ -25,6 +25,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTestPath = isTestPath;
 exports.matchesFtt = matchesFtt;
+exports.isRootFileToken = isRootFileToken;
 exports.fttPathTokens = fttPathTokens;
 exports.judgeScope = judgeScope;
 /** Repo test conventions — the single census every dispensation consumer shares. */
@@ -63,9 +64,37 @@ function matchesFtt(token, relPath) {
         return relPath === tok; // file literal: that file only
     return relPath === tok || relPath.startsWith(tok + '/'); // dir literal: its subtree
 }
-/** Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none. */
+/**
+ * @implements A-SPEC-654
+ * A repository-ROOT file named as a Files-to-Touch item: a bare filename with an extension that starts
+ * with a letter, so a version (`0.20.1`) is not a file and a bare word (`README`) is not either.
+ */
+const ROOT_FILE = /^[\w@.-]+\.[A-Za-z][A-Za-z0-9]*$/;
+function isRootFileToken(token) {
+    return !token.includes('/') && ROOT_FILE.test(token);
+}
+/**
+ * Concrete path-like tokens of a Files-to-Touch section (globs included) — prose yields none.
+ *
+ * @implements A-SPEC-654
+ * The slashed match alone could not see a ROOT-level file, so a sealed spec listing `- jest.config.js`
+ * admitted nothing at all and its own anchored write was refused as out of scope (measured 2026-09-15 on
+ * Windows; A-SPEC-652.4 was redesigned around it). A bare filename counts only as a LIST ITEM's first
+ * word: `- \`tsconfig.test.json\` (신규)` is a token, while `\`cfg.ts\`, \`ddg.ts\` 를 고친다` — prose, and a
+ * word carrying a comma — stays what it always was, nothing. The enforcer is unchanged: a root token
+ * admits that exact path (`matchesFtt`), and the grader requires a directory-scoped token of its own.
+ */
 function fttPathTokens(fttText) {
-    return fttText.match(/[\w@.*-]+(?:\/[\w@.*-]+)+/g) ?? [];
+    const tokens = [...(fttText.match(/[\w@.*-]+(?:\/[\w@.*-]+)+/g) ?? [])];
+    for (const line of fttText.split('\n')) {
+        const item = /^\s*[-*]\s+(.*)$/.exec(line);
+        if (!item)
+            continue;
+        const word = (item[1].trim().split(/\s+/)[0] ?? '').replace(/^[`'"]+|[`'"]+$/g, '');
+        if (isRootFileToken(word) && !tokens.includes(word))
+            tokens.push(word);
+    }
+    return tokens;
 }
 // @implements A-SPEC-508.1
 function judgeScope(input) {

package/dist/holmes/hooks/stop.d.ts

@@ -1,6 +1,8 @@
 import { PendingRequest } from '../governance/approval-queue';
 import { Spec } from '../spec/spec-parser';
 import type { TestOutcome } from '../review/test-runner';
+import { type KnownDefectJudgement } from '../rtm/known-defects';
+export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
 /**
  * @implements A-SPEC-100.2
  * Stop-hook governance gate (Phase-2 #1: push, not pull).
@@ -22,6 +24,13 @@ import type { TestOutcome } from '../review/test-runner';
 export interface StopEvidence {
     /** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
     testCasesByAspec?: Record<string, number>;
+    /**
+     * @implements A-SPEC-660
+     * `@known-defect` markers found in the workspace's test files, judged against the clock by the
+     * CLI: unexpired ones are DEBT (tracked, never blocking), expired and malformed ones are ART-9.
+     * `undefined` is no signal — a walk that could not run must not read as marker-free.
+     */
+    knownDefects?: KnownDefectJudgement;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

package/dist/holmes/hooks/stop.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
+exports.collectKnownDefects = collectKnownDefects;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
 exports.dependencyReappraisals = dependencyReappraisals;
@@ -76,6 +77,55 @@ const pre_tool_use_1 = require("./pre-tool-use");
 const governance_history_1 = require("../guardrail/governance-history");
 const constitution_debt_1 = require("../governance/constitution-debt");
 const root_1 = require("../project/root");
+const known_defects_1 = require("../rtm/known-defects");
+const test_files_1 = require("../cpg/test-files");
+// @implements A-SPEC-660 — the I/O half of the known-defect marker: walk the workspace's test files
+// (the same directory rule and test predicate ART-4's anchor scan uses), parse each for markers,
+// judge them against the injected clock. A walk that cannot START is NO SIGNAL (undefined) — never
+// an empty judgement; an unreadable file inside a readable tree is skipped like scanTestAnchors does.
+function collectKnownDefects(root, now) {
+    try {
+        if (!fs.statSync(root).isDirectory())
+            return undefined;
+        const found = { markers: [], malformed: [] };
+        const walk = (dir) => {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist' || e.name === '.ax')
+                    continue;
+                const abs = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    walk(abs);
+                    continue;
+                }
+                const rel = path.relative(root, abs).split(path.sep).join('/');
+                if (!(0, test_files_1.isTestFile)(rel))
+                    continue;
+                let text;
+                try {
+                    text = fs.readFileSync(abs, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                const r = (0, known_defects_1.knownDefectsIn)(text, rel);
+                found.markers.push(...r.markers);
+                found.malformed.push(...r.malformed);
+            }
+        };
+        walk(root);
+        return (0, known_defects_1.judgeKnownDefects)(found, now);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * @implements A-SPEC-534.4
  * ART-8 evidence (I/O half): the A-SPECs whose DIRTY source files carry an @implements anchor. git is
@@ -441,6 +491,7 @@ function governanceLostPreflight(specsDir, projectRoot) {
 const TRACK_LABELS = {
     'ART-8': 'RED-first',
     'ART-2': 'code-graph cycles',
+    'ART-9': 'known-defect debt',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -476,6 +527,8 @@ function evaluateStop(specs, evidence) {
         specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
         redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
         cycles: evidence?.cycles,
+        // @implements A-SPEC-660 — only the expired and unreadable markers are the constitution's business.
+        ...(evidence?.knownDefects ? { knownDefects: { expired: evidence.knownDefects.expired, malformed: evidence.knownDefects.malformed } } : {}),
     });
     // @implements A-SPEC-534.4 — `track` records ART-8 findings without blocking the turn. Computed
     // separately (the constitution stays silent on ART-8 outside strict) and returned in `tracked` for
@@ -497,6 +550,13 @@ function evaluateStop(specs, evidence) {
         if (t.length)
             tracked = [...(tracked ?? []), ...t];
     }
+    // @implements A-SPEC-660 — unexpired known-defect markers are DEBT: recorded on the tracked channel
+    // with file, line, reason and expiry, never a block. A bypass is sometimes the right call; the
+    // marker exists so the next person can see it, and ART-9 speaks only once the grace runs out.
+    if (evidence?.knownDefects && evidence.knownDefects.unexpired.length > 0) {
+        const t = evidence.knownDefects.unexpired.map((k) => ({ article: 'ART-9', detail: `${k.file}:${k.line}: known defect "${k.reason}" until ${k.expires}` }));
+        tracked = [...(tracked ?? []), ...t];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -1079,7 +1139,9 @@ if (require.main === module) {
                 });
             }
             catch { /* maintenance, never a hook failure */ }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec });
+            // @implements A-SPEC-660 — the marker walk: no signal when it cannot run (never a clean verdict).
+            const knownDefects = collectKnownDefects(stopProjectRoot(), new Date());
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

package/dist/holmes/mcp/handlers/graph-operations.d.ts

@@ -64,6 +64,7 @@ export declare function createGraphOperationsHandlers(context: GraphOperationsCo
             reason: "hub" | "depth";
             inDegree?: number;
         }[] | undefined;
+        traceGaps?: import("../../rtm/trace-gaps").TraceGap[] | undefined;
         summariesOmitted?: number | undefined;
         impacted: string[];
         impactedSummaries: {

package/dist/holmes/mcp/handlers/graph-operations.js

@@ -45,6 +45,7 @@ const root_1 = require("../../project/root");
 const rtm_builder_1 = require("../../rtm/rtm-builder");
 const graph_store_1 = require("../../rtm/graph-store");
 const assoc_arm_1 = require("../../assoc/assoc-arm");
+const trace_gaps_1 = require("../../rtm/trace-gaps");
 // @implements A-SPEC-478 — the semantic tier runtime stays at the async reindex edge.
 const tier_1 = require("../../semantic/tier");
 const vector_cache_1 = require("../../semantic/vector-cache");
@@ -119,7 +120,8 @@ function createGraphOperationsHandlers(context) {
             // drops outdated/legacy), which is exactly what let this in. Diagnosis (rtm_check) and
             // matching (issue_localize / maintenance_analyze) keep their own populations — the replay
             // pins were measured on them.
-            const specs = (await context.listSpecs()).filter((s) => s.status === 'approved');
+            const specsAll = await context.listSpecs();
+            const specs = specsAll.filter((s) => s.status === 'approved');
             // @implements A-SPEC-283
             // Reuse the persisted graph when its basis still holds. Measured: on the warm path the graph
             // build is ~81% of the cost and reopening is ~0ms. `scanDigest` is the field that makes this
@@ -181,11 +183,26 @@ function createGraphOperationsHandlers(context) {
                     return { id, summary };
                 });
                 const summariesOmitted = impacted.length - shownSummaries.length;
+                // @implements A-SPEC-658 — the specs the graph CANNOT see for these changes: approved,
+                // anchored by no production source, and declaring a changed symbol's file. Information
+                // beside the closure, never inside it; unresolved symbols yield no files and therefore no
+                // guess.
+                const changedFiles = a.changed.flatMap((qn) => g.codeNodeIds(qn))
+                    .map((id) => id.slice(id.lastIndexOf('@') + 1)).filter((f) => f !== '');
+                const gaps = changedFiles.length > 0
+                    ? (0, trace_gaps_1.traceGaps)(changedFiles, (0, trace_gaps_1.unlinkedApproved)(specsAll, scanned), (id) => { try {
+                        return g.summaryOf(id);
+                    }
+                    catch {
+                        return null;
+                    } })
+                    : [];
                 answered = true;
                 return {
                     impacted,
                     impactedSummaries,
                     ...(summariesOmitted > 0 ? { summariesOmitted } : {}),
+                    ...(gaps.length > 0 ? { traceGaps: gaps } : {}),
                     rankedImpact,
                     reachedByDepth,
                     bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,

package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts

@@ -1,8 +1,12 @@
+import type { Spec } from '../../spec/spec-parser';
+import type { ScannedFile } from '../../cpg/cpg-scanner';
 interface MaintenanceEvidenceContext {
     foreignRootReason(root: string): string | null;
     projectRootOf(root: string): string;
     refusal(reason: string): Error;
     fileDigestOf(root: string, relativePath: string): string | null;
+    listSpecs(): Promise<Spec[]>;
+    cachedScan(root: string): ScannedFile[];
 }
 /** Raw handlers: the public facade attaches basis exactly once. */
 export declare function createMaintenanceEvidenceHandlers(context: MaintenanceEvidenceContext): {

package/dist/holmes/mcp/handlers/maintenance-evidence.js

@@ -41,6 +41,7 @@ const node_child_process_1 = require("node:child_process");
 const maintenance_evidence_1 = require("../maintenance-evidence");
 const impact_gate_1 = require("../../guardrail/impact-gate");
 const root_1 = require("../../project/root");
+const trace_gaps_1 = require("../../rtm/trace-gaps");
 /** Raw handlers: the public facade attaches basis exactly once. */
 function createMaintenanceEvidenceHandlers(context) {
     return {
@@ -77,11 +78,25 @@ function createMaintenanceEvidenceHandlers(context) {
                     throw context.refusal(`이 프로젝트에 저장된 분석이 아닙니다: ${a.digest}`);
                 artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
             }
+            const target = a.target.replace(/\\/g, '/');
+            // @implements A-SPEC-658 — approved specs that declare this file but anchor nothing: the graph
+            // cannot see them, so the gate must not read their silence as "no impact". A failed lookup
+            // drops the input (information lost, verdict unchanged) rather than inventing a gap.
+            let gaps;
+            try {
+                const found = (0, trace_gaps_1.traceGaps)([target], (0, trace_gaps_1.unlinkedApproved)(await context.listSpecs(), context.cachedScan(root)));
+                if (found.length > 0)
+                    gaps = found.map(({ id, file }) => ({ id, file }));
+            }
+            catch {
+                gaps = undefined;
+            }
             return (0, impact_gate_1.evaluateEditEvidence)({
-                target: a.target.replace(/\\/g, '/'),
+                target,
                 artifact,
                 currentHead: head,
                 currentTargetDigest: context.fileDigestOf(root, a.target),
+                ...(gaps ? { traceGaps: gaps } : {}),
             });
         },
         // @implements A-SPEC-268