@opengsd/gsd-core 1.2.0 → 1.3.0

package/{get-shit-done → gsd-core}/bin/lib/decisions.cjs

@@ -1,12 +1,16 @@
-'use strict';
-
+"use strict";
 /**
- * Shared parser for CONTEXT.md <decisions> blocks.
+ * Shared parser for CONTEXT.md <decisions> blocks (ADR-457 build-at-publish:
+ * the hand-written bin/lib/decisions.cjs collapsed to a TypeScript source of
+ * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
+ * .cjs; only types are added.
+ *
  * Accepts both numeric (D-42) and alphanumeric (D-INFRA-01) IDs.
  * Returns {id, text, category, tags, trackable} per decision.
  * CJS callers that only use {id, text} safely ignore the extra fields.
  */
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDecisions = parseDecisions;
 const DISCRETION_HEADINGS = new Set([
     "claude's discretion",
     'claudes discretion',
@@ -79,7 +83,7 @@ function parseDecisions(content) {
             // (review F20).
             const normalized = category
                 .toLowerCase()
-                .replace(/[\u2018\u2019\u201A\u201B\u201C\u201D\u201E\u201F'"`]/g, '')
+                .replace(/[‘’‚‛“”„‟'"`]/g, '')
                 .trim();
             inDiscretion = DISCRETION_HEADINGS.has(normalized);
             continue;
@@ -112,5 +116,3 @@ function parseDecisions(content) {
     flush();
     return out;
 }
-
-module.exports = { parseDecisions };

package/gsd-core/bin/lib/docs.cjs

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Docs — Commands for the docs-update workflow
+ *
+ * Provides `cmdDocsInit` which returns project signals, existing doc inventory
+ * with GSD marker detection, doc tooling detection, monorepo awareness, and
+ * model resolution. Used by Phase 2 to route doc generation appropriately.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/docs.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output, loadConfig, resolveModelInternal, pathExistsInternal, toPosixPath, checkAgentsInstalled } = core;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.planning', '.claude', '__pycache__',
+    'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+    '.vscode', '.idea',
+]);
+// ─── Private helpers ──────────────────────────────────────────────────────────
+/**
+ * Check whether a file begins with the GSD doc writer marker.
+ * Reads the first 500 bytes only — avoids loading large files.
+ */
+function hasGsdMarker(filePath) {
+    try {
+        const buf = Buffer.alloc(500);
+        const fd = node_fs_1.default.openSync(filePath, 'r');
+        const bytesRead = node_fs_1.default.readSync(fd, buf, 0, 500, 0);
+        node_fs_1.default.closeSync(fd);
+        return buf.slice(0, bytesRead).toString('utf-8').includes(GSD_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively scan the project root (immediate .md files) and docs/ directory
+ * (up to 4 levels deep) for Markdown files, excluding dirs in SKIP_DIRS.
+ */
+function scanExistingDocs(cwd) {
+    const MAX_DEPTH = 4;
+    const results = [];
+    function walkDir(dir, depth) {
+        if (depth > MAX_DEPTH)
+            return;
+        try {
+            const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                const abs = node_path_1.default.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walkDir(abs, depth + 1);
+                }
+                else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+                    const rel = toPosixPath(node_path_1.default.relative(cwd, abs));
+                    results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+                }
+            }
+        }
+        catch { /* directory may not exist — best-effort */ }
+    }
+    // Scan root-level .md files (non-recursive)
+    try {
+        const entries = node_fs_1.default.readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+                const abs = node_path_1.default.join(cwd, entry.name);
+                const rel = toPosixPath(node_path_1.default.relative(cwd, abs));
+                results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+            }
+        }
+    }
+    catch { /* best-effort */ }
+    // Recursively scan docs/ directory
+    const docsDir = node_path_1.default.join(cwd, 'docs');
+    walkDir(docsDir, 1);
+    // Fallback: if docs/ does not exist, try documentation/ or doc/
+    try {
+        node_fs_1.default.statSync(docsDir);
+    }
+    catch {
+        const alternatives = ['documentation', 'doc'];
+        for (const alt of alternatives) {
+            const altDir = node_path_1.default.join(cwd, alt);
+            try {
+                const stat = node_fs_1.default.statSync(altDir);
+                if (stat.isDirectory()) {
+                    walkDir(altDir, 1);
+                    break;
+                }
+            }
+            catch { /* not present */ }
+        }
+    }
+    return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Detect project type signals from the filesystem and package.json.
+ * All checks are best-effort and never throw.
+ */
+function detectProjectType(cwd) {
+    const exists = (rel) => {
+        try {
+            return pathExistsInternal(cwd, rel);
+        }
+        catch {
+            return false;
+        }
+    };
+    // Read package.json once — used by has_cli_bin, is_monorepo, has_tests checks.
+    const pkgRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'package.json'));
+    let pkg = null;
+    if (pkgRaw) {
+        try {
+            pkg = JSON.parse(pkgRaw);
+        }
+        catch { /* invalid JSON */ }
+    }
+    // has_cli_bin: package.json has a `bin` field
+    const binField = pkg?.['bin'];
+    const has_cli_bin = !!(binField && (typeof binField === 'string' ||
+        (typeof binField === 'object' && Object.keys(binField).length > 0)));
+    // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+    let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+    if (!is_monorepo && pkg) {
+        is_monorepo = Array.isArray(pkg['workspaces']) && pkg['workspaces'].length > 0;
+    }
+    // has_tests: common test directories or test frameworks in devDependencies
+    let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+    if (!has_tests && pkg) {
+        const devDeps = Object.keys(pkg['devDependencies'] || {});
+        has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    }
+    // has_deploy_config: various deployment config files
+    const deployFiles = [
+        'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+        'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+        '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+    ];
+    const has_deploy_config = deployFiles.some(f => exists(f));
+    return {
+        has_package_json: exists('package.json'),
+        has_api_routes: (exists('src/app/api') || exists('routes') || exists('src/routes') ||
+            exists('api') || exists('server')),
+        has_cli_bin,
+        is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+        has_deploy_config,
+        is_monorepo,
+        has_tests,
+    };
+}
+/**
+ * Detect known documentation tooling in the project.
+ */
+function detectDocTooling(cwd) {
+    const exists = (rel) => {
+        try {
+            return pathExistsInternal(cwd, rel);
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+        vitepress: (exists('.vitepress/config.js') ||
+            exists('.vitepress/config.ts') ||
+            exists('.vitepress/config.mts')),
+        mkdocs: exists('mkdocs.yml'),
+        storybook: exists('.storybook'),
+    };
+}
+/**
+ * Extract monorepo workspace globs from pnpm-workspace.yaml, package.json
+ * workspaces, or lerna.json.
+ */
+function detectMonorepoWorkspaces(cwd) {
+    // pnpm-workspace.yaml
+    const pnpmRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'pnpm-workspace.yaml'));
+    if (pnpmRaw) {
+        const workspaces = [];
+        for (const line of pnpmRaw.split('\n')) {
+            const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+            if (m)
+                workspaces.push(m[1].trim());
+        }
+        if (workspaces.length > 0)
+            return workspaces;
+    }
+    // package.json workspaces
+    const pkgRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'package.json'));
+    if (pkgRaw) {
+        try {
+            const pkg = JSON.parse(pkgRaw);
+            if (Array.isArray(pkg['workspaces']) && pkg['workspaces'].length > 0) {
+                return pkg['workspaces'];
+            }
+        }
+        catch { /* invalid JSON */ }
+    }
+    // lerna.json
+    const lernaRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'lerna.json'));
+    if (lernaRaw) {
+        try {
+            const lerna = JSON.parse(lernaRaw);
+            if (Array.isArray(lerna['packages']) && lerna['packages'].length > 0) {
+                return lerna['packages'];
+            }
+        }
+        catch { /* invalid JSON */ }
+    }
+    return [];
+}
+// ─── Public commands ──────────────────────────────────────────────────────────
+/**
+ * Return JSON context for the docs-update workflow: project signals, existing
+ * doc inventory, doc tooling detection, monorepo workspaces, and model
+ * resolution. Follows the cmdInitMapCodebase pattern.
+ *
+ * @example
+ * node gsd-tools.cjs docs-init --raw
+ */
+function cmdDocsInit(cwd, raw) {
+    const config = loadConfig(cwd);
+    const result = {
+        doc_writer_model: resolveModelInternal(cwd, 'gsd-doc-writer'),
+        commit_docs: config.commit_docs,
+        existing_docs: scanExistingDocs(cwd),
+        project_type: detectProjectType(cwd),
+        doc_tooling: detectDocTooling(cwd),
+        monorepo_workspaces: detectMonorepoWorkspaces(cwd),
+        planning_exists: pathExistsInternal(cwd, '.planning'),
+    };
+    // Inject project_root and agent installation status (mirrors withProjectRoot in init.cjs)
+    result['project_root'] = cwd;
+    const agentStatus = checkAgentsInstalled();
+    result['agents_installed'] = agentStatus.agents_installed;
+    result['missing_agents'] = agentStatus.missing_agents;
+    output(result, raw, undefined);
+}
+module.exports = { cmdDocsInit };

