@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/rtm/test-scope.js

@@ -0,0 +1,336 @@
+"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.SUPPORTED_TEST_FRAMEWORKS = void 0;
+exports.accountChangedFiles = accountChangedFiles;
+exports.countTestCases = countTestCases;
+exports.extractAnchors = extractAnchors;
+exports.scanTestAnchors = scanTestAnchors;
+exports.computeTestScope = computeTestScope;
+// @implements A-SPEC-121.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const rtm_check_1 = require("./rtm-check");
+const DEFAULTS = { partialBlast: 3, fullBlast: 12 };
+const stripSpecPrefix = (id) => (id.startsWith('SPEC:') ? id.slice('SPEC:'.length) : id);
+// "Is this a test file?" must be ONE predicate. Two copies had already drifted: the scanner excluded
+// JVM/.NET/Rust/C++ conventions from the production graph while this side still only recognized
+// TS/JS, Python `test_*` and Go — so those languages' tests were in neither set, contributing no
+// evidence while also not being production. The shared table also keeps the original constraint that
+// a test file must be CODE (adversarial finding: `.spec.md` prose was accepted and its English
+// "it (" counted as evidence), since every pattern in it ends in a code extension.
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+function accountChangedFiles(changedFiles, scanEntry) {
+    const anchorImpacted = new Set();
+    const changedTestFiles = [];
+    const unresolvedFiles = [];
+    for (const rel of changedFiles) {
+        if (rel.startsWith('.ax/'))
+            continue; // governance/derived state, never source
+        if ((0, cpg_scanner_1.isTestFile)(rel)) {
+            changedTestFiles.push(rel);
+            continue;
+        } // lane 3
+        if (!cpg_scanner_1.SCANNABLE_EXTENSIONS.some((ext) => rel.endsWith(ext)))
+            continue; // docs/config: no lane needed
+        const entry = scanEntry(rel);
+        if (entry && entry.symbolCount > 0)
+            continue; // lane 1 owns it
+        if (entry && entry.implementsSpecs.length > 0) { // lane 2
+            for (const id of entry.implementsSpecs)
+                anchorImpacted.add(id);
+            continue;
+        }
+        unresolvedFiles.push(rel); // no lane — including never-scanned
+    }
+    return {
+        anchorImpactedSpecs: [...anchorImpacted].sort(),
+        changedTestFiles: changedTestFiles.sort(),
+        unresolvedFiles: unresolvedFiles.sort(),
+    };
+}
+/**
+ * Count EXECUTABLE test cases in test-file source (H1/ART-4 evidence). Adversarial review proved a
+ * naive /\bit\(/ count is sham-able: commented-out `// it(`, string literals `'it(here)'`, and prose
+ * all counted, while real `it.each(...)('…')` did not. This strips comments and string/template
+ * literals FIRST, then counts `it|test|fit` heads including the `.each(...)(` form, and excludes
+ * `.skip`/`.todo`/`xit`/`xtest` (never execute), and a leading-`.` lookbehind excludes METHOD calls
+ * (`regex.test('x')` is not a test case — adversarial finding: 30 fake cases in 30 `R.test()` lines).
+ *
+ * Files containing ANY suite-skip construct (`describe.skip`, `xdescribe`, `describe[...]`) forfeit
+ * their evidence entirely (count 0). A balanced-paren strip proved gameable in the OVER direction (an
+ * extra `)` inside the skipped body — e.g. a regex literal — terminated the strip early and revived
+ * the sham), so the conservative rule is total: skip markers ⇒ no credit. Fewer counted cases can
+ * only make the gate stricter, never falsely satisfied.
+ *
+ * HONEST SCOPE: this is a syntactic LOWER-BOUND evidence counter, not execution proof — `if(false)`
+ * wrappers or aliasing can still fabricate heads. Execution proof is the test RUNNER's job
+ * (planTestRun/runTestScope); this counter only stops declared coverage over an absent/empty suite.
+ */
+/** Strip block/line comments and string literals from C-family source. */
+const stripCFamily = (src) => src
+    .replace(/\/\*[\s\S]*?\*\//g, ' ') // block comments
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1 ') // line comments (not ://)
+    .replace(/'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`/g, '""');
+/** Strip `#` comments, docstrings and string literals from Python source. */
+const stripPython = (src) => src
+    .replace(/'''[\s\S]*?'''|"""[\s\S]*?"""/g, '""') // docstrings first — they may contain #
+    .replace(/(^|[^\\])#[^\n]*/g, '$1 ')
+    .replace(/'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"/g, '""');
+/**
+ * One rule per test framework. Before this table, every non-JS framework counted ZERO — measured:
+ * pytest 3 cases -> 0, JUnit 2 -> 0, xUnit 2 -> 0, cargo 2 -> 0, gtest 3 -> 0, go test 2 -> 0. That
+ * is not a cosmetic gap: ART-4's syntactic baseline reads this number, so every anchored A-SPEC in a
+ * non-JS project looked like it had no tests, and the Stop gate would flag a violation forever.
+ *
+ * Every rule preserves the invariant this counter was built around: it is a sham-resistant LOWER
+ * BOUND. Under-counting only makes the gate stricter; over-counting would let declared coverage sit
+ * on an absent suite. That is why per-case skips are SUBTRACTED rather than attributed — subtracting
+ * an unrelated marker errs toward fewer cases, which is the safe direction.
+ */
+const FRAMEWORKS = [
+    {
+        id: 'jest',
+        ext: /\.(ts|mts|cts|tsx|jsx|js|mjs|cjs)$/i,
+        strip: stripCFamily,
+        suiteSkip: /\bdescribe\s*(?:\.\s*skip|\[\s*['"]skip['"]\s*\])|\bxdescribe\b/,
+        // Head must be a STANDALONE identifier (not `.test(`/`.it(` method calls) followed directly by
+        // `(` or by `.each(...)(`: `it.skip(`/`it.todo(`/`xit(` never match — no subtraction needed.
+        head: /(?<![.\w])(?:it|test|fit)(?:\s*\.\s*each\s*\([^)]*\)\s*)?\s*\(/g,
+    },
+    {
+        id: 'pytest',
+        ext: /\.py$/i,
+        strip: stripPython,
+        // Module-level `pytestmark = pytest.mark.skip` disables the whole file, the direct analogue of
+        // `describe.skip`.
+        suiteSkip: /^\s*pytestmark\s*=\s*[^\n]*\bskip/m,
+        head: /^[ \t]*(?:async[ \t]+)?def[ \t]+test_?\w*[ \t]*\(/gm,
+        caseSkip: /@\s*(?:pytest\.mark\.skip\w*|unittest\.skip\w*)\b/g,
+    },
+    {
+        id: 'junit',
+        ext: /\.java$/i,
+        strip: stripCFamily,
+        // A class-level @Disabled/@Ignore sits above the class declaration — but real code stacks
+        // annotations (`@Disabled("wip")` then `@ExtendWith(...)` then the class), so intervening
+        // annotation lines must be allowed. Requiring adjacency missed exactly that, and the per-case
+        // subtraction masked it by coincidentally landing on 1 instead of 0.
+        suiteSkip: /@\s*(?:Disabled|Ignore)\b[^\n]*\n(?:\s*@\w[^\n]*\n)*\s*(?:public\s+|final\s+|abstract\s+|static\s+)*class\b/,
+        head: /@\s*(?:Test|ParameterizedTest|RepeatedTest|TestFactory|TestTemplate)\b/g,
+        caseSkip: /@\s*(?:Disabled|Ignore)\b/g,
+    },
+    {
+        id: 'dotnet',
+        ext: /\.cs$/i,
+        strip: stripCFamily,
+        // NUnit/MSTest disable a whole fixture with a class-level [Ignore]. Attribute lines stack the
+        // same way Java's annotations do (`[Ignore("wip")]` then `[TestFixture]` then the class).
+        suiteSkip: /\[\s*Ignore[^\]]*\][^\n]*\n(?:\s*\[[^\n]*\n)*\s*(?:public\s+|internal\s+|sealed\s+|partial\s+|abstract\s+|static\s+)*class\b/,
+        head: /\[\s*(?:Fact|Theory|Test|TestCase|TestMethod|DataTestMethod)\b/g,
+        // xUnit disables a single case with `[Fact(Skip = "…")]`; NUnit/MSTest use [Ignore].
+        caseSkip: /\[\s*Ignore\b|\bSkip\s*=\s*""/g,
+    },
+    {
+        id: 'cargo',
+        ext: /\.rs$/i,
+        strip: stripCFamily,
+        // `#![ignore]`-style inner attributes are not a thing for tests; a Rust file has no true
+        // suite-level skip, so nothing forfeits the file. Kept explicit rather than omitted.
+        suiteSkip: /(?!)/,
+        head: /#\s*\[\s*(?:\w+\s*::\s*)?test\s*\]/g,
+        caseSkip: /#\s*\[\s*ignore\b/g,
+    },
+    {
+        id: 'gtest',
+        ext: /\.(cpp|cc|cxx|hpp|hh|h)$/i,
+        strip: stripCFamily,
+        suiteSkip: /(?!)/,
+        head: /\b(?:TYPED_)?TEST(?:_F|_P|_CASE)?\s*\(/g,
+        // gtest disables by prefixing the suite or the case name with DISABLED_.
+        caseSkip: /\b(?:TYPED_)?TEST\w*\s*\(\s*(?:DISABLED_\w*|\w+\s*,\s*DISABLED_\w*)/g,
+    },
+    {
+        id: 'gotest',
+        ext: /\.go$/i,
+        strip: stripCFamily,
+        suiteSkip: /(?!)/,
+        // Requiring the *testing.T parameter is what separates a real test from a `TestHelper` helper.
+        head: /\bfunc\s+(?:Test|Fuzz)\w*\s*\(\s*\w+\s+\*testing\.[TF]\s*\)/g,
+        caseSkip: /\bt\s*\.\s*Skip(?:Now|f)?\s*\(/g,
+    },
+];
+const ruleFor = (filePath) => (filePath && FRAMEWORKS.find((f) => f.ext.test(filePath))) || FRAMEWORKS[0];
+/** Frameworks this counter understands, for diagnostics and tests. */
+exports.SUPPORTED_TEST_FRAMEWORKS = FRAMEWORKS.map((f) => f.id);
+function countTestCases(source, filePath) {
+    const rule = ruleFor(filePath);
+    const stripped = rule.strip(source);
+    // Suite-skip detection runs on the ORIGINAL source: string-stripping turns `describe['skip'](`
+    // into `describe[""](`, hiding the marker (round-2 test caught this). Comments are already
+    // irrelevant here — a commented-out skip marker only makes the counter stricter (forfeits), which
+    // is the safe direction for an evidence counter.
+    if (rule.suiteSkip.test(source))
+        return 0;
+    const heads = stripped.match(rule.head) ?? [];
+    const skips = rule.caseSkip ? (stripped.match(rule.caseSkip) ?? []).length : 0;
+    return Math.max(0, heads.length - skips);
+}
+// An anchor must be a STANDALONE COMMENT LINE, and string/template literals are removed first
+// (adversarial review C2: a raw whole-file match credited a test file's entire executed count to
+// every id merely MENTIONED in it — a live run credited 50 cases to the nonexistent A-SPEC-999 from
+// a fixture string, and injecting one comment into any test file re-credited it to an arbitrary
+// spec). Both the fixture-string and the mid-code-line injection vectors die here.
+const IMPL_LINE_RE = /^[ \t]*(?:\/\/|\/\*|\*|#)[^\n]*?@implements\s+(A-SPEC-\d{3,}(?:\.\d+)?)/gm;
+const STRINGS_RE = /'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`/g;
+/** A-SPEC ids anchored by a file, counting only standalone comment-line markers outside literals. */
+function extractAnchors(source) {
+    const noStrings = source.replace(STRINGS_RE, '""');
+    return [...new Set([...noStrings.matchAll(IMPL_LINE_RE)].map((m) => m[1]))];
+}
+/**
+ * Scan the repo for TEST files and the A-SPEC ids they @implement. Separate from the CPG scan (which
+ * excludes tests), so the test↔spec edges actually exist for scoping. Returns repo-relative POSIX
+ * paths → the impacted-spec ids they anchor. Pure-ish (fs read only); resilient to unreadable files.
+ */
+function scanTestAnchors(root) {
+    const out = {};
+    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')
+                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, cpg_scanner_1.isTestFile)(rel))
+                continue;
+            let text;
+            try {
+                text = fs.readFileSync(abs, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const ids = extractAnchors(text);
+            if (ids.length)
+                out[rel] = ids;
+        }
+    };
+    walk(root);
+    return out;
+}
+function computeTestScope(impactedSpecsRaw, testAnchors, specs, coverageGaps = [], cfg, extras) {
+    const t = { ...DEFAULTS, ...(cfg ?? {}) };
+    const impactedSpecs = [...new Set(impactedSpecsRaw.map(stripSpecPrefix))].sort();
+    const impacted = new Set(impactedSpecs);
+    const changedTestFiles = [...new Set(extras?.changedTestFiles ?? [])].sort();
+    const unresolvedFiles = [...new Set(extras?.unresolvedFiles ?? [])].sort();
+    const impactedTestFiles = Object.entries(testAnchors)
+        .filter(([, ids]) => ids.some((a) => impacted.has(a)))
+        .map(([file]) => file)
+        .sort();
+    // Lane-3 (A-SPEC-130): a changed test file IS the regression scope for its own change — the symbol
+    // scan excludes it by design, so it enters at the selection, not the graph.
+    const selectedTestFiles = [...new Set([...impactedTestFiles, ...changedTestFiles])].sort();
+    // @implements A-SPEC-130
+    // Unresolved remainder: changed source the graph cannot see. "Zero impact" derived from an
+    // incomplete graph is not evidence of no impact — same epistemic state as C3 below, same answer.
+    // Checked FIRST so a contradictory input (empty impact + unresolved present) resolves toward
+    // full, never toward "nothing to re-test".
+    if (unresolvedFiles.length > 0) {
+        const shown = unresolvedFiles.slice(0, 5).join(', ');
+        const suffix = unresolvedFiles.length > 5 ? ` (${unresolvedFiles.length} unresolved total)` : '';
+        return {
+            tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
+            hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles,
+            reason: `${unresolvedFiles.length} changed source file(s) resolved to no spec — cannot narrow safely, full regression: ${shown}${suffix}`,
+        };
+    }
+    // Tier on the DIRECTLY-impacted A-SPECs (what the changed code implements), NOT the whole impacted
+    // set — impactedBy always returns the ancestor chain up to the REQ root, so keying on it made every
+    // change "reach a foundational REQ" → always full (verification H4). Downstream blast of the direct
+    // A-SPEC(s) is the real breadth signal; only a change that DIRECTLY touches a REQ/H-SPEC (no direct
+    // A-SPEC in the set) falls back to the whole set (where a foundational hit legitimately means full).
+    const byId = new Map(specs.map((s) => [s.id, s]));
+    const directSpecs = impactedSpecs.filter((id) => byId.get(id)?.type === 'A-SPEC');
+    const tierSpecs = directSpecs.length > 0 ? directSpecs : impactedSpecs;
+    let blastRadius = 0;
+    let hitsFoundational = false;
+    for (const id of tierSpecs) {
+        const br = (0, rtm_check_1.computeBlastRadius)(specs, id); // bare ids now — C1
+        blastRadius = Math.max(blastRadius, br.impactedSpecCount);
+        hitsFoundational = hitsFoundational || br.hitsFoundational;
+    }
+    let tier;
+    let reason;
+    if (impactedSpecs.length === 0) {
+        tier = 'unit';
+        // Lane-3 keeps this branch honest: with a changed test file in hand, "nothing to re-test" would
+        // be false — the changed test itself is the scope (A-SPEC-130).
+        reason = changedTestFiles.length > 0
+            ? `no impacted specs — running ${changedTestFiles.length} changed test file(s)`
+            : 'no impacted specs — nothing to re-test';
+    }
+    else if (hitsFoundational || blastRadius >= t.fullBlast || coverageGaps.length > 0) {
+        tier = 'full';
+        reason = hitsFoundational ? 'reaches a foundational REQ — full regression'
+            : coverageGaps.length > 0 ? `impacted specs with coverage gaps (${coverageGaps.length}) — full regression`
+                : `wide downstream blast (${blastRadius}) — full regression`;
+    }
+    else if (impactedTestFiles.length === 0) {
+        // SAFETY (C3): impacted specs but no anchored tests resolved → cannot prove a narrow run is safe.
+        tier = 'full';
+        reason = 'impacted specs but no anchored tests resolved — cannot narrow safely, full regression';
+    }
+    else if (blastRadius >= t.partialBlast) {
+        tier = 'partial';
+        reason = `moderate downstream blast (${blastRadius}) — impacted tests + margin`;
+    }
+    else {
+        tier = 'unit';
+        reason = `localized impact (blast=${blastRadius}) — run the ${impactedTestFiles.length} impacted test file(s)`;
+    }
+    return { tier, impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius, hitsFoundational, coverageGaps: [...coverageGaps], reason, unresolvedFiles: [] };
+}

package/dist/holmes/spec/approval-blockers.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockerClause = exports.BLOCKER_SEP = exports.unsealedParentMessage = exports.placeholderMessage = exports.SUPPLIED_BY_APPROVAL = void 0;
+exports.placeholderSections = placeholderSections;
+exports.parentBlockers = parentBlockers;
+exports.approvalBlockers = approvalBlockers;
+exports.blockerSummary = blockerSummary;
+const validator_1 = require("./validator");
+const breaking_change_1 = require("./breaking-change");
+const spec_digest_1 = require("./spec-digest");
+const spec_types_1 = require("./spec-types");
+const draft_1 = require("../reverse/draft");
+/**
+ * What stands between a spec and its approval — computed once, consumed by both the gate and the
+ * act of approving.
+ *
+ * The defect this exists for, measured over 244 governed benchmark runs on 2026-08-13: the gate
+ * refused 425 times across 99 distinct wordings, and every one of them stopped at "not approved".
+ * The reason was already computable — `spec_approve` derives it from the same specs moments later.
+ * Authors who could not see it went looking: 8.5 shell calls per run groping through `.ax/`,
+ * correlating with total token spend at r=0.71. Runs that never finished the chain burned 48% of all
+ * tokens and scored worse than the ones that did (76% vs 96%).
+ *
+ * SHARED, NOT COPIED — and adversarial review found the first version sharing only the leaves while
+ * the COMPOSITION stayed duplicated: the parent checks lived solely in `spec_approve`, so the gate
+ * reported "nothing blocks" for a draft under a draft parent, which is the modal state of top-down
+ * authoring. Every predicate that can refuse an approval now lives here, and `spec_approve` calls in
+ * rather than restating.
+ */
+/** A fence delimiter: three or more backticks or tildes, optionally indented. */
+const FENCE = /^(\s*)(`{3,}|~{3,})(.*)$/;
+/**
+ * Drop fenced blocks before judging a section.
+ *
+ * `parseSpec`'s splitter is fence-aware; this judge was not, so a section that merely QUOTED a
+ * generator's output was read as being one — review demonstrated it on A-SPEC-182's own Behavior
+ * section, which documents exactly that shape.
+ *
+ * MATCHES THE OPENER, per CommonMark: a fence closes only on the same character with a run at least
+ * as long, and a closer carries no info string. Two earlier versions were wrong in opposite
+ * directions and review caught both:
+ *  - a regex over the whole body knew only backticks, so a `~~~` quote was refused forever;
+ *  - a naive line toggle flipped on ANY fence line, so a 3-backtick example nested in a 4-backtick
+ *    block re-opened mid-quote (false refusal), and an UNTERMINATED opener swallowed the rest of the
+ *    section — failing OPEN, sealing the very stub this rule exists to catch.
+ * An opener with no closer is therefore treated as ordinary prose: the safe direction is to judge
+ * text we are unsure about, not to skip it.
+ */
+const stripFences = (s) => {
+    const lines = s.split('\n');
+    const drop = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const open = FENCE.exec(lines[i]);
+        if (!open || drop.has(i))
+            continue;
+        const [, , marker] = open;
+        let close = -1;
+        for (let j = i + 1; j < lines.length; j++) {
+            const c = FENCE.exec(lines[j]);
+            // A closer is the same character, at least as long, and nothing else on the line.
+            if (c && c[2][0] === marker[0] && c[2].length >= marker.length && c[3].trim() === '') {
+                close = j;
+                break;
+            }
+        }
+        if (close === -1)
+            continue; // unterminated: not a fence, judge it as prose
+        for (let k = i; k <= close; k++)
+            drop.add(k);
+        i = close;
+    }
+    return lines.filter((_, i) => !drop.has(i)).join('\n');
+};
+/**
+ * A line that is itself a generator's prompt. Anchored per-line, not to the start of the section:
+ * `reverse_draft` opens Intent, Objective and Normal Cases with its REVERSE-ENGINEERED note, so the
+ * prompt is the third line there. Measured against the real brownfield H-SPEC-100 — a
+ * section-anchored rule refused four of its sections and let Intent through, the one section whose
+ * emptiness matters most.
+ */
+const TODO_LINE = /^TODO\s*[—-]/m;
+/**
+ * Sections that still hold nothing but a generated placeholder.
+ *
+ * Two generators plant placeholders and both are judged here:
+ *  - `reverse_draft` writes `TODO — <prompt>` plus the INFERRED marker comment. Both are
+ *    required together: 11 of this repository's 257 approved specs use the word "TODO" in
+ *    legitimate prose ("남아 있는 TODO 주석을 제거한다"), and a word search refuses every one.
+ *  - `spec_create` writes the bare literal `TODO` (`FIELD_PLACEHOLDER`) into each required section.
+ *    That one is unambiguous on its own — an entire section equal to the string is never prose.
+ */
+function placeholderSections(spec) {
+    const out = [];
+    for (const [name, body] of Object.entries(spec.sections ?? {})) {
+        const text = String(body ?? '').trim();
+        if (text === spec_types_1.FIELD_PLACEHOLDER) {
+            out.push(name);
+            continue;
+        }
+        const prose = stripFences(text);
+        if (TODO_LINE.test(prose) && prose.includes(draft_1.INFERRED))
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * Codes that `validateSpec` reports but approval itself supplies, so they are not blockers.
+ * Exported because `spec_approve` filters by the same set — two hand-maintained lists were how the
+ * gate and the act drifted apart in the first place.
+ */
+exports.SUPPLIED_BY_APPROVAL = new Set(['unsealed-approval', 'stale-parent']);
+/**
+ * Parent-chain reasons an approval is refused.
+ *
+ * `validateSpec` deliberately stays silent on both (it `continue`s past a draft or unsealed parent —
+ * "other findings' business"), so nothing else computes these. Shared with `spec_approve` so the
+ * wording cannot drift.
+ */
+/** The one wording for a spec whose prose is still a generator stub. Shared for the same reason. */
+const placeholderMessage = (sections) => `자리표시자만 남은 절(${sections.join(', ')})이 있습니다 — 승인은 서술을 규범으로 만든다. 채운 뒤 다시 승인하라.`;
+exports.placeholderMessage = placeholderMessage;
+/** The one wording for an unsealed parent. Shared so a second, degraded copy cannot appear. */
+const unsealedParentMessage = (pid) => `parent ${pid} is approved but unsealed — seal parents first (spec_approve ${pid})`;
+exports.unsealedParentMessage = unsealedParentMessage;
+function parentBlockers(spec, resolve) {
+    const out = [];
+    for (const pid of spec.dependsOn ?? []) {
+        const parent = resolve(pid);
+        if (!parent)
+            continue; // dangling parents are validateSpec's finding
+        if (parent.status !== 'approved') {
+            out.push(`상위 스펙 ${parent.id}이(가) approved가 아닙니다(현재 ${parent.status})`
+                + ' — 자식은 승인되지 않은 부모 아래에서 승인될 수 없습니다. 부모를 먼저 승인하세요.');
+        }
+        else if (!(0, spec_digest_1.sealOf)(parent).approvedDigest) {
+            out.push((0, exports.unsealedParentMessage)(pid));
+        }
+    }
+    return out;
+}
+/**
+ * Every reason `spec` cannot be approved right now. Empty means nothing is in the way.
+ *
+ * Order matches `spec_approve`'s: parents, then static validity, then the declaration duty, then
+ * placeholders. Pure — it reads the spec objects it is handed and touches no filesystem, because
+ * the gate calls it from a PreToolUse hook on every tool call.
+ */
+function approvalBlockers(spec, resolve) {
+    const out = parentBlockers(spec, resolve);
+    // Validate AS IT WILL BE — approved. Approving is what supplies the status and the seals, so the
+    // question is what would still block THIS document once approved.
+    const candidate = { ...spec, status: 'approved', frontmatter: { ...spec.frontmatter } };
+    delete candidate.frontmatter.approved_digest;
+    delete candidate.frontmatter.parent_digests;
+    out.push(...(0, validator_1.validateSpec)(candidate, resolve).findings
+        .filter((f) => f.level === 'error' && !exports.SUPPLIED_BY_APPROVAL.has(f.code))
+        .map((f) => f.message));
+    const breaking = (0, breaking_change_1.checkBreakingChangeDeclared)(candidate);
+    if (breaking)
+        out.push(breaking);
+    const stubs = placeholderSections(spec);
+    if (stubs.length > 0) {
+        out.push((0, exports.placeholderMessage)(stubs));
+    }
+    return out;
+}
+/** The separator between one spec's blockers. Shared so nothing re-splits on a guessed delimiter. */
+exports.BLOCKER_SEP = '; ';
+/**
+ * One spec's blockers as a labelled clause.
+ *
+ * Exported so a caller that needs to CLAMP the list works on real blocker boundaries. Review found
+ * `tspec-state` re-splitting the joined string on `; ` — a delimiter that also occurs inside
+ * author-controlled text (a `depends_on` entry, a section name), which produced a sliced spec id
+ * with an unterminated quote and a remainder counting fragments rather than blockers.
+ */
+const blockerClause = (label, blockers) => ` [${label}] 승인까지 남은 것: ${blockers.join(exports.BLOCKER_SEP)}`;
+exports.blockerClause = blockerClause;
+/**
+ * The blockers as one line for a refusal message, or `null` when nothing blocks.
+ *
+ * `specId` labels the list. A refusal can name several specs at once, and review found the
+ * unlabelled form reintroduced exactly what REQ-155 forbids: the reader saw two reason-lists run
+ * together with no way to tell which spec each belonged to.
+ *
+ * Blockers are separated by `; ` rather than ` / ` because section names legitimately contain a
+ * slash (`Inputs / Outputs`), which made the boundaries unreadable.
+ *
+ * Never throws: a refusal that says less is recoverable, a hook that dies is not.
+ */
+function blockerSummary(spec, resolve, specId) {
+    if (!spec)
+        return null;
+    try {
+        const b = approvalBlockers(spec, resolve);
+        if (b.length === 0)
+            return null;
+        const label = specId ?? spec.id;
+        return (0, exports.blockerClause)(label, b);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/holmes/spec/breaking-change.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BREAKING_CHANGE_GRADES = void 0;
+exports.checkBreakingChangeDeclared = checkBreakingChangeDeclared;
+exports.breakingChangeDistribution = breakingChangeDistribution;
+/**
+ * ADR-013's enforcement device: the obligation to declare a breaking change lives on the ACT of
+ * approval, not on the document's static validity.
+ *
+ * WHY here and not in `validateSpec`'s `requiredFields`, measured rather than argued: all 38 governed
+ * A-SPECs in this repository are already approved, so adding the field to the state predicate
+ * produced **38 ART-3 violations and `evaluateStop().block === true`** — the harness would have
+ * blocked every turn, bricked by the very work meant to strengthen its governance.
+ *
+ * The move is not a workaround, it is the correct reading. "Is this change breaking?" is not a static
+ * property a document either has or lacks; it is a question that must be answered at the moment a
+ * change is sealed. Re-sealing means the content changed, which is exactly when the question is due.
+ *
+ * CONVERGENCE: any spec that changes must be re-approved and therefore acquires the field. A spec
+ * that never changes never acquires it — and cannot introduce a breaking change either. That is why
+ * no backfill is needed, and why mechanically filling 38 documents with `none` would be the very
+ * formulaic answer this device exists to discourage.
+ *
+ * REMOVAL AFTER APPROVAL is not defended here on purpose: deleting the field changes the body, the
+ * `approved_digest` stops matching, and the existing seal machinery reports `post-approval-edit`.
+ * Adding a second mechanism for a case the first already covers would be duplication, not depth.
+ */
+/** ADR-013's four tiers, plus `none`. Order is the order the denial message lists them in. */
+exports.BREAKING_CHANGE_GRADES = [
+    'none',
+    'persisted-artifact',
+    'derived-artifact',
+    'code-interface',
+    'gate-behavior',
+];
+const GRADES = new Set(exports.BREAKING_CHANGE_GRADES);
+/** Splits `grade` or `grade: reason` without discarding a reason that itself contains a colon. */
+function parse(value) {
+    const i = value.indexOf(':');
+    return i === -1
+        ? { grade: value.trim(), reason: '' }
+        : { grade: value.slice(0, i).trim(), reason: value.slice(i + 1).trim() };
+}
+/**
+ * `null` when the spec satisfies ADR-013's declaration duty, otherwise the reason it does not.
+ *
+ * Only A-SPEC is checked: it is the layer that carries the implementation contract (`Files to
+ * Touch`), so it is the layer where a change becomes breaking. Widening this to every spec type
+ * would collect answers from documents that touch no artefact.
+ */
+function checkBreakingChangeDeclared(spec) {
+    if (spec.type !== 'A-SPEC')
+        return null;
+    const raw = spec.frontmatter?.breaking_change;
+    // The denial names ADR-013 and lists the grades: a refusal that does not say what to do next is an
+    // obstacle rather than a gate.
+    const help = `허용 값: ${exports.BREAKING_CHANGE_GRADES.join(' | ')} (none 외에는 "<등급>: <사유>" 형태). 근거: ADR-013.`;
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        return `A-SPEC ${spec.id}에 breaking_change 선언이 없습니다 — 파괴적 변경 여부를 답하지 않고는 승인할 수 없습니다. ${help}`;
+    }
+    const { grade, reason } = parse(raw);
+    if (!GRADES.has(grade)) {
+        return `A-SPEC ${spec.id}의 breaking_change 등급 "${grade}"은(는) 허용되지 않습니다. ${help}`;
+    }
+    // A grade with no reason is a label, not a declaration — the reader learns that something broke
+    // but not what, which is the part that would have helped them.
+    if (grade !== 'none' && reason === '') {
+        return `A-SPEC ${spec.id}의 breaking_change가 "${grade}"인데 사유가 없습니다 — 등급만으로는 무엇이 깨지는지 알 수 없습니다. ${help}`;
+    }
+    return null;
+}
+/**
+ * Grade counts across the governed A-SPECs, with `(unset)` for those that have not been re-approved
+ * since ADR-013. A REPORT, never an assertion: "all `none` must fail" would fire falsely during a
+ * period when every change genuinely is non-breaking. ADR-013 recorded formulaic-`none` as a revisit
+ * trigger for a human to judge, and this surfaces the distribution that judgement needs — including
+ * how far the corpus has converged.
+ */
+function breakingChangeDistribution(specs) {
+    const out = {};
+    for (const s of specs) {
+        if (s.type !== 'A-SPEC')
+            continue;
+        const raw = s.frontmatter?.breaking_change;
+        const key = typeof raw === 'string' && raw.trim() !== '' ? parse(raw).grade : '(unset)';
+        out[key] = (out[key] ?? 0) + 1;
+    }
+    return out;
+}