@aperant/framework 0.6.7 → 0.7.0

package/dist/cli/util/version-preflight.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Preflight check: is the installed kernel new enough to support the
+ * named feature?
+ *
+ * - Returns `null` when the install is at-or-above `introducedIn` (pass).
+ * - Returns `null` when `installedVersion` is malformed (fail-open — a
+ *   corrupted `package.json` shouldn't lock users out of every cmd; the
+ *   route-level drift check still catches the same install via the
+ *   version mismatch path).
+ * - Returns a `version_drift` error envelope when the install predates
+ *   `introducedIn`. Callers `exitWith(envelope, 1)`.
+ *
+ * @param {Object} args
+ * @param {string} args.feature  Short name of the feature being gated.
+ * @param {string} args.introducedIn  Minimum framework version that ships the feature.
+ * @param {string} args.installedVersion  The installed kernel's version.
+ * @param {string} args.missingFlag  The CLI flag that requires this version (e.g. '--payload-file').
+ * @returns {null | {
+ *   status: 'error',
+ *   command: 'version-preflight',
+ *   error_code: 'version_drift',
+ *   feature: string,
+ *   introduced_in: string,
+ *   installed_version: string,
+ *   missing_flag: string,
+ *   reason: string,
+ * }}
+ */
+export function requireMinVersion({ feature, introducedIn, installedVersion, missingFlag }: {
+    feature: string;
+    introducedIn: string;
+    installedVersion: string;
+    missingFlag: string;
+}): null | {
+    status: "error";
+    command: "version-preflight";
+    error_code: "version_drift";
+    feature: string;
+    introduced_in: string;
+    installed_version: string;
+    missing_flag: string;
+    reason: string;
+};
+//# sourceMappingURL=version-preflight.d.mts.map

package/dist/cli/util/version-preflight.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-preflight.d.mts","sourceRoot":"","sources":["../../../src/cli/util/version-preflight.mjs"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4FAfG;IAAqB,OAAO,EAApB,MAAM;IACO,YAAY,EAAzB,MAAM;IACO,gBAAgB,EAA7B,MAAM;IACO,WAAW,EAAxB,MAAM;CACd,GAAU,IAAI,GAAG;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAmBH"}

package/dist/cli/util/version-preflight.mjs

@@ -0,0 +1,66 @@
+/**
+ * util/version-preflight.mjs — FRAMEWORK-BUG-017 (rung 2 of 3).
+ *
+ * Pure helper for cmds that depend on a flag / behavior introduced in a
+ * specific framework version. When the installed kernel predates that
+ * version, returning a structured `version_drift` envelope is strictly
+ * better than the silent infra-backoff loop that bit us in
+ * FRAMEWORK-BUG-010.
+ *
+ * Scope (Codex review edit 1): this is a **future-guard** for the next
+ * framework fix that introduces a new flag. A stale 0.6.6 install
+ * obviously cannot execute 0.6.8 preflight code (the helper doesn't
+ * exist there). The actual catch-point for already-stale installs is
+ * the route-side `detectSourceWorkspaceDrift`. This helper makes the
+ * NEXT bug bundle cheaper to ship safely.
+ */
+import { compareVersions, SEMVER_RE } from './semver.mjs';
+/**
+ * Preflight check: is the installed kernel new enough to support the
+ * named feature?
+ *
+ * - Returns `null` when the install is at-or-above `introducedIn` (pass).
+ * - Returns `null` when `installedVersion` is malformed (fail-open — a
+ *   corrupted `package.json` shouldn't lock users out of every cmd; the
+ *   route-level drift check still catches the same install via the
+ *   version mismatch path).
+ * - Returns a `version_drift` error envelope when the install predates
+ *   `introducedIn`. Callers `exitWith(envelope, 1)`.
+ *
+ * @param {Object} args
+ * @param {string} args.feature  Short name of the feature being gated.
+ * @param {string} args.introducedIn  Minimum framework version that ships the feature.
+ * @param {string} args.installedVersion  The installed kernel's version.
+ * @param {string} args.missingFlag  The CLI flag that requires this version (e.g. '--payload-file').
+ * @returns {null | {
+ *   status: 'error',
+ *   command: 'version-preflight',
+ *   error_code: 'version_drift',
+ *   feature: string,
+ *   introduced_in: string,
+ *   installed_version: string,
+ *   missing_flag: string,
+ *   reason: string,
+ * }}
+ */
+export function requireMinVersion({ feature, introducedIn, installedVersion, missingFlag }) {
+    if (!installedVersion || typeof installedVersion !== 'string')
+        return null;
+    if (!SEMVER_RE.test(installedVersion))
+        return null;
+    if (!SEMVER_RE.test(introducedIn))
+        return null;
+    if (compareVersions(installedVersion, introducedIn) >= 0)
+        return null;
+    return {
+        status: 'error',
+        command: 'version-preflight',
+        error_code: 'version_drift',
+        feature,
+        introduced_in: introducedIn,
+        installed_version: installedVersion,
+        missing_flag: missingFlag,
+        reason: `cmd needs feature ${feature} introduced in version ${introducedIn}; installed version is ${installedVersion} — run /apt:update`,
+    };
+}
+//# sourceMappingURL=version-preflight.mjs.map

