@aperant/framework 0.8.1 → 0.8.6

package/skills/apt-triage/SKILL.md

@@ -31,8 +31,8 @@ This skill moves a task through a 5-state machine. The state machine
 runs identically regardless of backend (local-only / github-issues /
 app-inbox); only the mirror destination changes.
 
-**Pocock adoption attribution.** State machine + AGENT-BRIEF.md +
-OUT-OF-SCOPE.md sub-files ported from Matt Pocock's MIT-licensed
+**Aperant adoption attribution.** State machine + AGENT-BRIEF.md +
+OUT-OF-SCOPE.md sub-files ported from 
 `triage` skill. Aperant-specific extensions:
 
 - Backend abstraction (configured at `apt:setup` Batch 8 — task_tracking.backend)

package/skills/apt-update/SKILL.md

@@ -49,13 +49,14 @@ The cache file is at `~/.cache/aperant/apt-update-check.json`. It contains `runt
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs check-version . --json
 ```
 
-Parse the JSON. From 0.6.7 the envelope merges the SessionStart worker's cache (when fresh — written within the last hour to `~/.cache/aperant/apt-update-check.json`). Capture:
+Parse the JSON. From 0.6.7 the envelope merges the SessionStart worker's cache (when fresh — written within the last hour to `~/.cache/aperant/apt-update-check.json`). From 0.8.3 it also carries the workspace-aware `framework.workspace_version` field (Bundle A). Capture:
 
 - `framework.installed_version` — what's currently on disk
 - `framework.latest_version` — what npm reports as the latest published version (MAY BE `null` when the worker cache is stale / missing / wrong schema)
+- `framework.workspace_version` — set when a workspace `packages/framework/package.json` (with `name === "@aperant/framework"`) is found above the project root; null otherwise. When non-null AND ahead of `installed_version`, the workspace is the source of truth for self-host contributors (auto-detect, no `--from-source` required).
 - `runtimes[]` — list of installed runtime ids + per-runtime `stale_files` count
 - `stale_files_total` — drift tally across runtimes
-- `update_available` — true when worker cache is fresh AND `installed_version < latest_version`
+- `update_available` — true when worker cache is fresh AND `installed_version < latest_version`, OR when `workspace_version > installed_version` (Bundle A — fires regardless of npm cache state)
 - `dev_install_ahead` — true when local kernel is ahead of published (typical local dev)
 - `not_published` — true when npm returned 404 (package not yet on registry)
 - `lookup_error` — non-null when npm view failed for any non-404 reason (timeout, ENETDOWN, etc.)
@@ -64,11 +65,20 @@ The envelope is **single-shape** — every field above is always present. When t
 
 If `runtimes[]` is empty, tell the user they haven't installed Aperant into any runtime yet and suggest `apt-tools init . --claude` (or their preferred runtime). Stop.
 
-## 1.5. Bump the local kernel from npm when newer is available
+## 1.5. Workspace-aware bump — auto-detect dev-host self-host (Bundle A)
 
-The Aperant kernel lives at `.aperant/deps/node_modules/@aperant/framework/`. `apt-tools init` re-installs runtime files at THE LOCAL KERNEL'S VERSION — so a stale kernel means `/apt:update` re-stamps manifests at the OLD version even when npm has a newer release. Bump the kernel BEFORE invoking init.
+The Aperant kernel lives at `.aperant/deps/node_modules/@aperant/framework/`. `apt-tools init` re-installs runtime files at THE LOCAL KERNEL'S VERSION — so a stale kernel means `/apt:update` re-stamps manifests at the OLD version. Bump the kernel BEFORE invoking init.
 
