@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/governance/trust-score.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeTrustScore = computeTrustScore;
+function computeTrustScore(m) {
+    // Malformed metrics fail SAFE to observe-only — trust must never be granted on unreadable data.
+    const nums = [m.slicesCompleted, m.suiteGreenRate, m.guardrailDenials, m.faults, m.regressions, m.criticalFindings];
+    if (nums.some((n) => typeof n !== 'number' || Number.isNaN(n) || n < 0) || m.suiteGreenRate > 1) {
+        return { score: 0, level: 'L0', rationale: 'malformed metrics — trust cannot be assessed (fail-safe to observe-only)' };
+    }
+    // Base: earned by volume of green work, saturating (12 slices ≈ full credit), scaled by green rate.
+    const earned = Math.min(1, m.slicesCompleted / 12) * m.suiteGreenRate;
+    // Penalties: multiplicative decay — each incident class independently shrinks trust.
+    const penalty = Math.pow(0.5, m.faults) *
+        Math.pow(0.6, m.regressions) *
+        Math.pow(0.7, m.criticalFindings) *
+        Math.pow(0.9, m.guardrailDenials);
+    const score = Math.round(earned * penalty * 1000) / 1000;
+    // Level from score, with HARD CAPS: fresh faults/regressions cap at L1; criticals cap at L2.
+    let level = score >= 0.85 ? 'L4' : score >= 0.65 ? 'L3' : score >= 0.35 ? 'L2' : score >= 0.15 ? 'L1' : 'L0';
+    if (m.faults > 0 || m.regressions > 0)
+        level = capLevel(level, 'L1');
+    else if (m.criticalFindings > 0)
+        level = capLevel(level, 'L2');
+    if (m.slicesCompleted === 0)
+        level = capLevel(level, 'L2'); // no track record -> never above default-gated
+    return { score, level, rationale: rationaleFor(m, score, level) };
+}
+const ORDER = ['L0', 'L1', 'L2', 'L3', 'L4'];
+function capLevel(l, cap) {
+    return ORDER.indexOf(l) > ORDER.indexOf(cap) ? cap : l;
+}
+function rationaleFor(m, score, level) {
+    const parts = [`score=${score}`, `slices=${m.slicesCompleted}`, `green=${m.suiteGreenRate}`];
+    if (m.faults)
+        parts.push(`faults=${m.faults} (caps L1)`);
+    if (m.regressions)
+        parts.push(`regressions=${m.regressions} (caps L1)`);
+    if (m.criticalFindings)
+        parts.push(`criticals=${m.criticalFindings} (caps L2)`);
+    if (m.guardrailDenials)
+        parts.push(`denials=${m.guardrailDenials}`);
+    return `${level}: ${parts.join(', ')} — hard-hitl always gates regardless of level`;
+}

package/dist/holmes/guardrail/anchors.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimedAnchors = claimedAnchors;
+exports.newlyClaimed = newlyClaimed;
+// @implements A-SPEC-166
+/**
+ * Which specs a piece of content CLAIMS to implement.
+ *
+ * Measured 2026-08-08: writing `@implements A-SPEC-163` — an unapproved spec — into an EXISTING file
+ * was allowed, while the identical content in a new file was denied. The gate asked whether the FILE
+ * carried an approved anchor, never what the CHANGE was claiming, so No-Spec-No-Code held per file
+ * and not per change. Most real work edits existing files.
+ *
+ * Whether a change falls within its spec's scope is a natural-language judgement, and this harness
+ * keeps LLM judgement out of governance. What a change CLAIMS, though, is right there in the text —
+ * that is the decidable subset, and this is it.
+ */
+const ANCHOR_RE = /@implements\s+([A-Za-z]+-SPEC-[\w.]+)/g;
+function claimedAnchors(content) {
+    return [...new Set([...content.matchAll(ANCHOR_RE)].map((m) => m[1]))];
+}
+/**
+ * The anchors this write ADDS, relative to what the file already had.
+ *
+ * Only the additions are judged. Re-judging anchors already in the file would block every edit to a
+ * file whose spec later moved back to draft — including the edits needed to fix exactly that.
+ */
+function newlyClaimed(content, previous) {
+    const had = new Set(previous ? claimedAnchors(previous) : []);
+    return claimedAnchors(content).filter((a) => !had.has(a));
+}

