@aperant/framework 0.6.6 → 0.6.7

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

@@ -16,7 +16,26 @@
  *       stale_files: [{ path, reason }],
  *       update_available: false
  *     }],
- *     legacy_install: false   // true when only the old .apt-version exists
+ *     legacy_install: false,  // true when only the old .apt-version exists
+ *     // === 0.6.7 cache-merge fields (Bug 1 fix) ===
+ *     // Merged from the SessionStart worker's cache at
+ *     // ~/.cache/aperant/apt-update-check.json when fresh (< 1 h,
+ *     // schema_version=1). When stale, missing, or malformed, the same
+ *     // field names are present with null/false/0 sentinel values so
+ *     // the skill's parser stays single-shape.
+ *     //
+ *     // Note: framework.installed_version is intentionally absent.
+ *     // The live kernel version is always in the top-level
+ *     // `framework_version` field (read from package.json, never from
+ *     // the cache).
+ *     framework: {
+ *       latest_version: '0.6.7' | null
+ *     },
+ *     update_available: false,
+ *     dev_install_ahead: false,
+ *     not_published: false,
+ *     stale_files_total: 0,
+ *     lookup_error: null
  *   }
  *
  * Per-file `reason` values:
@@ -31,6 +50,7 @@ import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 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'
 
@@ -56,6 +76,10 @@ function inspectRuntime(targetDir, descriptor) {
 			runtime: descriptor.id,
 			installed_version: null,
 			stale_files: [],
+			// 0.6.7 — per-runtime `update_available` is retained as `false` for
+			// backward shape compatibility with pre-0.6.7 callers. The real
+			// npm-bump signal now lives on the TOP-LEVEL `update_available`
+			// field (merged from the SessionStart worker's cache below).
 			update_available: false,
 		}
 	}
@@ -67,10 +91,14 @@ function inspectRuntime(targetDir, descriptor) {
 		runtime: descriptor.id,
 		installed_version: manifest.framework_version,
 		stale_files: stale,
+		// See note above — top-level `update_available` carries the real signal.
 		update_available: false,
 	}
 }
 
+/** Cache freshness window — 1 hour, matches the worker's CACHE_TTL_MS. */
+const CACHE_TTL_MS = 60 * 60 * 1_000
+
 /**
  * @param {string} projectDir
  */
@@ -106,6 +134,39 @@ export function cmdCheckVersion(projectDir) {
 		messageParts.push(`Skills are up to date for ${runtimes.length} runtime(s).`)
 	}
 
+	// 0.6.7 (Bug 1 fix) — merge the SessionStart worker's cache fields when
+	// the cache file is fresh (< 1 h, schema_version=1). On a stale / missing
+	// / malformed cache the same field names are emitted with null/false/0
+	// sentinel values so the skill's parser stays single-shape (ID-03).
+	//
+	// LOG-001: stale_files_total is always derived from the live per-runtime
+	// walk (totalStale). The cache value is intentionally NOT merged — it is
+	// up to 1 h old and would hide drift that occurred since the last worker
+	// run.
+	//
+	// LOG-002: installed_version always comes from the kernel's own
+	// package.json (frameworkVersion). The cache's installed_version is
+	// stale by definition and is NOT merged into the envelope. Consumers
+	// that need the live kernel version use the top-level `framework_version`
+	// field, which is identical.
+	const cacheResult = readFreshUpdateCache(CACHE_TTL_MS)
+	let latestVersion = null
+	let updateAvailable = false
+	let devInstallAhead = false
+	let notPublished = false
+	let lookupError = null
+	if (cacheResult.fresh) {
+		const c = cacheResult.cache
+		const fw = c.framework && typeof c.framework === 'object' ? c.framework : {}
+		// latest_version is semver-validated inside readFreshUpdateCache (SEC-001).
+		if (typeof fw.latest_version === 'string') latestVersion = fw.latest_version
+		if (typeof c.update_available === 'boolean') updateAvailable = c.update_available
+		if (typeof c.dev_install_ahead === 'boolean') devInstallAhead = c.dev_install_ahead
+		if (typeof c.not_published === 'boolean') notPublished = c.not_published
+		// stale_files_total intentionally NOT taken from cache (LOG-001).
+		if (typeof c.lookup_error === 'string') lookupError = c.lookup_error
+	}
+
 	return ok({
 		status,
 		command: 'check-version',
@@ -113,5 +174,16 @@ export function cmdCheckVersion(projectDir) {
 		runtimes,
 		legacy_install: legacyInstall,
 		message: messageParts.join(' '),
+		// Cache-merge fields (additive, nullable). Documented in the
+		// file-header schema comment.
+		framework: {
+			latest_version: latestVersion,
+		},
+		update_available: updateAvailable,
+		dev_install_ahead: devInstallAhead,
+		not_published: notPublished,
+		// stale_files_total: always the live sum from per-runtime walks (LOG-001).
+		stale_files_total: totalStale,
+		lookup_error: lookupError,
 	})
 }

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

