devflow-kit 3.0.1 → 3.2.0

package/dist/core/queue-drain.js

@@ -0,0 +1,31 @@
+/**
+ * @file queue-drain.ts
+ *
+ * `drainQueueFiles`, the delete the queue drains share — `drainLearningQueue`
+ * (learning-queue-cleanup.ts) and `drainMemoryQueue` (cli/commands/memory.ts) —
+ * and `formatRefusedDrain`, the line the CLI prints for a drain it refused.
+ */
+import { promises as fs } from 'fs';
+import { firstSymbolicLink } from './linked-path.js';
+/**
+ * Delete each of `files` unless one of `folders` — `.devflow` and the folder that
+ * holds the files, outermost first — is a symbolic link (D-CLI-NO-SYMLINK): through a
+ * linked folder, each delete would remove a same-named file wherever the link points.
+ * A file that is already gone is not an error; any other failure propagates, as the
+ * check's own does, so the command reports it.
+ */
+export async function drainQueueFiles(folders, files) {
+    const linkedFolder = await firstSymbolicLink(folders);
+    if (linkedFolder !== null)
+        return { drained: false, linkedFolder };
+    await Promise.all(files.map(file => fs.unlink(file).catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+    })));
+    return { drained: true };
+}
+/** The warning for a drain refused at `linkedFolder`: which queue kept its files, and why. */
+export function formatRefusedDrain(queue, linkedFolder) {
+    return `The ${queue} queue was not drained: ${linkedFolder} is a symbolic link, and devflow deletes nothing through one`;
+}
+//# sourceMappingURL=queue-drain.js.map

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,58 @@ 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.
+ * The largest ledger the statusline reads: 8 MiB, far above the roughly 0.5 MB
+ * real ledgers reach.
+ *
+ * D-HUD-LEDGER-BOUNDED: the statusline counts the ledger only when it is a regular
+ * file of at most LEDGER_MAX_BYTES, and never reads it if it is a symbolic link; a
+ * link, any other kind of file or a larger one shows no counts, as an absent
+ * ledger does. Reason: the statusline reads the ledger on every prompt, and a
+ * repository can commit it as a link to an endless source such as /dev/zero, or
+ * as a huge file, either of which would hang the statusline.
  */