package/dist/holmes/guardrail/blind-spots.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATE_BLIND_SPOTS = void 0;
+exports.blindSpotSummary = blindSpotSummary;
+exports.GATE_BLIND_SPOTS = [
+    { example: 'node ./cleanup.js', why: '스크립트 파일의 내용은 명령 문자열에 없습니다' },
+    { example: 'bash ./deploy.sh', why: '같은 이유 — 실행할 내용이 파일 안에 있습니다' },
+    { example: 'npm run clean', why: 'package.json의 스크립트 정의가 명령 문자열 밖에 있습니다' },
+    { example: 'make distclean', why: 'Makefile의 규칙이 명령 문자열 밖에 있습니다' },
+    { example: 'CMD="something"; $CMD', why: '실행될 명령이 실행 시점에 조립됩니다' },
+    { example: 'xargs rm < targets.txt', why: '대상 목록이 표준 입력으로 들어옵니다' },
+];
+/**
+ * One line for `doctor`.
+ *
+ * Deliberately neither "the gate stops everything" nor "the gate stops nothing". The first gets
+ * someone hurt; the second makes a reader distrust the parts that do work — and after REQ-167 those
+ * parts include creating the script in the first place.
+ */
+function blindSpotSummary() {
+    return '가드레일은 명령 문자열을 검사합니다 — 이미 저장소에 있는 스크립트를 실행하는 명령'
+        + `(${exports.GATE_BLIND_SPOTS.slice(0, 3).map((b) => b.example).join(', ')} 등)의 내용은 보지 못합니다.`
+        + ' 스크립트를 새로 작성하는 것은 승인이 필요합니다(A-SPEC-167).'
+        // @implements A-SPEC-170
+        // Stated, not implied. Four sweep rounds each found runner-manifest names the previous round's
+        // list had missed, so calling the list complete would be false — and this is the one place the
+        // harness tells a user what it cannot see. It belongs in the prose, not in GATE_BLIND_SPOTS,
+        // whose entries are commands a test executes against the gate.
+        + ' 루트 러너 매니페스트(Rakefile·Gemfile 등)의 이름 목록은 완전하지 않습니다 — 생태계마다 새로 생깁니다.'
+        // @implements A-SPEC-175
+        // The residual after REQ-175. Losing `.ax/specs` is now detected, because the ledger records the
+        // approvals and `init`'s .gitignore block keeps `provenance*.jsonl` committed. Losing the whole
+        // `.ax` takes that evidence with it, and a project then looks like one that never opted in. Every
+        // shell route to either state is denied by this gate; what remains is deletion from outside the
+        // session, and saying so is the only honest option left.
+        + ' `.ax` 전체가 세션 밖에서 삭제되면(에디터·Finder·세션 밖 git) 원장도 함께 사라져'
+        + ' 거버넌스를 켠 적 없는 프로젝트와 구별되지 않습니다 — `.ax/specs`만 사라진 경우는 탐지됩니다(REQ-175).';
+}

package/dist/holmes/guardrail/decision-ledger.js

@@ -0,0 +1,107 @@
+"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.DecisionLedger = void 0;
+// @implements A-SPEC-125.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// Default path used by callers: .ax/ledger/decisions.jsonl
+/**
+ * Append-only, provenance audit trail for riskGate decisions. Each call to
+ * `record` appends one JSON line per event to a `.jsonl` file -- never
+ * truncated, never rewritten -- so the file itself is the durable evidence
+ * trail.
+ *
+ * Timestamps and ids are caller-supplied: this ledger has no clock, so
+ * recording is fully deterministic given its inputs. Ledger I/O is
+ * deliberately separate from riskGate's decision -- a write failure here
+ * must never change a gate verdict that was already computed.
+ */
+class DecisionLedger {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    record(events) {
+        if (events.length === 0)
+            return;
+        const lines = events.map((e) => DecisionLedger.serialize(e)).join('');
+        fs.mkdirSync(path.dirname(this.path), { recursive: true });
+        fs.appendFileSync(this.path, lines, 'utf8');
+    }
+    list() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.path, 'utf8');
+        }
+        catch (err) {
+            // Missing file: no decisions recorded yet, not an error. Any other
+            // failure (EACCES, a directory at this path, etc.) must NOT be
+            // swallowed: silently returning [] here would erase the audit trail
+            // that the DecisionLedger exists to guarantee -- a silent gate-pass
+            // equivalent.
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const events = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim().length === 0)
+                continue;
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                // Corrupt line: skip it rather than throwing away the whole ledger.
+                continue;
+            }
+        }
+        return events;
+    }
+    /** Ordered-object serialization so identical events always produce identical bytes. */
+    static serialize(e) {
+        const ordered = {
+            ts: e.ts,
+            actor: e.actor,
+            action: e.action,
+            level: e.level,
+            decision: e.decision,
+            rationale: e.rationale,
+            reasons: e.reasons,
+        };
+        return JSON.stringify(ordered) + '\n';
+    }
+}
+exports.DecisionLedger = DecisionLedger;

