@aperant/framework 0.6.7 → 0.7.0

package/dist/cli/install/legacy-paths.mjs

@@ -0,0 +1,69 @@
+/**
+ * install/legacy-paths.mjs — shared registry of legacy install topologies
+ * the framework once wrote to but no longer owns. Single source of truth
+ * for both:
+ *
+ *   - BUG-021: `runLegacyCleanup` in `install/runtime-migrate.mjs` knows
+ *     which files under a legacy root are framework-owned (safe to
+ *     remove) vs user-added (preserve).
+ *   - BUG-022: `readSkillInstallState` in `util/skill-installs.mjs` falls
+ *     back to `version_file` here when no manifest is present, so a
+ *     pre-manifest install still surfaces as "installed" rather than
+ *     "missing-skills".
+ *
+ * Derivation: the codex `framework_files` list was extracted from
+ * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
+ * skill install surface" commit) — every `.agents/skills/…` path the
+ * installer once wrote, including the `.apt-version` stamp and the
+ * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
+ * codex installer was retargeted to `.codex/`, that entire tree became
+ * orphaned on upgrading projects.
+ *
+ * Schema:
+ *   { [runtimeId]: {
+ *       install_root:     relative path the runtime once wrote into,
+ *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       framework_files:  array of relative paths the installer once owned
+ *                         (under install_root).
+ *   } }
+ *
+ * Frozen via Object.freeze so callers cannot mutate the shared registry.
+ */
+/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
+export const LEGACY_INSTALL_PATHS = Object.freeze({
+    codex: Object.freeze({
+        install_root: '.agents/skills',
+        version_file: '.agents/skills/.apt-version',
+        framework_files: Object.freeze([
+            '.apt-version',
+            'apt/SKILL.md',
+            'apt-debug/SKILL.md',
+            'apt-discuss/SKILL.md',
+            'apt-discuss/examples/rationalization-example.md',
+            'apt-docs/SKILL.md',
+            'apt-execute/SKILL.md',
+            'apt-pause/SKILL.md',
+            'apt-plan/SKILL.md',
+            'apt-pr-review/SCHEMA.md',
+            'apt-pr-review/SKILL.md',
+            'apt-pr-review/prompts/fp-gate-codex.md',
+            'apt-pr-review/templates/external-comment.md',
+            'apt-quick/SKILL.md',
+            'apt-resume/SKILL.md',
+            'apt-review/SKILL.md',
+            'apt-roadmap/SKILL.md',
+            'apt-roundtable/SKILL.md',
+            'apt-run/SKILL.md',
+            'apt-scan/SKILL.md',
+            'apt-setup/SKILL.md',
+            'apt-ship/SKILL.md',
+            'apt-stress-test/SKILL.md',
+            'apt-verify/SKILL.md',
+            'apt-verify-proof/SKILL.md',
+            'apt-verify-proof/references/multi-model-setup.md',
+            'apt-verify-proof/references/multi-model-verification.md',
+            'apt-verify-proof/references/proof-capture.md',
+        ]),
+    }),
+});
+//# sourceMappingURL=legacy-paths.mjs.map

package/dist/cli/install/legacy-paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-paths.mjs","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qHAAqH;AACrH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,6BAA6B;QAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;YAC9B,cAAc;YACd,cAAc;YACd,oBAAoB;YACpB,sBAAsB;YACtB,iDAAiD;YACjD,mBAAmB;YACnB,sBAAsB;YACtB,oBAAoB;YACpB,mBAAmB;YACnB,yBAAyB;YACzB,wBAAwB;YACxB,wCAAwC;YACxC,6CAA6C;YAC7C,oBAAoB;YACpB,qBAAqB;YACrB,qBAAqB;YACrB,sBAAsB;YACtB,yBAAyB;YACzB,kBAAkB;YAClB,mBAAmB;YACnB,oBAAoB;YACpB,mBAAmB;YACnB,0BAA0B;YAC1B,qBAAqB;YACrB,2BAA2B;YAC3B,kDAAkD;YAClD,yDAAyD;YACzD,8CAA8C;SAC9C,CAAC;KACF,CAAC;CACF,CAAC,CAAA"}

