@aperant/framework 0.10.0 → 0.12.0

package/src/cli/commands/apply-recipe.mjs

@@ -0,0 +1,105 @@
+/**
+ * commands/apply-recipe.mjs — `apt-tools apply-recipe <projectDir> [--confirm] [--accept-all] [--force]`.
+ *
+ * Wraps applyRecipe() at the CLI surface.
+ *
+ *   --confirm     switches from dry-run (the default) to live writes.
+ *   --accept-all  bypasses per-change confirmation (pipeline/scripted use).
+ *   --force       overrides the TOFU user_modified guard — overwrites files
+ *                 whose SHA diverges from the recipe's expected before value.
+ *                 Files containing the recipe's marker are still skipped.
+ *
+ * The two flags compose: `--confirm` alone enters live mode but defers
+ * per-change accept/skip to the caller — without `--accept-all` and
+ * without a stdin-driven prompt, every change is SKIPPED (fail-safe per
+ * ID-02). Adopters using the interactive apt-setup SKILL.md mini-flow
+ * walk each change one at a time before invoking the CLI with
+ * `--accept-all` once they've reviewed the diff. Adopters in CI /
+ * fan-out / scripted contexts pass both flags up front.
+ *
+ * Exit codes:
+ *   0 — applyRecipe completed (dry-run or confirmed)
+ *   1 — usage error / no-recipe-match / applyRecipe threw
+ */
+
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+import { loadRuntimeCapabilities } from '../util/runtime-capabilities.mjs'
+import { applyRecipe } from '../verify-proof/sandbox/apply.mjs'
+import { matchPatternForProject } from '../verify-proof/sandbox/pattern-matcher.mjs'
+import { discoverBundledRecipes } from '../verify-proof/sandbox/sandbox-config.mjs'
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [extra]
+ */
+export async function cmdApplyRecipe(projectDir, extra = []) {
+	if (!projectDir) {
+		return err('Usage: apt-tools apply-recipe <project-dir> [--confirm] [--accept-all]')
+	}
+
+	const flags = parseFlags(extra)
+	const confirm = flags.has('confirm')
+	const acceptAll = flags.has('accept-all')
+	const force = flags.has('force')
+
+	const recipes = discoverBundledRecipes()
+	const runtime = loadRuntimeCapabilities(projectDir)
+
+	const explicitRecipeId = flags.get('recipe') ?? null
+	let recipeId
+	let matchReason
+	if (explicitRecipeId) {
+		recipeId = explicitRecipeId
+		matchReason = 'explicit'
+	} else {
+		const match = matchPatternForProject(projectDir, runtime, recipes)
+		recipeId = match.recipeId
+		matchReason = match.reason
+	}
+
+	if (!recipeId) {
+		return exitWith(
+			{
+				status: 'error',
+				command: 'apply-recipe',
+				code: 'E_NO_RECIPE',
+				reason: matchReason,
+				runtime,
+				docs: 'docs/verify-proof-sandbox-patterns.md',
+			},
+			1,
+		)
+	}
+
+	try {
+		const result = await applyRecipe({
+			projectDir,
+			recipeId,
+			recipes,
+			confirm,
+			// AC8 + ID-02 — only auto-accept when the caller passed
+			// --accept-all explicitly. Without the flag the underlying
+			// applyRecipe defaults to skip (every change recorded as
+			// `user_declined`); callers driving per-change UX wrap the
+			// applier directly with their own confirmer.
+			perChangeConfirm: acceptAll ? async () => 'accept' : undefined,
+			force,
+		})
+		return ok({
+			status: 'ok',
+			command: 'apply-recipe',
+			project_dir: projectDir,
+			recipe_id: recipeId,
+			recipe_version: result.recipe_version,
+			confirm,
+			accept_all: acceptAll,
+			aborted: result.aborted,
+			writes: result.writes,
+			skips: result.skips,
+			audit_path: result.audit_path,
+		})
+	} catch (e) {
+		return err(`apply-recipe: ${e?.message ?? String(e)}`)
+	}
+}

package/src/cli/commands/catch-up.mjs