package/dist/holmes/guardrail/executable-artifact.js

@@ -0,0 +1,129 @@
+"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.isExecutableArtifact = isExecutableArtifact;
+const path = __importStar(require("node:path"));
+// @implements A-SPEC-167
+/**
+ * Whether writing this file creates an EXECUTION path.
+ *
+ * Measured 2026-08-08: `package.json`, `Makefile`, `Dockerfile`, `.github/workflows/*` and `*.sh`
+ * all classified as nothing and were therefore allowed unconditionally — while every one of them
+ * runs. `package.json` executes on install, a workflow executes holding repository secrets, the
+ * Makefile and Dockerfile execute at build time. Combined with the indirection limit (REQ-165),
+ * writing `x.sh` and then running `bash ./x.sh` was a complete governance bypass in two allowed
+ * steps.
+ *
+ * The cause is that "code" was an extension list. What executes is code; the compiler's file list
+ * is a proxy that misses everything else.
+ */
+/** Names the ecosystem fixed. A short exact list is defensible where an extension list is not. */
+const MANIFESTS = [
+    'package.json', 'makefile', 'dockerfile',
+    // Axis sweep round 2: the first list was JS and C only, so a Java, Rust or Python project's build
+    // file went ungated while the harness claims eight languages. Each executes at build or install
+    // time; `.npmrc` reaches the supply chain through `ignore-scripts` and the registry.
+    'build.gradle', 'build.gradle.kts', 'pom.xml', 'cargo.toml', 'pyproject.toml',
+    'justfile', 'taskfile.yml', 'taskfile.yaml', '.npmrc', 'setup.py',
+    // Round 4. Root runner manifests share no property, so this stays an enumeration — and the fact
+    // that it is INCOMPLETE is declared rather than pretended away (see blind-spots.ts).
+    'rakefile', 'gemfile', 'jenkinsfile', 'vagrantfile',
+    'docker-compose.yml', 'docker-compose.yaml', '.gitlab-ci.yml', '.gitlab-ci.yaml',
+    // Round 5 parity: GitLab was in and Travis, Azure and Bitbucket were not — one CI service
+    // covered and three not is an inconsistency in this list, the same shape `.command` was. Brewfile
+    // and Procfile were also found and deliberately LEFT OUT: they describe an environment rather
+    // than running on write, and they fall inside the incompleteness this list already declares.
+    '.travis.yml', 'azure-pipelines.yml', 'bitbucket-pipelines.yml',
+];
+/** Scripts without a shebang. A supplement, and known to be insufficient on its own. */
+// `.command` is macOS's — double-clickable and executed by Finder. Round 3 found it missing while
+// `.bat` and `.cmd` were present, which was an inconsistency in this list rather than a new idea.
+/** Suffixes that mark a copy, a draft or a note rather than a live manifest. */
+const DOC_SUFFIXES = ['.md', '.txt', '.bak', '.example', '.sample', '.template', '.orig'];
+const SCRIPT_EXTS = ['.sh', '.bash', '.zsh', '.ps1', '.bat', '.cmd', '.command'];
+/**
+ * @implements A-SPEC-170
+ * Directories whose CONTENTS execute, whatever the files are called.
+ *
+ * Rounds 1-3 each filled a name list and round 4 found eight more — the trend was the finding, not
+ * the eight names. One rule covers them and the next CI tool lands in the same place.
+ *
+ * `.github` is narrowed to `workflows/` on purpose: `ISSUE_TEMPLATE/` and `CODEOWNERS` do not
+ * execute, and a blanket rule over the whole directory would repeat REQ-164's measured accident,
+ * where a broad directory match swallowed files that never belonged to the category.
+ */
+const EXECUTABLE_DIRS = ['.github/workflows/', '.circleci/', '.husky/', '.git/hooks/'];
+function isExecutableArtifact(relPath, content) {
+    // A shebang is the broadest signal and the cheapest — the content is already in the payload, so
+    // there is no I/O — and it is the only one that catches an extensionless `bin/deploy`.
+    if (typeof content === 'string' && content.startsWith('#!'))
+        return true;
+    // Lexically normalised before matching. Round 9 found `.github/workflows/../ISSUE_TEMPLATE/x.md`
+    // treated as a workflow because the raw string CONTAINS `.github/workflows/` — REQ-163 established
+    // that a path is judged by what it resolves to, and this function was still doing substring work.
+    // `path.posix.normalize` collapses `..` and `.` without touching the filesystem, so the rule stays
+    // pure.
+    const norm = path.posix.normalize(relPath.replace(/\\/g, '/')).toLowerCase();
+    const base = norm.slice(norm.lastIndexOf('/') + 1);
+    // Exact base name, or a manifest with a VARIANT suffix — `Dockerfile.prod`,
+    // `docker-compose.override.yml` and `Makefile.inc` are real conventions that build tools read,
+    // found in round 10 while their bare forms were covered. Still never a bare prefix: the suffix
+    // must not be a document or backup extension, or `Makefile.md` and `pom.xml.bak` would inherit
+    // protection they did not earn, and the over-blocking this design spends half its effort avoiding
+    // would start.
+    if (MANIFESTS.includes(base))
+        return true;
+    // A VARIANT keeps the manifest's identity, not just its opening letters. Two shapes, because the
+    // manifests come in two shapes:
+    //   - extensionless (`Dockerfile`)      → `Dockerfile.prod`      : name + a suffix
+    //   - with an extension (`…-compose.yml`) → `…-compose.override.yml`: stem + a segment + SAME ext
+    // A bare prefix rule was tried first and pulled in `pyproject.py`, a Python source file that is
+    // not a variant of `pyproject.toml` at all — the existing over-blocking control caught it.
+    if (!DOC_SUFFIXES.some((d) => base.endsWith(d))) {
+        for (const m of MANIFESTS) {
+            const dot = m.startsWith('.') ? m.indexOf('.', 1) : m.indexOf('.');
+            if (dot < 0) {
+                if (base.startsWith(`${m}.`))
+                    return true; // Dockerfile.prod
+            }
+            else if (base.startsWith(`${m.slice(0, dot)}.`) && base.endsWith(m.slice(dot))) {
+                return true; // docker-compose.override.yml
+            }
+        }
+    }
+    if (EXECUTABLE_DIRS.some((d) => norm.includes(d)))
+        return true;
+    return SCRIPT_EXTS.some((e) => base.endsWith(e));
+}

