devflow-kit 3.0.1 → 3.2.0

package/dist/core/agent-models.js

@@ -2,12 +2,12 @@
  * Agent model mapping engine — schema, persistence, and convergence for the
  * per-agent model configuration feature.
  *
- * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
- * avoids PF-014: all fallible operations return Result, no process.exit().
+ * Pure core-layer module, no Claude Code adapter concerns.
+ * All fallible operations return Result, no process.exit().
  *
  * Mapping file: ~/.devflow/agent-models.json
  *   { version: 1, agents: { [name]: { model?, effort? } } }
- *   Deviations-only: omit an agent to inherit its shipped default.
+ *   Deviations-only: omit an agent to inherit its shipped default (model AND effort).
  *   Unknown agent names are tolerated and preserved on save (plugin may not be installed).
  *   Invalid effort values are dropped with a warning.
  *
@@ -25,8 +25,8 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
-import { isDormantExternalModel } from './external-models.js';
-import { rewriteAgentFrontmatter, readFrontmatterModel, isValidModelName } from './agent-frontmatter.js';
+import { isDormantExternalModel, CLAUDE_MODEL_ALIASES } from './external-models.js';
+import { rewriteAgentFrontmatter, readFrontmatterModel, readFrontmatterEffort, isValidModelName, } from './agent-frontmatter.js';
 import { agentSourceDirs } from './assets.js';
 import { getAllAgentNames } from './plugins.js';
 import { mdEntryName, mdFileName } from './orphan-sweep.js';
@@ -48,9 +48,93 @@ export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
 /**
  * Membership set typed as ReadonlySet<string> so .has() accepts a plain
  * string argument without a cast — TypeScript's Set<T>.has() requires T, and
- * EFFORT_LEVELS[number] is a literal union, not string (applies ADR-003).
+ * EFFORT_LEVELS[number] is a literal union, not string.
  */
 const EFFORT_LEVELS_SET = new Set(EFFORT_LEVELS);