package/dist/cli/util/version-preflight.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-preflight.mjs","sourceRoot":"","sources":["../../../src/cli/util/version-preflight.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE;IACzF,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;IAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAA;IAE9C,IAAI,eAAe,CAAC,gBAAgB,EAAE,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAErE,OAAO;QACN,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,mBAAmB;QAC5B,UAAU,EAAE,eAAe;QAC3B,OAAO;QACP,aAAa,EAAE,YAAY;QAC3B,iBAAiB,EAAE,gBAAgB;QACnC,YAAY,EAAE,WAAW;QACzB,MAAM,EAAE,qBAAqB,OAAO,0BAA0B,YAAY,0BAA0B,gBAAgB,oBAAoB;KACxI,CAAA;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperant/framework",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": "Mikalsen AI <hello@mikalsen.ai>",
   "type": "module",

package/skills/apt-close-task/SKILL.md

@@ -123,6 +123,8 @@ close-merged emits an envelope with:
 
 Report the summary verbatim. If anything landed in `skipped[]` with a recoverable reason (`offline`, `rate_limited`), suggest the user re-run once the network clears.
 
+**Local cleanup recap (best-effort).** On confirmed merge, `task close-merged` runs `computeWorktreeCleanup` against the primary repo (`packages/framework/src/cli/task/worktree-cleanup.mjs:140-230`): `git fetch origin <base>` (failure → recorded as `fetch_failed` warning, cleanup proceeds), `git checkout <base>` (failure → returns `action: 'checkout_failed'` and preserves BOTH the worktree and the task branch — nothing is removed), `git merge --ff-only origin/<base>` (failure → `ff_only_failed` warning, GC still runs), `git worktree remove <wtPath>`, and `git branch -d <taskBranch>` (failure on squash/rebase merges → `branch_delete_failed` warning, `branch_deleted: false` in the envelope; user can `git branch -D` manually). This is why `/apt:watch-ci` auto-merge MUST NOT pass `gh pr merge --delete-branch` — that flag would try to do the same work from inside the worktree where `git switch <base>` cannot succeed (see FRAMEWORK-BUG-019).
+
 ## 4. Narrate-only mode
 
 When invoked with `--narrate-only`, skip §1 (no `gh pr view` polling) and §2 (no destructive close path). The deterministic close already ran via the passive post-merge sweep — your job is to drain the `state.pending_narration[]` ledger the sweep parked.
@@ -133,10 +135,13 @@ Flags:
 
 Per ledger entry `{ task_id, scope, phase_id, closed_at, pr_number }`:
 