package/dist/cli/install/runtime-migrate.d.mts

@@ -0,0 +1,84 @@
+/**
+ * Probe the codex legacy install tree at `<targetDir>/.agents/skills/`.
+ *
+ * @param {string} targetDir
+ * @returns {LegacyCodexDetection}
+ */
+export function detectLegacyCodexTree(targetDir: string): LegacyCodexDetection;
+/**
+ * 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 }: {
+    targetDir: string;
+    dryRun?: boolean;
+}): any | {
+    ran: false;
+    reason: "no-legacy" | "managed";
+} | {
+    ran: true;
+    removed: string[];
+    retained: string[];
+    rmdirs: string[];
+};
+export type LegacyCodexDetection = {
+    /**
+     * True when `.agents/skills/` exists.
+     */
+    present: boolean;
+    /**
+     * Subset of `framework_files` that
+     * actually exist on disk (relative
+     * to install_root).
+     */
+    frameworkFiles: string[];
+    /**
+     * Everything else under
+     * install_root (relative to
+     * install_root). May include both
+     * files and directories. Drives the
+     * `retained[]` warning.
+     */
+    userFiles: string[];
+    /**
+     * Whether the legacy `.apt-version`
+     * stamp is present.
+     */
+    hasAptVersion: boolean;
+    /**
+     * Whether an
+     * `apt-file-manifest.json` is
+     * present at install_root (signals
+     * a managed install — cleanup
+     * should no-op).
+     */
+    hasManifest: boolean;
+};
+//# sourceMappingURL=runtime-migrate.d.mts.map

package/dist/cli/install/runtime-migrate.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-migrate.d.mts","sourceRoot":"","sources":["../../../src/cli/install/runtime-migrate.mjs"],"names":[],"mappings":"AA8FA;;;;;GAKG;AACH,iDAHW,MAAM,GACJ,oBAAoB,CA0BhC;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wDANW;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAEjD,GAAC,GAAK;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,GAC/C;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAgF5E;;;;;aAxNa,OAAO;;;;;;oBACP,MAAM,EAAE;;;;;;;;eAGR,MAAM,EAAE;;;;;mBAKR,OAAO;;;;;;;;iBAEP,OAAO"}

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/route/drift-detect.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Detect whether the workspace source for `@aperant/framework` is ahead
+ * of the installed kernel.
+ *
+ * @param {string} targetDir  Absolute path the route was invoked against.
+ * @param {string|null} installedVersion  The installed kernel's version (semver string), or null when unknown.
+ * @returns {null | {
+ *   source_path: string,
+ *   source_version: string,
+ *   installed_version: string,
+ *   drift: true,
+ * }}
+ */
+export function detectSourceWorkspaceDrift(targetDir: string, installedVersion: string | null): null | {
+    source_path: string;
+    source_version: string;
+    installed_version: string;
+    drift: true;
+};
+//# sourceMappingURL=drift-detect.d.mts.map

package/dist/cli/route/drift-detect.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-detect.d.mts","sourceRoot":"","sources":["../../../src/cli/route/drift-detect.mjs"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;GAYG;AACH,sDATW,MAAM,oBACN,MAAM,GAAC,IAAI,GACT,IAAI,GAAG;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,IAAI,CAAC;CACb,CAuCH"}

package/dist/cli/route/drift-detect.mjs