@@ -0,0 +1,67 @@
+/**
+ * commands/catch-up.mjs — read-only re-view of the combined catch-up panel
+ * (LD-13). Backs the `/apt:catch-up` skill.
+ *
+ * Recompute-only contract: this command computes the SAME panel the
+ * interactive route call would show (Welcome-Back + gated Team-Change Digest)
+ * against the CURRENT Last-Seen Marker, but it NEVER advances the marker. A
+ * user who dismissed the auto-on-apt display can re-summon it without
+ * disturbing their baseline. Distinct from /apt:resume (full context restore).
+ */
+
+import { resolve } from 'node:path'
+import { loadProjectConfig } from '../config/load.mjs'
+import { resolveSharePolicy } from '../config/share-policy.mjs'
+import { computeCatchUpPanel } from '../coordination/catch-up.mjs'
+import { createCoordinationStore } from '../coordination/store.mjs'
+import { resolveLocalDefaultBranch } from '../git/default-branch.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * @param {string} projectDir
+ * @returns {{ envelope: object, exitCode: number }}
+ */
+export function cmdCatchUp(projectDir) {
+	if (!projectDir) return err('Usage: apt-tools catch-up <project-dir>')
+	const targetDir = resolve(projectDir)
+
+	// Setup mirrors computeCatchUpForRoute in commands/route.mjs (advances marker).
+	const config = loadProjectConfig(targetDir)
+	if (!config) {
+		return ok({
+			status: 'ok',
+			command: 'catch-up',
+			catch_up: null,
+			reason: 'No .aperant/config.json — nothing to catch up on',
+		})
+	}
+
+	const store = createCoordinationStore(targetDir)
+	const marker = store.readLastSeen()
+	const td = config?.collaboration?.team_digest
+	const vis = resolveSharePolicy(config).visibility
+	const needsDigest = td?.enabled !== false && (vis === 'team' || vis === 'oss')
+	const defaultBranch = needsDigest ? resolveLocalDefaultBranch(targetDir) : null
+
+	let catch_up = null
+	try {
+		catch_up = computeCatchUpPanel(targetDir, {
+			config,
+			now: Date.now(),
+			marker,
+			defaultBranch,
+		})
+	} catch (e) {
+		console.warn('[apt] catch-up:', e?.message ?? e)
+		catch_up = null
+	}
+
+	// NOTE: recompute-only — we deliberately do NOT call store.advanceLastSeen.
+	// The marker baseline is owned by the interactive route path (route.mjs).
+	return ok({
+		status: 'ok',
+		command: 'catch-up',
+		catch_up,
+		reason: catch_up ? 'Catch-up panel recomputed' : 'Nothing new since your last visit',
+	})
+}

package/src/cli/commands/mobile-prepare.mjs

