devflow-kit 3.0.1 → 3.2.0

package/dist/core/evidence-policy.js

@@ -3,7 +3,7 @@
  * `resolve-evidence-policy.cjs`, never a second implementation of it.
  *
  * D-POLICY-CJS-SEAM: the resolver is plain CommonJS under src/assets/scripts/,
- * outside every tsconfig (PF-043, PF-069), so the interfaces below are
+ * outside every tsconfig, so the interfaces below are
  * TRANSCRIBED from its JSDoc typedefs and are the only shape authority on this
  * side — open those typedefs before changing anything here. The module is loaded
  * with `require()` from `scriptsDir()`, which resolves under the package root both
@@ -20,7 +20,7 @@
  * `lib/project-config.cjs` (loadProjectConfigLib), so the CLI judges a config
  * file's bytes exactly as the resolvers do.
  *
- * D-POLICY-NO-WRITE (applies ADR-024): `.devflow/project.json` is team-owned, and
+ * D-POLICY-NO-WRITE: `.devflow/project.json` is team-owned, and
  * devflow never writes or replaces a shared file it cannot prove it wrote. This
  * module therefore imports no fs API; the CLI only PRINTS the bytes a team may
  * choose to commit (`evidencePolicySuggestion`, and the migration lines of
@@ -101,23 +101,24 @@ function surfaceMismatches(value, surface) {
  * require() one package script and shape-check it against `surface`. Never
  * throws: a missing file is `not-found`; a module that throws on load or lacks a
  * surface key is `unusable`. The caller's type parameter is justified by the
- * surface check, which `satisfies` ties to the interface's keys.
+ * surface check, which `satisfies` ties to the interface's keys. Exported for
+ * src/core/learning-store.ts, which loads the learning store the same way.
  */
-function loadScript(file, surface) {
+export function loadScript(scriptPath, surface) {
     let loaded;
     try {
-        loaded = createRequire(import.meta.url)(file);
+        loaded = createRequire(import.meta.url)(scriptPath);
     }
     catch (err) {
         const code = err.code;
         if (code === 'MODULE_NOT_FOUND')
-            return { ok: false, error: { kind: 'not-found', path: file } };
+            return { ok: false, error: { kind: 'not-found', path: scriptPath } };
         const detail = err instanceof Error ? err.message : String(err);
-        return { ok: false, error: { kind: 'unusable', path: file, detail } };
+        return { ok: false, error: { kind: 'unusable', path: scriptPath, detail } };
     }
     const mismatches = surfaceMismatches(loaded, surface);
     if (mismatches.length > 0) {
-        return { ok: false, error: { kind: 'unusable', path: file, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
+        return { ok: false, error: { kind: 'unusable', path: scriptPath, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
     }
     return { ok: true, value: loaded };
 }
@@ -167,10 +168,10 @@ export function formatEvidencePolicyUnavailable(error) {
 /**
  * The `compliance --status` line: the resolved policy for `opts.dir`, or the
  * unavailable line when the loader failed — that line is the whole handling
- * (ADR-028). The caller passes the compliance state it already read, so the
- * manifest is never read twice. `resolve()` makes at most three `gh` calls and
- * bounds every subprocess with a timeout, so an offline machine degrades to a
- * flagged result rather than a hang.
+ * (only a damaged package fails the load). The caller passes the compliance
+ * state it already read, so the manifest is never read twice. `resolve()` makes
+ * at most three `gh` calls and bounds every subprocess with a timeout, so an
+ * offline machine degrades to a flagged result rather than a hang.
  */
 export function evidencePolicyStatusLine(loaded, opts) {
     if (!loaded.ok)
@@ -198,7 +199,7 @@ function suggestedFrameworks(complianceState) {
  * count); `null` otherwise. The bytes come
  * from the settings resolver's `serializeProjectSuggestion`, which returns them
  * only when they read back through the shared parser as exactly what was asked.
- * Nothing is written (D-POLICY-NO-WRITE, applies ADR-024).
+ * Nothing is written (D-POLICY-NO-WRITE).
  */
 export function evidencePolicySuggestion(complianceState, policy, settings) {
     if (policy.complianceDefault(complianceState) !== 'required')

package/dist/core/external-models.js

@@ -9,7 +9,7 @@
  * in src/core/model-discovery.ts. The TUI picker and --set validation use the
  * ExternalModelCatalog returned by those functions.
  *
- * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
+ * Pure core-layer module, no Claude Code adapter concerns.
  *
  * NOTE: the internal routing runtime package name must NEVER appear in
  * user-visible strings, CLI output, or error messages. User-facing vocabulary:

package/dist/core/feature-config.js

@@ -1,5 +1,6 @@
 import * as path from 'path';
 import { promises as fs } from 'fs';
+import { firstSymbolicLink } from './linked-path.js';
 import { getFeatureConfigPath } from './project-paths.js';
 import { parseTrackerId } from './tracker.js';
 import { loadProjectConfigLib } from './evidence-policy.js';
@@ -14,7 +15,7 @@ import { loadProjectConfigLib } from './evidence-policy.js';
  * carrying it would leave a `learning: false` in the file that no longer does
  * what it says. `decisions` is the pre-rename spelling of `learning`;
  * `autoCommit` is inert. `features` is deliberately NOT here — it is a live key,
- * carried like any other unmanaged key (avoids PF-071).
+ * carried like any other unmanaged key.
  */
 const RETIRED_CONFIG_KEYS = new Set([
     'memory', 'learning', 'knowledge', 'decisions', 'autoCommit',
@@ -77,7 +78,7 @@ function coerceConfig(parsed) {
     if (!isJsonObject(parsed))
         return null;
     const p = parsed;
-    // Coerce reviewPublication: any invalid or absent value → 'auto' (self-heal, ADR-014 idiom).
+    // Coerce reviewPublication: any invalid or absent value → 'auto' (self-heal).
     const rp = p.reviewPublication;
     const reviewPublication = rp === 'auto' || rp === 'full' || rp === 'off' ? rp : 'auto';
     // The per-repo tracker override is carried through VERBATIM — never coerced,
@@ -169,23 +170,70 @@ async function readConfigBody(projectRoot, lib = loadProjectConfigLib()) {
     }
     return classifyConfigBytes(read.bytes, lib.value);
 }
+/** A thrown value's message, or the value itself when it is not an Error. */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /**
- * Serialise a config body to a project's config file.
+ * Serialise a config body to a project's config file. Never throws.
  * Creates the .devflow/ directory if missing.
  * Uses an atomic temp+rename pattern to prevent partial reads under concurrent writes.
+ * The copy is created only where nothing stands ('wx'), so an entry a repository
+ * planted at its name — a symbolic link among them — is never written through
+ * (D-CLI-NO-SYMLINK) and, not being this run's, is left where it is; the write then
+ * fails and the Result says so. Once this run has created the copy, a write, close or
+ * rename that fails removes it again, so a failed write leaves nothing beside the
+ * config; the Result names the failure, and the copy too when it could not be removed.
  */
 async function writeConfigBody(projectRoot, body) {
     const configPath = getFeatureConfigPath(projectRoot);
-    await fs.mkdir(path.join(projectRoot, '.devflow'), { recursive: true });
     const tmpPath = configPath + '.tmp.' + process.pid;
-    await fs.writeFile(tmpPath, JSON.stringify(body, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
-    await fs.rename(tmpPath, configPath);
+    let text;
+    let copy;
+    try {
+        text = JSON.stringify(body, null, 2) + '\n';
+        await fs.mkdir(path.join(projectRoot, '.devflow'), { recursive: true });
+        copy = await fs.open(tmpPath, 'wx', 0o600);
+    }
+    catch (err) {
+        return { ok: false, detail: messageOf(err) };
+    }
+    try {
+        try {
+            // The open handle is fs.writeFile's destination and the text its data: the same
+            // write as copy.writeFile(text), in the form a path-traversal scan reads right,
+            // since it takes a writeFile's first argument for a path.
+            await fs.writeFile(copy, text, 'utf-8');
+        }
+        finally {
+            await copy.close();
+        }
+        await fs.rename(tmpPath, configPath);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, detail: await removeCopy(tmpPath, messageOf(err)) };
+    }
+}
+/**
+ * Remove the copy a failed config write created, and say why the write failed:
+ * `detail`, followed by the removal's own failure when the copy stays. A copy that
+ * is already gone counts as removed (`force`).
+ */
+async function removeCopy(tmpPath, detail) {
+    try {
+        await fs.rm(tmpPath, { force: true });
+        return detail;
+    }
+    catch (err) {
+        return `${detail}; its copy ${tmpPath} could not be removed: ${messageOf(err)}`;
+    }
 }
 /**
  * Merge devflow's managed keys over the config body the file already holds.
  * Pure — returns a new object and never mutates `existing`.
  *
- * D-CONFIG-PRESERVE-UNMANAGED (avoids PF-071): `.devflow/config.json` is a
+ * D-CONFIG-PRESERVE-UNMANAGED: `.devflow/config.json` is a
  * user-editable file that devflow only PARTLY owns. The managed keys come from
  * `managed`; every other key comes from the file, verbatim and by key presence
  * — the hand-written per-repo `tracker` override (whose invalid values must
@@ -227,21 +275,31 @@ export function mergeManagedConfig(existing, managed) {
  * change. Acceptable because init is a single-threaded, user-initiated command
  * and the window is milliseconds on a local filesystem; the file swap itself is
  * atomic (temp + rename), so a reader never sees a partial file.
+ *
+ * D-CLI-NO-SYMLINK (firstSymbolicLink): a `.devflow` that is a symbolic link is
+ * left alone, and the Result says so; the file is neither read nor written there.
  */
 export async function writeManagedConfig(projectRoot, managed, lib = loadProjectConfigLib()) {
     const configPath = getFeatureConfigPath(projectRoot);
+    let linked;
+    try {
+        linked = await firstSymbolicLink([path.dirname(configPath)]);
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'unreadable', path: configPath, detail: messageOf(err) } };
+    }
+    if (linked !== null) {
+        return { ok: false, error: { kind: 'unreadable', path: configPath, detail: `${linked} is a symbolic link, and devflow writes nothing through one` } };
+    }
     const existing = await readConfigBody(projectRoot, lib);
     if (existing.kind === 'malformed')
         return { ok: false, error: { kind: 'malformed', path: configPath } };
     if (existing.kind === 'unreadable') {
         return { ok: false, error: { kind: 'unreadable', path: configPath, detail: existing.detail } };
     }
-    try {
-        await writeConfigBody(projectRoot, mergeManagedConfig(objectOf(existing), managed));
-    }
-    catch (err) {
-        return { ok: false, error: { kind: 'write-failed', path: configPath, detail: err instanceof Error ? err.message : String(err) } };
-    }
+    const written = await writeConfigBody(projectRoot, mergeManagedConfig(objectOf(existing), managed));
+    if (!written.ok)
+        return { ok: false, error: { kind: 'write-failed', path: configPath, detail: written.detail } };
     return { ok: true };
 }
 /**

package/dist/core/feature-switch.js

@@ -6,7 +6,7 @@ function isJsonObject(value) {
 }
 /**
  * The pre-rename key each machine feature was stored under, where one exists:
- * `learning` was `decisions` (ADR-011) and `knowledge` was `kb`. A manifest no
+ * `learning` was `decisions` and `knowledge` was `kb`. A manifest no
  * command has rewritten since the rename can still hold only the legacy key.
  * `memory` was never renamed.
  */
@@ -19,7 +19,7 @@ const LEGACY_KEYS = {
  *
  * Only an explicit boolean `false` switches a feature off. A missing key, a
  * non-boolean value, or anything that is not a manifest-shaped object reads as
- * ON — fail-open (ADR-028), and the exact rule `queue_read_gates` applies in the
+ * ON — fail-open, and the exact rule `queue_read_gates` applies in the
  * shell hooks, so the CLI's status and the runtime never disagree about the
  * same file.
  *
@@ -37,7 +37,7 @@ const LEGACY_KEYS = {
  * precedence exactly, so `devflow knowledge --status` reports a `kb: false`
  * as disabled. queue_read_gates never reads knowledge, so there is no shell
  * mirror. The knowledge write-back prose gate deliberately does not learn the
- * legacy key (ADR-028: no prompt text for a state only an un-upgraded install
+ * legacy key (no prompt text for a state only an un-upgraded install
  * can hold); readManifest rewrites `kb` to `knowledge` on the next CLI run
  * that loads the manifest, after which that gate reads the healed key.
  *

package/dist/core/flags.js

@@ -7,7 +7,7 @@
  * D14: Typed registry — flags carry kind (boolean|enum|number|string), target
  * (env|setting), and per-kind defaultValue. Neutral values delete their target
  * key; active values write the appropriate payload. Number 0 is ACTIVE. Sink
- * validation via coerceFlagValue (applies PF-023: validate at the convergence
+ * validation via coerceFlagValue (validate at the convergence
  * point every caller reaches). applyFlags(settingsJson, FlagsRecord) is the
  * sole API; init.ts works directly with FlagsRecord (no legacy string[] bridge).
  */
@@ -139,7 +139,7 @@ export const FLAG_REGISTRY = [
     {
         // Devflow fan-outs routinely exceed the upstream default of 20.
         // Set to 40 by default so parallel Code/Review/Research waves don't
-        // silently queue. upstreamDefault recorded for display. (applies PF-023 bounds)
+        // silently queue. upstreamDefault recorded for display.
         id: 'max-concurrent-subagents',
         label: 'Max concurrent subagents',
         description: 'Maximum number of subagents Claude Code will spawn concurrently',
@@ -150,7 +150,7 @@ export const FLAG_REGISTRY = [
         recommended: true,
         defaultValue: 40,
         min: 1,
-        max: 100, // devflow sanity bound (applies PF-023)
+        max: 100, // devflow sanity bound
         integer: true,
         upstreamDefault: 20,
     },
@@ -341,7 +341,7 @@ export const FLAG_REGISTRY = [
     // ── Valued flags (number/enum/string) ────────────────────────────────────
     {
         // Domain: unset by default; set only when users want a non-default spawn depth.
-        // upstreamDefault: 3 (recorded for display). PF-023 bounds: max 10.
+        // upstreamDefault: 3 (recorded for display). Sanity bound: max 10.
         id: 'subagent-spawn-depth',
         label: 'Max subagent spawn depth',
         description: 'Maximum depth of nested subagent spawning',
@@ -352,7 +352,7 @@ export const FLAG_REGISTRY = [
         recommended: false,
         defaultValue: undefined,
         min: 1,
-        max: 10, // devflow sanity bound (applies PF-023)
+        max: 10, // devflow sanity bound
         integer: true,
         upstreamDefault: 3,
     },
@@ -384,7 +384,7 @@ export const FLAG_REGISTRY = [
     },
     {
         // Upstream default: 30 min. 0 = disabled (still ACTIVE — written to env).
-        // PF-023 bounds: max 1440 (24h). min 0 (0 = off, explicit value not neutral).
+        // Sanity bounds: max 1440 (24h). min 0 (0 = off, explicit value not neutral).
         id: 'goal-checkin-minutes',
         label: 'Goal check-in interval',
         description: 'Interval in minutes for Claude to check in on task goals',
@@ -395,10 +395,34 @@ export const FLAG_REGISTRY = [
         recommended: false,
         defaultValue: undefined,
         min: 0, // 0 = off (ACTIVE, not neutral — written as "0")
-        max: 1440, // devflow sanity bound: 24 hours (applies PF-023)
+        max: 1440, // devflow sanity bound: 24 hours
         integer: true,
         upstreamDefault: 30,
     },
+    {
+        // D-FOREGROUND-RUN: every agent runs builds and tests in the foreground under an explicit
+        // Bash `timeout` whose ceiling is Claude Code's 600000 ms, or this variable when set. A
+        // suite that cannot be split under that ceiling is reported BLOCKED with the remedy
+        // `devflow flags --set bash-max-timeout-ms=<ms>`, so this flag is that remedy.
+        // The env name was confirmed against Claude Code 2.1.294 (docs/reference/claude-code-flags-probe.md):
+        // the binary reads BASH_MAX_TIMEOUT_MS, ignores a non-positive or NaN value, and takes the
+        // larger of it and the default timeout. Neutral by default (undefined → manifest null →
+        // key deleted). min 600000 = upstream default, so the flag only ever raises the ceiling;
+        // max 7200000 (2 h) is the devflow sanity bound.
+        id: 'bash-max-timeout-ms',
+        label: 'Bash max timeout',
+        description: 'Ceiling in milliseconds for a foreground Bash command timeout',
+        hint: 'Raises the Bash timeout ceiling past 600000 ms for long-running suites',
+        blurb: 'Bash timeout ceiling',
+        kind: 'number',
+        target: { type: 'env', key: 'BASH_MAX_TIMEOUT_MS' },
+        recommended: false,
+        defaultValue: undefined,
+        min: 600000, // upstream default ceiling: lower values would only shrink it
+        max: 7200000, // devflow sanity bound: 2 hours
+        integer: true,
+        upstreamDefault: 600000,
+    },
     {
         // Writes as { command: value } per Claude Code spellcheck setting shape.
         id: 'spellcheck',
@@ -411,7 +435,7 @@ export const FLAG_REGISTRY = [
         recommended: false,
         defaultValue: undefined,
         wrapKey: 'command',
-        maxLength: 256, // devflow sanity bound (applies PF-023)
+        maxLength: 256, // devflow sanity bound
     },
     {
         // view-mode folded into the registry; neutralValue 'default' deletes the viewMode key.
@@ -474,7 +498,7 @@ export function isNeutral(flag, value) {
 /**
  * Map a record value to a TUI value.
  *
- * viewMode GLUE RULE (PF-017 one-shared-definition corollary): the mapping lives here,
+ * viewMode GLUE RULE (one shared definition): the mapping lives here,
  * next to neutralValueOf — the definition it depends on — not across a module boundary.
  *   enum with neutralValue: neutralValue → null in TUI (null is the TUI representation
  *   of "use the default"; the key is deleted when persisted).
@@ -494,7 +518,7 @@ export function recordToTui(flag, v) {
 /**
  * Map a TUI value back to a record value.
  *
- * viewMode GLUE RULE (PF-017 one-shared-definition corollary): inverse of recordToTui,
+ * viewMode GLUE RULE (one shared definition): inverse of recordToTui,
  * co-located with that function so the round-trip contract is auditable in one place.
  *   enum with neutralValue: null → neutralValue (e.g. 'default').
  * All other values pass through unchanged.
@@ -509,7 +533,7 @@ export function tuiToRecord(flag, v) {
 }
 /**
  * Validate and coerce `raw` to a safe value for `flag` at the sink.
- * Returns null when the value is invalid (hostile-value defence — applies PF-023).
+ * Returns null when the value is invalid (hostile-value defence).
  *
  * Number invariants: finite, within [min, max], integer when required.
  * String invariants: within maxLength, no control characters.
@@ -567,7 +591,7 @@ export function coerceFlagValue(flag, raw) {
  * Parse a CLI text input to a FlagsRecordValue.
  * 'unset' (literal) → null for any flag.
  *
- * Number branch uses strict decimal grammar (applies PF-023 — invariant at the sink
+ * Number branch uses strict decimal grammar (invariant at the sink
  * every caller reaches, not per-caller): rejects empty, padded, hex, exponent,
  * and leading-zero forms. Equivalent to the TUI's strict parsing so both entry
  * points share one grammar.
@@ -749,7 +773,7 @@ export function readViewMode(record) {
  * Sanitize a FlagsRecord by coercing each known flag's value through
  * coerceFlagValue.
  *
- * Known flag IDs (applies ADR-014 key-presence semantics):
+ * Known flag IDs (key-presence semantics):
  *   - explicit null input → kept as null (deliberately unset)
  *   - valid non-null input → kept as coerced value
  *   - invalid non-null input → KEY DROPPED (absent = adopt default on next init,
@@ -758,7 +782,7 @@ export function readViewMode(record) {
  * Unknown flag IDs (forward-compat):
  *   - primitive values (boolean, number, string, null) → kept as-is
  *   - non-primitive values (objects, arrays) → DROPPED to avoid laundering
- *     untrusted shapes into FlagsRecordValue (applies PF-023)
+ *     untrusted shapes into FlagsRecordValue
  *
  * D39: `__proto__`, `constructor`, `prototype` are always skipped.
  */
@@ -823,7 +847,7 @@ export function getDefaultFlagsRecord() {
  * Migrate a legacy (string-array) enabled-flags manifest to a typed FlagsRecord.
  * Called by manifest.ts self-healing when it encounters an old string-array manifest.
  *
- * Contract (applies ADR-014 transition semantics):
+ * Contract:
  * - knownIds defined   → knownSet = knownIds ∪ enabledIds
  * - knownIds undefined → knownSet = full current registry ∪ enabledIds
  *   (pre-knownFlags manifests: all flags known, so adopt-nothing is expressed
@@ -884,7 +908,7 @@ export function settingValueHoldsManagedShape(flag, value) {
     return isDeepStrictEqual(value, guard);
 }
 /**
- * D-ATTR-GUARD single-source predicate (consistency-01 / ADR-024).
+ * D-ATTR-GUARD single-source predicate (consistency-01).
  *
  * Returns true when the settings.json string contains a value at the flag's
  * target key that equals the flag's managed shape (`settingDeleteGuard`).
@@ -926,7 +950,7 @@ export function settingHoldsManagedShape(settingsJson, flagId) {
  *
  * Delegates to `settingValueHoldsManagedShape` — the single equality oracle for
  * managed-shape comparisons — so there is exactly one `isDeepStrictEqual` call
- * across the entire apply/strip pipeline (ADR-024 mechanism 3).
+ * across the entire apply/strip pipeline.
  *
  * Single-source invariant: both the disable path (applyFlags neutral branch) and
  * the uninstall path (stripFlags) collapse to this predicate.
@@ -980,7 +1004,7 @@ function buildPayload(flag, value) {
  * Apply a FlagsRecord to a settings JSON string.
  *
  * - Unknown flag IDs are skipped (forward-compatible with future flags).
- * - `coerceFlagValue` is called at the sink before applying (applies PF-023).
+ * - `coerceFlagValue` is called at the sink before applying.
  * - Neutral values delete their target key.
  * - Env payloads for number flags are stringified ('40', never 40).
  * - Setting payloads for string flags with wrapKey are shaped ({ command: v }).
@@ -988,7 +1012,7 @@ function buildPayload(flag, value) {
  * - `__proto__`, `constructor`, `prototype` keys are silently skipped.
  */
 export function applyFlags(settingsJson, flags) {
-    // REL-M2 sink guard (applies PF-023): a non-plain-object root (null, array, scalar)
+    // REL-M2 sink guard: a non-plain-object root (null, array, scalar)
     // would cause a silent no-op or a confusing TypeError deep inside the loop.
     // Throw early with a clear message so every caller path is self-guarding.
     const root = JSON.parse(settingsJson);
@@ -1003,7 +1027,7 @@ export function applyFlags(settingsJson, flags) {
         const flag = FLAG_REGISTRY_MAP.get(id);
         if (!flag)
             continue; // unknown id — skip for forward compat
-        // Coerce at the sink (applies PF-023: validate at the convergence point)
+        // Coerce at the sink (validate at the convergence point)
         const safe = coerceFlagValue(flag, value);
         if (isNeutral(flag, safe)) {
             // Neutral → delete the target key
@@ -1045,7 +1069,7 @@ export function applyFlags(settingsJson, flags) {
  * Cleans up empty env object. Strip-then-apply idempotence preserved (INV-1).
  */
 export function stripFlags(settingsJson) {
-    // REL-M2 sink guard (applies PF-023): mirror of applyFlags — throw early on a
+    // REL-M2 sink guard: mirror of applyFlags — throw early on a
     // non-plain-object root so every caller path is self-guarding.
     const root = JSON.parse(settingsJson);
     if (root === null || typeof root !== 'object' || Array.isArray(root)) {
@@ -1122,7 +1146,7 @@ export function resolveFinalViewMode(current, selected, explicit) {
 // ─── Fold-before-strip pipeline ───────────────────────────────────────────────
 /**
  * Fold-before-strip pipeline — the single authoritative entry point for all
- * settings.json mutation paths (applies PF-015, PF-017, ADR-014).
+ * settings.json mutation paths.
  *
  * Both `init.ts` and `persistFlagConfig` (flags.ts) MUST call this instead of
  * invoking `stripFlags` + `applyFlags` directly; the invariant lives in the
@@ -1143,7 +1167,7 @@ export function resolveFinalViewMode(current, selected, explicit) {
  *   A flag is "claimed" when it is present and non-null in the claimed set.
  *   Claimed: record value wins (devflow previously set this value).
  *   Unclaimed: fold from settings — if the user has a value in settings.json,
- *   adopt it into the record (ADR-014 adoption, devflow takes ownership).
+ *   adopt it into the record (devflow takes ownership).
  *
  *   Boolean flags: never folded — on/off is always record-driven.
  *
@@ -1166,7 +1190,7 @@ export function resolveFinalViewMode(current, selected, explicit) {
  */
 export function convergeFlagsIntoSettings(settingsJson, record, opts) {
     // ── Step 1: fold view-mode (must read pre-strip) ──────────────────────────
-    // PF-015: resolveExistingViewMode reads the viewMode key. stripFlags removes
+    // resolveExistingViewMode reads the viewMode key. stripFlags removes
     // it as part of the view-mode registry entry. Reading after strip silently
     // reverts an externally-set /focus.
     const folded = {
@@ -1229,7 +1253,7 @@ export function convergeFlagsIntoSettings(settingsJson, record, opts) {
         }
     }
     // ── Step 2b: adopt guarded boolean settings before the strip ─────────────
-    // D-ATTR-ADOPT (PF-050 / ADR-024): a delete guard is evidence about the VALUE,
+    // D-ATTR-ADOPT: a delete guard is evidence about the VALUE,
     // never about the record — a pre-existing on-disk key whose value matches the
     // managed shape means devflow wrote it, so adopt it into the record now, before
     // stripFlags can unconditionally remove it on the next line.

package/dist/core/fs-atomic.js

@@ -5,11 +5,10 @@ import { promises as fs } from 'fs';
  * D34: Canonical atomic-write helper for the TypeScript CLI surface.
  *
  * Call sites: used by the CLI's exclusive-write call sites (migrations, init, post-install,
- * uninstall, security, ambient, memory, HUD, observation I/O).
- * The CJS counterpart (`writeExclusive` in `src/assets/scripts/hooks/json-helper.cjs` and
- * `src/assets/scripts/hooks/decisions-usage-scan.cjs`) intentionally remains a separate
- * implementation — same semantics, different module system. Any change to the
- * retry logic here MUST be mirrored in both CJS files.
+ * uninstall, security, ambient, memory, HUD).
+ * The CJS counterpart (`writeExclusive` in `src/assets/scripts/hooks/lib/learning-store.cjs`)
+ * intentionally remains a separate implementation — same semantics, different module
+ * system. Any change to the retry logic here MUST be mirrored there.
  */
 /**
  * Atomically write `filePath` by writing to a sibling `.tmp` then renaming.
@@ -34,7 +33,7 @@ export async function writeFileAtomicExclusive(filePath, data) {
     // PID-scope the tmp name so concurrent writers from different processes
     // (e.g., two Claude Code sessions) never collide on the same .tmp path.
     // mirrors proxy-log.ts rotation at src/core/proxy-log.ts which PID-scopes
-    // for the same reason.  avoids PF-011.
+    // for the same reason.
     const tmp = `${filePath}.tmp.${process.pid}`;
     try {
         await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
@@ -58,7 +57,7 @@ export async function writeFileAtomicExclusive(filePath, data) {
     //
     // Non-fatal path: if stat fails (ENOENT → fresh file, or any other I/O
     // error), skip chmod and keep the umask default — the write must still
-    // complete correctly (avoids PF-009 failure-isolation principle).
+    // complete correctly.
     try {
         const { mode } = await fs.stat(filePath);
         // mode includes file-type bits; mask to permission bits only for chmod.

package/dist/core/learning-queue-cleanup.js

@@ -1,92 +1,27 @@
 /**
  * @file learning-queue-cleanup.ts
  *
- * Shared cleanup helpers for `.devflow/learning/`. Imported solely by
- * `src/cli/commands/learning.ts`:
- * - `sweepLegacyDreamMarkers` — used by `devflow learning --reset`
- * - `drainLearningQueue` — used by `devflow learning --clear` / `--disable`
+ * `drainLearningQueue`, the learning queue drain shared by `devflow learning
+ * --clear` and `--disable` (src/cli/commands/learning.ts) and by the drain
+ * `devflow init` runs when learning is switched off (src/cli/commands/init.ts).
  */
-import { promises as fs } from 'fs';
 import * as path from 'path';
-import { getLearningPendingTurnsPath, getLearningPendingTurnsProcessingPath, } from './project-paths.js';
-// ---------------------------------------------------------------------------
-// Legacy marker-pipeline sweep
-// ---------------------------------------------------------------------------
-/** Fixed-name stamps left by the retired dream marker pipeline. */
-const LEGACY_FIXED_STAMPS = ['.decisions-runs-today', '.curation-last', '.processor-spawned-at'];
-/** Per-session marker variants: (decisions|curation).*.{json,processing,retries,failed} */
-function isLegacyPerSessionMarker(name) {
-    return ((name.startsWith('decisions.') || name.startsWith('curation.')) &&
-        (name.endsWith('.json') || name.endsWith('.processing') || name.endsWith('.retries') || name.endsWith('.failed')));
-}
-/**
- * Sweep legacy marker-pipeline files from a `.devflow/learning/` directory:
- * the fixed-name stamps above, plus per-session `decisions.*`/`curation.*`
- * markers. Never touches `learning.json` or the live
- * `.pending-turns.jsonl`/`.pending-turns.processing` queue files.
- *
- * ENOENT-idempotent (missing learning dir or already-removed files are not
- * errors). Non-ENOENT errors are rethrown — callers that need best-effort
- * semantics (e.g. `--reset`, which must still finish releasing its lock)
- * should wrap the call in their own try/catch.
- *
- * @returns number of files removed
- */
-export async function sweepLegacyDreamMarkers(learningDir) {
-    let removed = 0;
-    for (const name of LEGACY_FIXED_STAMPS) {
-        try {
-            await fs.unlink(path.join(learningDir, name));
-            removed++;
-        }
-        catch (err) {
-            const code = err.code;
-            if (code !== 'ENOENT')
-                throw err;
-        }
-    }
-    try {
-        const entries = await fs.readdir(learningDir);
-        for (const entry of entries) {
-            if (isLegacyPerSessionMarker(entry)) {
-                try {
-                    await fs.unlink(path.join(learningDir, entry));
-                    removed++;
-                }
-                catch (err) {
-                    const code = err.code;
-                    if (code !== 'ENOENT')
-                        throw err;
-                }
-            }
-        }
-    }
-    catch (err) {
-        const code = err.code;
-        if (code !== 'ENOENT')
-            throw err;
-    }
-    return removed;
-}
-// ---------------------------------------------------------------------------
-// Live queue drain
-// ---------------------------------------------------------------------------
+import { getLearningClaimOwnerPath, getLearningDir, getLearningPendingTurnsPath, getLearningPendingTurnsProcessingPath, } from './project-paths.js';
+import { drainQueueFiles } from './queue-drain.js';
 /**
- * Drain the learning (decisions-detection) pending-turns queue so stale turns
- * don't process later — used by both `--clear` and `--disable`. A mid-run
- * Learning agent whose claimed batch vanishes aborts without changes, which is
- * the desired outcome in both cases. ENOENT-tolerant; other errors propagate.
+ * Drain the learning (decisions-detection) pending-turns queue, its claimed
+ * batch and the claim's owner file so stale turns don't process later — used by
+ * both `--clear` and `--disable`. A mid-run Learning agent whose claimed batch
+ * vanishes aborts without changes, which is the desired outcome in both cases.
+ * Refused, deleting nothing, when `.devflow` or `.devflow/learning` under `gitRoot`
+ * is a symbolic link (D-CLI-NO-SYMLINK). ENOENT-tolerant; other errors propagate.
  */
 export async function drainLearningQueue(gitRoot) {
-    await Promise.all([
-        fs.unlink(getLearningPendingTurnsPath(gitRoot)).catch((e) => {
-            if (e.code !== 'ENOENT')
-                throw e;
-        }),
-        fs.unlink(getLearningPendingTurnsProcessingPath(gitRoot)).catch((e) => {
-            if (e.code !== 'ENOENT')
-                throw e;
-        }),
+    const learningDir = getLearningDir(gitRoot);
+    return drainQueueFiles([path.dirname(learningDir), learningDir], [
+        getLearningPendingTurnsPath(gitRoot),
+        getLearningPendingTurnsProcessingPath(gitRoot),
+        getLearningClaimOwnerPath(gitRoot),
     ]);
 }
 //# sourceMappingURL=learning-queue-cleanup.js.map