@@ -0,0 +1,107 @@
+/**
+ * route/drift-detect.mjs — FRAMEWORK-BUG-017 (rung 1 of 3).
+ *
+ * In-band detection of the "installed kernel drifts behind source
+ * workspace" failure mode. When an Aperant contributor self-hosts the
+ * framework out of a monorepo checkout, the kernel at
+ * `.aperant/deps/node_modules/@aperant/framework/` lags behind the
+ * source at `packages/framework/` after every same-PR framework fix.
+ * The SessionStart worker only knows about npm — it cannot tell that
+ * the workspace is ahead of the install.
+ *
+ * This module walks up from `targetDir`, looking for a sibling
+ * `packages/framework/package.json`. When found AND its `version`
+ * differs from the installed kernel's `version`, it returns a synthetic
+ * `update_check`-shaped object so `route.mjs` can surface the chip
+ * immediately — without waiting for the SessionStart hook to fire.
+ *
+ * Safe for the route hot path: synchronous, file-existence checks
+ * only, bounded walk (6 segments max), no network, no spawn.
+ *
+ * Security (Codex review edit 2): the workspace `package.json:version`
+ * is validated against the same semver-shape regex `update-chips.mjs`
+ * uses on the cache. A poisoned workspace `package.json` cannot
+ * propagate a non-semver `latest_version` into the synthesized
+ * `update_check` block.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { compareVersions, SEMVER_RE } from '../util/semver.mjs';
+/** Max directory frames to walk before giving up. */
+const MAX_WALK_DEPTH = 6;
+/**
+ * Walk up from `start`, returning every directory frame including
+ * `start` itself. Stops at the filesystem root or at a depth of
+ * `MAX_WALK_DEPTH` (whichever comes first). The hard cap keeps this
+ * cheap on the route hot path and contains accidental scans on deeply
+ * nested input paths.
+ *
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walkUp(start) {
+    const frames = [];
+    let cur = start;
+    for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+        frames.push(cur);
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return frames;
+}
+/**
+ * Detect whether the workspace source for `@aperant/framework` is ahead
+ * of the installed kernel.
+ *
+ * @param {string} targetDir  Absolute path the route was invoked against.
+ * @param {string|null} installedVersion  The installed kernel's version (semver string), or null when unknown.
+ * @returns {null | {
+ *   source_path: string,
+ *   source_version: string,
+ *   installed_version: string,
+ *   drift: true,
+ * }}
+ */
+export function detectSourceWorkspaceDrift(targetDir, installedVersion) {
+    if (!targetDir || typeof targetDir !== 'string')
+        return null;
+    if (!installedVersion || typeof installedVersion !== 'string')
+        return null;
+    if (!SEMVER_RE.test(installedVersion))
+        return null;
+    for (const dir of walkUp(targetDir)) {
+        const candidate = join(dir, 'packages', 'framework', 'package.json');
+        if (!existsSync(candidate))
+            continue;
+        let pkg;
+        try {
+            pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+        // Validate the workspace package is actually @aperant/framework —
+        // guard against false matches on unrelated monorepos that happen
+        // to have a `packages/framework/` directory.
+        if (pkg?.name !== '@aperant/framework')
+            continue;
+        const sourceVersion = pkg?.version;
+        if (typeof sourceVersion !== 'string' || !SEMVER_RE.test(sourceVersion))
+            return null;
+        // Only report drift when workspace source is strictly ahead of the installed
+        // kernel. Equal (already up-to-date) and behind (installed is newer) both
+        // return null — only source-ahead is a drift worth surfacing.
+        if (compareVersions(sourceVersion, installedVersion) <= 0)
+            return null;
+        return {
+            source_path: candidate,
+            source_version: sourceVersion,
+            installed_version: installedVersion,
+            drift: true,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=drift-detect.mjs.map

package/dist/cli/route/drift-detect.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-detect.mjs","sourceRoot":"","sources":["../../../src/cli/route/drift-detect.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE/D,qDAAqD;AACrD,MAAM,cAAc,GAAG,CAAC,CAAA;AAExB;;;;;;;;;GASG;AACH,SAAS,MAAM,CAAC,KAAK;IACpB,MAAM,MAAM,GAAG,EAAE,CAAA;IACjB,IAAI,GAAG,GAAG,KAAK,CAAA;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAChB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAK;QACzB,GAAG,GAAG,MAAM,CAAA;IACb,CAAC;IACD,OAAO,MAAM,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CAAC,SAAS,EAAE,gBAAgB;IACrE,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAC5D,IAAI,CAAC,gBAAgB,IAAI,OAAO,gBAAgB,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAC1E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAA;IAElD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,CAAC,CAAA;QACpE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,SAAQ;QAEpC,IAAI,GAAG,CAAA;QACP,IAAI,CAAC;YACJ,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;QACnD,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAA;QACZ,CAAC;QAED,kEAAkE;QAClE,iEAAiE;QACjE,6CAA6C;QAC7C,IAAI,GAAG,EAAE,IAAI,KAAK,oBAAoB;YAAE,SAAQ;QAEhD,MAAM,aAAa,GAAG,GAAG,EAAE,OAAO,CAAA;QAClC,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC;YAAE,OAAO,IAAI,CAAA;QACpF,6EAA6E;QAC7E,0EAA0E;QAC1E,8DAA8D;QAC9D,IAAI,eAAe,CAAC,aAAa,EAAE,gBAAgB,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;QAEtE,OAAO;YACN,WAAW,EAAE,SAAS;YACtB,cAAc,EAAE,aAAa;YAC7B,iBAAiB,EAAE,gBAAgB;YACnC,KAAK,EAAE,IAAI;SACX,CAAA;IACF,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/dist/cli/util/aperant-section.d.mts

@@ -0,0 +1,34 @@
+/**
+ * Build the full "## Aperant Framework" section, wrapped in the
+ * `<!-- APT:framework-* -->` markers.
+ *
+ * @param {Object} opts
+ * @param {string} opts.canonicalRoot   Absolute path to the framework root
+ *                                       (the directory that contains
+ *                                       `templates/aperant-claude-md-appendix.md`).
+ * @param {string} opts.targetDir       Project root (passed to discoverSkills).
+ * @param {string} [opts.cli]           Host CLI label (forwarded to
+ *                                       getTrustedSkillSources so the install
+ *                                       root for the runtime is included).
+ * @returns {string}                     The full section, including markers
+ *                                       and trailing newline before the
+ *                                       end-marker. No leading newline.
+ */
+export function buildAptSection({ canonicalRoot, targetDir, cli }: {
+    canonicalRoot: string;
+    targetDir: string;
+    cli?: string | undefined;
+}): string;
+/**
+ * Extract the `/apt:<slug>` (or bare `/apt`) row IDs from the
+ * `<!-- APT:framework-* -->` section of an existing instruction file.
+ * Returns `[]` when the file has no APT section.
+ *
+ * Used by `injectInstructionFile` to detect foreign rows that would be
+ * silently clobbered by a regeneration — see `--force-overwrite-catalog`.
+ *
+ * @param {string} text   Full instruction-file contents.
+ * @returns {string[]}    Row IDs in file order, e.g. `['/apt', '/apt:quick', …]`.
+ */
+export function extractAptSectionRowIds(text: string): string[];
+//# sourceMappingURL=aperant-section.d.mts.map

package/dist/cli/util/aperant-section.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aperant-section.d.mts","sourceRoot":"","sources":["../../../src/cli/util/aperant-section.mjs"],"names":[],"mappings":"AAuDA;;;;;;;;;;;;;;;GAeG;AACH,mEAXG;IAAqB,aAAa,EAA1B,MAAM;IAGO,SAAS,EAAtB,MAAM;IACQ,GAAG;CAGzB,GAAU,MAAM,CAqClB;AAED;;;;;;;;;;GAUG;AACH,8CAHW,MAAM,GACJ,MAAM,EAAE,CAoBpB"}