@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/project/change-source.js

@@ -0,0 +1,233 @@
+"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.EMPTY_CHANGE_SET = exports.GitChangeSource = exports.SnapshotChangeSource = exports.hashOf = exports.isDerivedState = void 0;
+exports.hashTree = hashTree;
+exports.diffHashes = diffHashes;
+// @implements A-SPEC-128
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const git_changes_1 = require("../rtm/git-changes");
+const baseline_1 = require("./baseline");
+const root_1 = require("./root");
+const EMPTY = { added: [], modified: [], deleted: [], renamed: [] };
+exports.EMPTY_CHANGE_SET = EMPTY;
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Derived state under `.ax/` — bookkeeping the harness writes about the project, not project content.
+ *
+ * Both adapters exclude exactly this set, which is what makes "the two sources agree" a property
+ * rather than a coincidence. Found by the agreement test: the snapshot source skipped all of `.ax/`
+ * while git reported a freshly written baseline file as an addition, so the same edits produced
+ * different change sets depending on which adapter answered.
+ *
+ * `.ax/specs/**` is deliberately NOT here. A spec is project content — a reviewer who changed a
+ * requirement should see that in the change set, and hiding it would make the two halves of the chain
+ * visible at different times. The line is derived-vs-authored, not "anything under .ax".
+ */
+const DERIVED_STATE_RE = /^\.ax\/(state|cpg_cache|ledger|reports)\/|^\.ax\/[^/]*\.sqlite/;
+const isDerivedState = (relPath) => DERIVED_STATE_RE.test(relPath);
+exports.isDerivedState = isDerivedState;
+/** Same digest the scan caches use, so a baseline and a scan cache never disagree about a file. */
+const hashOf = (content) => (0, node_crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');
+exports.hashOf = hashOf;
+/**
+ * Content hashes for every file in the tree, keyed by project-relative POSIX path.
+ *
+ * Derived state under `.ax/` is excluded (see `isDerivedState`) along with the scanner's vendor/cache
+ * skips, so a run never reports its own bookkeeping as project churn. Authored specs under
+ * `.ax/specs/**` ARE included — they are project content.
+ *
+ * Files that cannot be read are skipped rather than failing the walk — an unreadable file is not
+ * evidence of a change.
+ */
+function hashTree(root, opts = {}) {
+    const out = {};
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (cpg_scanner_1.SKIP.has(e.name))
+                continue;
+            const abs = path.join(dir, e.name);
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if ((0, exports.isDerivedState)(`${rel}${e.isDirectory() ? '/' : ''}`) || opts.isIgnored?.(rel))
+                continue;
+            if (e.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!e.isFile())
+                continue; // symlinks and devices are not project content
+            try {
+                out[rel] = (0, exports.hashOf)(fs.readFileSync(abs, 'utf8'));
+            }
+            catch { /* unreadable — not a change */ }
+        }
+    };
+    walk(root);
+    return out;
+}
+/** Compare a baseline's hashes against the tree's. Pure — the adapters supply the two maps. */
+function diffHashes(before, after) {
+    const added = [];
+    const modified = [];
+    const deleted = [];
+    for (const [p, h] of Object.entries(after)) {
+        if (!(p in before))
+            added.push(p);
+        else if (before[p] !== h)
+            modified.push(p);
+    }
+    for (const p of Object.keys(before))
+        if (!(p in after))
+            deleted.push(p);
+    return { added: added.sort(cmp), modified: modified.sort(cmp), deleted: deleted.sort(cmp), renamed: [] };
+}
+/** Changes since a labelled baseline. Available on any directory, with or without version control. */
+class SnapshotChangeSource {
+    root;
+    label;
+    opts;
+    constructor(root, label, 
+    // @implements A-SPEC-134 — `verify` is the provenance ledger path. When set, a baseline whose
+    // digest is not anchored on the chain (tampered, or written unanchored) is treated as ABSENT:
+    // a forged narrowing must never be honored. Omitted (pure unit tests) → today's behavior.
+    opts = {}) {
+        this.root = root;
+        this.label = label;
+        this.opts = opts;
+    }
+    /** Trusted iff a baseline exists AND (no verify requested OR its digest is anchored on the chain). */
+    trustedBaseline() {
+        const baseline = (0, baseline_1.readBaseline)(this.root, this.label);
+        if (!baseline)
+            return null;
+        if (this.opts.verify && !(0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify))
+            return null;
+        return baseline;
+    }
+    changes() {
+        const baseline = this.trustedBaseline();
+        if (!baseline)
+            return null;
+        return diffHashes(baseline.files, hashTree(this.root, this.opts));
+    }
+    describe() {
+        const raw = (0, baseline_1.readBaseline)(this.root, this.label);
+        const trusted = this.trustedBaseline();
+        const tampered = raw !== null && trusted === null; // exists but failed the integrity check
+        return {
+            kind: 'snapshot',
+            baseline: this.label,
+            detectsRenames: false,
+            available: trusted !== null,
+            ...(trusted ? {} : {
+                reason: tampered
+                    ? `baseline "${this.label}" failed its integrity check (not anchored on the provenance chain) — treating as absent, full scope`
+                    : `no baseline named "${this.label}" — run a passing test_run, or take one explicitly`,
+            }),
+        };
+    }
+}
+exports.SnapshotChangeSource = SnapshotChangeSource;
+/**
+ * Changes across a git range.
+ *
+ * THE TOP-LEVEL GUARD LIVES HERE, and only here. `gitChangedFiles` yields paths relative to the git
+ * top-level while `scan(root, root)` tags them relative to `root`; when those disagree the keys
+ * silently diverge and impact sets come back wrong. That hazard belongs to this adapter — it was
+ * previously imposed on every tool, including ones that never look at a diff, which is what made the
+ * whole harness demand a repository.
+ */
+class GitChangeSource {
+    root;
+    base;
+    head;
+    topLevel;
+    constructor(root, base, head) {
+        this.root = root;
+        this.base = base;
+        this.head = head;
+        this.topLevel = (0, root_1.resolveProjectRoot)(root).git?.topLevel;
+        if (this.topLevel && fs.realpathSync(path.resolve(root)) !== this.topLevel) {
+            throw new Error(`GitChangeSource: root must be the git top-level (got ${root}, top-level is ${this.topLevel})`);
+        }
+    }
+    changes() {
+        if (!this.topLevel)
+            return null;
+        try {
+            const c = (0, git_changes_1.gitChangedFiles)(this.root, this.base, this.head);
+            // The same derived-state exclusion the snapshot source applies. A project that committed its
+            // `.ax/state` before the ignore block existed would otherwise get different answers from the
+            // two adapters for identical edits.
+            const keep = (p) => !(0, exports.isDerivedState)(p);
+            return {
+                added: c.added.filter(keep).sort(cmp),
+                modified: c.modified.filter(keep).sort(cmp),
+                deleted: c.deleted.filter(keep).sort(cmp),
+                renamed: c.renamed.filter((r) => keep(r.to)).sort((a, b) => cmp(a.to, b.to)),
+            };
+        }
+        catch {
+            // An unreachable ref (a shallow clone, a range that does not exist yet) is an unavailable
+            // source, not a crash — the caller widens to full scope exactly as it does with no baseline.
+            return null;
+        }
+    }
+    describe() {
+        const range = `${this.base}..${this.head}`;
+        if (!this.topLevel) {
+            return { kind: 'git', baseline: range, detectsRenames: true, available: false, reason: 'not a git working tree' };
+        }
+        const available = this.changes() !== null;
+        return {
+            kind: 'git',
+            baseline: range,
+            detectsRenames: true,
+            available,
+            ...(available ? {} : { reason: `git range ${range} could not be resolved` }),
+        };
+    }
+}
+exports.GitChangeSource = GitChangeSource;

