@aperant/framework 0.6.2

package/src/cli/roadmap/io.mjs

@@ -0,0 +1,188 @@
+/**
+ * io.mjs — roadmap read/write/lookup helpers (C29, R5).
+ *
+ * R5 (subtask 10): dual-write transition.
+ *   - saveRoadmapForScope writes BOTH the legacy milestones.json AND per-phase
+ *     files under .aperant/roadmap/{scope}/phases/{phase-id}.json. This keeps
+ *     rollback possible until Wave 3 removes the legacy write.
+ *   - loadRoadmapForScope prefers phases/ when any phase file exists. If only
+ *     the legacy blob is present, parse it AND trigger a one-way migration
+ *     (savePhaseFile for every phase, legacy file preserved on disk).
+ *
+ * Subtask 11 tightens the read to NEVER fall back once phases/ exists, closing
+ * the window where a stale milestones.json could mask a fresh phase update.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { listRoadmapScopes, roadmapScopePaths } from './paths.mjs'
+import {
+	hasPhaseFiles,
+	loadPhasesAsRoadmap,
+	migrateRoadmapToPhasesDir,
+	savePhaseFile,
+} from './phases-io.mjs'
+import { renderRoadmapMd } from './render.mjs'
+
+/**
+ * Load the roadmap for a scope.
+ *
+ * Read preference:
+ *   1. If phases/ has at least one JSON file, reconstruct from there and
+ *      return. Never consult the legacy blob in this case (subtask 11
+ *      hardens this, subtask 10 already prefers phases/ when available).
+ *   2. Else if legacy milestones.json exists, parse it, auto-migrate each
+ *      phase into phases/ so the next reader hits the fast path, then return
+ *      the parsed legacy blob.
+ *   3. Else return null.
+ */
+export function loadRoadmapForScope(targetDir, scope) {
+	if (hasPhaseFiles(targetDir, scope)) {
+		const reconstructed = loadPhasesAsRoadmap(targetDir, scope)
+		// C12 overlay: milestone-level fields (today: seed_id) live only in
+		// the legacy milestones.json blob, not in phases/{id}.json. During
+		// Wave 2 dual-write, the legacy blob is kept in lockstep with phases/,
+		// so we overlay those fields on top of the phases/-reconstructed
+		// output. This preserves two invariants simultaneously:
+		//   1. A clean `seed assign` round-trips: seeds.json ↔ reconstructed
+		//      roadmap agree (seed_id present on both sides).
+		//   2. A hand-edit that strips seed_id from milestones.json shows up
+		//      as drift — the overlay simply finds no value to overlay, so
+		//      validate sees the milestone without seed_id and flags
+		//      `missing-seed-id`.
+		// After Wave 3 removes the legacy blob, seed_id will need to live on
+		// either phases/ records or a per-milestone sidecar; this overlay is
+		// a transition helper, not a permanent fixture.
+		if (reconstructed) overlayLegacyMilestoneFields(targetDir, scope, reconstructed)
+		return reconstructed
+	}
+	const { jsonPath } = roadmapScopePaths(targetDir, scope)
+	if (!existsSync(jsonPath)) return null
+	const legacy = JSON.parse(readFileSync(jsonPath, 'utf-8'))
+	// Fire-and-forget migration. Non-destructive: leaves milestones.json on
+	// disk. Best-effort — if the migration throws (permissions, disk full),
+	// we still return the parsed legacy blob so the caller isn't blocked.
+	try {
+		migrateRoadmapToPhasesDir(targetDir, scope)
+	} catch {
+		/* migration retries next load */
+	}
+	return legacy
+}
+
+/**
+ * Merge milestone-level fields from the legacy milestones.json blob onto a
+ * phases/-reconstructed roadmap. Today only `seed_id` participates — the
+ * phases/ layout doesn't own milestone metadata, so we copy from the legacy
+ * blob when it exists. Missing blob ⇒ no overlay, no error.
+ *
+ * Also surfaces empty-phases milestones. The phases/-reconstruction drops
+ * milestones that own zero phase files, because the reconstruction is built
+ * by grouping phase files by `milestone_id`. Freshly-added milestones (via
+ * `roadmap add-milestone`) start life with `phases: []`, so they exist in
+ * the legacy blob but never in the phases/ layout until the first phase is
+ * added. Without this augmentation, `findMilestoneScopes` (and any caller
+ * of `loadRoadmapForScope`) can't see a just-added milestone, and
+ * `add-phase --milestone <new-id>` fails with "not found in scope …".
+ * The legacy blob stays authoritative for the milestone *set*; the
+ * phases/ layout stays authoritative for phase *data*.
+ */
+function overlayLegacyMilestoneFields(targetDir, scope, reconstructed) {
+	const { jsonPath } = roadmapScopePaths(targetDir, scope)
+	if (!existsSync(jsonPath)) return
+	let legacy
+	try {
+		legacy = JSON.parse(readFileSync(jsonPath, 'utf-8'))
+	} catch {
+		return
+	}
+	if (!legacy || !Array.isArray(legacy.milestones)) return
+	const legacyById = new Map(legacy.milestones.map((m) => [m.id, m]))
+	const reconstructedIds = new Set(
+		(reconstructed.milestones || []).map((m) => m && m.id).filter(Boolean),
+	)
+	for (const ms of reconstructed.milestones || []) {
+		const legacyMs = legacyById.get(ms.id)
+		if (!legacyMs) continue
+		if (Object.hasOwn(legacyMs, 'seed_id')) {
+			ms.seed_id = legacyMs.seed_id
+		}
+		// C33 — milestone-level `status` is a derived rollup value that also
+		// lives only in the legacy blob (phases/ per-file records describe
+		// phases, not milestones). Overlay so the phases/-preferred read path
+		// returns the cached rollup, and writers see the current value for
+		// change-detection.
+		if (Object.hasOwn(legacyMs, 'status')) {
+			ms.status = legacyMs.status
+		}
+	}
+	// Append empty-phases milestones that the phases/ reconstruction missed.
+	// We only append when the legacy record itself has zero phases — a legacy
+	// milestone with phases that are absent from phases/ is data drift the
+	// operator should resolve, not a new blank milestone we should resurrect.
+	if (!reconstructed.milestones) reconstructed.milestones = []
+	for (const legacyMs of legacy.milestones) {
+		if (!legacyMs || !legacyMs.id) continue
+		if (reconstructedIds.has(legacyMs.id)) continue
+		const legacyPhases = Array.isArray(legacyMs.phases) ? legacyMs.phases : []
+		if (legacyPhases.length > 0) continue
+		reconstructed.milestones.push({
+			id: legacyMs.id,
+			title: legacyMs.title || legacyMs.id,
+			goal: legacyMs.goal || '',
+			scope: legacyMs.scope || scope,
+			phases: [],
+			...(Object.hasOwn(legacyMs, 'seed_id') ? { seed_id: legacyMs.seed_id } : {}),
+			...(Object.hasOwn(legacyMs, 'status') ? { status: legacyMs.status } : {}),
+		})
+	}
+}
+
+/**
+ * Save the roadmap for a scope (dual-write).
+ *
+ *   - Writes legacy milestones.json + ROADMAP.md atomically under a single
+ *     file lock (same behavior as before R5).
+ *   - Iterates milestones + phases and calls savePhaseFile for each, so the
+ *     per-phase layout stays in sync with the blob.
+ *
+ * The two writes are NOT atomic with each other (they hold separate locks),
+ * but both use atomic tmp+rename so neither can produce a torn file. During
+ * Wave 2 a partial failure is tolerable: the next load will prefer whichever
+ * layout completed (phases/ wins if any file landed), and saveRoadmapForScope
+ * will re-sync both on the next save.
+ */
+export function saveRoadmapForScope(targetDir, scope, roadmap) {
+	const { scopeDir, jsonPath, mdPath } = roadmapScopePaths(targetDir, scope)
+	roadmap.scope = scope
+	roadmap.updated_at = new Date().toISOString()
+	mkdirSync(scopeDir, { recursive: true })
+	withFileLock(
+		jsonPath,
+		() => {
+			writeFileSync(jsonPath, JSON.stringify(roadmap, null, 2) + '\n', 'utf-8')
+			writeFileSync(mdPath, renderRoadmapMd(roadmap), 'utf-8')
+		},
+		{ projectRoot: targetDir },
+	)
+	// Per-phase dual-write. Each savePhaseFile takes its own file lock, so
+	// concurrent callers never corrupt a phase record.
+	for (const milestone of roadmap.milestones || []) {
+		if (!milestone || !Array.isArray(milestone.phases)) continue
+		for (const phase of milestone.phases) {
+			if (!phase || !phase.id) continue
+			savePhaseFile(targetDir, scope, milestone, phase)
+		}
+	}
+}
+
+export function findMilestoneScopeGlobal(targetDir, milestoneId) {
+	const hits = []
+	for (const scope of listRoadmapScopes(targetDir)) {
+		const rm = loadRoadmapForScope(targetDir, scope)
+		if (rm && (rm.milestones || []).some((m) => m.id === milestoneId)) hits.push(scope)
+	}
+	if (hits.length === 0) return null
+	if (hits.length > 1) return null // ambiguous — drain treats as no-op
+	return hits[0]
+}

