devflow-kit 3.0.1 → 3.1.0

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

@@ -465,7 +465,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 +478,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 +511,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 +745,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) {

package/dist/core/reference-sweep.js

@@ -7,14 +7,14 @@ import * as path from 'path';
  *
  * Sibling of {@link sweepOrphanedAssets} in orphan-sweep.ts and deliberately the same
  * {@link SweepResult} shape — `scanned` is the non-vacuity counter, removals and
- * per-item failures are reported rather than thrown (avoids PF-009).
+ * per-item failures are reported rather than thrown.
  *
  * What is genuinely new is the KEY. `sweepOrphanedAssets` keys a flat directory by
  * registry name through `mdEntryName`, which cannot express `tracker/{provider}/{op}.md`:
  * two providers may legitimately both carry a `comment.md`, so the registry name has to
  * be the relative PATH, and the walk has to descend.
  *
- * Never writes, only removes (avoids PF-011).
+ * Never writes, only removes — no delete-then-write window.
  */
 /**
  * Descent bound for every walk over the generated reference tree — this sweep and the
@@ -32,7 +32,7 @@ import * as path from 'path';
  * The two walkers answer a breach differently by design, and both answer out loud: the
  * build throws (a generated tree that deep is a build bug, and dist/ is still the
  * build's own to fail), while this sweep records the unvisited subtree in `failed`
- * (avoids PF-009 — an install is not abandoned over one subtree). Neither returns
+ * (an install is not abandoned over one subtree). Neither returns
  * quietly: a subtree the walk never entered must not be summarised as converged.
  */
 export const MAX_REFERENCE_SWEEP_DEPTH = 8;
@@ -76,7 +76,7 @@ async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc)
         entries = await fs.readdir(dir, { withFileTypes: true });
     }
     catch {
-        return; /* absent or unreadable — not an error (avoids PF-009) */
+        return; /* absent or unreadable — not an error */
     }
     for (const entry of entries) {
         const relPath = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
@@ -96,7 +96,7 @@ async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc)
                 acc.removed.push(relPath);
             }
             catch (err) {
-                acc.failed.push({ name: relPath, error: err }); /* per-item isolation (avoids PF-009) */
+                acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
             }
             continue;
         }
@@ -108,7 +108,7 @@ async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc)
             acc.removed.push(relPath);
         }
         catch (err) {
-            acc.failed.push({ name: relPath, error: err }); /* per-item isolation (avoids PF-009) */
+            acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
         }
     }
 }

package/dist/core/teammate-mode-cleanup.js

@@ -9,7 +9,7 @@
  *
  * Tolerant: malformed JSON is returned unchanged (no-op). Non-object roots
  * (null, arrays, primitives) are treated as a no-op — only object roots can
