@aperant/framework 0.6.6 → 0.7.0

package/dist/cli/install/runtime-migrate.mjs

@@ -0,0 +1,244 @@
+/**
+ * install/runtime-migrate.mjs — at-install cleanup of legacy install
+ * trees the framework no longer owns (FRAMEWORK-BUG-021).
+ *
+ * Codex was originally installed into `.agents/skills/` (commit 1a8dd8a8)
+ * and later moved to `.codex/`. Projects that upgraded across that move
+ * end up with a stale `.agents/skills/` tree that:
+ *
+ *   - keeps `.apt-version` on disk → the legacy fallback in
+ *     `readSkillInstallState` reports a stale codex install.
+ *   - shows up in `health-check` as `stale-skills`.
+ *   - leaves dozens of orphaned SKILL.md files the runtime no longer
+ *     reads.
+ *
+ * `runLegacyCleanup` runs once per `apt-tools init` when codex is in the
+ * requested runtime set. It is conservative by default:
+ *
+ *   - Only files listed in `LEGACY_INSTALL_PATHS.codex.framework_files`
+ *     are removed. User-added skill directories (`my-skill/`, …) are
+ *     preserved. If anything beyond the known framework set remains,
+ *     `retained[]` lists those paths.
+ *   - A present-and-current `apt-file-manifest.json` is treated as the
+ *     authoritative "this is a managed install, leave it alone" signal:
+ *     the function no-ops with `reason: 'managed'`.
+ *   - The caller can suppress cleanup entirely via `--keep-legacy` at the
+ *     init.mjs site; the function itself is dumb about flags.
+ */
+import { existsSync, readdirSync, rmdirSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LEGACY_INSTALL_PATHS } from './legacy-paths.mjs';
+import { MANIFEST_FILENAME } from './manifest.mjs';
+/**
+ * @typedef {Object} LegacyCodexDetection
+ * @property {boolean} present              True when `.agents/skills/` exists.
+ * @property {string[]} frameworkFiles      Subset of `framework_files` that
+ *                                          actually exist on disk (relative
+ *                                          to install_root).
+ * @property {string[]} userFiles           Everything else under
+ *                                          install_root (relative to
+ *                                          install_root). May include both
+ *                                          files and directories. Drives the
+ *                                          `retained[]` warning.
+ * @property {boolean} hasAptVersion        Whether the legacy `.apt-version`
+ *                                          stamp is present.
+ * @property {boolean} hasManifest          Whether an
+ *                                          `apt-file-manifest.json` is
+ *                                          present at install_root (signals
+ *                                          a managed install — cleanup
+ *                                          should no-op).
+ */
+const LEGACY = LEGACY_INSTALL_PATHS.codex;
+/**
+ * Recursively enumerate every file path under `dir`, returning paths
+ * relative to `dir`. Used to compute the "user files" set (anything not
+ * in the framework_files list).
+ *
+ * Returns []  when the dir doesn't exist. Swallows per-entry errors so a
+ * single unreadable symlink doesn't abort detection.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkRelative(dir) {
+    /** @type {string[]} */
+    const out = [];
+    if (!existsSync(dir))
+        return out;
+    /** @param {string} current @param {string} rel */
+    const visit = (current, rel) => {
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const childPath = join(current, entry.name);
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                visit(childPath, childRel);
+            }
+            else if (entry.isFile()) {
+                out.push(childRel);
+            }
+            // Symlinks / other entry types are intentionally ignored — the
+            // framework only ever writes regular files.
+        }
+    };
+    visit(dir, '');
+    return out;
+}
+/**
+ * Probe the codex legacy install tree at `<targetDir>/.agents/skills/`.
+ *
+ * @param {string} targetDir
+ * @returns {LegacyCodexDetection}
+ */
+export function detectLegacyCodexTree(targetDir) {
+    const installRoot = join(targetDir, LEGACY.install_root);
+    if (!existsSync(installRoot)) {
+        return {
+            present: false,
+            frameworkFiles: [],
+            userFiles: [],
+            hasAptVersion: false,
+            hasManifest: false,
+        };
+    }
+    const onDisk = walkRelative(installRoot);
+    const frameworkSet = new Set(LEGACY.framework_files);
+    const frameworkFiles = onDisk.filter((p) => frameworkSet.has(p));
+    const userFiles = onDisk.filter((p) => !frameworkSet.has(p) && p !== MANIFEST_FILENAME);
+    return {
+        present: true,
+        frameworkFiles,
+        userFiles,
+        hasAptVersion: onDisk.includes('.apt-version'),
+        hasManifest: onDisk.includes(MANIFEST_FILENAME),
+    };
+}
+/**
+ * Try to remove a directory if it is empty. Swallows ENOTEMPTY / ENOENT
+ * so the caller can blindly sweep candidate dirs in any order.
+ *
+ * @param {string} dir
+ * @returns {boolean} true iff the dir was actually removed.
+ */
+function rmEmptyDir(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        rmdirSync(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clean up the legacy `.agents/skills/` tree if it looks orphaned.
+ *
+ * Branches:
+ *   1. `present: false` OR `frameworkFiles.length === 0` → no-op,
+ *      `{ ran: false, reason: 'no-legacy' }`.
+ *   2. `hasManifest: true` → managed install, no-op,
+ *      `{ ran: false, reason: 'managed' }`.
+ *   3. Otherwise: per-file `unlinkSync` each framework-owned file;
+ *      `rmdirSync` any now-empty `apt-*` subdirectory; sweep
+ *      `.agents/skills/` only if it is empty; sweep `.agents/` only if
+ *      its `skills/` got removed and `.agents/` is empty.
+ *
+ * Returns `{ ran: true, removed, retained, rmdirs }` on the cleanup
+ * branch:
+ *   - `removed`  — relative paths under `install_root` that were unlinked.
+ *   - `retained` — relative paths under `install_root` that were NOT
+ *     removed (user-added skills / files not in the legacy set).
+ *   - `rmdirs`   — absolute paths of directories that were removed
+ *     (apt-* subdirs, the install_root itself, .agents/), in removal order.
+ *
+ * Atomicity: per-file unlink is non-atomic. A partial-failure scenario
+ * (process killed mid-loop) is tolerable — the next `init` run will
+ * re-detect the remaining framework files and finish the sweep.
+ *
+ * @param {{ targetDir: string, dryRun?: boolean }} args
+ * @returns {
+ *   | { ran: false, reason: 'no-legacy' | 'managed' }
+ *   | { ran: true, removed: string[], retained: string[], rmdirs: string[] }
+ * }
+ */
+export function runLegacyCleanup({ targetDir, dryRun = false }) {
+    const detection = detectLegacyCodexTree(targetDir);
+    if (!detection.present || detection.frameworkFiles.length === 0) {
+        return { ran: false, reason: 'no-legacy' };
+    }
+    if (detection.hasManifest) {
+        return { ran: false, reason: 'managed' };
+    }
+    const installRoot = join(targetDir, LEGACY.install_root);
+    const removed = [];
+    const rmdirs = [];
+    if (dryRun) {
+        // Dry-run: report what WOULD be removed without touching the filesystem.
+        // `retained` is the user-file set from the pre-walk (no sweep occurred).
+        // `rmdirs` is the set of apt-* subdirs that would become empty after removal.
+        const wouldRemove = detection.frameworkFiles;
+        const retained = detection.userFiles;
+        const candidateDirs = new Set();
+        for (const rel of wouldRemove) {
+            let parent = dirname(rel);
+            while (parent !== '.' && parent !== '') {
+                candidateDirs.add(parent);
+                parent = dirname(parent);
+            }
+        }
+        const wouldRmdirs = [...candidateDirs]
+            .sort((a, b) => b.length - a.length)
+            .map((rel) => join(installRoot, rel));
+        return { ran: true, dryRun: true, removed: wouldRemove, retained, rmdirs: wouldRmdirs };
+    }
+    for (const rel of detection.frameworkFiles) {
+        const abs = join(installRoot, rel);
+        try {
+            unlinkSync(abs);
+            removed.push(rel);
+        }
+        catch {
+            /* best-effort: leave a partial sweep; next run finishes it */
+        }
+    }
+    // Sweep any now-empty `apt-*/` subdirs the unlinks left behind.
+    // Walk parent dirs of every removed file in reverse-depth order so
+    // nested `apt-pr-review/prompts/` empties before `apt-pr-review/`.
+    const candidateDirs = new Set();
+    for (const rel of removed) {
+        let parent = dirname(rel);
+        while (parent !== '.' && parent !== '') {
+            candidateDirs.add(parent);
+            parent = dirname(parent);
+        }
+    }
+    const sortedDirs = [...candidateDirs].sort((a, b) => b.length - a.length);
+    for (const rel of sortedDirs) {
+        const abs = join(installRoot, rel);
+        if (rmEmptyDir(abs))
+            rmdirs.push(abs);
+    }
+    // Sweep `.agents/skills/` only if fully empty after the per-file
+    // pass — preserves any user-added skill dirs.
+    if (rmEmptyDir(installRoot)) {
+        rmdirs.push(installRoot);
+        // Sweep `.agents/` only if it became empty too (i.e. no other
+        // `.agents/<sibling>` content the user keeps there).
+        const agentsRoot = dirname(installRoot);
+        if (rmEmptyDir(agentsRoot))
+            rmdirs.push(agentsRoot);
+    }
+    // Use the pre-walk's userFiles as `retained` — the post-walk only existed
+    // to defensively re-scan, but pre-walk already captured user files accurately.
+    // (PRF-002: avoid redundant detectLegacyCodexTree call.)
+    const retained = detection.userFiles;
+    return { ran: true, removed, retained, rmdirs };
+}
+//# sourceMappingURL=runtime-migrate.mjs.map

package/dist/cli/install/runtime-migrate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-migrate.mjs","sourceRoot":"","sources":["../../../src/cli/install/runtime-migrate.mjs"],"names":[],"mappings":"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"}

package/dist/cli/install/update-chips.d.mts

@@ -21,6 +21,29 @@ export function updateCachePath(): string;
  * @returns {UpdateCache|null}
  */
 export function readUpdateCache(): UpdateCache | null;
+/**
+ * Read the worker's cache file with TTL and schema validation. Returns
+ * `{ fresh: true, cache }` when the cache exists, parses, declares
+ * `schema_version === 1`, and was written within `ttlMs` milliseconds.
+ * Returns `{ fresh: false }` when missing, stale, or schema mismatch.
+ *
+ * Security: `latest_version` and `installed_version` inside
+ * `cache.framework` are validated as semver strings. Invalid values are
+ * dropped (set to null) so they never propagate into shell-interpolated
+ * contexts.
+ *
+ * ENOENT and JSON parse errors stay silent (expected when the cache is
+ * missing or being rewritten). Unexpected errors are logged to stderr.
+ *
+ * @param {number} ttlMs  Maximum age in milliseconds before cache is treated as stale.
+ * @returns {{ fresh: true, cache: Record<string, unknown> } | { fresh: false }}
+ */
+export function readFreshUpdateCache(ttlMs: number): {
+    fresh: true;
+    cache: Record<string, unknown>;
+} | {
+    fresh: false;
+};
 /**
  * Build the chip string array for a given cache. Empty array when there
  * are no chips to show. Order: stale_files first (most urgent), then

package/dist/cli/install/update-chips.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"update-chips.d.mts","sourceRoot":"","sources":["../../../src/cli/install/update-chips.mjs"],"names":[],"mappings":"AAwBA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,mCAFa,MAAM,CAIlB;AAED;;;;;GAKG;AACH,mCAFa,WAAW,GAAC,IAAI,CAY5B;AAED;;;;;;;;GAQG;AACH,yCAJW,WAAW,GAAC,IAAI,aAChB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAChB,MAAM,EAAE,CA0BpB;;mBArEa,OAAO;sBACP,OAAO;uBACP,OAAO;uBACP,MAAM;gBACN,MAAM"}
+{"version":3,"file":"update-chips.d.mts","sourceRoot":"","sources":["../../../src/cli/install/update-chips.mjs"],"names":[],"mappings":"AAwBA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,mCAFa,MAAM,CAIlB;AAED;;;;;GAKG;AACH,mCAFa,WAAW,GAAC,IAAI,CAY5B;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,4CAHW,MAAM,GACJ;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAqC9E;AAED;;;;;;;;GAQG;AACH,yCAJW,WAAW,GAAC,IAAI,aAChB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAChB,MAAM,EAAE,CA0BpB;;mBA9Ha,OAAO;sBACP,OAAO;uBACP,OAAO;uBACP,MAAM;gBACN,MAAM"}

package/dist/cli/install/update-chips.mjs

@@ -57,6 +57,66 @@ export function readUpdateCache() {
         return null;
     }
 }
+/** Semver-shape pattern: MAJOR.MINOR.PATCH with optional pre-release and build metadata. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Read the worker's cache file with TTL and schema validation. Returns
+ * `{ fresh: true, cache }` when the cache exists, parses, declares
+ * `schema_version === 1`, and was written within `ttlMs` milliseconds.
+ * Returns `{ fresh: false }` when missing, stale, or schema mismatch.
+ *
+ * Security: `latest_version` and `installed_version` inside
+ * `cache.framework` are validated as semver strings. Invalid values are
+ * dropped (set to null) so they never propagate into shell-interpolated
+ * contexts.
+ *
+ * ENOENT and JSON parse errors stay silent (expected when the cache is
+ * missing or being rewritten). Unexpected errors are logged to stderr.
+ *
+ * @param {number} ttlMs  Maximum age in milliseconds before cache is treated as stale.
+ * @returns {{ fresh: true, cache: Record<string, unknown> } | { fresh: false }}
+ */
+export function readFreshUpdateCache(ttlMs) {
+    const path = updateCachePath();
+    if (!existsSync(path))
+        return { fresh: false };
+    let data;
+    try {
+        data = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        // SyntaxError = malformed JSON (expected); anything else is unexpected.
+        if (!(err instanceof SyntaxError)) {
+            console.error('[update-cache] read failed:', err.message);
+        }
+        return { fresh: false };
+    }
+    try {
+        if (!data || typeof data !== 'object')
+            return { fresh: false };
+        if (data.schema_version !== 1)
+            return { fresh: false };
+        if (typeof data.checked_at !== 'string')
+            return { fresh: false };
+        const age = Date.now() - new Date(data.checked_at).getTime();
+        if (!Number.isFinite(age) || age < 0 || age >= ttlMs)
+            return { fresh: false };
+        // Validate semver fields in framework block — reject non-semver strings.
+        const fw = data.framework && typeof data.framework === 'object' ? data.framework : {};
+        const sanitized = { ...data, framework: { ...fw } };
+        for (const field of ['latest_version', 'installed_version']) {
+            if (typeof sanitized.framework[field] === 'string' &&
+                !SEMVER_RE.test(sanitized.framework[field])) {
+                sanitized.framework[field] = null;
+            }
+        }
+        return { fresh: true, cache: sanitized };
+    }
+    catch (err) {
+        console.error('[update-cache] read failed:', err.message);
+        return { fresh: false };
+    }
+}
 /**
  * Build the chip string array for a given cache. Empty array when there
  * are no chips to show. Order: stale_files first (most urgent), then

package/dist/cli/install/update-chips.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"update-chips.mjs","sourceRoot":"","sources":["../../../src/cli/install/update-chips.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,IAAI,GAAG;IACZ,MAAM,EAAE,UAAU;IAClB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,SAAS;IACd,KAAK,EAAE,SAAS;CAChB,CAAA;AAED;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC9B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,uBAAuB,CAAC,CAAA;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,IAAI,GAAG,eAAe,EAAE,CAAA;IAC9B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;QACpD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QAClD,OAAO,IAAI,CAAA;IACZ,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAA;IACrB,MAAM,KAAK,GAAG,EAAE,CAAA;IAChB,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAE3E,IAAI,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kCAAkC,CAAC,CAAC,CAAA;IAC/D,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;IAC/C,CAAC;IACD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC,CAAA;IAClE,CAAC;IACD,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAA;IAC5C,CAAC;IACD,0EAA0E;IAC1E,0EAA0E;IAC1E,uDAAuD;IACvD,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,8BAA8B,CAAC,CAAC,CAAA;IAC3D,CAAC;IACD,OAAO,KAAK,CAAA;AACb,CAAC"}
+{"version":3,"file":"update-chips.mjs","sourceRoot":"","sources":["../../../src/cli/install/update-chips.mjs"],"names":[],"mappings":"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"}

package/dist/cli/release-notes/compile.d.mts

@@ -0,0 +1,38 @@
+/**
+ * @typedef {Object} CompileInput
+ * @property {string} projectDir
+ * @property {string} tag
+ * @property {string | null} outputDir
+ */
+/**
+ * @typedef {Object} CompileResult
+ * @property {boolean} written
+ * @property {string} path
+ * @property {number} fragmentsTotal
+ * @property {number} fragmentsInBody
+ * @property {number} fragmentsInTriage
+ * @property {number} fragmentsFiltered
+ * @property {boolean} clearedUnreleased
+ */
+/**
+ * Compile every `_unreleased/PR-*.md` fragment into `<output_dir>/<tag>.md`.
+ *
+ * @param {CompileInput} input
+ * @returns {CompileResult}
+ */
+export function compileTag(input: CompileInput): CompileResult;
+export type CompileInput = {
+    projectDir: string;
+    tag: string;
+    outputDir: string | null;
+};
+export type CompileResult = {
+    written: boolean;
+    path: string;
+    fragmentsTotal: number;
+    fragmentsInBody: number;
+    fragmentsInTriage: number;
+    fragmentsFiltered: number;
+    clearedUnreleased: boolean;
+};
+//# sourceMappingURL=compile.d.mts.map

package/dist/cli/release-notes/compile.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.mts","sourceRoot":"","sources":["../../../src/cli/release-notes/compile.mjs"],"names":[],"mappings":"AAgFA;;;;;GAKG;AAEH;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,kCAHW,YAAY,GACV,aAAa,CA4FzB;;gBAhHa,MAAM;SACN,MAAM;eACN,MAAM,GAAG,IAAI;;;aAKb,OAAO;UACP,MAAM;oBACN,MAAM;qBACN,MAAM;uBACN,MAAM;uBACN,MAAM;uBACN,OAAO"}

package/dist/cli/release-notes/compile.mjs

@@ -0,0 +1,244 @@
+/**
+ * release-notes/compile.mjs — tag-time narrative compiler.
+ *
+ * Reads every `<output_dir>/_unreleased/PR-*.md` fragment, classifies each
+ * against the project's persona roster + filter mode, and writes
+ * `<output_dir>/<tag>.md`. Atomic-rename pattern: the fragments dir is
+ * cleared only AFTER the compiled file lands on disk, so a crash mid-write
+ * cannot orphan fragments without their compiled output.
+ *
+ * Non-negotiable invariant (ID-6): unmapped fragments (no persona tag, or
+ * a tag the roster doesn't recognize) MUST appear in a `## Needs Triage`
+ * section. Never silent-drop. The triage section is the human curator's
+ * safety net — its presence is asserted by TD-3.
+ */
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { readPersonas } from '../personas/sidecar.mjs';
+import { atomicWriteText } from '../util/atomic-write.mjs';
+import { resolveOutputDir, validateTag } from './output-dir.mjs';
+import { buildPersonaTierMap, classifyFragment, isNoneSentinel } from './persona-filter.mjs';
+const VALID_MODES = new Set(['primary', 'primary+secondary', 'all']);
+/** Pre-compiled at module level to avoid recompilation in the sort comparator (PRF-001). */
+const PR_FILENAME_RE = /^PR-(\d+)\.md$/;
+/**
+ * Parse a single fragment file. Tolerant: missing keys default to empty
+ * strings; the body after `## Release note` is read verbatim.
+ *
+ * @param {string} text
+ * @returns {{ pr: string, date: string, persona: string, note: string, raw: string }}
+ */
+function parseFragment(text) {
+    const lines = text.split('\n');
+    let pr = '';
+    let date = '';
+    let persona = '';
+    let note = '';
+    let noteStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('pr: '))
+            pr = line.slice(4).trim();
+        else if (line.startsWith('date: '))
+            date = line.slice(6).trim();
+        else if (line.startsWith('persona: '))
+            persona = line.slice(9).trim();
+        else if (line.startsWith('## Release note')) {
+            noteStart = i;
+            break;
+        }
+    }
+    if (noteStart >= 0) {
+        note = lines
+            .slice(noteStart + 1)
+            .join('\n')
+            .trim();
+    }
+    return { pr, date, persona, note, raw: text };
+}
+/**
+ * Resolve the output dir and persona filter mode from config + flag override.
+ *
+ * @param {string} projectDir
+ * @param {string | null} flagOverride
+ * @returns {{ outputDir: string, personaFilter: 'primary' | 'primary+secondary' | 'all' }}
+ */
+function resolveContext(projectDir, flagOverride) {
+    const config = loadProjectConfig(projectDir);
+    const outputDir = resolveOutputDir(projectDir, flagOverride);
+    const filterRaw = config?.changelog?.release_notes?.persona_filter;
+    const personaFilter = typeof filterRaw === 'string' && VALID_MODES.has(filterRaw)
+        ? /** @type {'primary' | 'primary+secondary' | 'all'} */ (filterRaw)
+        : 'primary+secondary';
+    return { outputDir, personaFilter };
+}
+/**
+ * @typedef {Object} CompileInput
+ * @property {string} projectDir
+ * @property {string} tag
+ * @property {string | null} outputDir
+ */
+/**
+ * @typedef {Object} CompileResult
+ * @property {boolean} written
+ * @property {string} path
+ * @property {number} fragmentsTotal
+ * @property {number} fragmentsInBody
+ * @property {number} fragmentsInTriage
+ * @property {number} fragmentsFiltered
+ * @property {boolean} clearedUnreleased
+ */
+/**
+ * Compile every `_unreleased/PR-*.md` fragment into `<output_dir>/<tag>.md`.
+ *
+ * @param {CompileInput} input
+ * @returns {CompileResult}
+ */
+export function compileTag(input) {
+    validateTag(input.tag);
+    const { outputDir, personaFilter } = resolveContext(input.projectDir, input.outputDir);
+    const fragmentsDir = join(outputDir, '_unreleased');
+    const targetPath = join(outputDir, `${input.tag}.md`);
+    const rawFiles = existsSync(fragmentsDir)
+        ? readdirSync(fragmentsDir).filter((f) => PR_FILENAME_RE.test(f))
+        : [];
+    // Pre-compute PR numbers once to avoid re-running the regex in the comparator (PRF-001).
+    const withNumbers = rawFiles.map((f) => ({
+        f,
+        n: Number.parseInt(PR_FILENAME_RE.exec(f)?.[1] ?? '0', 10),
+    }));
+    withNumbers.sort((a, b) => a.n - b.n);
+    const fragments = withNumbers.map(({ f }) => ({
+        filename: f,
+        ...parseFragment(readFileSync(join(fragmentsDir, f), 'utf-8')),
+    }));
+    const personasEnvelope = readPersonas(input.projectDir);
+    const tierMap = buildPersonaTierMap(personasEnvelope);
+    /** @type {Array<{ pr: string, date: string, persona: string, note: string, tier: 'primary' | 'secondary' | 'tertiary' }>} */
+    const bodyEntries = [];
+    /** @type {Array<{ pr: string, date: string, persona: string, note: string, reason: string }>} */
+    const triageEntries = [];
+    let filteredCount = 0;
+    for (const frag of fragments) {
+        const { bucket, resolvedTier } = classifyFragment(frag.persona, tierMap, personaFilter);
+        if (bucket === 'body' && resolvedTier !== null && resolvedTier !== 'unknown') {
+            bodyEntries.push({
+                pr: frag.pr,
+                date: frag.date,
+                persona: frag.persona,
+                note: frag.note,
+                tier: resolvedTier,
+            });
+        }
+        else if (bucket === 'triage' || resolvedTier === 'unknown') {
+            // Use the shared sentinel predicate so this label stays in lockstep
+            // with persona-filter.mjs's NONE_SENTINELS set. Without it, the
+            // classifier and labeller drift (e.g. literal "null" persona tags
+            // land in triage as 'unknown-persona' instead of 'no-persona-tag').
+            // 'unknown' tier (malformed tier value in personas.json) is also
+            // routed here — never silent-drop (ID-6 / LOG-001).
+            const reason = isNoneSentinel(frag.persona)
+                ? 'no-persona-tag'
+                : resolvedTier === 'unknown'
+                    ? 'unknown-tier'
+                    : 'unknown-persona';
+            triageEntries.push({
+                pr: frag.pr,
+                date: frag.date,
+                persona: frag.persona,
+                note: frag.note,
+                reason,
+            });
+        }
+        else {
+            filteredCount++;
+        }
+    }
+    const compiled = renderCompiled({
+        tag: input.tag,
+        body: bodyEntries,
+        triage: triageEntries,
+        filter: personaFilter,
+    });
+    atomicWriteText(targetPath, compiled);
+    // Clear _unreleased only AFTER the compiled file is durably written.
+    let clearedUnreleased = false;
+    if (existsSync(fragmentsDir) && fragments.length > 0) {
+        for (const frag of fragments) {
+            rmSync(join(fragmentsDir, frag.filename), { force: true });
+        }
+        clearedUnreleased = true;
+    }
+    return {
+        written: true,
+        path: targetPath,
+        fragmentsTotal: fragments.length,
+        fragmentsInBody: bodyEntries.length,
+        fragmentsInTriage: triageEntries.length,
+        fragmentsFiltered: filteredCount,
+        clearedUnreleased,
+    };
+}
+/**
+ * Render the per-tag compiled body.
+ *
+ * Layout:
+ *   # Release <tag>
+ *
+ *   (per-tier sections — primary first, then secondary, then tertiary
+ *    when filter==='all'. Each section's entries sorted by PR number.)
+ *
+ *   ## Needs Triage   (only when triage[] non-empty)
+ *
+ * @param {{
+ *   tag: string,
+ *   body: Array<{ pr: string, date: string, persona: string, note: string, tier: 'primary' | 'secondary' | 'tertiary' }>,
+ *   triage: Array<{ pr: string, date: string, persona: string, note: string, reason: string }>,
+ *   filter: 'primary' | 'primary+secondary' | 'all',
+ * }} input
+ * @returns {string}
+ */
+function renderCompiled(input) {
+    const lines = [];
+    lines.push(`# Release ${input.tag}`);
+    lines.push('');
+    lines.push(`<!-- persona_filter: ${input.filter} -->`);
+    lines.push('');
+    const tiersInOrder = /** @type {const} */ (['primary', 'secondary', 'tertiary']);
+    for (const tier of tiersInOrder) {
+        const rows = input.body.filter((e) => e.tier === tier);
+        if (rows.length === 0)
+            continue;
+        lines.push(`## ${capitalize(tier)} personas`);
+        lines.push('');
+        for (const row of rows) {
+            lines.push(`- **PR #${row.pr}** (${row.persona}): ${row.note}`);
+        }
+        lines.push('');
+    }
+    if (input.triage.length > 0) {
+        lines.push('## Needs Triage');
+        lines.push('');
+        lines.push('_These fragments lack a recognized persona tag. Curate before publishing._');
+        lines.push('');
+        for (const row of input.triage) {
+            const personaLabel = row.persona && row.persona !== '(none)' ? row.persona : '(no tag)';
+            lines.push(`- **PR #${row.pr}** (${personaLabel}, ${row.reason}): ${row.note}`);
+        }
+        lines.push('');
+    }
+    if (input.body.length === 0 && input.triage.length === 0) {
+        lines.push('_No fragments to compile._');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function capitalize(s) {
+    return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=compile.mjs.map