package/src/cli/roadmap/lifecycle.mjs

@@ -0,0 +1,105 @@
+/**
+ * lifecycle.mjs — shared lifecycle-phase side-effect helper (C29).
+ */
+
+import { loadRoadmapForScope, saveRoadmapForScope } from './io.mjs'
+import { applyRollup } from './rollup.mjs'
+import { syncRoadmapInProcess } from './sync.mjs'
+
+/**
+ * Shared lifecycle phase side-effect helper.
+ *
+ * Applies a phase-status transition to a task's linked roadmap phase, mirroring
+ * what the effects drain used to do — from-state guarded, idempotent, commits
+ * via `syncRoadmapInProcess`.
+ *
+ * Callers:
+ *   - `task update --lifecycle-phase` (mapping lifecycle → phase spec inline)
+ *   - `task close --verdict approved` ({from: 'in-progress', to: 'completed'})
+ *   - The drain's `applyPhaseTransition` wrapper (legacy ops / in-flight queue)
+ *
+ * Contract:
+ *   - No-op (returns null) when `task.milestone_id` / `task.phase_id` missing,
+ *     when the roadmap / milestone / phase can't be located, or when the phase
+ *     is not currently at `spec.from`.
+ *   - On success, mutates `phase.status` (and `phase.completed_at` when
+ *     transitioning to `completed`), writes via `saveRoadmapForScope`, and
+ *     runs `syncRoadmapInProcess` with reason `${reasonPrefix}:${phase_id}`.
+ *
+ * Returns: `{ transition: {op, scope, milestone_id, phase_id, from, to}, commit: string|null } | null`
+ *   - `commit` is the short sha from `syncRoadmapInProcess`, or null when
+ *     the sync was skipped (team mode off / clean / etc).
+ */
+export function applyLifecyclePhaseSideEffect(targetDir, task, spec, reasonPrefix, opts = {}) {
+	if (!task || !task.milestone_id || !task.phase_id) return null
+	const scope = task.scope || 'project'
+	// R7 — when a task carries `worktree_path`, the durable/reviewable roadmap
+	// file lives in the worktree's working tree (so the commit can snapshot it
+	// onto the worktree's feature branch). When no worktree is present, the
+	// roadmap lives in the project root.
+	//
+	// Shared/ephemeral state (state.json, team-status/, locks, events) is
+	// unaffected — it always resolves against `targetDir` via the surrounding
+	// call site. This split mirrors spec §5's three-class model:
+	//   durable/reviewable → worktree tree
+	//   ephemeral/coordination → main repo `.aperant/`
+	const roadmapDir = task.worktree_path || targetDir
+	const roadmap = loadRoadmapForScope(roadmapDir, scope)
+	if (!roadmap) return null
+	const milestone = (roadmap.milestones || []).find((m) => m.id === task.milestone_id)
+	if (!milestone) return null
+	const phase = (milestone.phases || []).find((p) => p.id === task.phase_id)
+	if (!phase) return null
+	// From-state guard: idempotent no-op when phase is not at `spec.from`.
+	if (phase.status !== spec.from) return null
+
+	const transition = {
+		op: reasonPrefix,
+		scope,
+		milestone_id: task.milestone_id,
+		phase_id: task.phase_id,
+		from: spec.from,
+		to: spec.to,
+	}
+
+	if (opts.dryRun) {
+		return { transition, commit: null }
+	}
+
+	phase.status = spec.to
+	if (spec.to === 'completed') {
+		phase.completed_at = new Date().toISOString()
+	}
+	// C33 — after the phase-status flip, recompute the milestone rollup in
+	// memory so the saved roadmap reflects both the phase change AND any
+	// derived milestone status flip (e.g. last phase → milestone completed).
+	// Idempotent: applyRollup is a no-op when nothing changed.
+	const rollup = applyRollup(roadmap, task.milestone_id)
+	saveRoadmapForScope(roadmapDir, scope, roadmap)
+
+	// R7 — git runs against the worktree so the commit lands on the feature
+	// branch (fixes the C29 leak where bookkeeping landed on the main repo's
+	// branch instead).
+	//
+	// R11 — forward the task's declared outputs allowlist so syncRoadmapInProcess
+	// can refuse to stage any dirty path outside of it. `task.outputs` is the
+	// source of truth; `opts.outputs` overrides for test/debugging callers.
+	let commit = null
+	const outputs = Array.isArray(opts.outputs)
+		? opts.outputs
+		: Array.isArray(task.outputs)
+			? task.outputs
+			: undefined
+	// C33 — when rollup also mutated, tag the commit reason so logs show both
+	// the phase change and the milestone rollup occurred in a single write.
+	const reasonSuffix = rollup?.changed
+		? `${reasonPrefix}:${task.phase_id}+rollup`
+		: `${reasonPrefix}:${task.phase_id}`
+	const sync = syncRoadmapInProcess(roadmapDir, reasonSuffix, {
+		cwd: roadmapDir,
+		outputs,
+	})
+	if (sync.committed && sync.sha) commit = sync.sha
+
+	return { transition, commit, rollup }
+}