+/** True when `value` is one of EFFORT_LEVELS (narrows string to EffortLevel). */
+export function isEffortLevel(value) {
+    return EFFORT_LEVELS_SET.has(value);
+}
+/**
+ * D-SHIPPED-EFFORT: the stored effort value that drops an agent's effort line
+ * altogether. A mapping `inherit` yields no `effort:` line and does NOT fall
+ * back to the shipped effort, so the agent follows the session's effort. It is
+ * a stored value, unlike `default` (which deletes the key so the shipped
+ * effort applies again), and it is effort-only: model-side inherit semantics
+ * are a separate decision.
+ */
+export const EFFORT_INHERIT = 'inherit';
+// ---------------------------------------------------------------------------
+// Workers
+// ---------------------------------------------------------------------------
+/**
+ * D-WORKER-AGENTS: background workers whose model and effort are settable in
+ * `devflow agents` although they are not agents. A worker runs as its own
+ * `claude -p` process outside any session and has no installed agent file, so
+ * there is nothing for a reapply to rewrite.
+ *
+ * Worker entries are stored under `agents.<name>` in agent-models.json, in the
+ * same map as agent entries; an absent entry means the default declared here.
+ * Because the map is shared, every agent-only path (the reapply walk, the init
+ * reapply gate, countExternalMappedAgents, the list and TUI agent sets) goes
+ * through agentOnlyMapping, the one definition of the agent-only subset.
+ *
+ * A worker is not a DEVFLOW_PLUGINS agent: getAllAgentNames() and the roster
+ * count are unaffected.
+ *
+ * Shipped value of `memory`: `claude-sonnet-5-5` at `high` effort. User decision
+ * 2026-10-08: memory quality is worth more than the cost saving of Haiku, which
+ * replaces the plan's Haiku default. The worker does not read `agents.memory`
+ * yet. Until it does, background-memory-update names this model as a literal in
+ * its `claude -p --model` argument, and tests/agent-models-worker.test.ts holds
+ * that literal equal to this row so the two cannot drift apart. Wiring the
+ * worker to this map, and `--effort` behind a CLI version probe, is a separate
+ * change.
+ */
+export const WORKER_AGENTS = {
+    memory: { model: 'claude-sonnet-5-5', effort: 'high' },
+};
+/**
+ * True when `name` is a worker key. Own-property check, so a hostile key such as
+ * `constructor` or `__proto__` is never answered from the prototype chain.
+ */
+export function isWorkerAgent(name) {
+    return Object.hasOwn(WORKER_AGENTS, name);
+}
+/** A full Claude model identifier: the `claude-` prefix and at least one more character. */
+const CLAUDE_FULL_ID_RE = /^claude-.+$/;
+/**
+ * D-WORKER-AGENTS: the worker value domain, owned here once and shared by
+ * `validateSetArgs` (the write boundary) and `readAgentMapping` (the read
+ * boundary), so a hand-edited file and a CLI argument are held to one rule.
+ *
+ *  - model:  `default`, a CLAUDE_MODEL_ALIASES alias, or a full identifier
+ *            starting `claude-`. Anything else is rejected, `inherit` included
+ *            (a worker has no session model to inherit). External models are
+ *            rejected too: the worker runs `claude -p` outside a session and
+ *            nothing here verifies it routes through the proxy, so allowing
+ *            them later is a deliberate change to this function.
+ *  - effort: `default` or an EFFORT_LEVELS level. `inherit` is rejected because
+ *            a worker has no session effort to inherit.
+ *
+ * Pure function — no catalog lookup, no I/O.
+ */
+export function validateWorkerValue(field, value) {
+    if (field === 'effort') {
+        if (value === 'default' || isEffortLevel(value))
+            return Ok(undefined);
+        return Err(`Invalid effort "${value}" for a worker. Valid: default, ${EFFORT_LEVELS.join(', ')} ` +
+            `(a worker has no session effort to inherit)`);
+    }
+    const inDomain = isValidModelName(value) &&
+        (value === 'default' ||
+            CLAUDE_MODEL_ALIASES.includes(value) ||
+            CLAUDE_FULL_ID_RE.test(value));
+    if (inDomain)
+        return Ok(undefined);
+    return Err(`Invalid model "${value}" for a worker. Valid: default, ${CLAUDE_MODEL_ALIASES.join(', ')}, ` +
+        `or a full claude- identifier (external models are not supported for workers)`);
+}
 // ---------------------------------------------------------------------------
 // Key migration
 // ---------------------------------------------------------------------------
@@ -216,6 +300,34 @@ export async function parseAgentMappingEnvelope(filePath) {
     }
     return { kind: 'ok', envelope, rawAgents: rawAgents };
 }
