devflow-kit 3.0.1 → 3.2.0

package/dist/cli/commands/agents.js

@@ -1,9 +1,9 @@
 /**
  * devflow agents — Manage per-agent model/effort assignments.
  *
- * applies ADR-013: CLI-layer module; core logic in src/core/agent-models.ts.
- * avoids PF-014: never process.exit() inside a finally-guarded scope (terminal.ts
- *   handles cleanup in Promise resolve, not process.exit).
+ * CLI-layer module; core logic in src/core/agent-models.ts.
+ * Never process.exit() inside a finally-guarded scope: it skips the finally
+ *   (terminal.ts handles cleanup in Promise resolve, not process.exit).
  *
  * Branding note: "subswitch" must NEVER appear in user-visible strings.
  * User-facing vocabulary: "external model routing" / "Devflow proxy" /
@@ -14,14 +14,19 @@
  *   devflow agents --list    → tabular list (safe in non-TTY)
  *   devflow agents --set <agent> --model <m> --effort <e>
  *   devflow agents --reset [--yes]
+ *
+ * D-WORKER-AGENTS: `memory` is a background worker, not an agent, and is
+ * settable here as `--set memory` and as a row after the agents in `--list` and
+ * the TUI. Its state is always 'worker'; its values are held to the worker
+ * domain (Claude models and effort levels only) by validateWorkerValue.
  */
 import { Command } from 'commander';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { EFFORT_LEVELS, LEGACY_AGENT_KEYS, readAgentMapping, saveAgentMapping, reapplyAgentMapping, loadShippedDefaults, readInstalledAgentNames, } from '../../core/agent-models.js';
+import { EFFORT_INHERIT, EFFORT_LEVELS, LEGACY_AGENT_KEYS, WORKER_AGENTS, agentOnlyMapping, isEffortLevel, isWorkerAgent, readAgentMapping, saveAgentMapping, reapplyAgentMapping, loadShippedAgentDefaults, readInstalledAgentNames, validateWorkerValue, } from '../../core/agent-models.js';
 import { CLAUDE_MODEL_ALIASES, isDormantExternalModel, } from '../../core/external-models.js';
-import { classifyAgentState, AGENT_STATE_LABELS, } from '../../core/agent-state.js';
+import { classifyAgentState, formatEffortDisplay, AGENT_STATE_LABELS, } from '../../core/agent-state.js';
 import { isValidModelName } from '../../core/agent-frontmatter.js';
 import { isProxyEnabled } from '../../core/proxy-state.js';
 import { getAllAgentNames } from '../../core/plugins.js';