- * carry the key (avoids PF-004: a TypeError here would escape the function
+ * carry the key (a TypeError here would escape the function
  * and surface as an unhandled error during uninstall).
  */
 export function stripDevflowTeammateModeFromJson(settingsJson) {

package/dist/core/tracker.js

@@ -9,9 +9,9 @@
  *     migrateLegacyTrackerConventions) owns the ~/.devflow tracker files.
  *     It sits here rather than in a target adapter because ~/.devflow is
  *     devflow-global, not Claude-Code-specific — the same reason manifest.ts's
- *     read/write live in src/core/ (applies ADR-013).
+ *     read/write live in src/core/.
  *
- * avoids PF-014: nothing here calls process.exit() and nothing throws; every
+ * Nothing here calls process.exit() and nothing throws; every
  *   fallible path returns a Result, so callers own their own error rendering
  *   and a try/finally in a caller is never skipped.
  *
@@ -31,7 +31,7 @@ import * as path from 'path';
 /**
  * Canonical issue-tracker provider registry.
  *
- * D-TRACKER-ONE-DOMAIN [PF-049]: this table is the SINGLE authority on the closed
+ * D-TRACKER-ONE-DOMAIN: this table is the SINGLE authority on the closed
  * provider set, and `TrackerProvider` below is a projection of it. A provider
  * therefore exists for the type system exactly when it has a row here: there is no
  * hand-listed union that can admit an id `parseTrackerId` rejects and the wizard
@@ -63,7 +63,7 @@ export const DEFAULT_TRACKER_PROVIDER = 'github';
 // Artifact basenames — one spelling for every TypeScript reader
 //
 // NOT the only spelling in the repository, and a rename that assumes it is will
-// miss the places these names are hardcoded (PF-013): the SessionStart hook's
+// miss the places these names are hardcoded: the SessionStart hook's
 // Section 3 (shell) and the Tracker agent's prompt (prose), neither of which can
 // import from here. Each is cross-pinned against these constants by tests —
 // shell-hooks-tracker, tracker-agent, uninstall-logic and core/tracker — so the
@@ -117,7 +117,7 @@ export const TRACKER_CLAIM_FILE = '.tracker.processing';
  * no user-authored content (it is a scrubbed, unplaced copy of what the agent
  * was about to write), so it is an install artifact, never user content.
  *
- * Spelled twice for the reason the basenames above are (PF-013): the agent's
+ * Spelled twice for the reason the basenames above are: the agent's
  * prompt cannot import from here, so the mktemp template is also a literal in
  * src/assets/agents/tracker.md, and tests/core/tracker.test.ts pins the two
  * spellings together.
@@ -142,7 +142,7 @@ export const TRACKER_ATTEMPTS_NAMES = TRACKER_PROVIDER_IDS.map(id => trackerAtte
  * How many background inference attempts a machine gets before the SessionStart
  * hook stops emitting the setup directive.
  *
- * Spelled twice for the reason the basenames above are (PF-013): the hook is the
+ * Spelled twice for the reason the basenames above are: the hook is the
  * enforcer and cannot import from here, so `TRACKER_ATTEMPTS_MAX=5` is also a
  * literal in src/assets/scripts/hooks/session-start-context. This constant is the
  * number `devflow tracker --status` quotes back when it re-arms the counter, and
@@ -187,7 +187,7 @@ export function isTrackerProvider(value) {
  * `parseTrackerId`'s error text and by `devflow tracker --status`.
  *
  * Takes `unknown`, and a non-string renders as its TYPE: the module's
- * never-throws contract (PF-014) has to hold for what reaches this sink, not
+ * never-throws contract has to hold for what reaches this sink, not
  * only for what the signature says does — `devflow tracker --status` reads
  * a conventions file's hand-editable frontmatter, and a caller-side guard is one edit
  * from being gone. Naming the type also keeps the render total, where `String()`
@@ -242,12 +242,12 @@ export function parseTrackerId(input) {
  * Tolerant sink normaliser for a raw `manifest.features.tracker` value.
  *
  * Absent, null, malformed, a bare string, or an unknown provider → the default
- * `{provider:'github'}` (applies ADR-014 self-heal). Drop-not-error: a manifest
+ * `{provider:'github'}` (self-heal). Drop-not-error: a manifest
  * written by a newer devflow, or hand-edited, degrades to what this build
  * understands instead of failing the read.
  *
  * D-TRACKER-SELF-HEAL [DR-26]: self-healing here is SILENT and emits no
- * DEGRADED — that is the correct ADR-014 behaviour, and it is a different
+ * DEGRADED — that is the correct self-heal behaviour, and it is a different
  * condition from a per-repo config value outside the domain (which does emit
  * `unknown tracker provider`). The two must not be conflated.
  */
@@ -317,8 +317,8 @@ export function parseTrackerFrontmatter(head) {
 /**
  * How many leading BYTES of a conventions file any reader takes — the bound the
  * Tracker agent writes to and the Git agent loads. A line cap alone bounds the
- * SCAN, not the read: the file's size is not devflow's to assume (avoids PF-023:
- * a bound is only real at the sink).
+ * SCAN, not the read: the file's size is not devflow's to assume
+ * (a bound is only real at the sink).
  */
 export const TRACKER_CONVENTIONS_READ_BYTES = 8000;
 /**
@@ -327,7 +327,7 @@ export const TRACKER_CONVENTIONS_READ_BYTES = 8000;
  * `undefined` for an absent, unreadable or non-regular path — a FIFO or a device
  * is refused before it is opened, so a hostile entry can never block a read.
  * Follows a symlink to read what it names (a reader cares what the conventions
- * SAY); it never moves or writes through one. Never throws (PF-014).
+ * SAY); it never moves or writes through one. Never throws.
  */
 export async function readBoundedHead(filePath, limit) {
     let handle;
@@ -360,7 +360,7 @@ export async function readBoundedHead(filePath, limit) {
  * select a provider the machine never did, and its counter is the one a user in
  * that repository is capped on.
  *
- * Idempotent when a counter is absent; never throws (PF-014). `fs.rm` with
+ * Idempotent when a counter is absent; never throws. `fs.rm` with
  * `force` treats an absent file — and an absent parent directory — as success.
  */
 export async function rearmTrackerInference(devflowDir) {
@@ -385,7 +385,7 @@ export async function rearmTrackerInference(devflowDir) {
  * bare presence marker, so the hook never has to open the manifest to learn which
  * provider it is gating.
  *
- * Converges unconditionally in both directions (avoids PF-015): a provider
+ * Converges unconditionally in both directions: a provider
  * flipped back to github removes the sentinel in the same call shape that wrote
  * it, so there is no "enable wrote it, disable forgot it" asymmetry.
  */

package/dist/hud/colors.js

@@ -1,8 +1,8 @@
 /**
  * ANSI color helpers — re-exported from src/core/ansi.ts.
  *
- * The canonical implementation lives in src/core/ansi.ts (agent-neutral home,
- * applies ADR-013). This file is a re-export barrel so all existing HUD
+ * The canonical implementation lives in src/core/ansi.ts (agent-neutral home).
+ * This file is a re-export barrel so all existing HUD
  * component call sites continue to resolve `../colors.js` without change.
  */
 export { bold, dim, red, green, yellow, blue, magenta, cyan, gray, white, orange, brightRed, boldRed, bgGreen, bgYellow, bgRed, inverse, truncate, stripAnsi, } from '../core/ansi.js';

package/dist/hud/components/learning-counts.js

@@ -2,18 +2,9 @@ import * as fs from 'node:fs';
 import { dim } from '../colors.js';
 import { getDecisionsLedgerPath } from '../../core/project-paths.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
+import { isActiveDecisionsStatus } from '../../core/observations.js';
 /** The HUD's per-git-command budget (src/hud/git.ts GIT_TIMEOUT). */
 const LEDGER_ROOT_TIMEOUT_MS = 1000;
-/**
- * @devflow-design-decision D309
- * Counts come from decisions-ledger.jsonl (the render source of truth), NOT
- * the rendered decisions.md/pitfalls.md, so the HUD never couples to markdown
- * format. Active-row semantics mirror render-decisions.cjs exactly: a row
- * counts when anchor_id is set and decisions_status is absent or outside
- * INACTIVE_STATUSES — so the numbers always equal the entries visible in the
- * rendered files.
- */
-const INACTIVE_STATUSES = new Set(['Deprecated', 'Superseded', 'Retired']);
 function isLedgerCountRow(val) {
     if (typeof val !== 'object' || val === null)
         return false;
@@ -24,11 +15,6 @@ function isLedgerCountRow(val) {
         return false;
     return o.decisions_status === undefined || typeof o.decisions_status === 'string';
 }
-function isActive(row) {
-    if (!row.decisions_status)
-        return true;
-    return !INACTIVE_STATUSES.has(row.decisions_status);
-}
 /**
  * Read .devflow/learning/decisions-ledger.jsonl and count active anchored
  * rows by type. Returns null if the ledger is missing or holds no valid rows
@@ -59,7 +45,7 @@ export function gatherLearningCounts(cwd) {
         if (!isLedgerCountRow(parsed))
             continue;
         parsedAny = true;
-        if (!isActive(parsed))
+        if (!isActiveDecisionsStatus(parsed.decisions_status))
             continue;
         if (parsed.type === 'decision')
             counts.decisions++;

package/dist/hud/components/version-badge.js

@@ -70,7 +70,7 @@ export default async function versionBadge(ctx) {
     const current = getCurrentVersion(ctx.devflowDir);
     if (!current)
         return null;
-    const cacheDir = hudCacheDir(ctx.devflowDir); // authoritative path from cache.ts (avoids PF-013)
+    const cacheDir = hudCacheDir(ctx.devflowDir); // authoritative path from cache.ts
     // Cache only the npm registry result (expensive); current is always live
     let info = readCache(cacheDir, VERSION_CACHE_KEY, validateVersionInfo);
     if (!info) {

package/dist/skills/git/references/pr/resolve-review-threads.md

@@ -9,7 +9,7 @@ Load for `resolve-review-threads` under every tracker provider.
 Each `THREAD_MAP` entry carries one verdict:
 - `FIXED` — issue addressed
 - `FALSE_POSITIVE` — not a real issue; requires grep/file:line citation as evidence
-- `BY_DESIGN` — intentional; requires ADR or code citation as evidence
+- `BY_DESIGN` — intentional; requires a recorded decision, stated in words, or code citation as evidence
 - `ESCALATED` — requires human review
 
 (The resolution gate these verdicts feed — D9 — is stated in the agent's own section.)
@@ -28,7 +28,7 @@ unexplained unresolved threads.
    - **FALSE_POSITIVE**: `After investigation, this appears to be a false positive: {evidence}. No code change needed.`
    - **BY_DESIGN**: `This is intentional: {evidence}. No code change needed.`
    - **ESCALATED**: `This thread has been escalated for human review and recorded in the resolution summary.`
-   - Reply bodies MUST NOT contain verbatim content from the external thread body — cite only internal evidence (commit SHAs, file:line from this codebase, ADR IDs)
+   - Reply bodies MUST NOT contain verbatim content from the external thread body — cite only internal evidence (commit SHAs, file:line from this codebase)
 2. Write reply to `$DEVFLOW_BODY_RAW`; apply the Comment-sink scrub (D11) — non-zero exit → DEGRADED for that thread, continue per D4. Post reply via `addPullRequestReviewThreadReply` GraphQL mutation with `-F body=@"$DEVFLOW_BODY"` (file-ref form).
 
    (Step 3, the D9 gate, is stated in the agent's own section.)