devflow-kit 3.0.1 → 3.2.0

package/dist/core/learning-store.js

@@ -0,0 +1,61 @@
+/**
+ * The CLI's view of the learning store — a typed seam onto the package's own
+ * `hooks/lib/learning-store.cjs`, never a second implementation of it.
+ *
+ * D-LEARNING-STORE-SEAM: `devflow learning` reads and writes the learning tree only
+ * through the store module json-helper's ops and the hooks run, loaded with the
+ * evidence-policy seam's `loadScript` from the package's own scripts directory and
+ * shape-checked against LEARNING_STORE_SURFACE; the interfaces below are
+ * TRANSCRIBED from the store's JSDoc and are this side's only shape authority.
+ * Reason: the CLI's own TypeScript reader judged every row by the v1 shape, so it
+ * counted v2 observations as invalid, and its `--clear` truncated the log without
+ * the lock every learning writer takes.
+ *
+ * As with the evidence resolver (D-POLICY-CJS-SEAM), the CLI loads the package
+ * copy, which `npm` installs with this CLI, not `~/.devflow/scripts`, which
+ * `devflow init` refreshes: the two can differ until the next init.
+ */
+import { join } from 'path';
+import { scriptsDir } from './assets.js';
+import { loadScript } from './evidence-policy.js';
+/** The store, relative to src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const LEARNING_STORE_SCRIPT_NAME = join('hooks', 'lib', 'learning-store.cjs');
+/**
+ * Every key of LearningStoreModule and the runtime kind the loader requires of
+ * it. `satisfies` makes the compiler reject an interface key missing here.
+ */
+export const LEARNING_STORE_SURFACE = Object.freeze({
+    INACTIVE_STATUSES: 'string-array',
+    ANCHOR_ID_RE: 'regexp',
+    readLearningState: 'function',
+    buildListing: 'function',
+    readListing: 'function',
+    formatListing: 'function',
+    showByKey: 'function',
+    restoreAnchor: 'function',
+    clearUnreferenced: 'function',
+    resetLearning: 'function',
+});
+/**
+ * Load the learning store from `dir` (default: the package's own scripts
+ * directory) and shape-check its surface. Never throws: a missing file is
+ * `not-found`; a module that throws on load or lacks a surface key is `unusable`.
+ */
+export function loadLearningStore(dir = scriptsDir()) {
+    return loadScript(join(dir, LEARNING_STORE_SCRIPT_NAME), LEARNING_STORE_SURFACE);
+}
+/**
+ * Why the store cannot be used, and the remedy: a package reinstall, since the
+ * CLI loads the package's own copy, which `devflow init` does not restore.
+ */
+export function formatLearningStoreUnavailable(error) {
+    switch (error.kind) {
+        case 'not-found': return 'learning store not found — reinstall devflow-kit';
+        case 'unusable': return 'learning store failed to load — reinstall devflow-kit';
+        default: {
+            const exhaustive = error;
+            return exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=learning-store.js.map

package/dist/core/linked-path.js

@@ -0,0 +1,46 @@
+/**
+ * @file linked-path.ts
+ *
+ * `firstSymbolicLink`, the check the CLI makes before it writes or deletes under a
+ * project's `.devflow/`, or under its `.claude/` when uninstall removes a legacy
+ * local install (D-CLI-NO-SYMLINK).
+ */
+import { promises as fs } from 'fs';
+/**
+ * The first of `paths` that is itself a symbolic link, or null when none is.
+ *
+ * D-CLI-NO-SYMLINK: the CLI writes or deletes under a project's `.devflow/` only
+ * where neither `.devflow` nor the entry it acts on through it is a symbolic link:
+ * `devflow init` stamps its carve-out marker, removes the legacy markers and
+ * writes `.devflow/config.json` only then, `devflow learning --configure` writes
+ * the project's `learning.json` only then, and the queue drains (`devflow learning
+ * --clear|--disable`, `devflow memory --disable|--clear` and `devflow init
+ * --no-learning|--no-memory`) delete nothing when `.devflow` or the queue's folder
+ * is one. `devflow uninstall`, removing a legacy local install, deletes or rewrites
+ * nothing under the project's `.devflow` or `.claude` where either, or anything
+ * below it on the way to what it removes, is one (legacyLocalChangeGuard in
+ * uninstall.ts). Reason: a repository can commit `.devflow`, or a folder or file in
+ * it, as a link to any place on the machine, and a write or delete through one lands
+ * wherever it points. The hooks hold the same rule (D-HOOKS-NO-SYMLINK, git-marker)
+ * and so do the learning ops (D-NO-LINKED-TREE). Only paths below the project root
+ * are passed here: the root and the folders above it are the user's choice.
+ *
+ * Each path is checked with lstat, so a link is seen rather than followed. Nothing at
+ * a path, or a file where a folder was expected on the way to it, is no link; any
+ * other lstat failure is thrown, so a caller that cannot check acts on nothing.
+ */
+export async function firstSymbolicLink(paths) {
+    for (const candidate of paths) {
+        try {
+            if ((await fs.lstat(candidate)).isSymbolicLink())
+                return candidate;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=linked-path.js.map

package/dist/core/manifest.js

@@ -54,7 +54,7 @@ function parseManifestFlags(features, knownFlags) {
 /**
  * Read and parse the manifest file. Returns null if missing or corrupt.
  *
- * Self-heals the following on-disk inconsistencies (applies ADR-014):
+ * Self-heals the following on-disk inconsistencies:
  * - features.kb → features.knowledge rename (both absent → true, D-FEATURES-ABSENT-ON)
  * - features.decisions → features.learning rename (both absent → true, D-FEATURES-ABSENT-ON)
  * - features.flags as string[] → FlagsRecord (via migrateLegacyFlagsToRecord)
@@ -103,7 +103,7 @@ export async function readManifest(devflowDir) {
         const knowledge = typeof features.knowledge === 'boolean' ? features.knowledge
             : typeof features.kb === 'boolean' ? features.kb
                 : true;
-        // Self-heal: rename features.decisions → features.learning on disk (ADR-011).
+        // Self-heal: rename features.decisions → features.learning on disk.
         // Coalesce: features.learning wins; fall back to features.decisions; default ON.
         // D-LEARNING-LEGACY-DECISIONS: isMachineFeatureOn and queue_read_gates apply
         // this exact precedence, so the legacy key is honoured before the heal lands.
@@ -122,7 +122,7 @@ export async function readManifest(devflowDir) {
         // `flagsWereLegacy` is true only when the on-disk shape was a string[] (Case A),
         // keeping the needsHeal predicate in lockstep with the parse branch above.
         const { flags: parsedFlags, legacy: flagsWereLegacy } = parseManifestFlags(features, knownFlags);
-        // PF-023 + D39: sanitize all values; block prototype pollution keys.
+        // D39: sanitize all values; block prototype pollution keys.
         const sanitizedFlags = sanitizeFlagsRecord(parsedFlags);
         // needsHeal when any legacy artifact is present on disk
         const needsHeal = features.kb !== undefined ||
@@ -154,14 +154,14 @@ export async function readManifest(devflowDir) {
                 security: typeof features.security === 'string' && SECURITY_MODES.includes(features.security)
                     ? features.security
                     : undefined,
-                // Self-heal: absent proxy field defaults to false (applies ADR-014 self-heal idiom)
+                // Self-heal: absent proxy field defaults to false
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
                 // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
                 // Deliberately NOT in the hard-null set above — see the field's doc comment.
                 // Healing here is silent and emits no DEGRADED: that is the correct
-                // ADR-014 behaviour, and a different condition from a per-repo config
+                // self-heal behaviour, and a different condition from a per-repo config
                 // value outside the domain (which does emit `unknown tracker provider`).
                 tracker: normalizeTrackerFeature(features.tracker),
             },

package/dist/core/mds-variants.js

@@ -4,11 +4,11 @@
  * Pure module — zero I/O. Every question a caller asks about a HOST is answered
  * with a Result; callers own every filesystem call and every process exit.
  *
- * applies ADR-013: pure core-layer module, no build-script or adapter concerns.
+ * Pure core-layer module, no build-script or adapter concerns.
  * The registries below are agent-neutral, so what is DERIVED from them is derived
  * here rather than inside an install target — a target adapter computing a build
  * fact, with tests importing that adapter to learn it, is the seam inverting.
- * avoids PF-014: no process.exit(); every fallible path returns Result. The
+ * No process.exit(); every fallible path returns Result. The
  * exiting shell is scripts/build-mds.ts, which renders these errors into its
  * pre-existing messages.
  *
@@ -85,7 +85,7 @@ export function validateOutputName(name) {
  * `tracker/jira/`, and `tracker/mcp.md` would read as a third provider.
  * Relaxing the shared rule instead would have admitted `_anything.md`
  * as a command or an agent basename too — a widening across all three build
- * destinations to buy a property only this one needs (ADR-025: classify the case,
+ * destinations to buy a property only this one needs (classify the case,
  * never blanket-widen).
  *
  * Every other guarantee is inherited by delegation, so the dot-segment,
@@ -127,8 +127,8 @@ export const AGENTS_OUTPUT_DIR = 'dist/agents';
  * the installer decides which skill install triggers the reference overlay from
  * it, and the init summary renders `prefixSkillName()` of it. Retyped at each of
  * those three sites, moving the references to another skill would mean finding
- * all three spellings with nothing failing if only two were found — the PF-013
- * shape, a hardcoded spelling that still resolves.
+ * all three spellings with nothing failing if only two were found — a hardcoded
+ * spelling that still resolves.
  *
  * Bare, not `devflow:`-prefixed: the build writes to `dist/skills/git/…` while
  * the install target is `skills/devflow:git/`. prefixSkillName is what spans that
@@ -162,7 +162,7 @@ const ALLOWED_OUTPUT_DIRS = [
  *
  * Exported so guards assert the build's refusal text against the table itself
  * rather than against a retyped literal: adding a destination then rewrites both
- * the message and its assertion from one edit (PF-018 — the expectation must
+ * the message and its assertion from one edit (the expectation must
  * come from the thing under test, not a copy of it).
  */
 export const ALLOWED_OUTPUT_DIR_NAMES = ALLOWED_OUTPUT_DIRS.map(entry => entry.dir);
@@ -223,7 +223,7 @@ export function resolveOutputDir(root, declared) {
  * reverse alone lets a listed op silently emit nothing.
  *
  * The list is long from its first commit on purpose. A one- or two-element list
- * makes every parity assertion over it vacuous (GAP-42, the PF-018 trap) and is
+ * makes every parity assertion over it vacuous (GAP-42) and is
  * structurally identical to the single-arm conditional AC-1.2 forbids, so
  * expandVariants refuses a pair list below MIN_VARIANT_PAIRS.
  */
@@ -283,8 +283,8 @@ export const TRACKER_GITHUB_OPS = TRACKER_OPS;
  * carries one pointer to each.
  *
  * 9 entries, one above {@link MIN_VARIANT_PAIRS}, which is a floor and not a
- * target: a shorter roster makes every parity assertion over it vacuous (GAP-42,
- * the PF-018 trap) and `expandVariants` refuses the build, so the roster can grow
+ * target: a shorter roster makes every parity assertion over it vacuous (GAP-42)
+ * and `expandVariants` refuses the build, so the roster can grow
  * but never drop below 8. `update-pr-evidence` (#363) is the ninth — it edits the
  * PR body and comments on the PR, both GitHub whatever the tracker is.
  */
@@ -558,7 +558,7 @@ export const MIN_VARIANT_PAIRS = 8;
  * writes.
  *
  * Pure and total: every refusal is a Result, so the build shell keeps its single
- * exit (avoids PF-014). The expansion is deliberately flat rather than nested —
+ * exit. The expansion is deliberately flat rather than nested —
  * one list of destinations is what the plan pass needs to detect two hosts
  * claiming one file, and a nested shape would have to be flattened there anyway.
  *
@@ -642,14 +642,14 @@ export function expandVariants(modules = resolveVariantModules()) {
  * Lives beside the registry it reads rather than in the Claude Code installer that
  * consumes it: nothing about the answer is Claude-Code-specific, and the packaging
  * and containment tests that read it are asking the BUILD what it emits, not
- * asking an install target (applies ADR-013).
+ * asking an install target.
  *
  * Asserts where its siblings return a Result. The registry is a compile-time
  * constant, so a refusal is a programming error rather than an install-time
  * degradation: no caller could sensibly continue, and every caller would otherwise
  * carry the same impossible branch. The full refusal is rendered and not just its
  * `kind` — the payload is what names the offending module and op, and a payload
- * nothing reads is a payload nothing maintains (avoids PF-041). Same rendering the
+ * nothing reads is a payload nothing maintains. Same rendering the
  * build's own refusal sinks use (scripts/build-mds.ts).
  */
 export function generatedReferenceManifest() {
@@ -721,7 +721,7 @@ export const VARIANT_SECTION_MARKER_RE = /^<!-- op: (_?[a-z0-9][a-z0-9._-]{0,63}
  *
  * Bidirectional, and both directions are load-bearing:
  *   - unknown-section — the body carries a section for an op the registry does
- *     not name, so a file would ship that nothing loads (ADR-003);
+ *     not name, so a file would ship that nothing loads;
  *   - missing-section — the registry names an op the body does not cover, so the
  *     preamble's load instruction resolves to nothing at runtime.
  * A forward-only check passes on either half of that pair.

package/dist/core/model-discovery.js

@@ -4,14 +4,14 @@
  * Discovers routable external models from the routing runtime.
  * The only impure piece of the external-model-routing design.
  *
- * applies ADR-013: pure core-layer module — no adapter imports.
- * applies PF-013: cwd = os.tmpdir() so discovery never assumes the devflow
+ * Pure core-layer module — no adapter imports.
+ * cwd = os.tmpdir() so discovery never assumes the devflow
  *   directory exists (the --set read path never mkdirs, so the dir may not
  *   exist; os.tmpdir() also prevents a stale subswitch.config.json in any
  *   particular working directory from causing exit 1 in the routing runtime).
- * avoids PF-009: discoverExternalModels never throws or rejects — every
+ * discoverExternalModels never throws or rejects — every
  *   failure path returns { known: false }.
- * avoids PF-016: real-binary tests (T1–T4) live in tests/, never in
+ * Real-binary tests (T1–T4) live in tests/, never in
  *   tests/integration/ which is excluded from npm test by vitest.config.ts.
  *
  * Branding constraint: the routing runtime package name ("subswitch") must
@@ -508,9 +508,9 @@ function buildRealSpawnAndCollect(logPath) {
  *  - parse failure on live payload → log reason to proxy.log.
  *  - All failures degrade to stale-cache then { known: false } — never throw.
  *
- * applies PF-013: cwd = os.tmpdir() (not devflow dir, which may not exist on
- *   the cold --set path; also prevents legacy subswitch.config.json in cwd
- *   from causing exit 1 in the routing runtime).
+ * cwd = os.tmpdir() (not devflow dir, which may not exist on
+ * the cold --set path; also prevents legacy subswitch.config.json in cwd
+ * from causing exit 1 in the routing runtime).
  *
  * AC-C7: resolveProxyBin() is called live every invocation, never proxy.json.binPath.
  * AC-C8: never throws or rejects.
@@ -524,7 +524,7 @@ export async function discoverExternalModels(cacheDir, logPath, deps) {
         return await _discoverInternal(cacheDir, logPath, deps);
     }
     catch {
-        // Catch-all: discoverExternalModels MUST NOT throw (avoids PF-009).
+        // Catch-all: discoverExternalModels MUST NOT throw.
         return { known: false };
     }
 }

package/dist/core/observations.js

@@ -1,109 +1,25 @@
 /**
  * @file observations.ts
  *
- * Core observation type, type guard, parsing, and pure formatting.
- * No I/O, no UI dependencies — pure data module.
+ * The ledger entry statuses on the TypeScript side. Pure data: no I/O and no
+ * imports, so the HUD can load it without growing its import closure.
  */
 /**
- * D201: Canonical status vocabulary for rendered decisions.md / pitfalls.md entries.
- *
- * Derived from an `as const` literal array so the union type, the runtime set,
- * and the VALID_DECISIONS_STATUSES guard below are always in sync — no manual
- * duplication. `Retired` is the output of the `retire-anchor` op and MUST be
- * present; `Unknown` was never produced by any operation and has been removed.
- *
- * Defined here (pure data module) so both observation-io.ts and learning.ts
- * can import without creating a utility→command circular dependency.
- * Re-exported through src/cli/commands/learning.ts for external consumers.
- * Consumed by LedgerRow (this file) and LearningObservation.decisions_status (this file).
- */
-export const DECISIONS_ENTRY_STATUSES = [
-    'Accepted', 'Active', 'Deprecated', 'Superseded', 'Retired',
-];
-/** Valid values for the decisions_status optional field — derived from DECISIONS_ENTRY_STATUSES. */
-const VALID_DECISIONS_STATUSES = new Set(DECISIONS_ENTRY_STATUSES);
-/**
- * Type guard for validating raw JSON as a LearningObservation.
- * Accepts all 4 types (v2: decision + pitfall added) and all statuses including deprecated.
- * New optional fields (anchor_id, date, decisions_status, amendments, raw_body) are
- * validated when present but their absence never causes rejection — backward compatible.
- */
-export function isLearningObservation(obj) {
-    if (typeof obj !== 'object' || obj === null)
-        return false;
-    const o = obj;
-    // Required fields
-    if (!(typeof o.id === 'string' && o.id.length > 0))
-        return false;
-    if (!(o.type === 'workflow' || o.type === 'procedural' || o.type === 'decision' || o.type === 'pitfall'))
-        return false;
-    if (!(typeof o.pattern === 'string' && o.pattern.length > 0))
-        return false;
-    if (typeof o.confidence !== 'number')
-        return false;
-    if (typeof o.observations !== 'number')
-        return false;
-    if (typeof o.first_seen !== 'string')
-        return false;
-    if (typeof o.last_seen !== 'string')
-        return false;
-    if (!(o.status === 'observing' || o.status === 'ready' || o.status === 'created' || o.status === 'deprecated'))
-        return false;
-    if (!Array.isArray(o.evidence))
-        return false;
-    if (typeof o.details !== 'string')
-        return false;
-    // Optional ledger fields: validate type when present, reject if wrong type
-    if (o.anchor_id !== undefined && typeof o.anchor_id !== 'string')
-        return false;
-    if (o.date !== undefined && typeof o.date !== 'string')
-        return false;
-    if (o.decisions_status !== undefined && !VALID_DECISIONS_STATUSES.has(o.decisions_status))
-        return false;
-    if (o.amendments !== undefined) {
-        if (!Array.isArray(o.amendments))
-            return false;
-        for (const a of o.amendments) {
-            if (typeof a !== 'object' || a === null)
-                return false;
-            const am = a;
-            if (typeof am.date !== 'string' || typeof am.note !== 'string')
-                return false;
-        }
-    }
-    if (o.raw_body !== undefined && typeof o.raw_body !== 'string')
-        return false;
-    return true;
-}
-/**
- * Parse a JSONL learning log into typed observations.
- * Skips empty and malformed lines.
- */
-export function parseLearningLog(logContent) {
-    const observations = [];
-    for (const line of logContent.split('\n')) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            const parsed = JSON.parse(trimmed);
-            if (isLearningObservation(parsed)) {
-                observations.push(parsed);
-            }
-        }
-        catch {
-            // Skip malformed lines
-        }
-    }
-    return observations;
-}
-/**
- * Parse a JSONL log and return valid observations plus the count of invalid entries.
- * Centralises the raw-line-count + parse pattern used by --status, --list, and --purge.
+ * D201: a ledger entry's `decisions_status` takes one of DECISIONS_ENTRY_STATUSES.
+ * `Accepted` (decisions) and `Active` (pitfalls) are active and render; the
+ * INACTIVE_DECISIONS_STATUSES stay in the ledger and leave the rendered files and
+ * the HUD counts; an absent or unknown status counts as active. These lists
+ * mirror ACTIVE_STATUSES / INACTIVE_STATUSES in
+ * src/assets/scripts/hooks/lib/learning-store.cjs, which the hooks and the
+ * renderer use, and the parity test in tests/decisions/learning-store.test.ts
+ * pins the two equal. Reason: the renderer, the HUD and this module each kept a
+ * list of their own, so a status added to one counted as active in the others.
  */
-export function loadAndCountObservations(logContent) {
-    const rawLines = logContent.split('\n').filter(l => l.trim()).length;
-    const observations = parseLearningLog(logContent);
-    return { observations, invalidCount: rawLines - observations.length };
+export const INACTIVE_DECISIONS_STATUSES = ['Encoded', 'Superseded', 'Retired', 'Deprecated'];
+export const DECISIONS_ENTRY_STATUSES = ['Accepted', 'Active', ...INACTIVE_DECISIONS_STATUSES];
+const INACTIVE_DECISIONS_STATUS_SET = new Set(INACTIVE_DECISIONS_STATUSES);
+/** True unless `status` is one of INACTIVE_DECISIONS_STATUSES (D201). */
+export function isActiveDecisionsStatus(status) {
+    return !status || !INACTIVE_DECISIONS_STATUS_SET.has(status);
 }
 //# sourceMappingURL=observations.js.map

package/dist/core/orphan-sweep.js

@@ -61,8 +61,8 @@ export function mdEntryName(entry) {
  *
  * Per-item failure isolation: both the outer readdir and the inner rm are
  * independently try/caught — a missing directory is a no-op and a failed
- * individual removal is recorded in `failed` without aborting the sweep (avoids PF-009).
- * Never writes, only removes (avoids PF-011).
+ * individual removal is recorded in `failed` without aborting the sweep.
+ * Never writes, only removes — no delete-then-write window.
  */
 export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName) {
     const removed = [];
@@ -81,12 +81,12 @@ export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName)
                     removed.push(registryName);
                 }
                 catch (err) {
-                    failed.push({ name: registryName, error: err }); /* per-item isolation (avoids PF-009) */
+                    failed.push({ name: registryName, error: err }); /* per-item isolation */
                 }
             }
         }
     }
-    catch { /* directory absent or unreadable — not an error (avoids PF-009) */ }
+    catch { /* directory absent or unreadable — not an error */ }
     return { scanned, removed, failed };
 }
 //# sourceMappingURL=orphan-sweep.js.map

package/dist/core/plugins.js

@@ -72,6 +72,10 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/plan'],
         agents: ['git', 'skim', 'synthesize', 'design'],
         skills: ['gap-analysis', 'design-review', 'patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        // D-CHARTER-BOUNDED-INLINE: /plan's main thread orchestrates and loads no
+        // companion skills, so `requires:` lists only skills this plugin's command,
+        // agents and skills reference. `software-design` and `test-driven-development`
+        // have no reader here; the closure guard's reverse arm rejects an unread entry.
         requires: [
             'apply-decisions',
             'architecture',
@@ -87,8 +91,6 @@ export const DEVFLOW_PLUGINS = [
             'reliability',
             'review-methodology',
             'security',
-            'software-design',
-            'test-driven-development',
             'testing',
         ],
         rules: [],
@@ -127,7 +129,11 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/code-review'],
         agents: ['git', 'review', 'synthesize'],
         skills: ['architecture', 'complexity', 'consistency', 'database', 'dependencies', 'documentation', 'performance', 'regression', 'reliability', 'review-methodology', 'security', 'testing', 'worktree-support', 'apply-feature-knowledge'],
-        requires: ['apply-decisions', 'docs-framework', 'git', 'quality-gates', 'software-design'],
+        // D-CHARTER-BOUNDED-INLINE: /code-review's main thread orchestrates and loads
+        // no companion skills, so `requires:` lists only skills this plugin's command,
+        // agents and skills reference. `quality-gates` and `software-design` have no
+        // reader here; the closure guard's reverse arm rejects an unread entry.
+        requires: ['apply-decisions', 'docs-framework', 'git'],
         rules: [],
     },
     {
@@ -465,7 +471,7 @@ export const DELETED_PLUGIN_NAMES = [
  *   - uninstall.ts sweepDevflowNamespaces: union into knownNames to spare devflow:compliance
  *     from the post-selective-uninstall sweep (nothing converges after selective uninstall)
  *   - skills.ts: union into allSkills for shadow/unshadow/list
- *   - tests: independent literal ['compliance'] (avoids EXCLUDED-as-oracle trap, PF-018)
+ *   - tests: independent literal ['compliance'] (avoids EXCLUDED-as-oracle trap)
  *
  * D-FO-1: FEATURE_OWNED_SKILLS must be disjoint from getAllSkillNames()
  * (guarded by plugins.test.ts FEATURE_OWNED constants describe block).
@@ -478,7 +484,7 @@ export const FEATURE_OWNED_SKILLS = ['compliance'];
  *
  * Used by:
  *   - rules.ts: union into allRules for shadow/unshadow/list
- *   - tests: independent literal ['compliance'] (avoids EXCLUDED-as-oracle trap, PF-018)
+ *   - tests: independent literal ['compliance'] (avoids EXCLUDED-as-oracle trap)
  *
  * D-FO-2: FEATURE_OWNED_RULES must be disjoint from getAllRuleNames()
  * (guarded by plugins.test.ts FEATURE_OWNED constants describe block).
@@ -511,7 +517,7 @@ export const PRESENCE_GATED_SKILLS = [
  * The classified exception to the closure guard — declared HERE, at the
  * declaration site of the field it exempts, and imported by the guard.
  *
- * D-TEMPLATE-EXCEPTION (applies PF-067: one authority for a prohibition and its
+ * D-TEMPLATE-EXCEPTION (one authority for a prohibition and its
  * exemptions). Every other templated reference in the corpus carries a literal
  * prefix and resolves through it — `devflow:research-{RESEARCH_TYPE}` resolves
  * because five in-scope skills start with `research-`. The Review focus skill is
@@ -745,8 +751,7 @@ export function buildFullSkillsMap() {
  * add X, not a statement that X is the whole selection, so it may never remove
  * what another plugin contributed (AC-22). {@link FEATURE_OWNED_SKILLS} is
  * subtracted unconditionally: those install and uninstall with their feature,
- * and sweeping them here would delete an artifact this code does not own
- * (applies ADR-024).
+ * and sweeping them here would delete an artifact this code does not own.
  *
  * A shadow is NEVER removed, whatever the selection — `~/.devflow/skills/` is
  * user content. One that falls outside the install set simply applies to

package/dist/core/project-paths.js

@@ -46,10 +46,14 @@ export function getFeatureConfigPath(projectRoot) {
 export function getLearningPendingTurnsPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.jsonl');
 }
-/** .devflow/learning/.pending-turns.processing — atomic claim held by the Learning agent while processing */
+/** .devflow/learning/.pending-turns.processing — the claimed batch a Learning run holds while it processes it */
 export function getLearningPendingTurnsProcessingPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.processing');
 }
+/** .devflow/learning/.pending-turns.owner — the token of the run that holds the claim (learning-store.cjs) */
+export function getLearningClaimOwnerPath(projectRoot) {
+    return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.owner');
+}
 // ---------------------------------------------------------------------------
 // Learning content files
 // ---------------------------------------------------------------------------
@@ -77,26 +81,18 @@ export function getDecisionsLogPath(projectRoot) {
 export function getDecisionsArchivePath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', 'decisions-log.archive.jsonl');
 }
+/** .devflow/learning/decisions-history.jsonl — prior content versions of rewritten entries (learning-store.cjs) */
+export function getDecisionsHistoryPath(projectRoot) {
+    return path.join(projectRoot, '.devflow', 'learning', 'decisions-history.jsonl');
+}
 /** .devflow/learning/.decisions.lock — mkdir-based lock directory */
 export function getDecisionsLockDir(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', '.decisions.lock');
 }
-/** .devflow/learning/.decisions-usage.json */
-export function getDecisionsUsagePath(projectRoot) {
-    return path.join(projectRoot, '.devflow', 'learning', '.decisions-usage.json');
-}
-/** .devflow/learning/.decisions-usage.lock/ — mkdir-based lock directory for usage file */
-export function getDecisionsUsageLockDir(projectRoot) {
-    return path.join(projectRoot, '.devflow', 'learning', '.decisions-usage.lock');
-}
 /** .devflow/learning/index.md — pre-rendered compact index written by render-decisions.cjs */
 export function getDecisionsIndexPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', 'index.md');
 }
-/** .devflow/learning/.observations.lock — mkdir-based lock directory for observation log writes */
-export function getObservationsLockDir(projectRoot) {
-    return path.join(projectRoot, '.devflow', 'learning', '.observations.lock');
-}
 // ---------------------------------------------------------------------------
 // Memory / working-memory files
 // ---------------------------------------------------------------------------

package/dist/core/proxy-log.js

@@ -10,8 +10,8 @@ import * as path from 'path';
  *   - openProxyLog      — 0700-parent + 0600-file open with best-effort chmod (SEC-2)
  *   - rotateProxyLogIfLarge — pre-spawn-only 2MB→1MB rotation that preserves 0600 mode
  *
- * avoids PF-009: every failure path is non-fatal (wrapped in try/catch); one bad
- *   chmod or rotation error must never abort the enable flow.
+ * Every failure path is non-fatal (wrapped in try/catch); one bad
+ * chmod or rotation error must never abort the enable flow.
  */
 /** 2 MB max log size before rotation (mirrors ensure-proxy _LOG_MAX_BYTES). */
 export const PROXY_LOG_MAX_BYTES = 2_097_152;
@@ -28,7 +28,7 @@ export const PROXY_LOG_TAIL_BYTES = 1_048_576;
  * Call sites compose on top of this result to add process-specific vars
  * (e.g. SUBSWITCH_CONFIG for the relay spawn and doctor spawn).
  *
- * applies ADR-003: the prior denylist rationale is gone — on the paths devflow
+ * On the paths devflow
  * invokes (serve, doctor, models) the routing runtime reads ANTHROPIC_API_KEY,
  * FORCE_COLOR, NO_COLOR (dist/tty.js, presence semantics), SUBSWITCH_CONFIG and
  * XDG_CONFIG_HOME (user-config lookup, reached only on an implicit config load —
@@ -42,8 +42,8 @@ export const PROXY_LOG_TAIL_BYTES = 1_048_576;
  * NODE_EXTRA_CA_CERTS is included so corporate-TLS deployments can supply a CA
  * bundle; it is omitted when unset (the absent-→-omit loop handles this).
  * NODE_OPTIONS is deliberately excluded: it permits arbitrary code execution via
- * --require/--import. Mirrored in the ensure-proxy bash hook's _RELAY_ENV array
- * (avoids PF-017); both allowlists must be kept in sync.
+ * --require/--import. Mirrored in the ensure-proxy bash hook's _RELAY_ENV array;
+ * both allowlists must be kept in sync.
  */
 export function scrubChildEnv() {
     const POSIX_ALLOWLIST = ['PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_ALL', 'NODE_EXTRA_CA_CERTS'];
@@ -71,7 +71,7 @@ export function scrubChildEnv() {
  *   3. best-effort fs.chmod(logPath, 0o600) — widens a pre-existing file
  *      that was created before this guard existed (e.g. mode 0644 on disk).
  *      Non-fatal: a chmod failure (EPERM, ENOENT race) must never prevent the
- *      handle from being returned — avoids PF-009 failure-isolation principle.
+ *      handle from being returned.
  *      Follows the SEC-1 precedent in src/core/fs-atomic.ts (commit 5755d56):
  *      chmod in try/catch, never fatal, with a comment citing the rationale.
  *
@@ -88,7 +88,7 @@ export async function openProxyLog(logPath) {
     const handle = await fs.open(logPath, 'a', 0o600);
     // Step 3: best-effort chmod for a pre-existing file that has a wider mode.
     // Non-fatal: chmod failure must not prevent the handle from being returned.
-    // avoids PF-009: failure-isolation — one bad chmod must never abort the enable flow.
+    // Failure isolation — one bad chmod must never abort the enable flow.
     try {
         await fs.chmod(logPath, 0o600);
     }
@@ -120,7 +120,7 @@ export async function openProxyLog(logPath) {
  *
  * Non-fatal: rotation failure (disk full, EPERM, read error) leaves the
  * original log untouched and the enable proceeds with an oversized log.
- * avoids PF-009: one rotation error must never abort the enable flow.
+ * One rotation error must never abort the enable flow.
  *
  * @param logPath - Absolute path to proxy.log.
  */

package/dist/core/proxy-state.js

@@ -2,8 +2,8 @@
  * Proxy state persistence and routing config helpers for the Devflow external
  * model routing feature.
  *
- * applies ADR-013: pure core-layer module — no Claude Code adapter concerns.
- * avoids PF-014: never call process.exit() inside finally-guarded scopes; all
+ * Pure core-layer module — no Claude Code adapter concerns.
+ * Never call process.exit() inside finally-guarded scopes; all
  *   fallible operations return Result instead of throwing.
  *
  * State file: ~/.devflow/proxy.json
@@ -155,7 +155,7 @@ const ROUTING_CONFIG_REJECTED_SUBKEYS = {
  *
  * If `existingContent` is missing or malformed, falls back to a port-only config.
  *
- * applies ADR-013: pure core-layer function — no I/O.
+ * Pure core-layer function — no I/O.
  * @D-EFR-4: see note above for the strict top-key constraint.
  */
 export function buildRoutingConfigJson(port, existingContent) {