@@ -0,0 +1,151 @@
+/**
+ * commands/mobile-prepare.mjs — `apt-tools mobile prepare`.
+ *
+ * Owns the mobile app lifecycle for the verify-proof mobile surface
+ * (decisions D-03/D-04): build → install → launch → Metro → launch-readiness
+ * gate. This is the home for multi-minute orchestration that CANNOT live in a
+ * driver PreflightCheck (those are ≤5s, shell-free, single LocalCommand).
+ *
+ * The command is PLAN-producing: it resolves the ordered launch sequence and
+ * the readiness-gate contract and returns them in the envelope. The
+ * verify-proof workflow runner (which holds the host tool surface) executes
+ * the sequence, gates on the readiness signals, THEN hands UI verbs to the
+ * mobile driver. This mirrors the driver pattern (driver.mjs are adapters;
+ * the runner dispatches).
+ *
+ * Pure, unit-testable seams: `planLaunchSequence` + `isAppReady`.
+ */
+
+import { loadRuntimeCapabilities } from '../util/runtime-capabilities.mjs'
+
+/**
+ * @typedef {{ binary: string, args: string[] }} LocalCommand
+ */
+
+/**
+ * Resolve the ordered launch sequence for a (platform, mode, device).
+ *
+ * - mode 'expo' — `npx expo run:ios|run:android` builds, installs, launches,
+ *   and starts Metro in one step (the common Expo/RN path).
+ * - mode 'native' — device-prep only (`xcrun simctl boot` / `adb
+ *   wait-for-device`); the native build+install+launch is delegated (gradle /
+ *   the XcodeBuildMCP escalation per D-02), out of scope for v1's planner.
+ *
+ * @param {{ platform?: string, mode?: string, device?: string }} [opts]
+ * @returns {LocalCommand[]}
+ */
+export function planLaunchSequence(opts = {}) {
+	const { platform, mode = 'expo', device } = opts
+	if (platform !== 'ios' && platform !== 'android') {
+		throw new Error(`planLaunchSequence: platform must be 'ios' or 'android', got "${platform}"`)
+	}
+	if (mode !== 'expo' && mode !== 'native') {
+		throw new Error(`planLaunchSequence: mode must be 'expo' or 'native', got "${mode}"`)
+	}
+
+	if (mode === 'expo') {
+		const expoArgs = ['expo', platform === 'ios' ? 'run:ios' : 'run:android']
+		if (device) expoArgs.push('--device', device)
+		return [{ binary: 'npx', args: expoArgs }]
+	}
+
+	// native — device prep only.
+	if (platform === 'ios') {
+		return [{ binary: 'xcrun', args: ['simctl', 'boot', device ?? 'booted'] }]
+	}
+	return [{ binary: 'adb', args: device ? ['-s', device, 'wait-for-device'] : ['wait-for-device'] }]
+}
+
+/**
+ * Launch-readiness predicate (D-04). A successful screenshot alone is NOT
+ * enough — for RN/Expo it can capture a native splash, an Expo loading
+ * overlay, a redbox, or the dev-client launcher. ALL signals must hold before
+ * UI driving starts. For a pure-native app (no JS bundle) the caller passes
+ * `bundleConnected: true` and `launcherState: false`.
+ *
+ * @param {{ foregrounded?: boolean, bundleConnected?: boolean, redbox?: boolean, launcherState?: boolean }} [signals]
+ * @returns {boolean}
+ */
+export function isAppReady(signals) {
+	const s = signals && typeof signals === 'object' ? signals : {}
+	return (
+		s.foregrounded === true &&
+		s.bundleConnected === true &&
+		s.redbox !== true &&
+		s.launcherState !== true
+	)
+}
+
+/** The readiness-gate contract surfaced to the workflow runner. */
+const READINESS_GATE = {
+	description:
+		'App-ready gate (D-04). All signals must hold before UI verbs are dispatched to the mobile driver.',
+	signals: ['foregrounded', 'bundleConnected', 'no-redbox', 'no-launcher-state'],
+}
+
+/** @param {string} message */
+function errorEnvelope(message) {
+	return { envelope: { status: 'error', command: 'mobile-prepare', error: message }, exitCode: 1 }
+}
+
+/**
+ * Parse `--platform <ios|android> [--mode <expo|native>] [--device <id>]`.
+ *
+ * @param {string[]} args
+ * @returns {{ platform?: string, mode?: string, device?: string }}
+ */
+function parseFlags(args) {
+	/** @type {{ platform?: string, mode?: string, device?: string }} */
+	const opts = {}
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === '--platform' && args[i + 1]) opts.platform = args[++i]
+		else if (args[i] === '--mode' && args[i + 1]) opts.mode = args[++i]
+		else if (args[i] === '--device' && args[i + 1]) opts.device = args[++i]
+	}
+	return opts
+}
+
+/**
+ * `apt-tools mobile prepare <project-dir> --platform <ios|android>
+ *  [--mode <expo|native>] [--device <id>]`
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ * @returns {{ envelope: object, exitCode: number }}
+ */
+export function cmdMobilePrepare(projectDir, args) {
+	const opts = parseFlags(args ?? [])
+	if (opts.platform !== 'ios' && opts.platform !== 'android') {
+		return errorEnvelope('--platform <ios|android> is required')
+	}
+	if (opts.mode && opts.mode !== 'expo' && opts.mode !== 'native') {
+		return errorEnvelope(`--mode must be 'expo' or 'native', got "${opts.mode}"`)
+	}
+
+	// Infer mode from the project shape when not explicitly given (ties the
+	// detector to the launch story — an Expo/RN project launches via `expo run`).
+	let mode = opts.mode
+	if (!mode) {
+		const caps = loadRuntimeCapabilities(projectDir ?? '.')
+		mode = caps.is_expo || caps.is_react_native ? 'expo' : 'native'
+	}
+
+	const launch_sequence = planLaunchSequence({ platform: opts.platform, mode, device: opts.device })
+
+	return {
+		envelope: {
+			status: 'ok',
+			command: 'mobile-prepare',
+			platform: opts.platform,
+			mode,
+			device: opts.device ?? null,
+			launch_sequence,
+			readiness_gate: READINESS_GATE,
+			note:
+				'Plan only — the verify-proof workflow runner executes the launch sequence, gates on ' +
+				'the readiness signals, then hands UI verbs to the mobile driver. System prereqs ' +
+				'(idb/adb/Xcode/SDK) are validated by `apt-tools driver doctor` (D-09).',
+		},
+		exitCode: 0,
+	}
+}