@@ -16,6 +16,12 @@
  * reads the gh payload from that file instead of shelling out. The stub
  * shape is `{ checks: [...], prMetadata: {...} }` — matches the classifier
  * input contract in stop-matrix.mjs.
+ *
+ * Production seam: when `--payload-file <path>` is passed, the tick path
+ * reads the gh payload from that file. Same shape as the stub. The
+ * orchestrator skill (apt-watch-ci §3) captures `gh pr checks ...` +
+ * `gh pr view ...` into the payload file BEFORE invoking the cmd — the cmd
+ * itself never shells out to gh.
  */
 
 import { randomBytes } from 'node:crypto'
@@ -290,7 +296,8 @@ function doTick(root, flags) {
 			})
 		}
 
-		const payload = fetchGhPayload(pr)
+		const payloadFile = flags.get('payload-file')
+		const payload = payloadFile ? loadPayloadFile(resolve(root, payloadFile)) : fetchGhPayload(pr)
 		if (payload.error) {
 			// gh CLI not available / auth failed → infra-backoff. Don't count it,
 			// double the next-tick interval (capped at MAX_TICK_INTERVAL_MS), and reschedule.
@@ -480,10 +487,34 @@ function fetchGhPayload(_pr) {
 	// Real gh shell-out lives in the skill body. The cmd's tick treats
 	// "no stub + no payload" as infra-backoff so unit tests can exercise the
 	// path without a live gh binary. The orchestrator skill is responsible
-	// for pre-fetching and re-invoking with APT_TEST_GH_STUB set, OR for
-	// passing real data via a future --payload-file flag (out of scope here).
+	// for pre-fetching and re-invoking with APT_TEST_GH_STUB set (tests) OR
+	// `--payload-file <path>` (production — see loadPayloadFile below).
 	return {
-		error: 'gh shell-out is the skill orchestrator boundary — set APT_TEST_GH_STUB for unit tests',
+		error:
+			'gh shell-out is the skill orchestrator boundary — set APT_TEST_GH_STUB for unit tests or pass --payload-file for production',
+	}
+}
+
+/**
+ * Read a gh payload from disk for the production path (FRAMEWORK-BUG-010).
+ * Returns the same shape as fetchGhPayload's stub branch on success, or an
+ * { error } envelope on missing path / parse failure — the existing
+ * infra-backoff branch surfaces the error cleanly.
+ *
+ * @param {string} path absolute or already-resolved path
+ */
+function loadPayloadFile(path) {
+	try {
+		if (!existsSync(path)) {
+			return { error: `payload-file path not found: ${path}` }
+		}
+		const data = JSON.parse(readFileSync(path, 'utf-8'))
+		return {
+			checks: data.checks || [],
+			prMetadata: data.prMetadata || { state: 'OPEN' },
+		}
+	} catch (e) {
+		return { error: `payload-file parse error: ${e.message}` }
 	}
 }
 

package/src/cli/commands/init.mjs

@@ -82,8 +82,14 @@ const TRANSFORM_LOADERS = new Map(
  * a missing runtimes flag should block (no flag, no `--yes`) or not
  * (flag passed, or `--yes`).
  *
+ * 0.6.7 — `--force-runtimes` (Bug 2 fix) bypasses the `upgrade_noop`
+ * short-circuit so `/apt:update` can re-stamp runtime manifests even
+ * when `.aperant/config.json` is at the current schema. Strictly
+ * additive: callers without the flag still get the no-op short-circuit
+ * (preserves `init-upgrade-drift.test.ts` case (a)).
+ *
  * @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 }}