package/src/cli/roadmap/paths.mjs

@@ -0,0 +1,57 @@
+/**
+ * paths.mjs — roadmap scope path helpers (C29).
+ *
+ * Per-scope roadmap layout:
+ *   .aperant/roadmap/{scope}/milestones.json   (structured)
+ *   .aperant/roadmap/{scope}/ROADMAP.md        (rendered)
+ *
+ * Each scope is fully independent — its own milestone/phase namespace, its
+ * own lock, its own rendered markdown. There is no top-level milestones.json
+ * or ROADMAP.md.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function roadmapScopePaths(targetDir, scope) {
+	const scopeDir = join(targetDir, '.aperant', 'roadmap', scope)
+	return {
+		scopeDir,
+		jsonPath: join(scopeDir, 'milestones.json'),
+		mdPath: join(scopeDir, 'ROADMAP.md'),
+		// R5 (subtask 10): per-phase JSON layout lives alongside the legacy
+		// milestones.json. Exposed here so io.mjs and CLI commands share the
+		// same path construction.
+		phasesDir: join(scopeDir, 'phases'),
+	}
+}
+
+export function phasesPath(targetDir, scope) {
+	return join(targetDir, '.aperant', 'roadmap', scope, 'phases')
+}
+
+export function listRoadmapScopes(targetDir) {
+	const roadmapRoot = join(targetDir, '.aperant', 'roadmap')
+	if (!existsSync(roadmapRoot)) return []
+	const out = []
+	for (const name of readdirSync(roadmapRoot)) {
+		const sub = join(roadmapRoot, name)
+		try {
+			if (!statSync(sub).isDirectory()) continue
+		} catch {
+			continue
+		}
+		// R5: a scope is considered initialized if it has a legacy milestones.json
+		// OR a populated phases/ directory (the new canonical layout).
+		if (existsSync(join(sub, 'milestones.json')) || existsSync(join(sub, 'phases'))) {
+			out.push(name)
+		}
+	}
+	out.sort((a, b) => {
+		if (a === b) return 0
+		if (a === 'project') return -1
+		if (b === 'project') return 1
+		return a.localeCompare(b)
+	})
+	return out
+}

package/src/cli/roadmap/phases-io.mjs

@@ -0,0 +1,227 @@
+/**
+ * phases-io.mjs — per-phase roadmap JSON layout (R5).
+ *
+ * Legacy roadmap state lives in `.aperant/roadmap/{scope}/milestones.json` as
+ * a single blob containing every milestone + every phase. Concurrent edits by
+ * sibling worktrees conflict on a single file — git's 3-way merge can't
+ * separate independent phase updates when they live in the same JSON array.
+ *
+ * R5 splits the state across one file per phase:
+ *
+ *   .aperant/roadmap/{scope}/phases/{phase-id}.json
+ *
+ * Each phase file carries its milestone_id + milestone_title so the reader can
+ * reconstruct the full `{milestones: [...]}` shape without cross-referencing.
+ * Two worktrees editing different phases now touch different files — git's
+ * default 3-way merge resolves cleanly. Same-phase edits still conflict, but
+ * that's a real conflict worth surfacing.
+ *
+ * Wave 2 (subtask 10): dual-write — `saveRoadmapForScope` writes BOTH the legacy
+ * blob AND the per-phase files; `loadRoadmapForScope` prefers phases/ when any
+ * file exists, else falls back to legacy (and triggers a one-way migration).
+ * Wave 3 (subtask 11): reads become phases/-only once phases/ is populated.
+ *
+ * The First Principles Thinker's R5 dissent is preserved on purpose: splitting
+ * state across N files loses the single-file invariant that "the whole roadmap
+ * either parses or doesn't." A future schema validator closes that gap.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { atomicWriteJson } from '../util/atomic-write.mjs'
+import { withFileLock } from '../util/fs-lock.mjs'
+
+/**
+ * Absolute path to the `phases/` directory for a scope.
+ *
+ *   phasesDir(root, 'framework') → `${root}/.aperant/roadmap/framework/phases`
+ */
+export function phasesDir(targetDir, scope) {
+	return join(targetDir, '.aperant', 'roadmap', scope, 'phases')
+}
+
+/**
+ * Absolute path to an individual phase file.
+ */
+export function phaseFilePath(targetDir, scope, phaseId) {
+	return join(phasesDir(targetDir, scope), `${phaseId}.json`)
+}
+
+/**
+ * Atomic-write a single phase file. Stamps milestone_id/milestone_title on
+ * the phase so readers can reconstruct the milestone list without needing the
+ * legacy blob.
+ *
+ * Under withFileLock so concurrent saveRoadmapForScope calls from two agents
+ * can't interleave writes to the same phase file. projectRoot scopes the lock
+ * directory so tests (and sibling worktrees) share a lock namespace with the
+ * roadmap they're mutating.
+ */
+export function savePhaseFile(targetDir, scope, milestone, phase) {
+	const dir = phasesDir(targetDir, scope)
+	mkdirSync(dir, { recursive: true })
+	const filePath = phaseFilePath(targetDir, scope, phase.id)
+	// Flatten milestone identity onto the phase record. Keep every original
+	// phase key (owner, status, description, blocked_by, deliverables,
+	// completed_at, scope, etc.) so the reader round-trips losslessly.
+	//
+	// C12: intentionally DO NOT stamp milestone.seed_id onto the phase record.
+	// seed_id is a milestone-level field owned by milestones.json (the legacy
+	// blob). Copying it here would make hand-edits to milestones.json
+	// invisible to the phases/-preferred reader — a drift check like "the
+	// user deleted seed_id from milestones.json" would then fire 0 findings.
+	// loadRoadmapForScope overlays seed_id from the legacy blob on top of the
+	// phases/-reconstructed milestones (io.mjs), so a clean assign still
+	// round-trips while a hand-edit still surfaces as drift.
+	const record = {
+		scope,
+		milestone_id: milestone.id,
+		milestone_title: milestone.title,
+		milestone_goal: milestone.goal || '',
+		...phase,
+	}
+	withFileLock(
+		filePath,
+		() => {
+			atomicWriteJson(filePath, record)
+		},
+		{ projectRoot: targetDir },
+	)
+}
+
+/**
+ * Unlink a single phase file by id (C34c). Silent + idempotent: missing files,
+ * permission quirks, and races where a sibling worktree already removed the
+ * file must never crash the caller. The on-disk phases/ layout is the primary
+ * source of truth for `loadPhasesAsRoadmap`, so stale files after a
+ * delete-phase / status=deleted / delete-milestone flow would let the roadmap
+ * resurrect deleted content on the next read. This helper closes that gap.
+ *
+ * Returns `true` when the file existed and was removed, `false` otherwise.
+ */
+export function deletePhaseFile(targetDir, scope, phaseId) {
+	if (!phaseId) return false
+	const filePath = phaseFilePath(targetDir, scope, phaseId)
+	if (!existsSync(filePath)) return false
+	try {
+		rmSync(filePath, { force: true })
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * True when `phases/` exists and contains at least one `.json` phase record.
+ * Used as the read-preference gate: once phases/ is populated, reads switch
+ * to the per-phase layout.
+ */
+export function hasPhaseFiles(targetDir, scope) {
+	const dir = phasesDir(targetDir, scope)
+	if (!existsSync(dir)) return false
+	try {
+		for (const name of readdirSync(dir)) {
+			if (name.endsWith('.json')) return true
+		}
+	} catch {
+		/* dir removed between exists + readdir */
+	}
+	return false
+}
+
+/**
+ * Reconstruct the legacy `{milestones: [...]}` shape from the per-phase files.
+ *
+ * Phases are grouped by `milestone_id`. Milestone order follows first-seen
+ * order in the sorted phase-file listing — we sort phase filenames so the
+ * output is deterministic for a given directory state. Milestone title/goal
+ * come from whichever phase was seen first for that milestone; callers that
+ * want authoritative milestone metadata should still rely on saveRoadmapForScope
+ * keeping the legacy blob in sync during Wave 2.
+ *
+ * Returns `null` when no phases/ directory exists, or an empty
+ * `{milestones:[]}` shape when the directory exists but has no phase files.
+ */
+export function loadPhasesAsRoadmap(targetDir, scope) {
+	const dir = phasesDir(targetDir, scope)
+	if (!existsSync(dir)) return null
+
+	const files = readdirSync(dir)
+		.filter((f) => f.endsWith('.json'))
+		.sort()
+
+	const milestoneMap = new Map()
+	const milestoneOrder = []
+
+	for (const f of files) {
+		let rec
+		try {
+			rec = JSON.parse(readFileSync(join(dir, f), 'utf-8'))
+		} catch {
+			// Skip malformed files rather than poisoning the whole load. A future
+			// validator can surface corruption explicitly.
+			continue
+		}
+		const msId = rec.milestone_id
+		if (!msId) continue
+		if (!milestoneMap.has(msId)) {
+			const milestoneRec = {
+				id: msId,
+				title: rec.milestone_title || msId,
+				goal: rec.milestone_goal || '',
+				scope,
+				phases: [],
+			}
+			milestoneMap.set(msId, milestoneRec)
+			milestoneOrder.push(msId)
+		}
+		// Strip the milestone-identity fields before handing the phase back to
+		// callers — they belong to the parent milestone now, not the phase.
+		const {
+			scope: _s,
+			milestone_id: _mid,
+			milestone_title: _mt,
+			milestone_goal: _mg,
+			...phase
+		} = rec
+		milestoneMap.get(msId).phases.push(phase)
+	}
+
+	return {
+		version: 1,
+		scope,
+		milestones: milestoneOrder.map((id) => milestoneMap.get(id)),
+	}
+}
+
+/**
+ * One-way migration: read legacy `milestones.json`, write each phase to
+ * `phases/{phase-id}.json`. Never deletes the legacy file — Wave 2 keeps it
+ * alive as a rollback lane. Idempotent: if `phases/` already has files for the
+ * phases we'd write, re-running is a no-op (savePhaseFile overwrites with the
+ * same bytes modulo timestamps, which is acceptable during the transition).
+ *
+ * Returns the number of phase files written, or 0 when the legacy file is
+ * absent / empty / malformed.
+ */
+export function migrateRoadmapToPhasesDir(targetDir, scope) {
+	const legacyPath = join(targetDir, '.aperant', 'roadmap', scope, 'milestones.json')
+	if (!existsSync(legacyPath)) return 0
+	let legacy
+	try {
+		legacy = JSON.parse(readFileSync(legacyPath, 'utf-8'))
+	} catch {
+		return 0
+	}
+	if (!legacy || !Array.isArray(legacy.milestones)) return 0
+	let written = 0
+	for (const milestone of legacy.milestones) {
+		if (!milestone || !Array.isArray(milestone.phases)) continue
+		for (const phase of milestone.phases) {
+			if (!phase || !phase.id) continue
+			savePhaseFile(targetDir, scope, milestone, phase)
+			written++
+		}
+	}
+	return written
+}

package/src/cli/roadmap/render.mjs

@@ -0,0 +1,75 @@
+/**
+ * render.mjs — roadmap JSON → ROADMAP.md renderer (C29).
+ */
+
+/**
+ * Render a per-scope roadmap.json to ROADMAP.md (human-readable).
+ *
+ * Each scope lives in its own directory (`.aperant/roadmap/{scope}/`), so
+ * every rendered file contains a single scope's milestones. The scope name
+ * is shown in the title so consumers reading a standalone file know which
+ * roadmap they're looking at.
+ */
+export function renderRoadmapMd(roadmap) {
+	const project = roadmap.project || 'Project'
+	const scope = roadmap.scope || 'project'
+	const lines = [`# ${project} — ${scope} Roadmap`, '']
+	lines.push(`*Scope: \`${scope}\` · Last updated: ${roadmap.updated_at}*`, '')
+
+	const statusIcon = {
+		planned: '\u25cb',
+		'in-progress': '\u25b6',
+		completed: '\u2713',
+		blocked: '\u2716',
+		skipped: '\u2014',
+	}
+
+	const allMilestones = roadmap.milestones || []
+
+	const renderMilestone = (milestone) => {
+		lines.push(`## ${milestone.title}`, '')
+		if (milestone.goal) lines.push(`**Goal:** ${milestone.goal}`, '')
+
+		lines.push('| Status | Phase | Owner | Description |')
+		lines.push('|--------|-------|-------|-------------|')
+
+		for (const phase of milestone.phases || []) {
+			const icon = statusIcon[phase.status] || '?'
+			const owner = phase.owner || 'TBD'
+			const desc = (phase.description || '').replace(/\|/g, '\\|').slice(0, 80)
+			lines.push(`| ${icon} ${phase.status} | **${phase.title}** | ${owner} | ${desc} |`)
+		}
+		lines.push('')
+
+		// Detailed section with deliverables + blocked_by
+		for (const phase of milestone.phases || []) {
+			if (
+				(phase.deliverables && phase.deliverables.length) ||
+				(phase.blocked_by && phase.blocked_by.length)
+			) {
+				lines.push(`### ${phase.title}`, '')
+				if (phase.blocked_by && phase.blocked_by.length) {
+					lines.push(`*Blocked by: ${phase.blocked_by.join(', ')}*`, '')
+				}
+				if (phase.deliverables && phase.deliverables.length) {
+					lines.push('**Deliverables:**')
+					for (const d of phase.deliverables) lines.push(`- ${d}`)
+					lines.push('')
+				}
+				if (phase.completed_at) {
+					lines.push(`*Completed: ${phase.completed_at}*`, '')
+				}
+			}
+		}
+	}
+
+	for (const m of allMilestones) renderMilestone(m)
+
+	lines.push(
+		'---',
+		'',
+		`*Auto-generated from \`.aperant/roadmap/${scope}/milestones.json\` by apt-tools*`,
+		'',
+	)
+	return lines.join('\n')
+}