+/**
+ * D-WORKER-AGENTS: the agent-only subset of the mapping — every entry whose key
+ * is not a worker. Unknown names stay: the file preserves entries for agents
+ * whose plugin is not installed.
+ *
+ * This is the one definition of "the agents in the mapping". The reapply walk,
+ * the init reapply gate, countExternalMappedAgents and the TUI's orphan rows all
+ * call it, so a worker entry can never be mistaken for an agent with no
+ * installed file.
+ *
+ * Pure function — returns a new record, never mutates the mapping.
+ */
+export function agentOnlyMapping(mapping) {
+    const agents = {};
+    for (const [name, entry] of Object.entries(mapping.agents)) {
+        if (!isWorkerAgent(name))
+            agents[name] = entry;
+    }
+    return agents;
+}
+/**
+ * True when the mapping holds at least one agent entry. The `devflow init`
+ * reapply gate: an agents.memory-only mapping keeps it closed, because there is
+ * no agent file for a reapply to converge.
+ */
+export function hasAgentMappingEntries(mapping) {
+    return Object.keys(agentOnlyMapping(mapping)).length > 0;
+}
 /**
  * Read and tolerantly parse ~/.devflow/agent-models.json.
  * Returns an empty mapping when the file is missing.
@@ -245,24 +357,39 @@ export async function readAgentMapping(devflowDir, opts) {
             continue;
         const raw = entry;
         const mapping = {};
+        // D-WORKER-AGENTS: a worker key is held to the worker value domain on read,
+        // by the same function the CLI write boundary uses.
+        const worker = isWorkerAgent(name);
         if (typeof raw.model === 'string') {
             // Tighten to the same charset used by rewriteAgentFrontmatter.
             // The effort field is enum-validated below; model must be equally strict.
             // An invalid entry is dropped with a warning rather than silently
             // persisting and permanently poisoning that agent on every reapply.
-            if (isValidModelName(raw.model)) {
-                mapping.model = raw.model;
+            if (!isValidModelName(raw.model)) {
+                warn(`agent-models: invalid-model name for agent "${name}" — dropping entry`);
             }
             else {
-                warn(`agent-models: invalid-model name for agent "${name}" — dropping entry`);
+                const workerCheck = worker ? validateWorkerValue('model', raw.model) : undefined;
+                if (workerCheck !== undefined && !workerCheck.ok) {
+                    warn(`agent-models: dropping out-of-domain model "${raw.model}" for worker "${name}" — ${workerCheck.error}`);
+                }
+                else {
+                    mapping.model = raw.model;
+                }
             }
         }
         if (typeof raw.effort === 'string') {
-            if (EFFORT_LEVELS_SET.has(raw.effort)) {
-                // Sound narrowing: has() proved membership; EffortLevel is a literal
-                // subtype of string so the assertion is not a compensating cast.
+            // `inherit` is a stored agent value; a worker has no session effort to
+            // inherit, so for a worker it is out of domain like any other non-level.
+            if (isEffortLevel(raw.effort)) {
                 mapping.effort = raw.effort;
             }
+            else if (raw.effort === EFFORT_INHERIT && !worker) {
+                mapping.effort = raw.effort;
+            }
+            else if (worker) {
+                warn(`agent-models: dropping out-of-domain effort "${raw.effort}" for worker "${name}"`);
+            }
             else {
                 warn(`agent-models: dropping invalid effort "${raw.effort}" for agent "${name}"`);
             }
@@ -288,7 +415,7 @@ export async function readAgentMapping(devflowDir, opts) {
  * A missing directory returns an empty set rather than throwing (ENOENT is
  * not an error — the install dir may not exist on a fresh machine before
  * `devflow init` runs). Any other OS error also returns an empty set
- * (degrade-not-throw per PF-009) — a transient or misconfigured path must
+ * (degrade-not-throw) — a transient or misconfigured path must
  * not prevent the TUI or --list from starting.
  *
  * @param installDir - Path to ~/.claude/agents/devflow (or equivalent).
@@ -330,41 +457,49 @@ export async function saveAgentMapping(devflowDir, mapping) {
  *   isDormantExternalModel) AND proxyEnabled is false → the entry is DORMANT.
  *   The shipped default model is used instead. The entry remains saved.
  *
- * Effort is ALWAYS applied regardless of proxy state.
+ * D-SHIPPED-EFFORT — effort rule, in order:
+ *   1. a mapping effort level wins;
+ *   2. a mapping `inherit` yields no effort line and does NOT fall back to the
+ *      shipped effort;
+ *   3. an absent mapping effort falls back to the shipped effort, which is
+ *      undefined when the agent ships none.
+ *   Effort is ALWAYS applied regardless of proxy state, a dormant external
+ *   model included.
  *
  * Pure function — no I/O.
  *
  * @param agentName - The agent's short name (e.g., 'code').
  * @param mapping - The full mapping file.
- * @param shippedDefaults - Map of agent name → shipped default model.
+ * @param shippedDefaults - Map of agent name → shipped model and effort.
  * @param proxyEnabled - Whether the Devflow proxy is currently active.
  */
 export function resolveEffective(agentName, mapping, shippedDefaults, proxyEnabled) {
     const entry = mapping.agents[agentName];
+    const shipped = shippedDefaults[agentName];
     let model;
     if (entry?.model !== undefined) {
         // Dormant: external model configured but proxy is off → fall back to shipped default.
         model = isDormantExternalModel(entry.model, proxyEnabled)
-            ? shippedDefaults[agentName]
+            ? shipped?.model
             : entry.model;
     }
     else {
         // No mapping entry → use shipped default.
-        model = shippedDefaults[agentName];
+        model = shipped?.model;
     }
-    const effort = entry?.effort;
+    const mapped = entry?.effort;
+    const effort = mapped === EFFORT_INHERIT ? undefined : (mapped ?? shipped?.effort);
     return { model, effort };
 }