package/dist/holmes/project/ignore.js

@@ -0,0 +1,145 @@
+"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.parseIgnore = parseIgnore;
+exports.loadIgnore = loadIgnore;
+// @implements A-SPEC-128
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const LIMITATIONS = [
+    'only the project-root .gitignore is read — nested per-directory .gitignore files are not',
+    'backslash escapes are not interpreted',
+    '.git/info/exclude and the global core.excludesFile are not read',
+];
+/** Constructs the subset deliberately does not implement: escapes, and an unterminated class. */
+const UNSUPPORTED_RE = /\\/;
+const UNTERMINATED_CLASS_RE = /\[[^\]]*$/;
+/**
+ * Translate one supported pattern into an anchored regex over project-relative FILE paths.
+ *
+ * `dirOnly` is expressed in the tail rather than as a second check at match time: a directory rule
+ * must have something UNDER it (`dist/` excludes `dist/bundle.js`, never a file named `dist`). An
+ * earlier version re-assembled the compiled regex's source at match time to express that, which
+ * passed its tests and was still the wrong shape — unreadable, and correct only for the cases tried.
+ */
+function compile(pattern, dirOnly) {
+    const anchored = pattern.startsWith('/');
+    let body = anchored ? pattern.slice(1) : pattern;
+    // A pattern containing a slash anywhere is anchored to the root; a bare name matches at any depth.
+    const rooted = anchored || body.includes('/');
+    let out = '';
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '*') {
+            if (body[i + 1] === '*') {
+                // `**/` spans zero or more directories; a bare `**` spans anything including separators.
+                if (body[i + 2] === '/') {
+                    out += '(?:[^/]+/)*';
+                    i += 2;
+                }
+                else {
+                    out += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                out += '[^/]*';
+            }
+            continue;
+        }
+        if (c === '?') {
+            out += '[^/]';
+            continue;
+        }
+        if (c === '[') {
+            // A character class, copied through with git's `!` negation translated to a regex `^`. `/` is
+            // excluded so a class can never cross a path separator.
+            const end = body.indexOf(']', i + 1);
+            const inner = body.slice(i + 1, end);
+            const negated = inner.startsWith('!') || inner.startsWith('^');
+            out += `[${negated ? '^' : ''}${(negated ? inner.slice(1) : inner).replace(/[\\\]]/g, '')}]`;
+            i = end;
+            continue;
+        }
+        out += c.replace(/[.+^${}()|]/g, '\\$&');
+    }
+    // Matching a FILE path: an ordinary rule matches the file itself or anything beneath it; a
+    // directory-only rule matches ONLY what is beneath it.
+    const tail = dirOnly ? '/.+$' : '(?:/.*)?$';
+    return new RegExp(rooted ? `^${out}${tail}` : `^(?:.*/)?${out}${tail}`);
+}
+function parseIgnore(content) {
+    const rules = [];
+    const unsupported = [];
+    for (const raw of content.split('\n')) {
+        const line = raw.replace(/\s+$/, ''); // trailing whitespace is not part of a pattern
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        if (UNSUPPORTED_RE.test(line) || UNTERMINATED_CLASS_RE.test(line)) {
+            unsupported.push(line);
+            continue;
+        }
+        const negated = line.startsWith('!');
+        let body = negated ? line.slice(1) : line;
+        const dirOnly = body.endsWith('/');
+        if (dirOnly)
+            body = body.slice(0, -1);
+        if (body === '')
+            continue;
+        rules.push({ negated, dirOnly, re: compile(body, dirOnly), source: line });
+    }
+    return {
+        isIgnored(relPath) {
+            const p = relPath.replace(/\\/g, '/').replace(/^\.\//, '');
+            let verdict = false;
+            // LAST match wins, which is what makes negation work: `*.log` then `!keep.log` re-includes.
+            for (const r of rules)
+                if (r.re.test(p))
+                    verdict = !r.negated;
+            return verdict;
+        },
+        unsupportedPatterns: () => [...unsupported],
+        limitations: () => [...LIMITATIONS],
+    };
+}
+/** Load the project-root `.gitignore`. A missing file ignores nothing. */
+function loadIgnore(root) {
+    try {
+        return parseIgnore(fs.readFileSync(path.join(root, '.gitignore'), 'utf8'));
+    }
+    catch {
+        return parseIgnore('');
+    }
+}

package/dist/holmes/project/root.js

@@ -0,0 +1,113 @@
+"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.MARKER = void 0;
+exports.cleanSubprocessEnv = cleanSubprocessEnv;
+exports.resolveProjectRoot = resolveProjectRoot;
+// @implements A-SPEC-128
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+// @implements A-SPEC-194
+// @implements A-SPEC-196
+function cleanSubprocessEnv(env = process.env) {
+    const cleaned = { ...env };
+    const SCRUB_KEYS = new Set(['HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY']);
+    for (const k of Object.keys(cleaned)) {
+        if (SCRUB_KEYS.has(k.toUpperCase())) {
+            delete cleaned[k];
+        }
+    }
+    return cleaned;
+}
+/** The marker directory that makes a directory a Holmes-Kit project. */
+exports.MARKER = '.ax';
+function gitTopLevel(dir) {
+    try {
+        // stderr silenced: "not a git repository" is an expected branch here, not a fault worth printing.
+        const out = (0, node_child_process_1.execFileSync)('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            env: cleanSubprocessEnv(),
+        }).trim();
+        // git resolves symlinks in its output; realpath ours too so comparisons are like-for-like
+        // (macOS /var -> /private/var otherwise makes an identical directory look like a mismatch).
+        return out ? fs.realpathSync(out) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveProjectRoot(dir) {
+    let start;
+    try {
+        start = fs.realpathSync(path.resolve(dir));
+    }
+    catch {
+        // @implements A-SPEC-189 §7 (round 11) — this is a POINTED refusal about the caller's own
+        // argument ('that path does not exist'), not a fault. Without the marker the MCP boundary
+        // rethrew it and 11 tools answered the commonest user mistake with a raw -32603 — the class
+        // this REQ exists to remove — while phase_status and spec_approve, which catch it themselves,
+        // answered with {ok:false, reason}. One mistake, two shapes.
+        throw Object.assign(new Error(`resolveProjectRoot: ${dir} does not exist`), { holmesRefusal: true });
+    }
+    if (!fs.statSync(start).isDirectory()) {
+        throw Object.assign(new Error(`resolveProjectRoot: ${dir} is not a directory`), { holmesRefusal: true });
+    }
+    // Walk up for the marker. The loop terminates at the filesystem root, where dirname(p) === p.
+    //
+    // @implements A-SPEC-191 §13 — a candidate INSIDE a `.ax` directory is never a project root.
+    // Round-9 measured the attack this closes: one ordinary `review_record({root: <P>/.ax/specs})`
+    // call — no approval, no shell, no gate — creates `<P>/.ax/specs/.ax/ledger/`, and the very next
+    // derivation walks up from the spec store and stops at that planted marker. Every consumed nonce
+    // then reopened, the audit lines moved to a shadow ledger the project never reads, and
+    // spec_approve refused the CORRECT root forever after. `.ax` holds a project's records; a project
+    // does not live inside its own records.
+    // round-10: the exclusion compared SPELLING. On a case-insensitive filesystem (macOS default) a
+    // store written as `.AX/specs` slipped past it, and the planted-marker hijack came straight back.
+    const insideAx = (p) => p.split(path.sep).some((seg) => seg.toLowerCase() === exports.MARKER.toLowerCase());
+    let found;
+    for (let cur = start;; cur = path.dirname(cur)) {
+        if (!insideAx(cur) && fs.existsSync(path.join(cur, exports.MARKER))) {
+            found = cur;
+            break;
+        }
+        if (path.dirname(cur) === cur)
+            break;
+    }
+    const root = found ?? start;
+    const topLevel = gitTopLevel(root);
+    return { root, marker: found ? exports.MARKER : 'given', ...(topLevel ? { git: { topLevel } } : {}) };
+}

package/dist/holmes/reverse/anchor.js

@@ -0,0 +1,162 @@
+"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.planAnchors = planAnchors;
+exports.applyAnchors = applyAnchors;
+// @implements A-SPEC-126
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Comment prefix per language, covering every extension in `SCANNABLE_EXTENSIONS`.
+ * An anchor written with the wrong prefix is a syntax error in the target file, so this table is
+ * matched explicitly rather than defaulted.
+ */
+const COMMENT_PREFIX = [
+    [/\.(py|rb|sh|yml|yaml|toml)$/, '#'],
+    [/\.(ts|mts|cts|tsx|jsx|js|mjs|cjs|java|cs|go|rs|cpp|cc|cxx|hpp|hh|h)$/, '//'],
+];
+const prefixFor = (file) => (COMMENT_PREFIX.find(([re]) => re.test(file)) ?? [null, '//'])[1];
+/**
+ * Compute the anchor edits for a mapping, refusing anything that must not be written.
+ *
+ * `approvedAspecs` is the caller's list of APPROVED A-SPEC ids — passed in rather than read here so
+ * the function stays pure with respect to the spec store and can be tested without one.
+ */
+function planAnchors(root, mapping, approvedAspecs) {
+    const edits = [];
+    const refused = [];
+    const approved = new Set(approvedAspecs);
+    const rootReal = path.resolve(root);
+    // The disk is read at PLAN time only, so a repeated pair would produce two identical edits and
+    // apply would insert the same anchor twice. Dedupe here rather than trusting the caller's mapping.
+    const planned = new Set();
+    // JSON-encoded pair, not a hand-picked separator: a filename may contain any character, and a
+    // separator that can occur in a path would silently merge two different mappings into one key.
+    const keyOf = (file, aspec) => JSON.stringify([file, aspec]);
+    for (const { file, aspec } of mapping) {
+        if (planned.has(keyOf(file, aspec))) {
+            refused.push({ file, aspec, reason: 'duplicate mapping entry' });
+            continue;
+        }
+        if (!approved.has(aspec)) {
+            refused.push({ file, aspec, reason: `target A-SPEC ${aspec} is not approved` });
+            continue;
+        }
+        // The mapping arrives as tool input, and applying an edit is a file write: a traversing path
+        // would let an anchor land anywhere on the host. Containment is checked before the read.
+        // @implements A-SPEC-189 §11 (round 12) — `path.resolve` folds `..` and nothing else, so a
+        // symlink INSIDE the root (a directory link or a file link) carried the write past this check
+        // while the returned plan still showed a root-relative path. The plan/apply split exists so a
+        // human can inspect the destinations before anything is written; naming the wrong destination
+        // defeats the split itself. Judge where the write LANDS, and say so when it lands outside.
+        const abs = path.resolve(rootReal, file);
+        const landing = (() => {
+            let head = abs;
+            const tail = [];
+            for (let hop = 0; hop < 64; hop++) {
+                try {
+                    return [fs.realpathSync(head), ...tail].join(path.sep);
+                }
+                catch { /* walk up */ }
+                const parent = path.dirname(head);
+                if (parent === head)
+                    return abs;
+                tail.unshift(path.basename(head));
+                head = parent;
+            }
+            return abs;
+        })();
+        // 뿌리도 같은 방식으로 해소해야 비교가 성립한다 — `/var` → `/private/var` 처럼 뿌리만
+        // 링크를 지나면 제 파일이 전부 '밖'이 된다(§17b 가 훅에서 배운 것과 같은 함정).
+        const rootLanding = (() => { try {
+            return fs.realpathSync(rootReal);
+        }
+        catch {
+            return rootReal;
+        } })();
+        const contained = (x, base) => x === base || x.startsWith(base + path.sep);
+        if (!contained(abs, rootReal) || !contained(landing, rootLanding)) {
+            refused.push({ file, aspec, reason: 'path resolves outside the root' });
+            continue;
+        }
+        let code;
+        try {
+            code = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            refused.push({ file, aspec, reason: 'unreadable' });
+            continue;
+        }
+        if (new RegExp(`@implements\\s+${aspec.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(code)) {
+            refused.push({ file, aspec, reason: 'already anchored' });
+            continue;
+        }
+        planned.add(keyOf(file, aspec));
+        edits.push({
+            file, aspec,
+            insert: `${prefixFor(file)} @implements ${aspec}\n`,
+            // A shebang must stay executable: line 1 is reserved for it.
+            atLine: /^#!/.test(code) ? 1 : 0,
+        });
+    }
+    return { edits, refused };
+}
+/** Apply an anchor plan. DRY-RUN BY DEFAULT: writing requires an explicit `dryRun: false`. */
+function applyAnchors(root, edits, opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    if (dryRun)
+        return { applied: 0, dryRun: true, would: edits.length, failed: [] };
+    let applied = 0;
+    const failed = [];
+    for (const e of edits) {
+        try {
+            const abs = path.join(root, e.file);
+            const code = fs.readFileSync(abs, 'utf8');
+            // Match the file's own line ending. Splicing an LF line into a CRLF file leaves one stray
+            // ending, which reads as a whole-file change in some tooling and a lint error in others —
+            // noise attributable to the anchor rather than to the code. Brownfield trees have both.
+            const eol = code.includes('\r\n') ? '\r\n' : '\n';
+            const lines = code.split(eol);
+            lines.splice(e.atLine, 0, e.insert.replace(/\n$/, ''));
+            fs.writeFileSync(abs, lines.join(eol));
+            applied++;
+        }
+        catch (err) {
+            // Fail-safe: one unwritable file yields fewer anchors, never a corrupted tree or a lost report.
+            failed.push({ file: e.file, aspec: e.aspec, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { applied, dryRun: false, would: edits.length, failed };
+}