package/dist/holmes/guardrail/governance-history.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GOVERNANCE_LOST_HINT = void 0;
+exports.hasGovernanceHistory = hasGovernanceHistory;
+// @implements A-SPEC-175
+/**
+ * Did this project ever opt into governance?
+ *
+ * The ungoverned escape hatch allows every write on a project with no spec tree, which is correct for
+ * a repository that never opted in — without it, pointing the Write matcher at a spec-less project
+ * denies 100% of source writes. But the condition could not tell that case apart from a governed
+ * project whose specs went missing, and measured 2026-08-12 on an installed tarball: moving
+ * `.ax/specs` aside turned an unanchored code write from `deny` to `allow`, silently.
+ *
+ * The answer has to come from evidence that outlives the spec tree. `spec_approve` writes a
+ * `spec-approved` event carrying the sealed digest, and the `.gitignore` block `init` installs
+ * excludes `provenance*.jsonl` from being ignored — so the record is committed and survives a clone.
+ * A marker file would fail twice over: it can be deleted alongside the specs, and no already-installed
+ * project has one.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const APPROVAL_EVENT = '"kind":"spec-approved"';
+/**
+ * The two ways out, and why the project is being judged governed at all.
+ *
+ * Shared by both hooks so they cannot describe the same situation differently. Naming only the
+ * restore path would be no guidance to a user whose actual intent is to stop being governed — they
+ * would keep deleting things until it stopped.
+ */
+exports.GOVERNANCE_LOST_HINT = '[Holmes-Kit] .ax/specs is missing, but this project has approved specs in its ledger — governance was'
+    + ' switched on here and its documents are gone, so every code write is refused rather than silently'
+    + ' ungoverned. Restore the spec tree (e.g. `git checkout -- .ax/specs`), or run'
+    + ' `holmes-kit init --target . --remove` if you are done with governance.';
+/**
+ * True if any provenance replica records a spec approval.
+ *
+ * Fails toward `true` on anything unreadable: if "cannot read" meant "never governed", corrupting a
+ * ledger file would be a way to switch the gate off — worse than the hole this closes.
+ */
+function hasGovernanceHistory(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (err) {
+        // A ledger directory that exists but cannot be listed is evidence withheld, not evidence absent.
+        return err.code !== 'ENOENT';
+    }
+    // Only provenance replicas. `stop-guard.json` and other bookkeeping live here too, and treating
+    // any file as the record would let unrelated state decide whether the gate is armed.
+    for (const name of entries.filter((n) => n.startsWith('provenance') && n.endsWith('.jsonl'))) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            return true;
+        }
+        // A substring scan, not a per-line parse: the answer is boolean, a broken line must not hide a
+        // real approval on another line, and a large ledger must not be walked object by object inside a
+        // hook. The needle is the serialized field, so ordinary prose in a `summary` cannot forge it.
+        if (text.includes(APPROVAL_EVENT))
+            return true;
+    }
+    return false;
+}