-// ---------------------------------------------------------------------------
-// loadShippedDefaults
-// ---------------------------------------------------------------------------
 /**
- * Parse the shipped model default out of every {name}.md in one directory.
+ * Parse the shipped model and effort out of every {name}.md in one directory.
  *
  * A missing or unreadable directory yields an empty map — dist/agents/ does not
  * exist until a generator host does, and a source tree that produced no agents
  * is caught by the registry-completeness guard rather than by a throw here.
- * Unknown or malformed files are skipped individually.
+ * Unknown or malformed files are skipped individually. The effort is returned as
+ * written: only the directory that wins the merge has its effort validated, so a
+ * typo in a losing file is never reported.
  */
 async function readDirDefaults(dir) {
     let entries;
@@ -380,9 +515,10 @@ async function readDirDefaults(dir) {
             return null;
         try {
             const content = await fs.readFile(path.join(dir, file), 'utf-8');
-            const result = readFrontmatterModel(content);
-            if (result.ok && result.value) {
-                return [agentName, result.value];
+            const model = readFrontmatterModel(content);
+            const effort = readFrontmatterEffort(content);
+            if (model.ok && model.value && effort.ok) {
+                return [agentName, { model: model.value, effort: effort.value }];
             }
         }
         catch {
@@ -399,11 +535,22 @@ async function readDirDefaults(dir) {
     return defaults;
 }
 /**
- * Load shipped default models from the agent files.
+ * Load the shipped default model and effort of every agent from the agent files.
+ *
+ * D-SHIPPED-EFFORT: this is the only production reader of shipped model and
+ * effort values. An agent's effort is part of its shipped default, so a reapply
+ * that did not see it would strip it (the mapping has no entry to say
+ * otherwise).
  *
  * Directories are MOST-PREFERRED FIRST — the convention owned by
  * agentSourceDirs() — and the first directory to supply a name wins, so once an
  * agent is generated into dist/agents/ its frontmatter is the shipped default.
+ * First-hit-wins applies to the whole record: an agent's effort is never read
+ * from a different file than its model.
+ *
+ * A shipped `effort:` outside EFFORT_LEVELS (`inherit` included — it is a
+ * mapping value, not a shipped one) is dropped with a warning naming the agent;
+ * its model survives.
  *
  * A registry agent that no directory supplies is reported through `onWarning`
  * as ONE aggregate message naming every missing agent and the build step. The
@@ -411,23 +558,37 @@ async function readDirDefaults(dir) {
  * keep rendering (`devflow agents --list`), so it warns instead. Staying silent
  * is what makes the gap dangerous: resolveEffective returns an undefined model,
  * reapplyAgentMapping buckets the agent 'unchanged', and disabling the proxy
- * leaves an externally-pinned agent unreverted with nothing said (PF-022).
+ * leaves an externally-pinned agent unreverted with nothing said.
  *
  * @param dirs - Agent directories, most-preferred first. Injectable so tests can
  *   prove the precedence against a temp tree; all real callers use the default.
  * @param opts - Optional warning channel; the gap is silent without one.
  */
-export async function loadShippedDefaults(dirs = agentSourceDirs(), opts) {
+export async function loadShippedAgentDefaults(dirs = agentSourceDirs(), opts) {
     const perDir = await Promise.all(dirs.map(readDirDefaults));
-    const defaults = {};
+    const winners = {};
     for (const dirDefaults of perDir) {
-        for (const [agentName, model] of Object.entries(dirDefaults)) {
-            if (!(agentName in defaults)) {
-                defaults[agentName] = model;
+        for (const [agentName, raw] of Object.entries(dirDefaults)) {
+            if (!Object.hasOwn(winners, agentName)) {
+                winners[agentName] = raw;
             }
         }
     }
-    const missing = getAllAgentNames().filter(name => !(name in defaults));
+    const defaults = {};
+    for (const [agentName, raw] of Object.entries(winners)) {
+        if (raw.effort === '') {
+            defaults[agentName] = { model: raw.model };
+        }
+        else if (isEffortLevel(raw.effort)) {
+            defaults[agentName] = { model: raw.model, effort: raw.effort };
+        }
+        else {
+            defaults[agentName] = { model: raw.model };
+            opts?.onWarning?.(`Shipped agent "${agentName}" declares effort "${raw.effort}", which is not one of ` +
+                `${EFFORT_LEVELS.join(', ')} — ignoring it.`);
+        }
+    }
+    const missing = getAllAgentNames().filter(name => !Object.hasOwn(defaults, name));
     if (missing.length > 0) {
         opts?.onWarning?.(`No shipped default found for declared agent(s): ${missing.join(', ')}. ` +
             `Run \`npm run build:mds\` if they are compiled from .mds generator hosts, otherwise ` +
@@ -439,10 +600,11 @@ export async function loadShippedDefaults(dirs = agentSourceDirs(), opts) {
  * Idempotent convergence function: walk every installed agent file and
  * rewrite frontmatter model/effort to match the effective mapping.
  *
- * - Reads shipped defaults LIVE from the agent sources — agentSourceDirs(),
- *   dist/agents/ preferred over src/assets/agents/. An agent no source supplies
- *   is reported through the warning channel rather than passing as 'unchanged'
- *   with no explanation.
+ * - Reads shipped defaults (model AND effort) LIVE from the agent sources —
+ *   agentSourceDirs(), dist/agents/ preferred over src/assets/agents/. An agent
+ *   no source supplies is reported through the warning channel rather than
+ *   passing as 'unchanged' with no explanation. D-SHIPPED-EFFORT: an agent that
+ *   ships an effort keeps it across a reapply unless its mapping says otherwise.
  * - Gets the agent name list from the registry (getAllAgentNames()) plus
  *   any mapping entries for agents not in the registry.
  * - Missing installed files → skip silently (recorded in skippedMissing).
@@ -461,11 +623,11 @@ export async function reapplyAgentMapping(opts) {
         return { updated: [], unchanged: [], skippedMissing: [], invalidMapping: [], warnings };
     }
     const mapping = mappingResult.value;
-    const shippedDefaults = await loadShippedDefaults(opts.agentSourceDirs, { onWarning: warn });
+    const shippedDefaults = await loadShippedAgentDefaults(opts.agentSourceDirs, { onWarning: warn });
     // Build the union of: all registered agent names + all names in the mapping
     // (so agents not yet in the registry but configured are also processed).
     const registryNames = new Set(getAllAgentNames());
-    const mappingNames = new Set(Object.keys(mapping.agents));
+    const mappingNames = new Set(Object.keys(agentOnlyMapping(mapping)));
     const allNames = new Set([...registryNames, ...mappingNames]);
     // Stable iteration order — Set preserves insertion order, array fixes it for the map.
     const allNamesList = [...allNames];
@@ -480,7 +642,7 @@ export async function reapplyAgentMapping(opts) {
         // Guard: reject mapping keys that would read/write outside the install directory.
         // A corrupted or adversarial agent-models.json could contain path-traversal keys
         // such as '../../etc/passwd'; this check prevents any filesystem access beyond
-        // opts.installDir. Per PF-009 (degrade-not-throw), this emits a warning and skips gracefully.
+        // opts.installDir. Degrade-not-throw: this emits a warning and skips gracefully.
         if (!isContainedIn(opts.installDir, mdFileName(agentName))) {
             localWarn(`reapplyAgentMapping: agent name "${agentName}" resolves outside the install ` +
                 `directory — skipped (containment guard)`);
@@ -589,7 +751,7 @@ export async function revertExternalAgents(opts) {
  */
 export function countExternalMappedAgents(mapping) {
     let count = 0;
-    for (const entry of Object.values(mapping.agents)) {
+    for (const entry of Object.values(agentOnlyMapping(mapping))) {
         if (isDormantExternalModel(entry.model, false)) {
             count++;
         }

package/dist/core/agent-state.js

@@ -1,11 +1,11 @@
 /**
- * Agent installation-state classification.
+ * Agent row vocabulary shared by `devflow agents --list` and the TUI.
  *
- * Single source of truth for the STATE column shared by `--list` and the TUI.
- * Centralised here (core layer) per ADR-013 so neither cli/commands nor
- * cli/agents-view owns the vocabulary.
+ * Single source of truth for the STATE column and the EFFORT cell, so neither
+ * surface can drift from the other. Centralised here (core layer) so neither
+ * cli/commands nor cli/agents-view owns the vocabulary.
  *
- * applies ADR-013: pure core-layer module, no CLI-adapter concerns.
+ * Pure core-layer module, no CLI-adapter concerns.
  */
 import { isDormantExternalModel } from './external-models.js';
 // ---------------------------------------------------------------------------
@@ -22,13 +22,35 @@ export const AGENT_STATE_LABELS = {
     'saved-inactive': 'saved-inactive',
     'not-installed': 'not installed',
     'unknown': 'unknown',
+    'worker': 'worker',
 };
+// ---------------------------------------------------------------------------
+// formatEffortDisplay
+// ---------------------------------------------------------------------------
+/**
+ * The text of an EFFORT cell, shared by `--list` and the TUI.
+ *
+ * D-SHIPPED-EFFORT: a configured level or `inherit` is shown as is. An
+ * unconfigured row shows `default (<shipped effort>)` when the shipped source
+ * carries an effort — the same `default (shippedDefault)` convention the MODEL
+ * cell uses — and plain `default` when it carries none.
+ *
+ * Pure function, no I/O.
+ *
+ * @param configured - The row's effort: a level, `inherit`, or `default` when unset.
+ * @param shippedEffort - The effort the shipped source carries, if any.
+ */
+export function formatEffortDisplay(configured, shippedEffort) {
+    if (configured !== 'default')
+        return configured;
+    return shippedEffort === undefined ? 'default' : `default (${shippedEffort})`;
+}
 /**
  * Classify an agent row's install state.
  *
  * Single source of truth shared by `--list` and the TUI so the two surfaces
  * cannot drift. The four-way result drives the STATE column in render.ts and
- * the STATE column in --list output.
+ * the STATE column in --list output. Worker rows never come through here.
  *
  * Pure function, no I/O.
  */

package/dist/core/ansi.js

@@ -6,9 +6,9 @@
  * feature module (src/hud/). Re-exported verbatim from src/hud/colors.ts
  * so all existing HUD call sites remain untouched.
  *
- * applies ADR-013: src/core/ = agent-neutral logic; ANSI primitives have no
+ * src/core/ = agent-neutral logic; ANSI primitives have no
  * feature coupling and belong here, not in a feature module.
- * applies PF-017 corollary: one shared definition over per-consumer copies.
+ * One shared definition over per-consumer copies.
  */
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;

package/dist/core/assets.js

@@ -75,7 +75,7 @@ export function compiledSkillRefsDir(root = getPackageRoot()) {
  * The single owner of the dist-first agent-resolution policy: a generator
  * host's compiled artifact in dist/agents/ supersedes a hand-authored file of
  * the same name in src/assets/agents/. Every consumer reads the order from
- * here — the installer's first-hit-wins resolve, loadShippedDefaults's
+ * here — the installer's first-hit-wins resolve, loadShippedAgentDefaults's
  * first-wins merge, and the test harness's resolveAgentSource — so the
  * convention is stated once and cannot drift apart between call sites.
  *

package/dist/core/cache.js

@@ -15,8 +15,9 @@
  *   path.join()'s normalization of ".." components. safeEntryPath() enforces
  *   containment and returns null on violation; all callers treat null as a miss.
  *
- * applies ADR-013: core-layer module, no Claude Code adapter concerns.
- * avoids PF-011: entries written via tmp→rename (writeFileAtomicExclusive).
+ * Core-layer module, no Claude Code adapter concerns.
+ * Entries are written via tmp→rename (writeFileAtomicExclusive), so a reader
+ * sees the old entry or the new one, never a missing or partial file.
  */
 import * as fs from 'node:fs';
 import { promises as fsAsync } from 'node:fs';
@@ -38,9 +39,9 @@ export const MAX_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 // All callers that write or read the model-discovery catalog AND the uninstall
 // removal target derive their directory paths from these functions. Keeping
 // write-site and removal-site in the same module prevents silent orphaning of
-// cache data on future relocations (avoids PF-013).
+// cache data on future relocations.
 //
-// applies ADR-013: path layout owned by the core module, not scattered across
+// Path layout owned by the core module, not scattered across
 // callers in src/cli/ or src/hud/.
 /**
  * Returns the model-discovery cache directory for the given devflowDir.
@@ -137,8 +138,6 @@ export function readCache(cacheDir, key, validate) {
  * The single canonical envelope parser — used by readCacheEntry (which adds
  * the expiry check on top) and exported for model-discovery.ts (stale-fallback
  * and prune sorters) so all callers share one parser and cannot drift.
- *
- * applies ADR-003: eliminated private parseEnvelope duplicate; one parser, one truth.
  */
 export function parseRawEnvelope(raw) {
     let parsed;
@@ -166,7 +165,7 @@ export function parseRawEnvelope(raw) {
  * Write a value to cache with a TTL in milliseconds.
  *
  * - Creates cacheDir at mode 0700 if absent (owner-only access).
- * - Writes the entry via atomic tmp→rename (avoids PF-011 delete-then-write window).
+ * - Writes the entry via atomic tmp→rename (no delete-then-write window).
  * - Hardens the entry to 0600 after the write (owner-only read/write for cache data
  *   that will feed agent frontmatter in later phases).
  * - TTL is clamped to MAX_TTL_MS before storage.
@@ -196,7 +195,7 @@ export async function writeCache(cacheDir, key, data, ttlMs) {
     }
     // Harden entry to 0600 after the atomic write. writeFileAtomicExclusive
     // preserves the existing mode on re-writes; this chmod bootstraps 0600 on
-    // the first write to a fresh entry. Best-effort, non-fatal (avoids PF-009).
+    // the first write to a fresh entry. Best-effort, non-fatal.
     try {
         await fsAsync.chmod(filePath, 0o600);
     }

package/dist/core/codex-auth-inspect.js

@@ -1,8 +1,8 @@
 /**
  * Codex credential-file inspection for `devflow proxy --status`.
  *
- * applies ADR-013: pure core-layer module — no Claude Code adapter concerns and
- *   no presentation (colour/format lives with the other CLI formatters).
+ * Pure core-layer module — no Claude Code adapter concerns and
+ * no presentation (colour/format lives with the other CLI formatters).
  *
  * WHY THIS EXISTS RATHER THAN IMPORTING THE ROUTING RUNTIME
  * The routing runtime validates this same file and exposes an equivalent
@@ -62,8 +62,8 @@ function jwtAccountId(token) {
 /**
  * Classify an I/O error from reading ~/.codex/auth.json into a CodexAuthState.
  *
- * applies ADR-013: pure classification logic belongs in src/core/, not in the
- *   CLI presentation layer that calls it.
+ * Pure classification logic belongs in src/core/, not in the
+ * CLI presentation layer that calls it.
  *
  * ENOENT is the ordinary "not signed in" case: the file has never been written
  * by `codex login`. Every other error (EACCES, EISDIR, EMFILE, …) is a real

package/dist/core/compliance-compose.js

@@ -5,8 +5,8 @@
  * fragment files, so installed artifacts differ by selection rather than being
  * static all-six blobs.
  *
- * Applies ADR-013: pure helpers in src/core/, no I/O.
- * Applies PF-009: warn-not-throw for per-item failures.
+ * Pure helpers in src/core/, no I/O.
+ * Warn-not-throw for per-item failures.
  */
 import { COMPLIANCE_FRAMEWORKS, stampComplianceRule } from './compliance.js';
 // ── Constants ──────────────────────────────────────────────────────────────────
@@ -278,7 +278,7 @@ function buildReferences(activeFrameworks, fragments) {
  * Strict boundary parser: validates all required sections (## Mapping / ##
  * Reference / ## Checklist / ## Rule) and their structural constraints.
  * CRLF-tolerant: Windows line endings are normalised before parsing.
- * Never throws (PF-009): all errors return { ok: false, error }.
+ * Never throws: all errors return { ok: false, error }.
  */
 export function parseComplianceFragment(id, raw) {
     // CRLF tolerance

package/dist/core/compliance.js

@@ -2,7 +2,7 @@
  * Core compliance framework registry and utilities.
  *
  * Pure module — no I/O, no side effects.
- * Applies ADR-013: pure helpers in src/core/, I/O orchestration in src/targets/.
+ * Pure helpers in src/core/, I/O orchestration in src/targets/.
  */
 /**
  * Canonical compliance framework registry.
@@ -26,7 +26,7 @@ export const COMPLIANCE_RULE_PLACEHOLDER = '${DEVFLOW_COMPLIANCE_FRAMEWORKS}';
  *   detection.md — generic detection heuristics
  *   sources.md   — authoritative source index
  *
- * Exported (ADR-013: pure constant in src/core/) so both compliance-install.ts
+ * Exported (pure constant in src/core/) so both compliance-install.ts
  * (install) and compliance.ts CLI (status/drift detection) share a single
  * definition. Adding a third always-present ref requires only one change here.
  */
@@ -60,7 +60,7 @@ function normalizeId(s) {
  * This is the trust boundary for framework IDs that did not come through
  * `parseFrameworkList` — most importantly `manifest.features.compliance.frameworks`,
  * which `normalizeComplianceFeature` only type-checks (it cannot reject unknown IDs
- * without violating the ADR-014 self-heal contract). Every framework ID that is about
+ * without violating the self-heal contract). Every framework ID that is about
  * to become an fs path segment or be written into an installed artifact must pass
  * through here first (AC-35, AC-36).
  *
@@ -111,7 +111,6 @@ export function parseFrameworkList(input) {
  *
  * Absent, null, malformed, or partially-valid → {enabled:false, frameworks:[]}.
  * Preserves valid {enabled: boolean, frameworks: string[]}.
- * (Applies ADR-014 self-heal idiom)
  */
 export function normalizeComplianceFeature(raw) {
     const DEFAULT = { enabled: false, frameworks: [] };