-First, resolve `latest_version` when the envelope had `null` (stale cache).
+**FIRST**, branch on `framework.workspace_version` from step 1's envelope (Bundle A — automatic on every `/apt:update` run, no flag required):
+
+- When `workspace_version` is non-null AND ahead of `installed_version` — the user is an Aperant contributor self-hosting the framework, and a same-PR change bumped `packages/framework/package.json:version`. The workspace is the source of truth (NOT npm). Proceed to §1.7's workspace-pack mechanism. Skip §1.6 (npm view).
+- When `workspace_version` is null OR equal to `installed_version` — no workspace package, OR workspace + kernel already match. Fall through to §1.6 (npm bump path).
+
+This auto-detection replaces the previous "user must remember `--from-source`" footgun. The `--from-source` flag is still honored as an explicit override (§1.7) for: (a) testing pre-publish bumps even when auto-detect didn't fire, (b) forcing the workspace path when a stale `latest_version > workspace_version`.
+
+## 1.6. Bump the local kernel from npm when newer is available
+
+When §1.5 fell through (no workspace-ahead signal), resolve `latest_version` from npm. First, resolve `latest_version` when the envelope had `null` (stale cache).
 
 **Timeout enforcement (ID-04):** The `npm view` call must complete within 10 s — never block the user longer than the SessionStart worker would. Use npm's `--fetch-timeout` flag as the primary mechanism (universally portable across all npm versions); it sets the HTTP fetch timeout in milliseconds:
 
@@ -90,17 +100,47 @@ 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)
+## 1.7. Self-host case — bump from local workspace (FRAMEWORK-BUG-017)
+
+Fires when EITHER §1.5's workspace-ahead auto-detect signaled it, OR the user invoked `/apt:update --from-source` as an explicit override, 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. §1.6's `npm view` would fetch the published version (still the OLD one), so we skip it.
+
+The reliable bump mechanism is the `apt-tools install-from-source` subcommand (Bundle D), which packs the framework AND every `workspace:*` dep (transitively) into a single `npm install --prefix` invocation. Handles the same-PR unpublished-pair case (e.g. `framework@0.8.3` + `driver-sdk@0.2.0` both at `workspace:*`, both unpublished) without `EUNSUPPORTEDPROTOCOL`.
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs install-from-source . --json
+```
+
+Parse the returned envelope:
+
+```json
+{
+  "status": "ok",
+  "command": "install-from-source",
+  "tarballs": ["/tmp/aperant-driver-sdk-0.2.0.tgz", "/tmp/aperant-framework-0.8.3.tgz"],
+  "kernel_path": "/path/to/project/.aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs"
+}
+```
+
+Capture `tarballs[]` count and `kernel_path` for the Scenario A summary line (the kernel-version slot reads from `kernel_path`'s parent `package.json` rather than a static `{latest_version}` format string when this branch fired).
+
+On `status: 'error'`, the envelope carries an `error` field with the underlying failure (e.g. `pnpm pack ... exited with N`, `no @aperant/framework workspace found`, etc.). Surface it verbatim and STOP — do NOT proceed to init with a half-installed kernel.
+
+If `--from-source` was passed but `install-from-source` returns `no @aperant/framework workspace found`, surface a one-line error (`⚠ --from-source: no workspace package.json found — falling back to npm`) and proceed with the standard §1.6 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.
 
-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.
+### What `install-from-source` does under the hood
 
-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`.
+The `apt-tools install-from-source` helper materializes the workspace chain end-to-end. This is the equivalent manual recipe — useful for debugging or for users who want to understand the mechanism. **Prefer the one-line invocation above** unless you have a reason to do it by hand:
 