package/dist/holmes/guardrail/phase.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIONS = void 0;
+exports.classifyAction = classifyAction;
+exports.phaseCheck = phaseCheck;
+const executable_artifact_1 = require("./executable-artifact");
+const test_files_1 = require("../cpg/test-files");
+const approval_blockers_1 = require("../spec/approval-blockers");
+const tspec_state_1 = require("./tspec-state");
+// @implements A-SPEC-100.2
+// @implements A-SPEC-189
+// The RUNTIME list is the single truth; the type derives from it. The phase_check schema's enum
+// advertises this same array — a hand-copied literal there was a second truth, and round-3 measured
+// that deleting two of its members survived the entire suite while the wire falsely refused actions
+// this module accepts.
+/** 문면에 실을 수 있는 id 만 문자 그대로 — 나머지는 이름을 잃되 문장은 잃지 않는다(§5R). */
+const quotableId = (id) => (id === undefined ? null : id.length <= tspec_state_1.ID_MAX ? id : null);
+exports.ACTIONS = [
+    'AUTHOR_REQ', 'AUTHOR_HSPEC', 'AUTHOR_ASPEC', 'AUTHOR_CSPEC', 'AUTHOR_TSPEC',
+    'WRITE_TEST', 'WRITE_CODE',
+];
+const NO_SPEC_NO_CODE = 'No Spec, No Code — 선행 스펙 승인 전 구현 진입 금지';
+// Executable-source extensions the WRITE_CODE gate must cover. Kept broad on purpose: an extension
+// NOT listed here silently escapes No-Spec-No-Code, so err toward inclusion (adversarial-review F2 —
+// .mjs/.cjs/.mts/.cts and C/C++ header/variant + other-language sources were escaping).
+const CODE_EXT_RE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|scala|cs|c|cc|cxx|cpp|h|hh|hpp|hxx|m|mm|swift|rb|php)$/i;
+/**
+ * Classify a write target. `p` must be PROJECT-RELATIVE (POSIX or Windows separators both fine).
+ *
+ * Relative matters for the test rules: several of them key on a directory segment, so an absolute
+ * path would let a project checked out under `/…/test/` classify its production code as tests —
+ * DOWNGRADING the gate, since WRITE_TEST does not require an approved T-SPEC. Callers that hold an
+ * absolute path make it relative first (see evaluateHook).
+ */
+function classifyAction(p, content) {
+    const norm = p.replace(/\\/g, '/');
+    // Spec authoring is a MARKDOWN file under a spec folder. A code file merely PLACED at such a path
+    // (e.g. src/x/.ax/specs/01_req/evil.ts) must NOT be downgraded to the permissive author gate —
+    // require the `.md` extension so it falls through to the WRITE_CODE gate instead (review F4).
+    if (/\.md$/i.test(norm)) {
+        if (norm.includes('.ax/specs/01_req/'))
+            return 'AUTHOR_REQ';
+        if (norm.includes('.ax/specs/02_h-spec/'))
+            return 'AUTHOR_HSPEC';
+        if (norm.includes('.ax/specs/03_a-spec/'))
+            return 'AUTHOR_ASPEC';
+        if (norm.includes('.ax/specs/04_cpg/'))
+            return 'AUTHOR_CSPEC';
+        if (norm.includes('.ax/specs/05_t-spec/'))
+            return 'AUTHOR_TSPEC';
+    }
+    // Test detection uses the SCANNER'S table, not a bespoke `.test.`/`.spec.` regex. The bespoke one
+    // knew only the TS/JS infix, so every pytest file (`tests/test_briefing.py`), Go `_test.go`, Rust
+    // `tests/*.rs` and JUnit `AppTest.java` fell through to WRITE_CODE — gating a project's own test
+    // suite MORE strictly than the code it tests (WRITE_CODE additionally demands an approved T-SPEC),
+    // which no Python or Go project can satisfy for its tests. Measured on a real Python target. One
+    // table means the gate and the graph cannot disagree about what a test is.
+    if ((0, test_files_1.isTestFile)(norm))
+        return 'WRITE_TEST';
+    if (/\.(test|spec)\.[a-z]+$/i.test(norm))
+        return 'WRITE_TEST';
+    if (CODE_EXT_RE.test(norm))
+        return 'WRITE_CODE';
+    // @implements A-SPEC-167
+    // What EXECUTES is code. The extension list above is the compiler's view, and it missed
+    // package.json, Makefile, Dockerfile, CI workflows and shell scripts — each an execution path,
+    // each previously unclassified and therefore ungated. Folding into WRITE_CODE rather than adding
+    // an action kind means the role policy, the phase gate and the playbooks all already know it.
+    if ((0, executable_artifact_1.isExecutableArtifact)(norm, content))
+        return 'WRITE_CODE';
+    return null;
+}
+function deny(phase, missing, message, next, discipline = NO_SPEC_NO_CODE) {
+    return { decision: 'deny', phase, missing, remediation: { message, next_action: next, discipline } };
+}
+function phaseCheck(action, ctx) {
+    const byId = new Map(ctx.specs.map((s) => [s.id, s]));
+    const approvedOfType = (t) => ctx.specs.some((s) => s.type === t && s.status === 'approved');
+    const existsOfType = (t) => ctx.specs.some((s) => s.type === t);
+    switch (action) {
+        case 'AUTHOR_REQ': return { decision: 'allow', phase: 'INTAKE' };
+        case 'AUTHOR_HSPEC':
+            return existsOfType('REQ') ? { decision: 'allow', phase: 'DESIGN' }
+                : deny('INTAKE', ['REQ'], '선행 REQ가 없습니다.', "spec_create(type='REQ', ...)");
+        case 'AUTHOR_ASPEC':
+            return approvedOfType('H-SPEC') ? { decision: 'allow', phase: 'SPECIFY' }
+                : deny('DESIGN', ['approved H-SPEC'], 'approved H-SPEC이 없습니다.', "H-SPEC 완성 후 spec_validate → approve");
+        case 'AUTHOR_CSPEC':
+        case 'AUTHOR_TSPEC':
+            return approvedOfType('A-SPEC') ? { decision: 'allow', phase: 'TEST-SPEC' }
+                : deny('SPECIFY', ['approved A-SPEC'], 'approved A-SPEC이 없습니다.', "A-SPEC 먼저 작성·승인");
+        case 'WRITE_TEST':
+        case 'WRITE_CODE': {
+            const aspec = ctx.targetAspecId ? byId.get(ctx.targetAspecId) : undefined;
+            if (!aspec || aspec.status !== 'approved') {
+                // @implements A-SPEC-182
+                // Say WHY it cannot be approved, not just that it is not. The reason is already computable
+                // here — `spec_approve` derives it from the same specs moments later. Measured over 244
+                // governed runs: 425 refusals in 99 wordings, none of which carried the reason, and authors
+                // then groped through `.ax/` with the shell (8.5 calls/run, r=0.71 against total tokens).
+                // Nothing is appended when the target is absent (nothing to compute) or when nothing blocks
+                // (the silence itself says "approve it") — see the boundary cases in T-SPEC-182.
+                // @implements A-SPEC-192 §5R (round 9) — the TWIN of the approval-claim refusal, and until
+                // now the unbudgeted one: the same fact, computed by the same `blockerSummary`, printed
+                // raw. Measured 60,286 characters on one call (a 20k-char id echoed twice plus a
+                // pathological section name repeated 700 times), while its sibling one function away was
+                // capped at 1,200 — so whether a refusal was bounded depended on whether the anchor already
+                // existed on disk, i.e. on input position. Same budget, same omission labels, same rule:
+                // sentences are omitted whole and counted, never cut.
+                // @implements A-SPEC-192 §7R (round 10) — a sentence that says the name was omitted must not
+                // then print it. Measured: with a 120-char id the refusal read "구현 대상 A-SPEC(이름이
+                // 문면 예산을 넘어 생략)…" and quoted the id whole two lines later — through the clause
+                // LABEL (blockerSummary defaults it to spec.id) and again through blocker BODIES that embed
+                // the id in their own prose (breaking_change, id-format). Both carriers are folded here, at
+                // the one place that knows the id is unquotable.
+                // One carrier, not two: folding the clause LABEL separately was unobservable once the whole
+                // summary is scrubbed (a mutation battery proved the label branch equivalent), and two
+                // places that must agree about the same fact is how they stop agreeing.
+                // @implements A-SPEC-192 §10R (round 10, 4th) — the twin now renders through the SAME
+                // budgeted clause the sibling uses (`budgetedClause`), instead of measuring the whole joined
+                // summary and dropping it all. Measured before: a 93-char parent blocker — the one action the
+                // author could take — disappeared because another blocker was 1,154 chars, and the effective
+                // budget slid with the id's length (one character past ID_MAX freed 63 and flipped a 236-char
+                // refusal that named nothing into a 1,209-char one that named everything).
+                const unquotable = ctx.targetAspecId !== undefined && quotableId(ctx.targetAspecId) === null;
+                const fold = (s) => (unquotable && ctx.targetAspecId
+                    ? s.split(ctx.targetAspecId).join('<이름이 문면 예산을 넘어 생략>')
+                    : s);
+                // Never throws — the contract `blockerSummary` carried and this call must keep: this runs in
+                // a PreToolUse hook on every tool call, and a refusal that says less is recoverable while a
+                // hook that dies is not. (Round-10 lost it for one build by calling approvalBlockers raw.)
+                const rawBlockers = (() => {
+                    try {
+                        return aspec ? (0, approval_blockers_1.approvalBlockers)(aspec, (id) => byId.get(id) ?? null).map(fold) : [];
+                    }
+                    catch {
+                        return [];
+                    }
+                })();
+                const why = (0, tspec_state_1.budgetedClause)(unquotable ? '<이름이 문면 예산을 넘어 생략>' : (ctx.targetAspecId ?? aspec?.id ?? ''), `${aspec?.type ?? 'A-SPEC'}`, rawBlockers);
+                // 부재는 '미지정'이고, 이름이 문면 예산을 넘는 것은 다른 사실이다 — 두 사정을 한 낱말로
+                // 뭉치면 호출자는 자기가 무엇을 잘못했는지 알 수 없다.
+                // 빈 문자열도 부재다(round-10: 빈 괄호만 남아 무엇이 문제인지 말하지 않았다).
+                const named = ctx.targetAspecId === undefined || ctx.targetAspecId === ''
+                    ? '미지정'
+                    : (quotableId(ctx.targetAspecId) ?? '이름이 문면 예산을 넘어 생략');
+                return deny('DESIGN', ['approved A-SPEC'], `구현 대상 A-SPEC(${named})이 approved가 아닙니다.${why}`, "spec_create/approve로 A-SPEC → T-SPEC 완성");
+            }
+            // @implements A-SPEC-183
+            // A STATE, not a boolean. Measured 2026-08-13: four different T-SPEC situations produced one
+            // identical sentence while needing four different actions, and `promote-slice`'s 「침묵의
+            // 실패 모드」 section existed to explain what the refusal could not. `decision`, `phase` and
+            // `missing` stay exactly as they were — this changes what is SAID, never what is decided.
+            if (action === 'WRITE_CODE') {
+                const state = (0, tspec_state_1.tspecStateFor)(aspec.id, ctx.specs);
+                if (state.kind !== 'approved') {
+                    const r = (0, tspec_state_1.tspecRemediation)(aspec.id, state, (s) => { try {
+                        return (0, approval_blockers_1.approvalBlockers)(s, (id) => byId.get(id) ?? null);
+                    }
+                    catch {
+                        return [];
+                    } });
+                    return deny('TEST-SPEC', ['approved T-SPEC'], r.message, r.next_action);
+                }
+            }
+            return { decision: 'allow', phase: 'IMPLEMENT' };
+        }
+    }
+}