package/src/cli/commands/pr-review.mjs

@@ -727,17 +727,30 @@ function parseGhPrView(raw) {
  * the viewer's personal handle (e.g. `AndyMik90`). They never match, which
  * previously caused every same-repo, owned PR to be mis-classified as
  * `external` and silently disabled auto-fix. The third arg `baseRepoOwner`
- * is the source of truth for "is this a fork PR?". `viewerLogin` is kept
- * only for backward-compatible signal reporting.
+ * is the source of truth for "is this a fork PR?".
+ *
+ * IMPORTANT (G44): "owned" means "a PR I authored," NOT "a branch in a repo I
+ * can push to." The owned test is strictly `gh.author.login === viewerLogin`
+ * — author IDENTITY, not `authorAssociation`. Previously a same-repo PR with
+ * `authorAssociation ∈ {OWNER, MEMBER, COLLABORATOR}` was classified `owned`,
+ * which meant every teammate's same-repo PR triggered the auto-fix-and-push
+ * pipeline on their branch. Now `authorAssociation` is retained only in the
+ * signal for human-readable tracing; it no longer gates the decision. The
+ * "is this mine" comparand is `gh.author?.login`, never `headRepoOwner`
+ * (comparing headRepoOwner to viewerLogin was the H1 bug — it never matches
+ * on an org-owned repo). Fork detection and author identity are independent:
+ * fork detection answers "did this come from a fork?"; author identity
+ * answers "did I write it?".
  *
  * @param {Record<string, any> | null | undefined} gh    parsed `gh pr view` JSON (may have `authorAssociation` grafted in by the REST-fetch path)
- * @param {string | null | undefined} viewerLogin        personal login from `gh api user` (fallback comparand for fork detection)
- * @param {string | null | undefined} [baseRepoOwner]    the org/user that owns the repo the PR targets (preferred comparand)
+ * @param {string | null | undefined} viewerLogin        personal login from `gh api user` (compared to `gh.author.login` for the owned test)
+ * @param {string | null | undefined} [baseRepoOwner]    the org/user that owns the repo the PR targets (fork-detection comparand)
  * @returns {{ authorship_mode: 'owned' | 'external' | 'unknown', authorship_signal: string }}
  */
 export function decideAuthorshipFromGh(gh, viewerLogin, baseRepoOwner = null) {
 	if (!gh) return { authorship_mode: 'unknown', authorship_signal: 'gh_payload_missing' }
 	const association = gh.authorAssociation ?? gh.author?.association ?? null
+	const author = gh.author?.login ?? null
 	const headRepoOwner =
 		gh.headRepository?.owner?.login ??
 		gh.headRepositoryOwner?.login ??
@@ -745,28 +758,36 @@ export function decideAuthorshipFromGh(gh, viewerLogin, baseRepoOwner = null) {
 		null
 	// Prefer baseRepoOwner when supplied; fall back to viewerLogin only for
 	// older callers that haven't been updated yet (e.g. legacy tests). The
-	// fallback preserves prior behavior for the personal-repo case.
+	// fallback preserves prior fork-detection behavior for the personal-repo
+	// case.
 	const compareOwner = baseRepoOwner ?? viewerLogin
 	const isFork = headRepoOwner && compareOwner && headRepoOwner !== compareOwner
 
-	const ownerLike = ['OWNER', 'MEMBER', 'COLLABORATOR']
 	const externalLike = ['NONE', 'CONTRIBUTOR', 'FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER']
 
-	if (!isFork && association && ownerLike.includes(association)) {
+	// G44: owned ⟺ (not a fork) AND the PR was authored by the running viewer.
+	if (!isFork && author && viewerLogin && author === viewerLogin) {
 		return {
 			authorship_mode: 'owned',
-			authorship_signal: `authorAssociation=${association}, same-repo branch (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'})`,
+			authorship_signal: `authored-by-viewer (author=${author}, viewer=${viewerLogin}), same-repo branch (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'}), authorAssociation=${association ?? 'null'}`,
 		}
 	}
-	if (isFork || (association && externalLike.includes(association))) {
+	// Forks, external-like associations, AND non-fork PRs authored by someone
+	// other than the viewer (a teammate's same-repo PR — the G44 case) all
+	// resolve to external (comment-only).
+	if (
+		isFork ||
+		(association && externalLike.includes(association)) ||
+		(!isFork && author && viewerLogin && author !== viewerLogin)
+	) {
 		return {
 			authorship_mode: 'external',
-			authorship_signal: `authorAssociation=${association}, fork=${Boolean(isFork)} (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'})`,
+			authorship_signal: `authorAssociation=${association ?? 'null'}, fork=${Boolean(isFork)}, author=${author ?? '?'}, viewer=${viewerLogin ?? '?'} (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'})`,
 		}
 	}
 	return {
 		authorship_mode: 'unknown',
-		authorship_signal: `authorAssociation=${association ?? 'null'}, fork=${Boolean(isFork)}`,
+		authorship_signal: `authorAssociation=${association ?? 'null'}, fork=${Boolean(isFork)}, author=${author ?? 'null'}`,
 	}
 }
 

package/src/cli/commands/recipe-diff.mjs

@@ -0,0 +1,81 @@
+/**
+ * commands/recipe-diff.mjs — `apt-tools recipe-diff <projectDir> [--format json|md]`.
+ *
+ * Loads bundled recipes, runs the pattern-matcher against the adopter's
+ * runtime + package.json to pick a recipe, then calls generateRecipeDiff
+ * to emit the Markdown body.
+ *
+ * Exit codes:
+ *   0 — success (envelope.status:'ok')
+ *   1 — no-recipe-match (envelope.status:'error', code:'E_NO_RECIPE')
+ *
+ * Output:
+ *   default / --format json → JSON envelope to stdout
+ *   --format md             → raw Markdown body to stdout
+ */
+
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok, rawText } from '../util/result.mjs'
+import { loadRuntimeCapabilities } from '../util/runtime-capabilities.mjs'
+import { matchPatternForProject } from '../verify-proof/sandbox/pattern-matcher.mjs'
+import { generateRecipeDiff } from '../verify-proof/sandbox/recipe-diff.mjs'
+import { discoverBundledRecipes } from '../verify-proof/sandbox/sandbox-config.mjs'
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [extra]
+ */
+export function cmdRecipeDiff(projectDir, extra = []) {
+	if (!projectDir) return err('Usage: apt-tools recipe-diff <project-dir> [--format json|md]')
+
+	const flags = parseFlags(extra)
+	const formatFlag = flags.get('format') ?? 'json'
+	if (formatFlag !== 'json' && formatFlag !== 'md') {
+		return err(`recipe-diff: --format must be 'json' or 'md', got '${formatFlag}'`)
+	}
+
+	const recipes = discoverBundledRecipes()
+	const runtime = loadRuntimeCapabilities(projectDir)
+
+	// recipeId can be passed explicitly via --recipe; otherwise we match.
+	const explicitRecipeId = flags.get('recipe') ?? null
+	let recipeId
+	let matchReason
+	if (explicitRecipeId) {
+		recipeId = explicitRecipeId
+		matchReason = 'explicit'
+	} else {
+		const match = matchPatternForProject(projectDir, runtime, recipes)
+		recipeId = match.recipeId
+		matchReason = match.reason
+	}
+
+	if (!recipeId) {
+		const envelope = {
+			status: 'error',
+			command: 'recipe-diff',
+			code: 'E_NO_RECIPE',
+			reason: matchReason,
+			runtime,
+			docs: 'docs/verify-proof-sandbox-patterns.md',
+		}
+		return exitWith(envelope, 1)
+	}
+
+	const diff = generateRecipeDiff({ projectDir, recipeId, recipes })
+
+	if (formatFlag === 'md') {
+		const exitCode = diff.envelope.status === 'ok' ? 0 : 1
+		return rawText(diff.body, exitCode)
+	}
+
+	return ok({
+		status: 'ok',
+		command: 'recipe-diff',
+		project_dir: projectDir,
+		recipe_id: recipeId,
+		match_reason: matchReason,
+		runtime,
+		...diff,
+	})
+}

package/src/cli/commands/roadmap.mjs

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 import { basename, join, resolve } from 'node:path'
 import { selfStageCommittableWrites } from '../artifacts/self-stage.mjs'
 import { getDefaultOwner, getGitIdentity } from '../git/identity.mjs'
+import { dispatchRoadmapWrite } from '../roadmap/backend-adapter.mjs'
 import { runConvexMirror } from '../roadmap/convex-mirror.mjs'
 import {
 	loadRoadmapForScope as ioLoadRoadmapForScope,
@@ -197,6 +198,34 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 		return defaultScope
 	}
 
+	// Task 26-05-26 subtask 2.4 — `.aperant/config.json :: roadmap.backend`
+	// dispatch. Called at the top of each write-side subcommand. When the
+	// configured backend is `cloud-mcp` AND the dispatch succeeds (or fails
+	// with a structured error), we surface that envelope and short-circuit
+	// the existing markdown file-write path. When the backend is `markdown`
+	// (the Fast Path Guarantee default), the dispatcher returns
+	// `delegated:false` and the subcommand proceeds with the existing
+	// markdown writes verbatim — byte-identical to pre-2.4 behaviour.
+	async function maybeDelegate(subcommand, args) {
+		const fetchImpl =
+			cmdRoadmap._injectedFetch !== undefined ? cmdRoadmap._injectedFetch : undefined
+		const decision = await dispatchRoadmapWrite(targetDir, subcommand, args, { fetchImpl })
+		if (decision.delegated === false) return null
+		if (decision.status === 'error') {
+			return err(decision.error, decision.code === 401 ? 1 : 1, {
+				command: `roadmap-${subcommand}`,
+				backend: 'cloud-mcp',
+			})
+		}
+		return ok({
+			status: 'ok',
+			command: `roadmap-${subcommand}`,
+			backend: 'cloud-mcp',
+			delegated: true,
+			result: decision.result,
+		})
+	}
+
 	// C28 D-07 — cascade-null helper. The scanning of affected tasks is
 	// inlined at each destructive roadmap path so the scan + mutate can run
 	// under a single `withFileLock(state.json)` and close the TOCTOU window.
@@ -357,6 +386,9 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			const scope = (flags.get('scope') || 'project').trim() || 'project'
 			if (!id || !title) throw new RoadmapUsageError('Required: --id <id> --title <title>')
 
+			const delegated = await maybeDelegate('add-milestone', { id, title, goal, scope })
+			if (delegated) return delegated
+
 			// Auto-init the scope if its roadmap file doesn't exist yet.
 			const { jsonPath } = scopePaths(scope)
 			if (!existsSync(jsonPath)) {
@@ -402,6 +434,15 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			if (!milestoneId || !id || !title)
 				throw new RoadmapUsageError('Required: --milestone <id> --id <id> --title <title>')
 
+			const delegated = await maybeDelegate('add-phase', {
+				milestoneId,
+				id,
+				title,
+				description: flags.get('description') || '',
+				status: flags.get('status') || 'planned',
+			})
+			if (delegated) return delegated
+
 			const scope = resolveScope({ milestoneId })
 			const roadmap = loadRoadmap(scope)
 			const milestone = roadmap.milestones.find((m) => m.id === milestoneId)
@@ -445,6 +486,13 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			if (!milestoneId || !phaseId || !status)
 				throw new RoadmapUsageError('Required: --milestone <id> --phase <id> --status <status>')
 
+			const delegated = await maybeDelegate('set-phase-status', {
+				milestoneId,
+				phaseId,
+				status,
+			})
+			if (delegated) return delegated
+
 			// C28 D-07 — `deleted` is the destructive path that triggers orphan
 			// block + cascade-null. All other statuses are non-destructive.
 			const validStatuses = ['planned', 'in-progress', 'completed', 'blocked', 'skipped', 'deleted']
@@ -602,6 +650,9 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			const phaseId = flags.get('phase')
 			if (!milestoneId || !phaseId)
 				throw new RoadmapUsageError('Required: --milestone <id> --phase <id>')
+
+			const delegated = await maybeDelegate('delete-phase', { milestoneId, phaseId })
+			if (delegated) return delegated
 			const force = extraArgs.includes('--force')
 			const reason = flags.get('reason') || null
 			if (force && !reason) {
@@ -698,6 +749,9 @@ async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 		case 'delete-milestone': {
 			const milestoneId = flags.get('id') || flags.get('milestone')
 			if (!milestoneId) throw new RoadmapUsageError('Required: --id <milestone-id>')
+
+			const delegated = await maybeDelegate('delete-milestone', { milestoneId })
+			if (delegated) return delegated
 			const force = extraArgs.includes('--force')
 			const reason = flags.get('reason') || null
 			if (force && !reason) {