-Walk up from the project root looking for a sibling `packages/framework/package.json`. When found AND its `name === "@aperant/framework"`:
+⚠ Do NOT substitute `npm pack` — it leaves `workspace:*` literal in the tarball's package.json and breaks `npm install --prefix` with `EUNSUPPORTEDPROTOCOL`. Only `pnpm pack` resolves workspace protocols.
 
 ```bash
-# 1. Pack the workspace source into a versioned tarball.
+# 0. Ensure the dep closure is materialized — the `...` suffix installs transitive workspace deps.
 cd <workspace-root>
+pnpm install --filter @aperant/framework... --frozen-lockfile=false
+
+# 1. Pack the workspace source into a versioned tarball.
 pnpm --filter @aperant/framework pack --pack-destination /tmp
 
 # 2. Install the tarball into the project's kernel root.
@@ -108,19 +148,16 @@ 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.
+The manual recipe DOES NOT handle workspace:* deps transitively — for a same-PR pair (framework + driver-sdk both at `workspace:*`), you would need to pnpm-pack each dep separately and pass every tarball to the single `npm install --prefix` call. The `apt-tools install-from-source` subcommand walks `dependencies` + `peerDependencies` automatically.
 
 ## 2. Classify the update scenario
 
 Pick ONE of three scenarios based on what you parsed in step 1:
 
-- **A. Version bump available** — `installed_version !== latest_version` (regardless of drift). Users see this most often. Step 1.5 bumped the kernel; step 3 re-stamps manifests at the new version.
-- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten. Step 1.5 was a no-op; step 3 still needs `--force-runtimes` to re-stamp.
+- **A. Version bump available** — `latest_version != null && installed_version !== latest_version` (regardless of drift). Users see this most often. Step 1.5 (workspace) or 1.6 (npm) bumped the kernel; step 3 re-stamps manifests at the new version. **Important:** the `latest_version != null` guard prevents this scenario from firing when npm-latest is unknown (cache stale, package not published, network down — see Scenario E for that case).
+- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten. Steps 1.5 / 1.6 were no-ops; step 3 still needs `--force-runtimes` to re-stamp.
 - **C. Nothing to do** — `installed_version === latest_version` AND `stale_files_total === 0`. Still re-run init with `--force-runtimes` to refresh manifests + cache, but tell the user plainly that no version change happened.
+- **E. No version info available** — `latest_version === null` (cache stale OR package not published OR network down) AND `stale_files_total === 0`. Step 1.5 was a no-op (no workspace-ahead signal), step 1.6 found no usable npm version. Step 3 still re-stamps runtime files for safety, but the skill does NOT claim a version bump happened.
 
 ## 3. Re-install the currently-installed runtimes
 
@@ -169,6 +206,7 @@ Use the format in `<output_format>` below, tailored to the scenario from step 2.
   {install_root_basename}     {file_count} files refreshed
   {install_root_basename}     {file_count} files refreshed
   .aperant/deps/   kernel v{latest_version}
+  Migrated:        legacy .codex/agents/* swept ({removed_count} files removed)
 
   Next: restart Claude Code / Codex to activate the refreshed skills.
 ```
@@ -194,6 +232,7 @@ Example:
 
   {install_root_basename}     {file_count} files ({stale_count} refreshed)
   {install_root_basename}     {file_count} files