package/gsd-core/bin/lib/drift.cjs

@@ -0,0 +1,364 @@
+/**
+ * Codebase Drift Detection (#2003)
+ *
+ * Detects structural drift between a committed codebase and the
+ * `.planning/codebase/STRUCTURE.md` map produced by `gsd-codebase-mapper`.
+ *
+ * Four categories of drift element:
+ *   - new_dir    → a newly-added file whose directory prefix does not appear
+ *                  in STRUCTURE.md
+ *   - barrel     → a newly-added barrel export at
+ *                  (packages|apps)/<name>/src/index.(ts|tsx|js|mjs|cjs)
+ *   - migration  → a newly-added migration file under one of the recognized
+ *                  migration directories (supabase, prisma, drizzle, src/migrations, …)
+ *   - route      → a newly-added route module under a `routes/` or `api/` dir
+ *
+ * Each file is counted at most once; when a file matches multiple categories
+ * the most specific category wins (migration > route > barrel > new_dir).
+ *
+ * Design decisions (see PR for full rubber-duck):
+ *   - The library is pure. It takes parsed git diff output and returns a
+ *     structured result. The CLI/workflow layer is responsible for running
+ *     git and for spawning mappers.
+ *   - `last_mapped_commit` is stored as YAML-style frontmatter at the top of
+ *     each `.planning/codebase/*.md` file. This keeps the baseline attached
+ *     to the file, survives git moves, and avoids a sidecar JSON.
+ *   - The detector NEVER throws on malformed input — it returns a
+ *     `{ skipped: true }` result. The phase workflow depends on this
+ *     non-blocking guarantee.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/drift.cjs collapsed to
+ * a TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DRIFT_CATEGORIES = Object.freeze(['new_dir', 'barrel', 'migration', 'route']);
+// Category priority when a single file matches multiple rules.
+// Higher index = more specific = wins.
+const CATEGORY_PRIORITY = { new_dir: 0, barrel: 1, route: 2, migration: 3 };
+const BARREL_RE = /^(packages|apps)\/[^/]+\/src\/index\.(ts|tsx|js|mjs|cjs)$/;
+const MIGRATION_RES = [
+    /^supabase\/migrations\/.+\.sql$/,
+    /^prisma\/migrations\/.+/,
+    /^drizzle\/meta\/.+/,
+    /^drizzle\/migrations\/.+/,
+    /^src\/migrations\/.+\.(ts|js|sql)$/,
+    /^db\/migrations\/.+\.(sql|ts|js)$/,
+    /^migrations\/.+\.(sql|ts|js)$/,
+];
+const ROUTE_RES = [
+    /^(apps|packages)\/[^/]+\/src\/routes\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+    /^src\/routes\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+    /^src\/api\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+    /^(apps|packages)\/[^/]+\/src\/api\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/,
+];
+// A conservative allowlist for `--paths` arguments passed to the mapper:
+// repo-relative path components separated by /, containing only
+// alphanumerics, dash, underscore, and dot (no `..`, no `/..`).
+const SAFE_PATH_RE = /^(?!.*\.\.)(?:[A-Za-z0-9_.][A-Za-z0-9_.\-]*)(?:\/[A-Za-z0-9_.][A-Za-z0-9_.\-]*)*$/;
+/**
+ * Classify a single file path into a drift category or null.
+ */
+function classifyFile(file) {
+    if (typeof file !== 'string' || !file)
+        return null;
+    const norm = file.replace(/\\/g, '/');
+    if (MIGRATION_RES.some((r) => r.test(norm)))
+        return 'migration';
+    if (ROUTE_RES.some((r) => r.test(norm)))
+        return 'route';
+    if (BARREL_RE.test(norm))
+        return 'barrel';
+    return null;
+}
+/**
+ * True iff any prefix of `file` (dir1, dir1/dir2, …) appears as a substring
+ * of `structureMd`. Used to decide whether a file is in "mapped territory".
+ *
+ * Matching is deliberately substring-based — STRUCTURE.md is free-form
+ * markdown, not a structured manifest. If the map mentions `src/lib/` the
+ * check `structureMd.includes('src/lib')` holds.
+ */
+function isPathMapped(file, structureMd) {
+    const norm = file.replace(/\\/g, '/');
+    const parts = norm.split('/');
+    // Check prefixes from longest to shortest; any hit means "mapped".
+    for (let i = parts.length - 1; i >= 1; i--) {
+        const prefix = parts.slice(0, i).join('/');
+        if (structureMd.includes(prefix))
+            return true;
+    }
+    // Finally, if even the top-level dir is mentioned, count as mapped.
+    if (parts.length > 0 && structureMd.includes(parts[0] + '/'))
+        return true;
+    if (parts.length > 0 && structureMd.includes('`' + parts[0] + '`'))
+        return true;
+    return false;
+}
+// ─── Main detection ──────────────────────────────────────────────────────────
+/**
+ * Detect codebase drift.
+ */
+function detectDrift(input) {
+    try {
+        if (!input || typeof input !== 'object') {
+            return skipped('invalid-input');
+        }
+        const inp = input;
+        const { addedFiles, modifiedFiles, deletedFiles, structureMd, } = inp;
+        const threshold = Number.isInteger(inp.threshold) && inp.threshold >= 1
+            ? inp.threshold
+            : 3;
+        const action = inp.action === 'auto-remap' ? 'auto-remap' : 'warn';
+        if (structureMd === null || structureMd === undefined) {
+            return skipped('missing-structure-md');
+        }
+        if (typeof structureMd !== 'string') {
+            return skipped('invalid-structure-md');
+        }
+        const added = Array.isArray(addedFiles) ? addedFiles.filter((x) => typeof x === 'string') : [];
+        const modified = Array.isArray(modifiedFiles) ? modifiedFiles : [];
+        const deleted = Array.isArray(deletedFiles) ? deletedFiles : [];
+        // Build elements. One element per file, highest-priority category wins.
+        const elements = [];
+        const seen = new Map();
+        for (const rawFile of added) {
+            const file = rawFile.replace(/\\/g, '/');
+            const specific = classifyFile(file);
+            let category = specific;
+            if (!category) {
+                if (!isPathMapped(file, structureMd)) {
+                    category = 'new_dir';
+                }
+                else {
+                    continue; // mapped, known, ordinary file — not drift
+                }
+            }
+            // Dedup: if we've already counted this path at higher-or-equal priority, skip
+            const prior = seen.get(file);
+            if (prior && CATEGORY_PRIORITY[prior] >= CATEGORY_PRIORITY[category])
+                continue;
+            seen.set(file, category);
+        }
+        for (const [file, category] of seen.entries()) {
+            elements.push({ category, path: file });
+        }
+        // Sort for stable output.
+        elements.sort((a, b) => a.category === b.category
+            ? a.path.localeCompare(b.path)
+            : a.category.localeCompare(b.category));
+        const actionRequired = elements.length >= threshold;
+        let directive = 'none';
+        let spawnMapper = false;
+        let affectedPaths = [];
+        let message = '';
+        if (actionRequired) {
+            directive = action;
+            affectedPaths = chooseAffectedPaths(elements.map((e) => e.path));
+            if (action === 'auto-remap') {
+                spawnMapper = true;
+            }
+            message = buildMessage(elements, affectedPaths, action, inp.runtime);
+        }
+        return {
+            skipped: false,
+            elements,
+            actionRequired,
+            directive,
+            spawnMapper,
+            affectedPaths,
+            threshold,
+            action,
+            message,
+            counts: {
+                added: added.length,
+                modified: modified.length,
+                deleted: deleted.length,
+            },
+        };
+    }
+    catch (err) {
+        // Non-blocking: never throw from this function.
+        const errMsg = err?.message ? err.message : String(err);
+        return skipped('exception:' + errMsg);
+    }
+}
+function skipped(reason) {
+    return {
+        skipped: true,
+        reason,
+        elements: [],
+        actionRequired: false,
+        directive: 'none',
+        spawnMapper: false,
+        affectedPaths: [],
+        message: '',
+    };
+}
+function buildMessage(elements, affectedPaths, action, runtime) {
+    const byCat = {};
+    for (const e of elements) {
+        if (!byCat[e.category])
+            byCat[e.category] = [];
+        byCat[e.category].push(e.path);
+    }
+    const lines = [
+        `Codebase drift detected: ${elements.length} structural element(s) since last mapping.`,
+        '',
+    ];
+    const labels = {
+        new_dir: 'New directories',
+        barrel: 'New barrel exports',
+        migration: 'New migrations',
+        route: 'New route modules',
+    };
+    for (const cat of ['new_dir', 'barrel', 'migration', 'route']) {
+        if (byCat[cat]) {
+            lines.push(`${labels[cat]}:`);
+            for (const p of byCat[cat])
+                lines.push(`  - ${p}`);
+        }
+    }
+    lines.push('');
+    if (action === 'auto-remap') {
+        lines.push(`Auto-remap scheduled for paths: ${affectedPaths.join(', ')}`);
+    }
+    else {
+        // drift.cts is a pure library — it must never read env/config. The
+        // caller (verify.cmdVerifyCodebaseDrift) resolves the runtime once and
+        // passes it in via input.runtime so emitted commands match the project
+        // the caller is targeting, not the current process directory.
+        const mapCmd = (0, runtime_slash_cjs_1.formatGsdSlash)('map-codebase', runtime || 'claude');
+        lines.push(`Run ${String(mapCmd)} --paths ${affectedPaths.join(',')} to refresh planning context.`);
+    }
+    return lines.join('\n');
+}
+// ─── Affected paths ──────────────────────────────────────────────────────────
+/**
+ * Collapse a list of drifted file paths into a sorted, deduplicated list of
+ * the top-level directory prefixes (depth 2 when the repo uses an
+ * `<apps|packages>/<name>/…` layout; depth 1 otherwise).
+ */
+function chooseAffectedPaths(paths) {
+    const out = new Set();
+    for (const raw of paths || []) {
+        if (typeof raw !== 'string' || !raw)
+            continue;
+        const file = raw.replace(/\\/g, '/');
+        const parts = file.split('/');
+        if (parts.length === 0)
+            continue;
+        const top = parts[0];
+        if ((top === 'apps' || top === 'packages') && parts.length >= 2) {
+            out.add(`${top}/${parts[1]}`);
+        }
+        else {
+            out.add(top);
+        }
+    }
+    return [...out].sort();
+}
+/**
+ * Filter `paths` to only those that are safe to splice into a mapper prompt.
+ * Any path that is absolute, contains traversal, or includes shell
+ * metacharacters is dropped.
+ */
+function sanitizePaths(paths) {
+    if (!Array.isArray(paths))
+        return [];
+    const out = [];
+    for (const p of paths) {
+        if (typeof p !== 'string')
+            continue;
+        if (p.startsWith('/'))
+            continue;
+        if (!SAFE_PATH_RE.test(p))
+            continue;
+        out.push(p);
+    }
+    return out;
+}
+// ─── Frontmatter helpers ─────────────────────────────────────────────────────
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function parseFrontmatter(content) {
+    if (typeof content !== 'string')
+        return { data: {}, body: '' };
+    const m = content.match(FRONTMATTER_RE);
+    if (!m)
+        return { data: {}, body: content };
+    const data = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z0-9_][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (!kv)
+            continue;
+        data[kv[1]] = kv[2];
+    }
+    return { data, body: content.slice(m[0].length) };
+}
+function serializeFrontmatter(data, body) {
+    const keys = Object.keys(data);
+    if (keys.length === 0)
+        return body;
+    const lines = ['---'];
+    for (const k of keys)
+        lines.push(`${k}: ${data[k]}`);
+    lines.push('---');
+    return lines.join('\n') + '\n' + body;
+}
+/**
+ * Read `last_mapped_commit` from the frontmatter of a `.planning/codebase/*.md`
+ * file. Returns null if the file does not exist or has no frontmatter.
+ */
+function readMappedCommit(filePath) {
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const { data } = parseFrontmatter(content);
+    const sha = data['last_mapped_commit'];
+    return typeof sha === 'string' && sha.length > 0 ? sha : null;
+}
+/**
+ * Upsert `last_mapped_commit` and `last_mapped_at` into the frontmatter of
+ * the given file, preserving any other frontmatter keys and the body.
+ */
+function writeMappedCommit(filePath, commitSha, isoDate) {
+    // Symmetric with readMappedCommit (which returns null on missing files):
+    // tolerate a missing target by creating a minimal frontmatter-only file
+    // rather than throwing ENOENT. This matters when a mapper produces a new
+    // doc and the caller stamps it before any prior content existed.
+    let content = '';
+    try {
+        content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    const { data, body } = parseFrontmatter(content);
+    data['last_mapped_commit'] = commitSha;
+    if (isoDate)
+        data['last_mapped_at'] = isoDate;
+    (0, shell_command_projection_cjs_1.platformWriteSync)(filePath, serializeFrontmatter(data, body));
+}
+module.exports = {
+    DRIFT_CATEGORIES,
+    classifyFile,
+    detectDrift,
+    chooseAffectedPaths,
+    sanitizePaths,
+    readMappedCommit,
+    writeMappedCommit,
+    // Exposed for the CLI layer to reuse the same parser.
+    parseFrontmatter,
+};