+0. **Enumerate the ledger first.** Run `apt-tools task close-merged . --narrate-only [--task <id>]`. The envelope's `closed[]` is the read-only list of pending narration rows (each carries `narration_pending: true`); state.json is not mutated. When `closed[]` is empty, exit early with `{status: 'ok', narrated: [], skipped: [], remaining: 0}` — there is nothing to drain.
 1. Run `apt-tools features-audit . --apply-stubs --task <task_id>` so the feature registry catches whatever the closed task introduced. If the subprocess exits non-zero, skip the entry with `reason: 'features-audit-failed'` — never block narration on registry update.
 2. When `phase_id` is non-null, spawn `apt-team-docs-narrator` (background, fire-and-forget) using the same shape as §2.5: `subagent_type: apt-team-docs-narrator`, `run_in_background: true`, `description: Narrate shipped phase {phase_id}`, `prompt: Run in phase-ship mode with --phase {phase_id} --scope {scope}.`. When `phase_id` is null, skip the spawn with `reason: 'no-phase-id'` (quick tasks have no phase to narrate).
 3. On successful spawn (or successful no-phase skip), drain the row via `apt-tools task narration-drain . --task <task_id>` which acquires `withFileLock(state.json)` and removes the matching `pending_narration[]` entry. On spawn failure, leave the row in place with `reason: 'narrator-spawn-failed'` so the user can re-invoke.
 
+**At-least-once retry semantics (FRAMEWORK-BUG-020).** Step 0 is read-only — it does NOT remove rows. Steps 1–3 are the existing per-row drain contract: a row stays in `pending_narration[]` until step 3 calls `narration-drain` successfully. If the orchestrator crashes between step 2 (narrator spawn) and step 3 (drain), the row remains parked and a retry will spawn narration again. Re-spawning is safe because the narrator is **anchor-replace idempotent** by design (see `agents/apt-team-docs-narrator.md` §6 / §2 and the "Idempotent operations only" rule in §notes) — it uses HTML-comment anchors to bound the replaced region in ROADMAP.md, so a second run replaces the same span rather than appending.
+
 Emit a summary envelope:
 
 ```json

package/skills/apt-ship/SKILL.md

@@ -412,19 +412,30 @@ ci_watch_armed=$(echo "$ship_update" | jq -r '.ci_watch_armed // false')
 ci_watch_skip_reason=$(echo "$ship_update" | jq -r '.ci_watch_skip_reason // empty')
 ci_watch_host=$(echo "$ship_update" | jq -r '.ci_watch.host // "unknown"')
 ci_watch_deadline=$(echo "$ship_update" | jq -r '.ci_watch.deadline // empty')
+ci_watch_scheduler_handle=$(echo "$ship_update" | jq -r '.scheduler_handle // empty')
 host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
 ```
 
 **Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
 
-**Branch on the task-update envelope:**
+**Branch on the task-update envelope** (FRAMEWORK-BUG-018 — Track 1: distinguish state-recording from wake-registration):
 