+  Migrated:        legacy .codex/agents/* swept ({removed_count} files removed)
 
   Statusline chip cleared.
 ```
@@ -205,10 +244,28 @@ Example:
 
   {install_root_basename}   {file_count} files
   {install_root_basename}   {file_count} files
+  Migrated:                 legacy .codex/agents/* swept ({removed_count} files removed)
 
   No changes applied. Statusline cache cleared.
 ```
 
+## Scenario E — no version info available
+
+```
+⚠ Aperant version info unavailable — refreshed runtime files only
+
+  Reason: {lookup_error || 'cache stale / not published'}
+  {install_root_basename}   {file_count} files
+  {install_root_basename}   {file_count} files
+  Migrated:                 legacy .codex/agents/* swept ({removed_count} files removed)
+
+  Run /apt:update again later to bump the kernel when npm view becomes reachable.
+```
+
+Scenario E fires when `latest_version === null` AND `stale_files_total === 0`. Step 1.5 (workspace-aware) was a no-op (no workspace-ahead signal); step 1.6 (npm view) returned null (cache stale, not published, or network down). The runtime refresh in step 3 still happens — the skill just does NOT claim a bump occurred.
+
+**`Migrated:` slot — conditional render.** The `Migrated:` line in Scenarios A / B / C / E fires ONLY when `init.legacy_cleanup?.ran === true && init.legacy_cleanup.rmdirs.some(p => p.includes('.codex'))`. When no migration happened, OMIT the line entirely (do NOT render an empty placeholder). The label reports the legacy Codex topology sweep (v0.7/v0.8 `.codex/agents/` + `.codex/commands/` misdirect → v0.8.2+ canonical `.agents/skills/<folder>/SKILL.md`) so users understand what changed under `.codex/` on disk.
+
 ## Scenario D — kernel install failed
 
 If init's `kernel.status !== "installed"`, append a warning ABOVE the summary:

package/skills/apt-verify-proof/SKILL.md

@@ -40,9 +40,95 @@ an action, evidence, and a verdict. No hallucinated passes.
 - For code review — use `/apt:review`
 - If no UI/visual changes were made — `/apt:verify` is faster
 
+## Driver Architecture
+
+`/apt:verify-proof` is **runtime-agnostic** — the workflow refers to IDL
+verbs (`driver.click`, `driver.screenshot`, `driver.navigate`, ...) and
+NEVER to concrete MCP tool names (per ID-01). The driver layer at
+`packages/framework/drivers/<id>/` maps verbs to transports.
+
+### Auto-detect
+
+The resolver auto-selects the highest-scoring driver per ID-02
+(capability_coverage > compatibility > stability > priority > locality).
+Preview the selection before running verify-proof:
+
+```bash
+apt-tools detect-runtime .
+# → { runtime: {is_electron, is_nextjs, ...}, selected_driver_id: "..." }
+```
+
+v0.8.6 — the runtime detector now walks `apps/*/package.json` by
+default and OR-merges each child's capabilities into the root. The
+canonical Aperant monorepo (Electron at `apps/desktop`, Next.js at
+`apps/web`) now reports `is_electron: true` AND `is_nextjs: true`
+without any config override.
+
+### Per-outcome dispatch (v0.8.6+)
+
+When the spec ships `## User Outcomes` (the verify-proof input
+contract — see CLAUDE.md), the workflow runner imports
+`resolveDriversForOutcomes()` from the resolver module and picks a
+driver PER OUTCOME SURFACE instead of a single per-run driver pick.
+
+```js
+import { resolveDriversForOutcomes } from '.aperant/deps/node_modules/@aperant/framework/src/cli/verify-proof/resolver.mjs'
+
+const entries = resolveDriversForOutcomes({
+  drivers, runtime,
+  outcomes: parsed.outcomes,  // from parseUserOutcomes(spec)
+})
+// → [{outcome_id: "O1", surface: "electron", driver: {...}}, ...]
+// For [electron+web] outcomes, two entries share the same outcome_id.
+```
+
+The legacy `apt-tools detect-runtime` still answers the per-run
+"which driver would be picked?" question for the override preview.
+For the per-outcome dispatch (the new contract), import
+`resolveDriversForOutcomes` directly.
+
+### Override
+
+Force a specific driver chain in `.aperant/config.json`:
+
+```json
+{ "verification": { "runtimes": ["electron", "cli"] } }
+```
+
+v0.8.6 — `verification.monorepo_globs` is the new opt-out for the
+monorepo walk. The walk now runs by default — adopters whose
+monorepo lives at a non-canonical prefix
+(`packages/apps/*`, `services/*`) override via
+`verification.monorepo_globs: ["packages/apps/*"]`; set to `[]` to
+disable the walk entirely (root-only behaviour, backwards compat).
+The `verification.runtimes[]` override stays the final escape hatch
+and is now usually unnecessary because the walk runs by default.
+
+### Bundled drivers (4)
+
+- **browser** (priority=100, ga) — Next.js / vanilla web frontends.
+- **electron** (priority=90, ga) — Electron desktop apps.
+- **cli** (priority=60, ga) — headless CI, output-shape assertions.
+- **api** (priority=50, ga) — HTTP / JSON-API regression tests.
+
+### Driver authors
+
+Third-party driver authors should run `apt-tools driver doctor .` before
+publishing to validate manifest schema + IDL conformance:
+
+```bash
+apt-tools driver doctor .
+# → { drivers: [{driverId, manifest_valid, idl_conformant, ...}], summary: {...} }
+```
+
+IDL types, error taxonomy, and conformance kit live inside the framework
+itself under `packages/framework/src/driver-sdk/` — see that directory's
+public-api-lock test for the surface contract.
+
 ## Execution
 
-Execute the verify-proof workflow end-to-end:
+Execute the verify-proof workflow end-to-end using IDL verbs (the driver
+maps verbs to its transport — MCP server, local command, HTTP):
 
 <execution_context>
 @packages/framework/workflows/verify-proof.md