+ * @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 }}
  */
 export function parseInstallFlags(args) {
 	const flagSet = new Set(args.filter((a) => a.startsWith('--')))
@@ -96,12 +102,16 @@ export function parseInstallFlags(args) {
 	// C47 D-04 — opt out of the PROJECT.md auto-chain. Forwarded as
 	// `answers.skipBootstrap` into both interview paths.
 	const skipBootstrap = flagSet.has('--skip-bootstrap')
+	// 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')
 
 	const classFlags = parseClassFlags(args)
 
 	const base = {
 		target,
 		skipBootstrap,
+		forceRuntimes,
 		visibility: classFlags.visibility,
 		autonomy: classFlags.autonomy,
 		accept_new_defaults: classFlags.accept_new_defaults,
@@ -326,6 +336,33 @@ function applyCollapsedClassAToMigration(
 	}
 }
 
+/**
+ * Resolve the effective runtimes list from flags, with fallback to
+ * `suggestRuntimes` and a final fallback to `['claude']`.
+ *
+ * Shared by the `nonInteractiveAnswers` upgrade path and the
+ * `--force-runtimes` synthesis block in `cmdInit` to avoid duplication.
+ *
+ * Emits a one-line stderr warning when the final fallback fires (no
+ * explicit flags and `suggestRuntimes` returned empty) so the choice is
+ * visible without breaking automated callers.
+ *
+ * @param {string} targetDir
+ * @param {ReturnType<typeof parseInstallFlags>} parsedFlags
+ * @returns {string[]}
+ */
+function selectRuntimes(targetDir, parsedFlags) {
+	if (parsedFlags.runtimes_explicit) return parsedFlags.runtimes
+	const suggested = new Set(suggestRuntimes(targetDir))
+	if (suggested.size === 0) {
+		process.stderr.write(
+			'[apt-tools] No runtime specified and config has no suggestRuntimes; defaulting to claude.\n',
+		)
+		suggested.add('claude')
+	}
+	return [...suggested]
+}
+
 /**
  * Non-TTY / scripted path — derive answers from flags + sensible defaults,
  * gated by the Class A/B classifier (spec R2 + R3).
@@ -427,9 +464,7 @@ function nonInteractiveAnswers(targetDir, canonicalRoot, archetype, parsedFlags)
 		const visibility = migration.migrated?.share?.visibility === 'team' ? 'team' : 'solo'
 		const autonomyDefault = migration.migrated?.autonomy?.default ?? 1
 		const xverify = migration.migrated?.multi_model?.cross_verification?.tools ?? []
-		const suggested = new Set(suggestRuntimes(targetDir))
-		if (suggested.size === 0) suggested.add('claude')
-		const runtimes = parsedFlags.runtimes_explicit ? parsedFlags.runtimes : [...suggested]
+		const runtimes = selectRuntimes(targetDir, parsedFlags)
 		return {
 			runtimes,
 			autonomyDefault,
@@ -599,6 +634,12 @@ async function interactiveInterview(targetDir, version, canonicalRoot, archetype
 			migration.applied_defaults.length === 0 &&
 			migration.auto_added.length === 0
 		if (noDrift) {
+			// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses the TTY
+			// "Nothing to do." outro so the runtime walker re-stamps every
+			// manifest; cmdInit's force-runtimes synthesis path takes over.
+			if (parsedFlags.forceRuntimes) {
+				return { upgrade_noop: true, skipBootstrap, migration }
+			}
 			process.stdout.write(`\n${aperantBanner(version)}\n\n`)
 			clack.intro('install')
 			clack.note(`Already up to date — v${version}`, 'No drift')
@@ -907,6 +948,22 @@ function applyInterviewAnswers(config, answers) {
 	}
 	config.project_type =
 		answers.archetype.type === 'brownfield' ? 'unknown' : config.project_type || 'unknown'
+
+	// Onboarding marker (task 15-05-26_apt-setup-onboarding-marker-7q9c).
+	// `/apt:setup` dispatches on this marker to decide review-mode vs full
+	// Batch 1-8 flow — file existence alone cannot disambiguate "fresh seed
+	// from template" from "fully tuned by setup" because templates/config.json
+	// ships with every key populated. Only the fresh-seed branch reaches this
+	// function (finishInit:1331); the upgrade branch (finishInit:1338-1357)
+	// writes answers.migration.migrated directly and never calls
+	// applyInterviewAnswers, so legacy unmarked configs correctly stay
+	// unmarked on upgrade. --yes / --accept-new-defaults walk this same fresh
+	// path but do NOT walk Batch 1-8 questions, so completed stays false.
+	config.onboarding = {
+		completed: false,
+		seeded_from_template: true,
+		seeded_at: new Date().toISOString(),
+	}
 }
 
 /**
@@ -1061,7 +1118,13 @@ export async function cmdInit(projectDir, extraArgs = []) {
 		// idempotent — preserves PROJECT.md, refreshes sidecar from it).
 		// In TTY mode clack already rendered "Nothing to do." to stdout,
 		// so suppress the JSON envelope (matches the cancelled path).
-		if (answers?.upgrade_noop) {
+		//
+		// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses this short-circuit
+		// so `/apt:update` can re-stamp every runtime manifest even when
+		// `.aperant/config.json` is at the current schema. We synthesize a
+		// real InstallAnswers shape from the existing config so
+		// installRuntimes + finishInit run their normal upgrade path.
+		if (answers?.upgrade_noop && !parsedFlags.forceRuntimes) {
 			if (interactiveTty) return rawText('', 0)
 			const bootstrap = answers.skipBootstrap
 				? { status: 'skipped', reason: '--skip-bootstrap flag' }
@@ -1077,7 +1140,36 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			})
 		}
 
-		const results = await installRuntimes(answers.runtimes, canonicalRoot, installTarget, version)
+		// 0.6.7 (Bug 2 fix) — when forceRuntimes is set on a no-drift run,
+		// synthesize a real InstallAnswers shape from the existing config so
+		// the runtime walker re-stamps every manifest. Visibility/autonomy/
+		// cross-verification are read from answers.migration.migrated (already
+		// in memory from nonInteractiveAnswers — avoids a second config read);
+		// runtimes resolved via selectRuntimes helper shared with the upgrade path.
+		let effectiveAnswers = answers
+		if (answers?.upgrade_noop && parsedFlags.forceRuntimes) {
+			const existing = answers.migration?.migrated || {}
+			const runtimes = selectRuntimes(installTarget, parsedFlags)
+			effectiveAnswers = {
+				runtimes,
+				autonomyDefault: existing?.autonomy?.default ?? 1,
+				visibility: existing?.share?.visibility === 'team' ? 'team' : 'solo',
+				crossVerificationTools: existing?.multi_model?.cross_verification?.tools ?? [],
+				scanNow: false,
+				skipBootstrap: answers.skipBootstrap,
+				archetype: detectArchetype(installTarget),
+				agent_runtime: detectAgentRuntime(),
+				applied_defaults: [],
+				explicit_inputs: collectExplicitInputs(parsedFlags),
+			}
+		}
+
+		const results = await installRuntimes(
+			effectiveAnswers.runtimes,
+			canonicalRoot,
+			installTarget,
+			version,
+		)
 
 		// Provision the project-local kernel BEFORE finishInit runs its JSON
 		// output — that way the "structure" summary can reflect the kernel
@@ -1089,14 +1181,14 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			installTarget,
 			canonicalRoot,
 			version,
-			answers.runtimes,
+			effectiveAnswers.runtimes,
 			results,
-			answers,
+			effectiveAnswers,
 			interactiveTty,
 			kernelResult,
 		)
 		if (interactiveTty) {
-			await renderOutro(answers, results, version, kernelResult)
+			await renderOutro(effectiveAnswers, results, version, kernelResult)
 			// TTY mode: envelope was persisted to disk + suppressed from stdout
 			// because the clack outro already rendered the user-facing summary.
 			// Return the rawText shape with empty payload so wrap() routes us

package/src/cli/commands/release-notes.mjs

@@ -0,0 +1,187 @@
+/**
+ * commands/release-notes.mjs — `apt-tools release-notes <sub>` (subtask 2-3
+ * of persona-aware-changelog-and-release-note_16-05-26).
+ *
+ * Deterministic I/O surface for the apt:release-notes skill. NEVER calls
+ * an LLM. The SKILL.md body invokes the host LLM to author the note text
+ * and hands the structured payload to this CLI for persistence + compile.
+ *
+ * Sub-verb menu:
+ *
+ *   apt-tools release-notes draft <project-dir> --pr <n> --note "<text>"
+ *       [--persona <id>] [--output-dir <path>] [--commits <sha,sha,...>]
+ *       [--date <YYYY-MM-DD>]
+ *     → write `<output_dir>/_unreleased/PR-<n>.md`. Idempotent.
+ *
+ *   apt-tools release-notes compile <project-dir> --tag <tag>
+ *       [--output-dir <path>]
+ *     → read every `_unreleased/PR-*.md`, filter by persona_filter, write
+ *       `<output_dir>/<tag>.md`, clear `_unreleased/` only on success.
+ *
+ *   apt-tools release-notes publish <project-dir> --tag <tag>
+ *       [--output-dir <path>] [--dry-run]
+ *     → read `<output_dir>/<tag>.md` + shell `gh release create/edit`.
+ *
+ * Return shape: always `{ status, command, ... }`. The wrap() helper in
+ * dispatch.mjs translates `{ status: 'error' }` envelopes into exit-1.
+ */
+
+import { resolve } from 'node:path'
+
+import { compileTag } from '../release-notes/compile.mjs'
+import { writeDraft } from '../release-notes/draft.mjs'
+import { publishTag } from '../release-notes/publish.mjs'
+import { getFlagValue } from '../util/common-flags.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Dispatch shape (mirrors `audit`): `release-notes: (args) =>
+ * wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3))` — args[1] is the
+ * sub-verb, args[2] is the project dir.
+ *
+ * @param {string | undefined} subcommand
+ * @param {string | undefined} projectDirArg
+ * @param {string[] | undefined} extraArgs
+ */
+export async function cmdReleaseNotes(subcommand, projectDirArg, extraArgs) {
+	const args = extraArgs ?? []
+	if (!subcommand) {
+		return err(
+			'Usage: apt-tools release-notes <draft|compile|publish> <project-dir> [flags]\n' +
+				'  draft     write docs/releases/_unreleased/PR-<n>.md\n' +
+				'  compile   read fragments → docs/releases/<tag>.md, clear _unreleased/\n' +
+				'  publish   shell gh release create/edit',
+		)
+	}
+	const projectDir = resolve(projectDirArg && projectDirArg.length > 0 ? projectDirArg : '.')
+
+	switch (subcommand) {
+		case 'draft':
+			return runDraft(projectDir, args)
+		case 'compile':
+			return runCompile(projectDir, args)
+		case 'publish':
+			return runPublish(projectDir, args)
+		default:
+			return err(
+				`apt-tools release-notes: unknown subcommand "${subcommand}". Known: draft, compile, publish.`,
+			)
+	}
+}
+
+/**
+ * draft — write a single PR fragment.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runDraft(projectDir, args) {
+	const prRaw = getFlagValue(args, '--pr')
+	const note = getFlagValue(args, '--note')
+	const persona = getFlagValue(args, '--persona')
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const commitsFlag = getFlagValue(args, '--commits')
+	const dateFlag = getFlagValue(args, '--date')
+
+	if (!prRaw) {
+		return err('release-notes draft: --pr <number> is required')
+	}
+	const pr = Number.parseInt(prRaw, 10)
+	if (!Number.isFinite(pr) || pr <= 0) {
+		return err(`release-notes draft: --pr must be a positive integer (got "${prRaw}")`)
+	}
+	if (!note || note.trim().length === 0) {
+		return err('release-notes draft: --note "<text>" is required (and must be non-empty)')
+	}
+
+	const commits = commitsFlag
+		? commitsFlag
+				.split(',')
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0)
+		: null
+
+	const result = writeDraft({
+		projectDir,
+		pr,
+		note,
+		persona,
+		outputDir: outputDirFlag,
+		commits,
+		date: dateFlag,
+	})
+
+	return ok({
+		status: 'ok',
+		command: 'release-notes-draft',
+		projectDir,
+		pr,
+		written: result.written,
+		reason: result.reason,
+		path: result.path,
+	})
+}
+
+/**
+ * compile — produce the per-tag narrative file from accumulated fragments.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runCompile(projectDir, args) {
+	const tag = getFlagValue(args, '--tag')
+	if (!tag) {
+		return err('release-notes compile: --tag <tag> is required')
+	}
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const result = compileTag({ projectDir, tag, outputDir: outputDirFlag })
+	return ok({
+		status: 'ok',
+		command: 'release-notes-compile',
+		projectDir,
+		tag,
+		written: result.written,
+		path: result.path,
+		fragments_total: result.fragmentsTotal,
+		fragments_in_body: result.fragmentsInBody,
+		fragments_in_triage: result.fragmentsInTriage,
+		fragments_filtered: result.fragmentsFiltered,
+		cleared_unreleased: result.clearedUnreleased,
+	})
+}
+
+/**
+ * publish — shell `gh release create/edit`. Returns a graceful
+ * `{status: 'skipped', reason: 'gh-not-found'}` when gh is unavailable.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runPublish(projectDir, args) {
+	const tag = getFlagValue(args, '--tag')
+	if (!tag) {
+		return err('release-notes publish: --tag <tag> is required')
+	}
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const dryRun = args.includes('--dry-run')
+	const result = publishTag({ projectDir, tag, outputDir: outputDirFlag, dryRun })
+	if (result.status === 'skipped') {
+		return ok({
+			status: 'skipped',
+			command: 'release-notes-publish',
+			projectDir,
+			tag,
+			reason: result.reason,
+			notes_path: result.notesPath ?? null,
+		})
+	}
+	return ok({
+		status: 'ok',
+		command: 'release-notes-publish',
+		projectDir,
+		tag,
+		mode: result.mode,
+		dry_run: dryRun,
+		notes_path: result.notesPath,
+	})
+}

package/src/cli/config/load.mjs

@@ -20,6 +20,43 @@ export function loadProjectConfig(targetDir) {
 	}
 }
 
+/**
+ * Load `.aperant/config.json` deep-merged with `.aperant/config.local.json`.
+ * Local wins on key collision. Nested objects merge key-by-key; arrays and
+ * primitives replace wholesale.
+ *
+ * Returns null if config.json is missing/malformed (same as loadProjectConfig).
+ * Throws Error("config.local.json parse error: <msg>") if config.local.json
+ * exists but is malformed — this is a user-visible failure surface; silent
+ * fallback would mask the user's broken override. See FRAMEWORK-AUDIT-001.
+ *
+ * @param {string} targetDir
+ * @returns {object | null}
+ */
+export function loadMergedProjectConfig(targetDir) {
+	const shared = loadProjectConfig(targetDir)
+	if (shared === null) return null
+	const localPath = join(targetDir, '.aperant', 'config.local.json')
+	if (!existsSync(localPath)) return shared
+	let local
+	try {
+		local = JSON.parse(readFileSync(localPath, 'utf-8'))
+	} catch (e) {
+		throw new Error(`config.local.json parse error: ${e.message}`)
+	}
+	return deepMerge(shared, local)
+}
+
+function deepMerge(a, b) {
+	if (a === null || typeof a !== 'object' || Array.isArray(a)) return b
+	if (b === null || typeof b !== 'object' || Array.isArray(b)) return b
+	const out = { ...a }
+	for (const k of Object.keys(b)) {
+		out[k] = k in a ? deepMerge(a[k], b[k]) : b[k]
+	}
+	return out
+}
+
 /**
  * Return a normalized task_isolation config object with safe fallbacks.
  * Always returns a concrete object even when the project has no config at all,

package/src/cli/config/upgrade-gitignore.mjs

@@ -183,6 +183,12 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 	lines.push('events/')
 	lines.push('locks/')
 	lines.push('team-status/')
+	// config.local.json — per-user override file (FRAMEWORK-AUDIT-001). The
+	// deny-by-default `*` rule above already ignores it because no allow line
+	// exists for it; this explicit deny is defense in depth so a future
+	// maintainer cannot accidentally un-ignore it with a broad `!config*.json`
+	// allow rule.
+	lines.push('config.local.json')
 	lines.push('')
 	lines.push('# ── Derived markdown indexes (regenerated from JSON) ──────────────')
 	lines.push('tasks/INDEX.md')

package/src/cli/consistency/parse-review.mjs

@@ -10,7 +10,8 @@
  * `warning` -> `major`. `suggestion|nitpick|note|info` are dropped.
  *
  * Status normalizes to `fixed | deferred | open` (default `open`).
- * `resolved: true` is treated as `status: 'fixed'`.
+ * Both `fixed: true` and `resolved: true` are treated as `status: 'fixed'`
+ * (the reviewer skill writes `fixed: true`; `resolved: true` is legacy).
  *
  * Output: {findings: [{id, severity, status, title, file}]}
  */
@@ -89,6 +90,7 @@ function normalizeSeverity(sev) {
 }
 
 function normalizeStatus(f) {
+	if (f.fixed === true) return 'fixed'
 	if (f.resolved === true) return 'fixed'
 	if (typeof f.status === 'string') {
 		const s = f.status.toLowerCase().trim()

package/src/cli/dispatch.mjs

@@ -71,6 +71,7 @@ import { cmdPrReview } from './commands/pr-review.mjs'
 import { cmdPrecompactHook } from './commands/precompact-hook.mjs'
 import { cmdProductContext } from './commands/product-context.mjs'
 import { cmdProfile } from './commands/profile.mjs'
+import { cmdReleaseNotes } from './commands/release-notes.mjs'
 import { cmdRiskCheck } from './commands/risk-check.mjs'
 import { cmdRoadmap } from './commands/roadmap.mjs'
 import { cmdRoute } from './commands/route.mjs'
@@ -253,6 +254,7 @@ export const DISPATCH = {
 	'variant-pick': (args) => wrap(cmdVariantPick)(args[1], args[2], args.slice(3)),
 	worktree: (args) => wrap(cmdWorktree)(args[1], args[2], args.slice(3)),
 	audit: (args) => wrap(cmdAudit)(args[1], args[2], args.slice(3)),
+	'release-notes': (args) => wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3)),
 	team: (args) => wrap(cmdTeam)(args[1], args[2], args.slice(3)),
 	active: (args) => wrap(cmdActive)(args[1], args[2], args.slice(3)),
 	roadmap: (args) => wrap(cmdRoadmap)(args[1], args[2], args.slice(3)),

package/src/cli/gate/gates/review-clean.mjs

@@ -4,7 +4,9 @@
  *
  * Skipped when {task_dir}/review.json is absent (review is optional for some
  * tracks). When it is present, fails if any finding has
- * severity ∈ {"critical", "warning"} AND resolved !== true.
+ * severity ∈ {"critical", "warning"} AND neither `resolved === true` nor
+ * `fixed === true`. The reviewer skill writes resolution as `fixed: true`
+ * paired with `fix_commit`; `resolved: true` is a legacy alias.
  *
  * The findings array may be under `findings` or `issues` depending on the
  * reviewer format — we accept either.
@@ -47,7 +49,7 @@ const gate = {
 				? doc.issues
 				: []
 		const unresolved = findings.filter(
-			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true,
+			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true && f?.fixed !== true,
 		)
 		if (unresolved.length > 0) {
 			return {