-const INACTIVE_STATUSES = new Set(['Deprecated', 'Superseded', 'Retired']);
+export const LEDGER_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * The ledger's text, or null when D-HUD-LEDGER-BOUNDED refuses it or it cannot be
+ * read. lstat refuses a link without following it, the open refuses one that took
+ * the ledger's place since (O_NOFOLLOW) and never blocks on a FIFO (O_NONBLOCK),
+ * and the read takes at most the size fstat checked.
+ */
+function readBoundedLedger(ledgerPath) {
+    let fd;
+    try {
+        if (!fs.lstatSync(ledgerPath).isFile())
+            return null;
+        fd = fs.openSync(ledgerPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > LEDGER_MAX_BYTES)
+            return null;
+        const buf = Buffer.alloc(stat.size);
+        let total = 0;
+        while (total < buf.length) {
+            const read = fs.readSync(fd, buf, total, buf.length - total, total);
+            if (read === 0)
+                break;
+            total += read;
+        }
+        return buf.toString('utf-8', 0, total);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 function isLedgerCountRow(val) {
     if (typeof val !== 'object' || val === null)
         return false;
@@ -24,24 +64,16 @@ 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
- * (graceful fallback). Exported for use by the main HUD entry point.
+ * rows by type. Returns null if the ledger is missing, is refused by
+ * D-HUD-LEDGER-BOUNDED, or holds no valid rows (graceful fallback). Exported for
+ * use by the main HUD entry point.
  */
 export function gatherLearningCounts(cwd) {
-    let content;
-    try {
-        content = fs.readFileSync(getDecisionsLedgerPath(cwd), 'utf-8');
-    }
-    catch {
+    const content = readBoundedLedger(getDecisionsLedgerPath(cwd));
+    if (content === null)
         return null;
-    }
     const counts = { decisions: 0, pitfalls: 0 };
     let parsedAny = false;
     for (const rawLine of content.split('\n')) {
@@ -59,7 +91,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.)

package/dist/skills/git/references/tracker/github/create-release.md

@@ -2,10 +2,10 @@
 
 Load when the resolved tracker provider is `github` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` provided: append a `## Closed Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
+   - If `SHIPPED_ISSUES` provided: append a `## Shipped Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)

package/dist/skills/git/references/tracker/jira/create-release.md

@@ -2,13 +2,13 @@
 
 Load when the resolved tracker provider is `jira` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - Pre-flight the list against `^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`, anchored at both ends, and **drop** every entry that fails, reporting each as `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match jira reference grammar)` — a bare number among them goes with them, in silence: `ambiguous issue reference` answers a reference a caller named, not one line of a list nobody chose. Every entry dropped ⇒ `TRACEABILITY: DEGRADED (no parseable refs for provider {p})` and the section is omitted rather than rendered empty.
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the key itself on its own line, and record the discard under `### Substitutions`.
 

package/dist/skills/git/references/tracker/linear/create-release.md

@@ -2,13 +2,13 @@
 
 Load when the resolved tracker provider is `linear` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - **ASCII-upper-normalise every entry first.** Pre-flight the list against **either** anchored form — the team-key form `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` or the internal-id form `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$`, anchored at both ends, never joined into one alternation, and **drop** every entry that fails, reporting each as `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match linear reference grammar)` — a bare number among them goes with them, in silence: `ambiguous issue reference` answers a reference a caller named, not one line of a list nobody chose. Every entry dropped ⇒ `TRACEABILITY: DEGRADED (no parseable refs for provider {p})` and the section is omitted rather than rendered empty.
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the reference itself on its own line, and record the discard under `### Substitutions`.
 

package/dist/targets/claude-code/compliance-install.js

@@ -14,10 +14,10 @@
  * decided by the ids its caller passes (D-COMPLIANCE-REPO-LENS), never by which
  * files are present.
  *
- * Applies ADR-013: I/O orchestration in src/targets/; pure helpers in src/core/.
- * Applies PF-009: warn-not-throw for per-item failures.
- * Applies PF-011: temp-sibling+rename for skill dir rewrites.
- * Applies PF-015: both artifacts converge unconditionally (no || short-circuits).
+ * I/O orchestration in src/targets/; pure helpers in src/core/.
+ * Warn-not-throw for per-item failures.
+ * Temp-sibling+rename for skill dir rewrites.
+ * Both artifacts converge unconditionally (no || short-circuits).
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
@@ -53,7 +53,7 @@ async function pathExists(p) {
  * Fragments always come from the canonical source (not user-overridable) — they carry
  * registry-owned content (mapping cells, reference blurbs, checklist items, rule bullets).
  *
- * PF-009: parse errors and unreadable files are reported via warn; the framework is
+ * Parse errors and unreadable files are reported via warn; the framework is
  * silently omitted from the result map (C5 in composeComplianceSkill handles the gap).
  */
 async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
@@ -92,8 +92,8 @@ async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
  * `fragments` is loaded once by convergeComplianceArtifacts and shared with the rule
  * installer — the SKILL.md and the rule compose from the same parsed set.
  *
- * Applies PF-011: build under a .tmp sibling, remove old target, rename.
- * Applies PF-009: unexpected I/O failures are reported via warn; never thrown.
+ * Build under a .tmp sibling, remove old target, rename.
+ * Unexpected I/O failures are reported via warn; never thrown.
  */
 async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn) {
     const canonicalSrc = path.join(skillsDir(), 'compliance');
@@ -108,7 +108,7 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
     try {
         // Clean up any orphaned tmp from a prior crashed run (best-effort).
         await fs.rm(tmpTarget, { recursive: true, force: true });
-        // Build the new directory tree under the tmp sibling (PF-011).
+        // Build the new directory tree under the tmp sibling.
         const refDst = path.join(tmpTarget, 'references');
         await fs.mkdir(refDst, { recursive: true });
         // SKILL.md: compose from template (shadow or canonical) + fragments.
@@ -121,7 +121,7 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
         // Always-present reference files (detection.md, sources.md) from the canonical
         // references/ directory — these are not framework-specific.
         //
-        // PF-009: each copy is isolated. A skill dir missing one reference still works;
+        // Each copy is isolated. A skill dir missing one reference still works;
         // aborting the whole install because one file is unreadable would take out
         // SKILL.md too. Failures warn and the remaining refs still install.
         const alwaysPresentSrc = path.join(canonicalSrc, 'references');
@@ -148,7 +148,7 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
                 warn(`compliance: reference "${fw}.md" not installed — ${String(err)}`);
             }
         }
-        // Atomically swap: remove old target, rename tmp into place.
+        // Swap: remove old target, rename tmp into place (two calls, not atomic).
         await fs.rm(target, { recursive: true, force: true });
         await fs.rename(tmpTarget, target);
     }
@@ -174,7 +174,7 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
  * source (never the shadow — fragments are registry-owned) and shared with the skill
  * installer.
  *
- * Applies PF-009: I/O failures are reported via warn; never thrown.
+ * I/O failures are reported via warn; never thrown.
  */
 async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, warn) {
     const ruleShadowFile = path.join(devflowDir, 'rules', 'compliance.md');
@@ -203,8 +203,10 @@ async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, war
  *   enabled + !rulesEnabled → skill dir (every ref, machine stamp); remove stale rule
  *   !enabled                → skill dir (every ref, neutral stamp); remove rule
  *
- * PF-015: both artifact operations execute unconditionally — no || short-circuits.
- * PF-011: skill dir write uses temp-sibling+rename to avoid ENOENT windows.
+ * Both artifact operations execute unconditionally — no || short-circuits.
+ * Skill dir write builds under a temp sibling, then removes the target and renames
+ * the sibling into place, which narrows the ENOENT window to the gap between those
+ * two calls.
  *
  * D: the `warn` callback is injected (not console.warn) so callers control
  * surfacing (init log lines, test spies, etc.) — per the dependency-injection
@@ -227,7 +229,7 @@ export async function convergeComplianceArtifacts(opts) {
     const safeFrameworks = normalizeFrameworks(frameworks);
     // I13: Track whether every artifact operation in this run completed without error.
     // `converged` starts true and is set false by the tracking wrapper whenever any warn
-    // path is taken — including inside installSkillDir / installRuleFile (PF-009 paths).
+    // path is taken — including inside installSkillDir / installRuleFile (their per-item warn paths).
     let converged = true;
     const trackingWarn = (msg) => {
         converged = false;
@@ -239,7 +241,7 @@ export async function convergeComplianceArtifacts(opts) {
     // frameworks need one — a compliance-off machine stamps none.
     const stampFrameworks = enabled ? safeFrameworks : [];
     const fragments = await loadComplianceFragments(path.join(skillsDir(), 'compliance'), stampFrameworks, trackingWarn);
-    // PF-015: the skill and the rule are independent operations. An error in
+    // The skill and the rule are independent operations. An error in
     // installSkillDir is caught internally and reported via trackingWarn, so
     // execution always continues to the rule step.
     await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn);

package/dist/targets/claude-code/hooks.js

@@ -40,8 +40,8 @@ export function endsWithAny(suffixes) {
  * `/scripts/hooks/session-start-memory.sh`), under any directory — so installs made
  * under a custom or retired devflow directory are still recognised. It is never
  * devflow's because it merely CONTAINS a marker word: a user's `~/bin/memory-worker`,
- * `echo capture-turn` or `/opt/tools/run-hook preamble` is theirs (applies ADR-024 —
- * remove only what devflow can prove it wrote). Removal goes through `removeHooks`,
+ * `echo capture-turn` or `/opt/tools/run-hook preamble` is theirs
+ * (remove only what devflow can prove it wrote). Removal goes through `removeHooks`,
  * one hook at a time. Every hook module builds its predicates here;
  * D-AMBIENT-EXACT-HOOK is the ambient instance of this rule.
  */