package/skills/apt-zoom-out/SKILL.md

@@ -26,8 +26,8 @@ Tiny skill. High signal. The user named an area; you produce a one-page
 orientation so they (or a future agent) can plan or edit without
 re-learning the codebase from scratch.
 
-**Pocock adoption note.** This skill descends from Matt Pocock's `zoom-out`
-discipline. Aperant's router is dynamic and LLM-driven, so unlike Pocock's
+**Aperant adoption note.** This skill descends from 's `zoom-out`
+discipline. Aperant's router is dynamic and LLM-driven, so unlike 's
 upstream this skill is **router-invocable** (no `disable-model-invocation:
 true` flag). The work-intent — "give me a broader picture of X" — is
 genuine and the router resolves natural-language triggers without forcing
@@ -37,7 +37,7 @@ the user to remember the verb name.
 
 - Dropped into a new module / package / area of the monorepo
 - About to plan a feature that crosses an unfamiliar boundary
-- The codebase has CONTEXT.md (Pocock glossary) and you want to load it
+- The codebase has CONTEXT.md (Aperant glossary) and you want to load it
   alongside the structural map
 
 ## When Not to Use

package/src/cli/commands/adr.mjs

@@ -1,5 +1,5 @@
 /**
- * commands/adr.mjs — `apt-tools adr write` (Pocock adoption ST-6, AC5).
+ * commands/adr.mjs — `apt-tools adr write`.
  *
  * Writes an ADR under `docs/adr/NNNN-slug.md` ONLY when all three Nygard
  * gates pass: hard-to-reverse AND surprising-without-context AND

package/src/cli/commands/audit-branch-current.mjs

@@ -0,0 +1,250 @@
+/**
+ * commands/audit-branch-current.mjs — pre-PR rebase gate envelope for apt:ship §0.7.
+ *
+ * Pure read-only branch-drift audit. Given a base ref (default `main`), reports
+ * how many commits HEAD is ahead/behind `origin/<base>`, captures the current
+ * `origin/<base>` tip SHA (the lease target for any subsequent
+ * `--force-with-lease=refs/heads/<branch>:<sha>` push), and probes whether a
+ * trial merge against the remote tip would conflict.
+ *
+ * Single network call: `git fetch origin <base>`. Fetch failure is recovered
+ * as `audit_warning: 'fetch-failed'` — the envelope still returns, just with
+ * stale counts. No `git rebase`, no `git push`, no `git reset` — the SKILL.md
+ * prose owns history rewrites.
+ *
+ * Envelope:
+ *
+ *   {
+ *     status:             'ok',
+ *     command:            'audit-branch-current',
+ *     projectDir:         string,
+ *     base:               string,
+ *     ahead:              number,           // commits HEAD has over origin/<base>
+ *     behind:             number,           // commits origin/<base> has over HEAD
+ *     remote_tip_sha:     string | null,    // origin/<base> after fetch
+ *     mergeable:          boolean | null,   // null when probe unavailable
+ *     conflicts_preview?: string[],         // populated only when mergeable=false
+ *     audit_warning?:     string            // 'fetch-failed' | 'git-version-too-old' | ...
+ *   }
+ *
+ * Spec cross-ref: .aperant/tasks/apt-ship-pre-pr-rebase-gate-audit-branch_21-05-26/spec.md
+ *
+ * @internal
+ */
+
+import { execFileSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Try-execute a git command, returning {ok, stdout, stderr, code}. Never throws.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitTry(cwd, args) {
+	try {
+		const stdout = execFileSync('git', args, {
+			cwd,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+		return { ok: true, stdout, stderr: '', code: 0 }
+	} catch (e) {
+		// execFileSync throws an error whose `stdout`, `stderr`, and `status`
+		// properties carry the captured output and exit code.
+		return {
+			ok: false,
+			stdout: typeof e?.stdout === 'string' ? e.stdout : (e?.stdout?.toString() ?? ''),
+			stderr: typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? ''),
+			code: typeof e?.status === 'number' ? e.status : 1,
+		}
+	}
+}
+
+/**
+ * Parse `--base <ref>` (or `--base=<ref>`) from extraArgs. Defaults to 'main'.
+ *
+ * @param {string[]} extraArgs
+ * @returns {string}
+ */
+function parseBaseFlag(extraArgs) {
+	for (let i = 0; i < extraArgs.length; i++) {
+		const a = extraArgs[i]
+		if (a === '--base' && i + 1 < extraArgs.length) return extraArgs[i + 1]
+		if (a.startsWith('--base=')) return a.slice('--base='.length)
+	}
+	return 'main'
+}
+
+/**
+ * Parse `git merge-tree --write-tree --no-messages HEAD origin/<base>` output
+ * for conflict file paths. Modern (git ≥ 2.38) merge-tree emits, on conflict:
+ *
+ *   <tree-OID>
+ *   <conflict report lines, each "<mode> <stage> <oid>\t<path>" for stage > 0>
+ *   (NUL separator)
+ *   <textual conflict messages>
+ *
+ * Older variants emit a `+<<<<<<< ... +======= ... +>>>>>>>` diff per file.
+ * For correctness we use the stable form: extract file paths from the conflict
+ * report. The report includes the SAME path multiple times (once per non-zero
+ * stage), so we de-dupe.
+ *
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+function parseConflictPaths(stdout) {
+	const paths = new Set()
+	for (const rawLine of stdout.split('\n')) {
+		const line = rawLine.replace(/\0/g, '')
+		if (!line.trim()) continue
+		// Match "<mode> <oid> <stage>\t<path>" — git merge-tree --write-tree
+		// emits conflict report lines as "<mode> <oid> <stage>\t<path>".
+		// Stage 0 means no conflict, so we only surface stage ≥ 1.
+		const m = line.match(/^(\d{6})\s+([0-9a-f]{4,40})\s+(\d)\t(.+)$/)
+		if (m) {
+			const stage = Number.parseInt(m[3], 10)
+			if (stage >= 1) paths.add(m[4])
+			continue
+		}
+		// Fallback (older git): the textual report block prefixes paths with
+		// "CONFLICT (content): Merge conflict in <path>".
+		const c = line.match(/Merge conflict in (.+)$/)
+		if (c) paths.add(c[1].trim())
+	}
+	return Array.from(paths).sort()
+}
+
+/**
+ * Detect "git too old" from merge-tree stderr. Pre-2.38 git rejects
+ * `--write-tree` outright; older still rejects merge-tree's modern arg
+ * shape entirely. We treat any non-zero-with-no-output as "version too old"
+ * — callers are expected to fall back gracefully.
+ *
+ * @param {string} stderr
+ * @returns {boolean}
+ */
+function isGitVersionTooOld(stderr) {
+	return /unknown option|did you mean|usage: git merge-tree/i.test(stderr)
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export function auditBranchCurrent(projectDir, extraArgs = []) {
+	if (!projectDir) {
+		return err('Usage: apt-tools audit branch-current <project-dir> [--base <ref>]')
+	}
+	const targetDir = resolve(projectDir)
+	const base = parseBaseFlag(extraArgs)
+
+	/** @type {string | undefined} */
+	let auditWarning
+	/** @type {string[]} */
+	const warnings = []
+
+	// 1. Fetch origin <base>. Tolerate failure (offline, no remote, etc.).
+	const fetch = gitTry(targetDir, ['fetch', 'origin', base])
+	if (!fetch.ok) {
+		auditWarning = 'fetch-failed'
+		warnings.push(fetch.stderr.trim().split('\n').slice(0, 3).join(' | '))
+	}
+
+	// 2. Resolve origin/<base> tip.
+	let remoteTipSha = null
+	const tip = gitTry(targetDir, ['rev-parse', `origin/${base}`])
+	if (tip.ok) {
+		remoteTipSha = tip.stdout.trim()
+	} else {
+		// No origin/<base> ref at all — emit an envelope with null counts so the
+		// caller can recognise the gap. The SKILL.md prose treats null counts as
+		// "audit unavailable, STOP with a clear message" rather than proceeding.
+		return ok({
+			status: 'ok',
+			command: 'audit-branch-current',
+			projectDir: targetDir,
+			base,
+			ahead: null,
+			behind: null,
+			remote_tip_sha: null,
+			mergeable: null,
+			audit_warning: auditWarning ?? 'no-remote-base-ref',
+			warnings,
+		})
+	}
+
+	// 3. Counts.
+	let ahead = 0
+	let behind = 0
+	const aheadOut = gitTry(targetDir, ['rev-list', '--count', `origin/${base}..HEAD`])
+	const behindOut = gitTry(targetDir, ['rev-list', '--count', `HEAD..origin/${base}`])
+	if (aheadOut.ok) ahead = Number.parseInt(aheadOut.stdout.trim(), 10) || 0
+	if (behindOut.ok) behind = Number.parseInt(behindOut.stdout.trim(), 10) || 0
+
+	// 4. Mergeability.
+	//    - When behind === 0, the branch is current or strictly ahead — no
+	//      remote changes to integrate, mergeable = true by definition.
+	//    - When behind > 0 AND ahead === 0, the branch is strictly fast-forward
+	//      behind — a clean fast-forward rebase is always mergeable.
+	//    - When diverged (behind > 0 AND ahead > 0), probe via git merge-tree.
+	let mergeable
+	/** @type {string[] | undefined} */
+	let conflictsPreview
+	if (behind === 0) {
+		mergeable = true
+	} else if (behind > 0 && ahead === 0) {
+		mergeable = true
+	} else {
+		// Diverged. Run modern merge-tree trial.
+		const probe = gitTry(targetDir, [
+			'merge-tree',
+			'--write-tree',
+			'--no-messages',
+			'HEAD',
+			`origin/${base}`,
+		])
+		if (probe.ok) {
+			mergeable = true
+		} else if (probe.code === 1) {
+			// Documented merge-tree exit-code semantics: 0 clean, 1 conflict,
+			// other = invocation error.
+			mergeable = false
+			conflictsPreview = parseConflictPaths(probe.stdout)
+		} else if (isGitVersionTooOld(probe.stderr)) {
+			mergeable = null
+			auditWarning = auditWarning ?? 'git-version-too-old'
+			warnings.push(`git merge-tree --write-tree unsupported: ${probe.stderr.trim().slice(0, 200)}`)
+		} else {
+			// Unknown probe failure — treat as unknown rather than asserting
+			// clean.
+			mergeable = null
+			auditWarning = auditWarning ?? 'merge-tree-probe-failed'
+			warnings.push(
+				`git merge-tree probe failed (code ${probe.code}): ${probe.stderr.trim().slice(0, 200)}`,
+			)
+		}
+	}
+
+	const envelope = {
+		status: 'ok',
+		command: 'audit-branch-current',
+		projectDir: targetDir,
+		base,
+		ahead,
+		behind,
+		remote_tip_sha: remoteTipSha,
+		mergeable,
+	}
+	if (conflictsPreview && conflictsPreview.length > 0) {
+		envelope.conflicts_preview = conflictsPreview
+	}
+	if (auditWarning) envelope.audit_warning = auditWarning
+	if (warnings.length > 0) envelope.warnings = warnings
+	return ok(envelope)
+}
+
+// Test-only export for unit-level parser coverage (not part of the public CLI
+// contract).
+export { parseConflictPaths as __parseConflictPathsForTests }

package/src/cli/commands/audit.mjs

@@ -28,6 +28,14 @@
  *       committable bucket is non-empty after staging (CI-friendly gate).
  *       Default: report-only, exits 0 regardless.
  *
+ *   apt-tools audit branch-current <project-dir> [--base <ref>]
+ *       Pre-PR rebase gate envelope for apt:ship §0.7. Pure read-only:
+ *       `git fetch origin <base>`, captures origin/<base> tip SHA, counts
+ *       ahead/behind, and (when diverged) probes mergeability with
+ *       `git merge-tree --write-tree`. Returns {ahead, behind,
+ *       remote_tip_sha, mergeable, conflicts_preview?}. Never mutates
+ *       HEAD, the index, the worktree, or any remote ref.
+ *
  * Single source of truth: buildPolicyIgnoreMatcher in share-policy.mjs is
  * the ONLY matcher anywhere in the CLI. If you add a new taxonomy class or
  * toggle, update share-policy and this command follows automatically.
@@ -46,6 +54,7 @@ import { selfStageCommittableWrites } from '../artifacts/self-stage.mjs'
 import { buildPolicyIgnoreMatcher, resolveSharePolicy } from '../config/share-policy.mjs'
 import { detectPublicRemote } from '../git/remote.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
+import { auditBranchCurrent } from './audit-branch-current.mjs'
 
 /**
  * Dispatch an `audit <subcommand>` call.
@@ -59,7 +68,7 @@ import { err, exitWith, ok } from '../util/result.mjs'
 export function cmdAudit(subcommand, projectDir, extraArgs = []) {
 	if (!subcommand) {
 		return err(
-			'Usage: apt-tools audit <privacy|visibility-signals|pending-artifacts> <project-dir> [flags]',
+			'Usage: apt-tools audit <privacy|visibility-signals|pending-artifacts|branch-current> <project-dir> [flags]',
 		)
 	}
 	if (!projectDir) {
@@ -73,9 +82,11 @@ export function cmdAudit(subcommand, projectDir, extraArgs = []) {
 			return auditVisibilitySignals(targetDir)
 		case 'pending-artifacts':
 			return auditPendingArtifacts(targetDir, extraArgs)
+		case 'branch-current':
+			return auditBranchCurrent(targetDir, extraArgs)
 		default:
 			return err(
-				`Unknown audit subcommand: ${subcommand}. Expected 'privacy', 'visibility-signals', or 'pending-artifacts'.`,
+				`Unknown audit subcommand: ${subcommand}. Expected 'privacy', 'visibility-signals', 'pending-artifacts', or 'branch-current'.`,
 			)
 	}
 }

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

@@ -29,7 +29,13 @@
  *     // `framework_version` field (read from package.json, never from
  *     // the cache).
  *     framework: {
- *       latest_version: '0.6.7' | null
+ *       latest_version: '0.6.7' | null,
+ *       // Bundle A (0.8.3) — additive nullable field. Set when a workspace
+ *       // `packages/framework/package.json` is found above the project root
+ *       // and its `name === '@aperant/framework'`. When workspace_version
+ *       // is ahead of the running kernel, `update_available` flips true
+ *       // regardless of cache state (workspace wins on self-host).
+ *       workspace_version: '0.8.3' | null
  *     },
  *     update_available: false,
  *     dev_install_ahead: false,
@@ -48,11 +54,13 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { findWorkspaceFrameworkVersion } from '../install/find-workspace-framework-version.mjs'
 import { readManifest } from '../install/manifest.mjs'
 import { detectInstalledRuntimes } from '../install/runtime-detect.mjs'
 import { readFreshUpdateCache } from '../install/update-chips.mjs'
 import { inspectManifestFiles } from '../install/version-header.mjs'
 import { err, ok } from '../util/result.mjs'
+import { compareVersions } from '../util/semver.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -167,6 +175,16 @@ export function cmdCheckVersion(projectDir) {
 		if (typeof c.lookup_error === 'string') lookupError = c.lookup_error
 	}
 
+	// Bundle A — additive `framework.workspace_version` field. When the
+	// workspace package.json is ahead of the running kernel, flip
+	// `update_available` true regardless of cache state (the workspace is
+	// the source of truth on self-host). schema_version stays at 1 (D-01).
+	const workspace = findWorkspaceFrameworkVersion(targetDir)
+	const workspaceVersion = workspace?.source_version ?? null
+	if (workspaceVersion && compareVersions(workspaceVersion, frameworkVersion) > 0) {
+		updateAvailable = true
+	}
+
 	return ok({
 		status,
 		command: 'check-version',
@@ -178,6 +196,7 @@ export function cmdCheckVersion(projectDir) {
 		// file-header schema comment.
 		framework: {
 			latest_version: latestVersion,
+			workspace_version: workspaceVersion,
 		},
 		update_available: updateAvailable,
 		dev_install_ahead: devInstallAhead,