-- **`ci_watch_armed=true` AND `host_cron=true`** — emit:
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` non-empty** — emit:
 
   ```
   [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
   ```
 
+  This is the only honest "armed" case — a scheduler handle proves the wake is registered.
+
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` empty** — emit:
+
+  ```
+  [APT:ship] CI watcher state created (host: {ci_watch_host}). Register a wake-up to drive ticks: CronCreate every ~3min running '/apt:watch-ci --tick --pr {N}'. Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+  State is recorded but no scheduler is registered — the orchestrator MUST register a wake or ticks will never fire. Track 2 (auto-wake on arm) will populate `scheduler_handle` and route into the first branch instead.
+
 - **`ci_watch_armed=true` AND `host_cron=false`** — emit:
 
   ```
@@ -442,10 +453,11 @@ host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host
   On `Y` (or empty enter), call:
 
   ```bash
-  node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli}
+  arm_envelope=$(node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli})
+  ci_watch_scheduler_handle=$(echo "$arm_envelope" | jq -r '.scheduler_handle // empty')
   ```
 
-  Then emit the same host-cron-aware success banner used for `ci_watch_armed=true`. On `N` or any other response, proceed silently to Section 8.
+  Then route into the same four-way logic above — branch 1 (armed with handle), branch 2 (state-created, needs wake), or branch 3 (host has no cron). On `N` or any other response, proceed silently to Section 8.
 
 - **`ci_watch_skip_reason=disabled`** — silent. Proceed directly to Section 8.
 

package/skills/apt-spar/SKILL.md

@@ -129,14 +129,26 @@ If `--with` resolves to the same CLI as the host (e.g. `--with claude` when `hos
 
 Do NOT proceed; self-sparring is sycophancy by construction (the host cannot objectively challenge itself). This check runs after `host-detect` and before any partner availability check.
 
-**Partner unavailable.** If the resolved partner CLI binary or script is not on `$PATH` — or, for the codex-companion path, if `CLAUDE_PLUGIN_ROOT` is unset OR `${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs` does not exist — print a clean fallback and stop:
+**Partner transport ladder (FRAMEWORK-BUG-024).** Read `host.partner_transports.<partner>` from the host-detect envelope (`jq '.host.partner_transports.codex'`, etc.). Each partner has a 3-rung ladder evaluated in preference order — **MCP-first** for cleaner tool-call integration, with automatic fallthrough to plugin shim then raw CLI:
+
+1. **Rung 1 — MCP tool** (`mcp__<partner>-mcp__*`, e.g. `mcp__codex-mcp__codex`). Detected if the host exposes its deferred-tool manifest via `CLAUDE_MCP_DEFERRED_TOOLS` and the tool is registered. When `detected: "runtime-host-only"` the framework process cannot probe the host's tool registry from outside — treat as candidate and attempt the tool call; if the tool is genuinely unavailable in the host's visible registry, fall through to rung 2.
+2. **Rung 2 — Plugin shim** (`${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`). Codex only (claude / gemini have no plugin shim).
+3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini -m`).
+
+Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 60000ms, configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. Empirical: the Codex MCP `claude_code` tool has been observed to hang past 120s. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
+
+If all three rungs are unavailable (every rung `detected: false`, or MCP `runtime-host-only` timed out AND rungs 2+3 are `detected: false`), print:
 
 ```
-[apt:spar] partner `<id>` unavailable. Either:
-  - install the partner CLI (Codex: install the `codex` Claude Code plugin so `CLAUDE_PLUGIN_ROOT/scripts/codex-companion.mjs` resolves; Claude: install the `claude` CLI on $PATH; Gemini: install the `gemini` CLI on $PATH)
-  - re-run with `--with <other-id>` to pick a different partner
+[apt:spar] partner `<id>` unavailable. Tried:
+  - MCP tool `mcp__<partner>-mcp__*`: <not loaded in this host | runtime-host-only + timed out at <ms>ms>
+  - Plugin shim `${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`: <missing reason>
+  - Raw CLI `<bin>` on $PATH: not found
+Install any one of the three or re-run with `--with <other-id>`.
 ```
 
+The failure message MUST name all three transports tried (`mcp`, `plugin shim`, `raw CLI`) so the user can pick the cheapest fix.
+
 Do NOT silently degrade to the host (sparring with yourself is sycophancy by construction).
 
 ## 4. Frame the Round
@@ -159,13 +171,26 @@ The frame is one shot per round — no multi-turn conversation with the partner
 
 **Wrap every partner Bash call with an explicit timeout** (default 90000ms, override via `--timeout-ms`). The empirical reason: the Codex MCP `claude_code` tool has been observed to hang past 120s while the `claude -p` CLI returns in seconds. A hung partner CLI must NOT stall the spar loop.
 
-The table below shows the canonical command shape; the actual invocation MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation.
-
-| Host | Command | Notes |
-|---|---|---|
-| `host=claude-code` (or `--with codex`) | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
-| `host=codex` (or `--with claude`) | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
-| `--with gemini` (any host) | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
+The table below shows the canonical command shape per (partner × rung); the actual invocation for shell-based rungs (plugin shim, raw CLI) MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation. The MCP rung is a structured tool call — no shell quoting concern applies.
+
+<!--
+  Future contributor: the `codex exec` flag below is taken from the precedent
+  at `packages/framework/skills/apt-pr-review/SKILL.md:1084`. Codex CLI flag
+  surface evolves; verify with `codex --help` at execution time and update
+  this table if the non-interactive invocation shape changes.
+-->
+
+| Partner | Rung | Command | Notes |
+|---|---|---|---|
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt})` | Preferred. 60s timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
+| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
+| codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. Verify with `codex --help`. |
+| claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 60s timeout + fallthrough rule. |
+| claude | plugin | n/a | No plugin shim exists for Claude. Skip this rung. |
+| claude | cli | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
+| gemini | mcp | tool call: `mcp__gemini-mcp__*({prompt})` | Preferred. Same 60s timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
+| gemini | plugin | n/a | No plugin shim exists for Gemini. Skip this rung. |
+| gemini | cli | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
 
 Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 90000).
 

package/skills/apt-update/SKILL.md

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Write"
-argument-hint: "apt:update"
+argument-hint: "apt:update [--from-source]"
 gates: []
 ---
 
@@ -90,6 +90,30 @@ npm install --prefix .aperant/deps @aperant/framework@<latest_version> --no-save
 
 On `npm 404` (`E404` in stderr) treat it as `not_published` and skip the kernel bump (proceed to step 3). On any other npm failure, surface the npm stderr verbatim and STOP — do NOT proceed to init with a half-installed kernel.
 
+## 1.6. Self-host case — bump from local workspace (FRAMEWORK-BUG-017)
+
+When the user invokes `/apt:update --from-source` OR the route envelope's `update_check.reason` mentions `workspace source ahead of installed kernel`, the source of truth is the local `packages/framework/` workspace — NOT npm. This is the Aperant-contributor self-host case: a same-PR framework fix bumps the workspace `packages/framework/package.json:version` but the kernel under `.aperant/deps/node_modules/@aperant/framework/` still reflects the previous version. Step 1.5's `npm view` would fetch the published version (still the OLD one), so we must skip it.
+
+The reliable bump mechanism mirrors what `runKernelInstall` does today — `pnpm pack` produces a versioned tarball, then `npm install --prefix` consumes it. Symlinking is fragile across re-installs and `pnpm install --filter` doesn't relocate the published artifact into `.aperant/deps`.
+
+Walk up from the project root looking for a sibling `packages/framework/package.json`. When found AND its `name === "@aperant/framework"`:
+
+```bash
+# 1. Pack the workspace source into a versioned tarball.
+cd <workspace-root>
+pnpm --filter @aperant/framework pack --pack-destination /tmp
+
+# 2. Install the tarball into the project's kernel root.
+cd <project-root>
+npm install --prefix .aperant/deps /tmp/aperant-framework-<version>.tgz --no-save --no-package-lock --no-audit --no-fund
+```
+
+Replace `<version>` with the workspace `package.json:version` you just read. The tarball name follows npm's `pack` convention (`@aperant/framework@X.Y.Z` → `aperant-framework-X.Y.Z.tgz`).
+
+If `--from-source` was passed but no `packages/framework/package.json` is found anywhere above the project root, surface a one-line error (`⚠ --from-source: no workspace package.json found — falling back to npm`) and proceed with the standard step 1.5 npm path.
+
+Then proceed to step 3 to re-install the runtime files at the new kernel version. Skip step 4 (cache clear) — the cache is keyed on `latest_version` from npm, and a `--from-source` bump never wrote to it, so there's nothing to invalidate.
+
 ## 2. Classify the update scenario
 
 Pick ONE of three scenarios based on what you parsed in step 1:
@@ -206,5 +230,6 @@ Runtime files were still refreshed; `/apt` will still work from PATH if `apt-too
 - **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
 - **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
 - **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
+- **CLAUDE.md / AGENTS.md foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce. Two paths: (a) remove the foreign rows from CLAUDE.md / AGENTS.md by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
 
 </edge_cases>

package/skills/apt-watch-ci/SKILL.md

@@ -87,7 +87,10 @@ For the `--tick` mode, execute exactly the following sequence — once — insid
 
 When `action ∈ {green, merged, closed, attempts-cap, wall-cap, identical-log}`:
 
-- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`. Else print the exact D-08 text:
+- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`.
+  - **DO NOT pass `--delete-branch`** to `gh pr merge` from this auto-merge path — ever, unconditionally. The watcher's cwd is the task worktree, where `gh`'s `--delete-branch` post-merge cleanup tries to `git switch <base>` and fails because `<base>` is checked out in the primary worktree. The remote merge has already succeeded by then; local branch + worktree cleanup is `/apt:close-task`'s job via `apt-tools task close-merged` → `computeWorktreeCleanup` (see FRAMEWORK-BUG-019).
+
+  Else print the exact D-08 text:
 
   ```
   ✅ CI green — merge in browser or run /apt:close-task post-merge

package/src/cli/commands/ci-watch.mjs

@@ -26,12 +26,33 @@
 
 import { randomBytes } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { acquireLock, releaseLock } from '../ci-watch/lock.mjs'
 import { deleteState, listWatches, readState, writeState } from '../ci-watch/state.mjs'
 import { classify, isFailing } from '../ci-watch/stop-matrix.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { requireMinVersion } from '../util/version-preflight.mjs'
+
+/**
+ * Installed kernel version — read once at module scope, same pattern as
+ * commands/check-version.mjs:108-109. Used by the version-preflight in
+ * `doTick` to fail loud (instead of infra-backoff-loop) when a future
+ * framework fix introduces a new tick flag and the user is on a stale
+ * install. See FRAMEWORK-BUG-017 rung 2 + the helper docstring for the
+ * "future-guard" framing.
+ */
+const INSTALLED_KERNEL_VERSION = (() => {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkgPath = resolve(here, '..', '..', '..', 'package.json')
+		const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		return typeof pkg?.version === 'string' ? pkg.version : null
+	} catch {
+		return null
+	}
+})()
 
 const DEFAULT_TICK_INTERVAL_MS = 300_000 // 5 minutes
 const MAX_TICK_INTERVAL_MS = 30 * 60 * 1000 // 30 min
@@ -119,12 +140,14 @@ function doStart(root, flags) {
 				command: 'ci-watch-start',
 				pr: Number(pr),
 				reason: 'already-armed',
+				scheduler_handle: existingState.scheduler_handle ?? null,
 				existing: {
 					task_id: existingState.task_id,
 					host: existingState.host,
 					attempts: existingState.attempts,
 					started_at: existingState.started_at,
 					deadline: existingState.deadline,
+					scheduler_handle: existingState.scheduler_handle ?? null,
 				},
 			},
 			2,
@@ -261,6 +284,21 @@ function summarize(s) {
 // ---------------------------------------------------------------------------
 
 function doTick(root, flags) {
+	// FRAMEWORK-BUG-017 rung 2 (future-guard): emit a structured
+	// version_drift envelope when a future framework fix requires a
+	// new tick flag and the installed kernel predates it. The current
+	// pin to 0.6.7 (the version that introduced --payload-file) is a
+	// no-op on every 0.6.7+ install — but the scaffolding is in place
+	// for the NEXT new-flag fix to bump `introducedIn` without
+	// re-discovering the silent-infra-backoff failure mode.
+	const versionGate = requireMinVersion({
+		feature: 'payload-file',
+		introducedIn: '0.6.7',
+		installedVersion: INSTALLED_KERNEL_VERSION,
+		missingFlag: '--payload-file',
+	})
+	if (versionGate) return exitWith(versionGate, 1)
+
 	const prCheck = validatePr(flags.get('pr'))
 	if (typeof prCheck !== 'string') return prCheck
 	const pr = prCheck

package/src/cli/commands/health-check.mjs

@@ -140,7 +140,7 @@ export function cmdHealthCheck(projectDir) {
 			issues.push({
 				type: 'missing-skills',
 				severity: 'warning',
-				detail: 'No installed skill version stamps found under .claude/skills or .agents/skills',
+				detail: 'No apt install manifests or version stamps found for any supported runtime',
 				install_surfaces: installs,
 			})
 		}

package/src/cli/commands/init.mjs

@@ -41,6 +41,7 @@ import {
 	writeLastInstallSummary,
 } from '../install/pipeline.mjs'
 import { RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs'
+import { runLegacyCleanup } from '../install/runtime-migrate.mjs'
 import {
 	CLASS_A_SETTINGS,
 	CLASS_B_SETTINGS,
@@ -48,6 +49,7 @@ import {
 	parseClassFlags,
 } from '../install/setting-class.mjs'
 import { detectAgentRuntime } from '../util/agent-runtime.mjs'
+import { buildAptSection } from '../util/aperant-section.mjs'
 import { atomicWriteJson } from '../util/atomic-write.mjs'
 import { aperantBanner } from '../util/banner.mjs'
 import { copyDirRecursive, injectInstructionFile } from '../util/copy.mjs'
@@ -88,8 +90,15 @@ const TRANSFORM_LOADERS = new Map(
  * additive: callers without the flag still get the no-op short-circuit
  * (preserves `init-upgrade-drift.test.ts` case (a)).
  *
+ * 0.7.0 — `--force-overwrite-catalog` (FRAMEWORK-BUG-023) bypasses the
+ * foreign-row defensive check in `injectInstructionFile`. Power-user
+ * flag only — no interview prompt. Without it, an instruction file
+ * carrying rows the generator didn't produce causes init to exit 2 with
+ * `code: 'instruction-file.foreign-rows'` so unattended upgrade flows
+ * surface the would-be data loss instead of silently clobbering it.
+ *
  * @param {string[]} args
- * @returns {{ runtimes: string[], runtimes_explicit: boolean, target: string|null, interactive: boolean, skipBootstrap: boolean, visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean, forceRuntimes: boolean }}
+ * @returns {{ runtimes: string[], runtimes_explicit: boolean, target: string|null, interactive: boolean, skipBootstrap: boolean, visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean, forceRuntimes: boolean, forceOverwriteCatalog: boolean, keepLegacy: boolean }}
  */
 export function parseInstallFlags(args) {
 	const flagSet = new Set(args.filter((a) => a.startsWith('--')))
@@ -105,6 +114,14 @@ export function parseInstallFlags(args) {
 	// 0.6.7 (Bug 2 fix) — opt-in bypass of the upgrade_noop short-circuit
 	// so /apt:update can re-stamp runtime files on a no-drift upgrade.
 	const forceRuntimes = flagSet.has('--force-runtimes')
+	// 0.7.0 (FRAMEWORK-BUG-023) — opt-in bypass of the foreign-row check
+	// in injectInstructionFile. Power-user flag only.
+	const forceOverwriteCatalog = flagSet.has('--force-overwrite-catalog')
+	// 0.7.0 (FRAMEWORK-BUG-021) — opt out of the codex legacy-tree cleanup
+	// that fires when `codex` is in the runtime set. Defaults to false so
+	// the cleanup runs by default; pass `--keep-legacy` to preserve the
+	// orphaned `.agents/skills/` tree on upgrades.
+	const keepLegacy = flagSet.has('--keep-legacy')
 
 	const classFlags = parseClassFlags(args)
 
@@ -112,6 +129,8 @@ export function parseInstallFlags(args) {
 		target,
 		skipBootstrap,
 		forceRuntimes,
+		forceOverwriteCatalog,
+		keepLegacy,
 		visibility: classFlags.visibility,
 		autonomy: classFlags.autonomy,
 		accept_new_defaults: classFlags.accept_new_defaults,
@@ -1164,6 +1183,27 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			}
 		}
 
+		// FRAMEWORK-BUG-021 — sweep the legacy `.agents/skills/` codex tree
+		// BEFORE the install pipeline runs so the install can re-stamp
+		// `.codex/` against a clean slate. Only fires when codex is in the
+		// requested runtime set and `--keep-legacy` was not passed; the
+		// helper itself is conservative (no-op on managed installs, no-op
+		// when no legacy framework files are present).
+		let legacyCleanup = null
+		if (effectiveAnswers.runtimes.includes('codex')) {
+			if (parsedFlags.keepLegacy) {
+				legacyCleanup = { runtime: 'codex', ran: false, reason: '--keep-legacy' }
+			} else {
+				const cleanup = runLegacyCleanup({ targetDir: installTarget })
+				legacyCleanup = { runtime: 'codex', ...cleanup }
+				if (cleanup.ran && cleanup.retained.length > 0) {
+					process.stderr.write(
+						`[apt-tools] legacy_cleanup retained ${cleanup.retained.length} user-added path(s) under .agents/skills/: ${cleanup.retained.join(', ')}\n`,
+					)
+				}
+			}
+		}
+
 		const results = await installRuntimes(
 			effectiveAnswers.runtimes,
 			canonicalRoot,
@@ -1186,7 +1226,14 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			effectiveAnswers,
 			interactiveTty,
 			kernelResult,
+			parsedFlags.forceOverwriteCatalog === true,
+			legacyCleanup,
 		)
+		// FRAMEWORK-BUG-023 — finishInit signals the foreign-row defensive
+		// abort by returning an early-exit sentinel envelope.
+		if (envelope?.__earlyExit) {
+			return envelope.__earlyExit
+		}
 		if (interactiveTty) {
 			await renderOutro(effectiveAnswers, results, version, kernelResult)
 			// TTY mode: envelope was persisted to disk + suppressed from stdout
@@ -1365,6 +1412,19 @@ async function renderOutro(answers, results, version, kernelResult) {
  *                                         deps/` — surfaced in the envelope so
  *                                         downstream tooling can detect a
  *                                         degraded install.
+ * @param {boolean} [forceOverwriteCatalog=false]
+ *                                         FRAMEWORK-BUG-023 — bypass the
+ *                                         foreign-row check in
+ *                                         injectInstructionFile when the user
+ *                                         explicitly opted in via
+ *                                         --force-overwrite-catalog.
+ * @param {object|null} [legacyCleanup=null]
+ *                                         FRAMEWORK-BUG-021 — outcome of the
+ *                                         codex `.agents/skills/` cleanup
+ *                                         step. `null` when codex was not in
+ *                                         the runtime set; otherwise the
+ *                                         shape `{ runtime, ran, … }` from
+ *                                         `runLegacyCleanup`.
  */
 function finishInit(
 	targetDir,
@@ -1376,6 +1436,8 @@ function finishInit(
 	answers,
 	suppressStdout = false,
 	kernelResult = null,
+	forceOverwriteCatalog = false,
+	legacyCleanup = null,
 ) {
 	writeLastInstallSummary(targetDir, runtimeResults, version)
 
@@ -1506,7 +1568,40 @@ function finishInit(
 	if (existsSync(claudeMdPath)) instructionFile = claudeMdPath
 	else if (existsSync(agentsMdPath)) instructionFile = agentsMdPath
 	else instructionFile = claudeMdPath
-	const injectionResult = injectInstructionFile(instructionFile)
+	// FRAMEWORK-BUG-023 — generate the section from discoverSkills before
+	// handing it to the writer. The writer also runs a foreign-row defensive
+	// check; if rows present in the file aren't in the generated set we
+	// signal exit-2 via the __earlyExit sentinel so cmdInit can route the
+	// envelope through exitWith() without writing a malformed install.
+	const aptSection = buildAptSection({
+		canonicalRoot,
+		targetDir,
+		cli: detectAgentRuntime(),
+	})
+	const injectionOutcome = injectInstructionFile(instructionFile, {
+		aptSection,
+		force: forceOverwriteCatalog,
+	})
+	if (injectionOutcome.status === 'aborted-foreign-rows') {
+		return {
+			__earlyExit: exitWith(
+				{
+					ok: false,
+					status: 'error',
+					command: 'init',
+					code: 'instruction-file.foreign-rows',
+					message:
+						`${basename(instructionFile)} contains skill rows not present in the installed framework: ` +
+						`${injectionOutcome.foreignRowIds.join(', ')}. ` +
+						'Re-run with --force-overwrite-catalog to regenerate anyway, or remove the foreign rows manually.',
+					foreignRowIds: injectionOutcome.foreignRowIds,
+					instructionFile: basename(instructionFile),
+				},
+				2,
+			),
+		}
+	}
+	const injectionResult = injectionOutcome.status
 
 	const installedClaude = chosenIds.includes('claude') || existsSync(join(targetDir, '.claude'))
 	const precompactResult = installedClaude
@@ -1617,6 +1712,11 @@ function finishInit(
 					...(kernelResult.reason ? { reason: kernelResult.reason } : {}),
 				}
 			: null,
+		// FRAMEWORK-BUG-021 — always-present envelope field. `null` when
+		// codex was not in the runtime set; otherwise the cleanup outcome
+		// (uses `{ ran: false, reason }` for every skip case so parsers
+		// see a uniform shape).
+		legacy_cleanup: legacyCleanup,
 	}
 
 	if (suppressStdout) {