@@ -47,26 +52,43 @@ function Err(error) {
  *   This preserves the configure-first-then-enable provisioning flow and keeps
  *   `--set` at zero subprocess cost (AC-P9: cache-only, 0 spawns).
  *
+ * D-WORKER-AGENTS: when `agentName` is a worker (`memory`), model and effort are
+ * held to the worker value domain instead — validateWorkerValue, the function
+ * readAgentMapping applies on read — with no catalog lookup: a worker runs
+ * outside any session, so an external model, `inherit` as a model and `inherit`
+ * as an effort are all rejected.
+ *
+ * D-SHIPPED-EFFORT: for an agent, `--effort inherit` is accepted. It stores the
+ * sentinel that drops the agent's effort line; `--effort default` deletes the
+ * key so the shipped effort applies again.
+ *
  * Returns Err when:
  *  - neither model nor effort is provided
  *  - model is unknown AND catalog is known
- *  - effort is unknown (not in EFFORT_LEVELS ∪ 'default')
+ *  - effort is unknown (not in EFFORT_LEVELS ∪ 'default' ∪ 'inherit')
+ *  - agentName is a worker and a value is outside the worker domain
  */
-export function validateSetArgs(args, catalog = { known: false }) {
+export function validateSetArgs(args, catalog = { known: false }, agentName) {
     const { model, effort } = args;
     if (model === undefined && effort === undefined) {
         return Err('Specify at least one of --model or --effort');
     }
+    const worker = agentName !== undefined && isWorkerAgent(agentName);
     if (model !== undefined) {
         // Charset gate: applied at every trust boundary regardless of catalog state.
         // Rejects injection payloads (newlines, YAML metacharacters) before they can
-        // propagate to agent-models.json or agent frontmatter. avoids PF-017: allowlist
+        // propagate to agent-models.json or agent frontmatter. Allowlist
         // what the callee actually consumes rather than denylist individual bad chars.
         if (!isValidModelName(model)) {
             return Err(`Invalid model name "${model}". Model names must start with an alphanumeric character ` +
                 `and contain only alphanumeric, dot, underscore, or hyphen characters (max 64 chars).`);
         }
-        if (catalog.known) {
+        if (worker) {
+            const check = validateWorkerValue('model', model);
+            if (!check.ok)
+                return Err(check.error);
+        }
+        else if (catalog.known) {
             // Full validation against the discovered catalog.
             const valid = ['default', ...CLAUDE_MODEL_ALIASES, ...catalog.selectableNames];
             if (!valid.includes(model)) {
@@ -77,9 +99,16 @@ export function validateSetArgs(args, catalog = { known: false }) {
         // warning fires at agents.ts call site if the proxy is off.
     }
     if (effort !== undefined) {
-        const valid = ['default', ...EFFORT_LEVELS];
-        if (!valid.includes(effort)) {
-            return Err(`Unknown effort "${effort}". Valid: ${valid.join(', ')}`);
+        if (worker) {
+            const check = validateWorkerValue('effort', effort);
+            if (!check.ok)
+                return Err(check.error);
+        }
+        else {
+            const valid = ['default', ...EFFORT_LEVELS, EFFORT_INHERIT];
+            if (!valid.includes(effort)) {
+                return Err(`Unknown effort "${effort}". Valid: ${valid.join(', ')}`);
+            }
         }
     }
     return Ok(args);
@@ -106,10 +135,9 @@ export function applySetMapping(mapping, agentName, args) {
         if (args.effort === 'default') {
             delete existing.effort;
         }
-        else {
-            // Sound narrowing: validateSetArgs already confirmed args.effort is a valid
-            // EffortLevel before this function is called. SetArgs.effort is string to keep
-            // the CLI entry type permissive; the assertion here is not a compensating cast.
+        else if (isEffortLevel(args.effort) || args.effort === EFFORT_INHERIT) {
+            // SetArgs.effort is a string to keep the CLI entry type permissive;
+            // validateSetArgs has already confirmed it is a level or the inherit sentinel.
             existing.effort = args.effort;
         }
     }
@@ -133,23 +161,62 @@ export async function buildListRows(input) {
         const entry = mapping.agents[name];
         const configured = entry?.model ?? 'default';
         const effort = entry?.effort ?? 'default';
-        const defaultModel = shippedDefaults[name] ?? 'unknown';
+        const defaultModel = shippedDefaults[name]?.model ?? 'unknown';
+        const shippedEffort = shippedDefaults[name]?.effort;
         const installed = installedNames.has(name);
         // inRegistry is always true here — agentNames comes from the registry.
         const state = classifyAgentState({ configured, proxyEnabled, installed, inRegistry: true });
-        return { name, defaultModel, configured, effort, state };
+        return { name, defaultModel, configured, effort, shippedEffort, state };
     });
     return rows;
 }
+/**
+ * Build the list rows of the background workers (D-WORKER-AGENTS), which follow
+ * the agent rows in `--list`.
+ *
+ * A worker has no installed agent file, so its row never consults the install
+ * directory: its state is always 'worker', never classified (it can be neither
+ * not installed nor dormant — validateSetArgs rejects an external model for a
+ * worker). DEFAULT is the model WORKER_AGENTS ships and EFFORT shows the shipped
+ * effort while unconfigured, the same convention as an agent row.
+ *
+ * Pure function, no I/O.
+ */
+export function buildWorkerListRows(mapping) {
+    return Object.entries(WORKER_AGENTS).map(([name, shipped]) => {
+        const entry = mapping.agents[name];
+        return {
+            name,
+            defaultModel: shipped.model,
+            configured: entry?.model ?? 'default',
+            effort: entry?.effort ?? 'default',
+            shippedEffort: shipped.effort,
+            state: 'worker',
+        };
+    });
+}
 // ---------------------------------------------------------------------------
 // --list output formatting
 // ---------------------------------------------------------------------------
+/**
+ * Width of the EFFORT column: the longest `default (<level>)` an unconfigured row
+ * can show, derived from EFFORT_LEVELS so a new level cannot truncate the cell.
+ */
+const EFFORT_COLUMN_WIDTH = Math.max(...EFFORT_LEVELS.map(level => formatEffortDisplay('default', level).length), EFFORT_INHERIT.length);
+/** Narrowest the DEFAULT column of `--list` renders; it widens to fit a longer shipped default. */
+const DEFAULT_COLUMN_MIN_WIDTH = 10;
+/** Narrowest the CONFIGURED column of `--list` renders; it widens to fit a longer configured model. */
+const CONFIGURED_COLUMN_MIN_WIDTH = 16;
 export function formatListOutput(rows, proxyEnabled) {
     const lines = [];
     const AGENT_W = 20;
-    const DEFAULT_W = 10;
-    const CONFIGURED_W = 16;
-    const EFFORT_W = 12;
+    // DEFAULT and CONFIGURED grow to the longest value in their column, so a full
+    // model identifier (the memory worker ships claude-sonnet-5-5; a user maps
+    // claude-sonnet-4-6) is shown whole, not cut to a fixed width and read as a
+    // different model.
+    const DEFAULT_W = Math.max(DEFAULT_COLUMN_MIN_WIDTH, ...rows.map(row => stripAnsi(row.defaultModel).length));
+    const CONFIGURED_W = Math.max(CONFIGURED_COLUMN_MIN_WIDTH, ...rows.map(row => stripAnsi(row.configured).length));
+    const EFFORT_W = EFFORT_COLUMN_WIDTH;
     // Header
     lines.push([
         color.gray('AGENT'.padEnd(AGENT_W)),
@@ -176,6 +243,9 @@ export function formatListOutput(rows, proxyEnabled) {
             case 'unknown':
                 stateStr = color.dim(AGENT_STATE_LABELS['unknown']);
                 break;
+            case 'worker':
+                stateStr = color.dim(AGENT_STATE_LABELS['worker']);
+                break;
             default: {
                 const _ = row.state;
                 void _;
@@ -188,15 +258,18 @@ export function formatListOutput(rows, proxyEnabled) {
             stripAnsi(row.name).padEnd(AGENT_W).slice(0, AGENT_W),
             stripAnsi(row.defaultModel).padEnd(DEFAULT_W).slice(0, DEFAULT_W),
             stripAnsi(row.configured).padEnd(CONFIGURED_W).slice(0, CONFIGURED_W),
-            stripAnsi(row.effort).padEnd(EFFORT_W).slice(0, EFFORT_W),
+            stripAnsi(formatEffortDisplay(row.effort, row.shippedEffort)).padEnd(EFFORT_W).slice(0, EFFORT_W),
             stateStr,
         ].join('  '));
     }
-    const installed = rows.filter(r => r.state !== 'not-installed').length;
-    const configured = rows.filter(r => r.configured !== 'default' || r.effort !== 'default').length;
+    // The footer counts agent rows only: a worker row is neither installed nor
+    // not installed, and configuring it changes no agent (D-WORKER-AGENTS).
+    const agentRows = rows.filter(r => r.state !== 'worker');
+    const installed = agentRows.filter(r => r.state !== 'not-installed').length;
+    const configured = agentRows.filter(r => r.configured !== 'default' || r.effort !== 'default').length;
     const proxyLabel = proxyEnabled ? color.green('enabled') : color.yellow('disabled');
     lines.push('');
-    lines.push(`${installed}/${rows.length} installed · ${configured} configured · proxy: ${proxyLabel}`);
+    lines.push(`${installed}/${agentRows.length} installed · ${configured} configured · proxy: ${proxyLabel}`);
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
@@ -241,7 +314,8 @@ async function buildTuiState(agentNames, mapping, shippedDefaults, proxyEnabled,
         const entry = mapping.agents[name];
         return buildRow({
             name,
-            shippedDefault: shippedDefaults[name] ?? 'unknown',
+            shippedDefault: shippedDefaults[name]?.model ?? 'unknown',
+            shippedEffort: shippedDefaults[name]?.effort,
             savedModel: entry?.model,
             savedEffort: entry?.effort,
             proxyEnabled,
@@ -251,12 +325,31 @@ async function buildTuiState(agentNames, mapping, shippedDefaults, proxyEnabled,
             inRegistry: true,
         });
     });
-    // Orphan rows: keys in agent-models.json not present in the registry.
+    // Worker rows (D-WORKER-AGENTS) follow the agents. A worker has no installed
+    // file and takes only the worker value domain, so it is built with its own
+    // shipped defaults and never classified as an orphan (state 'unknown').
+    for (const [workerName, shipped] of Object.entries(WORKER_AGENTS)) {
+        const entry = mapping.agents[workerName];
+        rows.push(buildRow({
+            name: workerName,
+            shippedDefault: shipped.model,
+            shippedEffort: shipped.effort,
+            savedModel: entry?.model,
+            savedEffort: entry?.effort,
+            proxyEnabled,
+            installed: false,
+            inRegistry: false,
+            worker: true,
+        }));
+    }
+    // Orphan rows: agent keys in agent-models.json not present in the registry.
     // Appended at the end so they are visually separated from known agents.
-    for (const orphanKey of Object.keys(mapping.agents)) {
+    // agentOnlyMapping leaves out the worker keys, which have their own rows above.
+    const agentEntries = agentOnlyMapping(mapping);
+    for (const orphanKey of Object.keys(agentEntries)) {
         if (registrySet.has(orphanKey))
             continue;
-        const entry = mapping.agents[orphanKey];
+        const entry = agentEntries[orphanKey];
         rows.push(buildRow({
             name: orphanKey,
             shippedDefault: 'unknown',
@@ -352,14 +445,15 @@ export const agentsCommand = new Command('agents')
     .option('--list', 'List all agents with their current configuration')
     .option('--set <agent>', 'Set model/effort for a specific agent')
     .option('--model <model>', 'Model to assign (use with --set)')
-    .option('--effort <level>', 'Effort level to assign (use with --set)')
+    .option('--effort <level>', `Effort level to assign (use with --set): ${EFFORT_LEVELS.join(', ')}, ` +
+    `default (use the shipped effort), or ${EFFORT_INHERIT} (drop the effort line, follow the session)`)
     .option('--reset', 'Clear all agent customisations and restore defaults')
     .option('--yes', 'Skip confirmation prompt (use with --reset)')
     .action(async (options) => {
     const claudeDir = getClaudeDirectory();
     const devflowDir = getDevFlowDirectory();
     const installDir = path.join(claudeDir, 'agents', 'devflow');
-    // Cache directory for model discovery — authoritative path from cache.ts (avoids PF-013).
+    // Cache directory for model discovery — authoritative path from cache.ts.
     const cacheDir = modelCacheDir(devflowDir);
     // Log path mirrors proxy.ts for unified proxy diagnostics.
     const logPath = path.join(devflowDir, 'logs', 'proxy.log');
@@ -376,20 +470,23 @@ export const agentsCommand = new Command('agents')
     // An agent with no shipped default renders a blank DEFAULT column and can
     // never be reverted off an external model; surface the gap rather than
     // letting the table imply the agent simply ships without one.
-    const shippedDefaults = await loadShippedDefaults(undefined, {
+    const shippedDefaults = await loadShippedAgentDefaults(undefined, {
         onWarning: (msg) => p.log.warn(msg),
     });
-    // ── --list ──────────────────────────────────────────────────────────────
-    if (options.list) {
-        const agentNames = getAllAgentNames().sort();
-        const rows = await buildListRows({
-            agentNames,
+    // Agent rows in registry order, then the worker rows (D-WORKER-AGENTS).
+    const loadListRows = async () => {
+        const agentRows = await buildListRows({
+            agentNames: getAllAgentNames().sort(),
             mapping,
             installDir,
             shippedDefaults,
             proxyEnabled,
         });
-        process.stdout.write(formatListOutput(rows, proxyEnabled) + '\n');
+        return [...agentRows, ...buildWorkerListRows(mapping)];
+    };
+    // ── --list ──────────────────────────────────────────────────────────────
+    if (options.list) {
+        process.stdout.write(formatListOutput(await loadListRows(), proxyEnabled) + '\n');
         return;
     }
     // ── --reset ─────────────────────────────────────────────────────────────
@@ -447,10 +544,11 @@ export const agentsCommand = new Command('agents')
             p.log.info(`Agent '${agentName}' has been renamed to '${canonical}' — using canonical name.`);
             agentName = canonical;
         }
-        // Validate agent name
+        // Validate agent name. D-WORKER-AGENTS: the workers are settable too, so a
+        // first `--set memory` is accepted although nothing in the mapping names it yet.
         const knownAgents = getAllAgentNames();
         const knownMapping = Object.keys(mapping.agents);
-        const allKnown = new Set([...knownAgents, ...knownMapping]);
+        const allKnown = new Set([...knownAgents, ...Object.keys(WORKER_AGENTS), ...knownMapping]);
         if (!allKnown.has(agentName)) {
             p.log.error(`Unknown agent "${agentName}". Valid: ${[...allKnown].sort().join(', ')}`);
             process.exitCode = 1;
@@ -461,7 +559,7 @@ export const agentsCommand = new Command('agents')
         // dormancy warning below fires if needed). This preserves the
         // configure-first-then-enable provisioning flow.
         const setCatalog = getExternalModelsCached(cacheDir);
-        const validation = validateSetArgs({ model: options.model, effort: options.effort }, setCatalog);
+        const validation = validateSetArgs({ model: options.model, effort: options.effort }, setCatalog, agentName);
         if (!validation.ok) {
             p.log.error(validation.error);
             process.exitCode = 1;
@@ -510,15 +608,7 @@ export const agentsCommand = new Command('agents')
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     if (!isInteractive) {
         // Non-TTY: print list and exit 1 with note
-        const agentNames = getAllAgentNames().sort();
-        const rows = await buildListRows({
-            agentNames,
-            mapping,
-            installDir,
-            shippedDefaults,
-            proxyEnabled,
-        });
-        process.stdout.write(formatListOutput(rows, proxyEnabled) + '\n');
+        process.stdout.write(formatListOutput(await loadListRows(), proxyEnabled) + '\n');
         process.stderr.write('Note: interactive view requires a terminal. Use --list for non-TTY output.\n');
         process.exitCode = 1;
         return;
@@ -569,7 +659,8 @@ export const agentsCommand = new Command('agents')
     // Lazy-import terminal to avoid loading readline/tty in non-TTY paths
     const { runAgentsTui } = await import('../agents-view/terminal.js');
     // Wrap: runTui rejects on initial-render failure or handler throw.
-    // On rejection: log and bail — no partial write (avoids PF-014 process.exit).
+    // On rejection: log and bail — no partial write; set process.exitCode
+    // rather than calling process.exit(), which would skip pending cleanup.
     let result;
     try {
         result = await runAgentsTui(tuiState);

package/dist/cli/commands/ambient.js

@@ -17,7 +17,7 @@ const ORCHESTRATOR_HOOK_MARKER = 'session-start-orchestrator';
  * hook is devflow's when its command ENDS in one of these, under any directory — so
  * installs made under a custom or repo-local devflow directory are still recognised —
  * and never because it merely contains a marker word: a user's
- * `~/bin/preamble-logger.sh` or `echo preamble` is theirs (applies ADR-024). The
+ * `~/bin/preamble-logger.sh` or `echo preamble` is theirs. The
  * legacy forms are the pre-preamble `ambient-prompt` hook (first a bare
  * `ambient-prompt.sh`, then through `run-hook`) and the retired
  * `session-start-classification` hook, both still swept on enable and disable.

package/dist/cli/commands/attribution-prompts.js

@@ -1,13 +1,13 @@
 /**
  * Attribution prompt helpers for devflow init.
  *
- * CLI-layer module (ADR-013): prompt-rendering logic lives in src/cli/commands/,
+ * CLI-layer module: prompt-rendering logic lives in src/cli/commands/,
  * core business logic stays in src/core/.
  *
- * Applies PF-029: the gate is an exported pure predicate with an explicit isTTY guard,
+ * The gate is an exported pure predicate with an explicit isTTY guard,
  * so --recommended (flag, no prompt) and the non-TTY fallback keep their promptless
  * contracts and the reachability rule is unit-testable without a terminal.
- * Applies PF-014: runAttributionStep never calls process.exit() or throws — callers
+ * runAttributionStep never calls process.exit() or throws — callers
  * own the cancel idiom (p.cancel + process.exit(0)), keeping try/finally cleanup safe.
  *
  * D27: suppress-attribution flag — gates Claude Code's AI-attribution injection.
@@ -37,7 +37,7 @@ import { clackNote, clackSelect } from './prompt-io.js';
  * Gating on the mode name is sound here because 'advanced' is only ever resolved on an
  * interactive path (the Advanced branch exit-1s on non-TTY), and the explicit isTTY guard
  * keeps the promptless contracts of --recommended and the non-TTY fallback pinned
- * regardless (PF-029).
+ * regardless.
  *
  * There is no CLI override for attribution — it is toggled post-install via
  * `devflow flags --enable/--disable suppress-attribution`.
@@ -65,7 +65,7 @@ export function buildClackAttributionPrompts() {
  *
  * Returns true only when `suppress-attribution` is explicitly set to the boolean
  * true — undefined, null, and false all map to false, giving `p.select` a real
- * boolean rather than an unchecked cast (PF-018: non-vacuous path).
+ * boolean rather than an unchecked cast.
  *
  * Pure function — no side effects, fully testable without a TTY.
  */
@@ -94,14 +94,14 @@ export function applyAttributionAnswer(flags, outcome) {
  *   1. Note — "Current setting: …" header with context about what the flag does.
  *   2. Enable select — labeled Yes / No with hints (seeded from prior state);
  *      p.select is immune to Enter-through muscle memory while still preserving
- *      the seeded value (ambient-prompt style — per PF-029).
+ *      the seeded value (ambient-prompt style).
  *
  * Returns:
  *   {kind:'resolved', suppress, messages} — step completed; `suppress` is the chosen
  *     boolean; `messages` are emitted by the caller.
  *   {kind:'cancelled'} — user pressed Escape; caller runs p.cancel + process.exit(0).
  *
- * Invariants (PF-014):
+ * Invariants:
  *   - Never calls process.exit(), never throws.
  *   - All I/O is routed through the `prompts` parameter (injectable for tests).
  */
@@ -109,7 +109,7 @@ export async function runAttributionStep(opts) {
     const { seed, prompts } = opts;
     const currentStr = seed ? 'suppressed' : 'shown (default)';
     // security-02: name the destructive branch (Yes) BEFORE the user consents.
-    // ADR-024 corollary (b): turning the flag ON replaces any existing attribution
+    // Turning the flag ON replaces any existing attribution
     // value, including a custom one — this is deliberate. Only the exact
     // devflow-managed shape {"commit":"","pr":""} is removed on disable.
     // security-04: surface the org AI-disclosure-policy dimension as a note (not a gate).

package/dist/cli/commands/capture.js

@@ -76,7 +76,7 @@ export function removeCaptureHooks(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : structuredClone(input);
     let changed = false;
     for (const [hookType, marker] of Object.entries(CAPTURE_HOOK_CONFIG)) {
-        // Evaluate every removal — never short-circuit (PF-015).
+        // Evaluate every removal — never short-circuit.
         const removed = removeHooks(settings, hookType, isCaptureHook(marker));
         changed = changed || removed;
     }

package/dist/cli/commands/compliance-prompts.js

@@ -1,13 +1,13 @@
 /**
  * Compliance prompt helpers for devflow init.
  *
- * CLI-layer module (ADR-013): prompt-rendering logic lives in src/cli/commands/,
+ * CLI-layer module: prompt-rendering logic lives in src/cli/commands/,
  * core business logic stays in src/core/compliance.ts.
  *
- * Applies PF-029: every wizard gate keys on `modePromptShown` (was the Setup-mode
+ * Every wizard gate keys on `modePromptShown` (was the Setup-mode
  * p.select prompt actually shown?), never on the mode name, so --recommended (flag,
  * no prompt) and the non-TTY fallback preserve their promptless contracts.
- * Applies PF-014: runComplianceStep never calls process.exit() or throws — callers
+ * runComplianceStep never calls process.exit() or throws — callers
  * own the cancel idiom (p.cancel + process.exit(0)), keeping try/finally cleanup safe.
  *
  * Shared DI seam (PromptOutcome, WizardPromptIO, clackNote, clackSelect) lives in
@@ -53,7 +53,7 @@ export function formatComplianceSummary(enabled, frameworks) {
 /**
  * Determines whether the compliance wizard step should run for a given init invocation.
  *
- * Gate table (per PF-029: key on modePromptShown, never on the mode name):
+ * Gate table (key on modePromptShown, never on the mode name):
  *
  *   --recommended flag / !isTTY fallback             → no (promptless contract preserved)
  *   Interactive mode-prompt → Recommended             → yes (modePromptShown=true)
@@ -106,7 +106,7 @@ export function buildClackCompliancePrompts() {
  *   1. Note — "Current setting: …" header then the framework catalogue.
  *   2. Enable select — labeled Yes / No with hints (seeded from prior state);
  *      p.select is immune to Enter-through muscle memory while still preserving
- *      the seeded value (ambient-prompt style — per PF-029).
+ *      the seeded value (ambient-prompt style).
  *   3. If Yes — framework multiselect (seeded, required:false).
  *
  * Returns:
@@ -114,7 +114,7 @@ export function buildClackCompliancePrompts() {
  *     ComplianceFeatureState; `messages` are emitted by the caller.
  *   {kind:'cancelled'} — user pressed Escape; caller runs p.cancel + process.exit(0).
  *
- * Invariants (PF-014):
+ * Invariants:
  *   - Never calls process.exit(), never throws.
  *   - Returned arrays never alias seed arrays (defensive copies throughout).
  *   - All I/O is routed through the `prompts` parameter (injectable for tests).
@@ -141,7 +141,7 @@ export async function runComplianceStep(opts) {
     if (!enabled) {
         return {
             kind: 'resolved',
-            // Never alias seed.frameworks — defensive copy (PF-014).
+            // Never alias seed.frameworks — defensive copy.
             state: { enabled: false, frameworks: [...seed.frameworks] },
             messages: [{
                     level: 'info',
@@ -153,7 +153,7 @@ export async function runComplianceStep(opts) {
     const multiselectOutcome = await prompts.multiselect({
         message: FRAMEWORK_SELECT_MESSAGE,
         options: frameworkChoices(),
-        // Defensive copy: never alias seed.frameworks (PF-014).
+        // Defensive copy: never alias seed.frameworks.
         initialValues: [...seed.frameworks],
         required: false,
     });

package/dist/cli/commands/compliance.js

@@ -1,15 +1,16 @@
 /**
  * devflow compliance — Enable, disable, set, and check status of the compliance feature.
  *
- * Applies ADR-013: CLI-layer module; pure helpers in src/core/compliance.ts,
+ * CLI-layer module; pure helpers in src/core/compliance.ts,
  *   I/O orchestration in src/targets/claude-code/compliance-install.ts.
- * Applies ADR-001: compliance is manifest-group (like proxy), not config.json-gated.
- * Avoids PF-009: per-artifact failures are warn-not-throw.
- * Avoids PF-015: enable/disable each converge BOTH artifacts unconditionally.
+ * Compliance is manifest-group (like proxy), not config.json-gated.
+ * Per-artifact failures are warn-not-throw, so one failed artifact never aborts the rest.
+ * Enable/disable each converge BOTH artifacts unconditionally, so neither is left
+ *   half-converged.
  * The evidence-policy lines (--status, and the --enable/--set suggestion) come
  *   from src/core/evidence-policy.ts, the seam onto the package's own resolvers;
  *   the CLI prints the keys to add to .devflow/project.json and never writes it
- *   (applies ADR-024).
+ *   (the file is team-owned).
  */
 import { Command } from 'commander';
 import { promises as fs } from 'fs';
@@ -277,7 +278,7 @@ export const complianceCommand = new Command('compliance')
         action = 'disable';
     }
     const resolved = resolveComplianceCliAction(current, action, setFrameworks);
-    // Converge artifacts (PF-015: always converge, never short-circuit)
+    // Converge artifacts (always converge, never short-circuit)
     await convergeFromManifest({
         claudeDir,
         devflowDir,
@@ -310,7 +311,7 @@ export const complianceCommand = new Command('compliance')
             'run `devflow rules --enable` to install the stamped rule'));
     }
     // Suggest the team file compliance now implies. Printed, never written:
-    // .devflow/project.json is team-owned (D-POLICY-NO-WRITE, applies ADR-024).
+    // .devflow/project.json is team-owned (D-POLICY-NO-WRITE).
     if (resolved.nextState.enabled) {
         const policyModule = loadEvidencePolicyModule();
         const settingsModule = loadSettingsModule();