devflow-kit 3.0.0 → 3.1.0

package/dist/cli/commands/init.js

@@ -84,7 +84,7 @@ export async function runMigrationsWithFallback(discoveredProjects, gitRoot, dev
  * or command still loading in Claude Code with no diagnostic at all. Both outcomes
  * have to reach the summary.
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  */
 export function formatSweepSummary(report) {
     const lines = [];
@@ -194,7 +194,8 @@ export function resolveComplianceInitState(complianceOption, seedFrameworks) {
     return undefined;
 }
 // Re-export formatComplianceSummary from compliance-prompts.ts so existing test imports
-// (tests/init-logic.test.ts:1615 — imports from '../src/cli/commands/init.js') keep resolving.
+// (the 'formatComplianceSummary' suite in tests/init-logic.test.ts imports it from
+// '../src/cli/commands/init.js') keep resolving.
 export { formatComplianceSummary } from './compliance-prompts.js';
 /**
  * Parse the --tracker CLI option into a tracker override.
@@ -222,7 +223,7 @@ export function resolveTrackerInitState(trackerOption) {
 /**
  * The outcome line for a provider that arrived as `--tracker <id>`.
  *
- * D-TRACKER-CLI-SURFACE [PF-029]: the Advanced path prints no end-of-wizard
+ * D-TRACKER-CLI-SURFACE: the Advanced path prints no end-of-wizard
  * summary, and `--tracker` suppresses the wizard step that would otherwise
  * print one, so the CLI-override arm is the only place the selection can
  * surface there. Without this line `devflow init --advanced --tracker jira`
@@ -255,7 +256,7 @@ export function buildTrackerLifecycleIO() {
  *
  * D-TRACKER-CONVERGE: the manifest write and the tracker file-lifecycle owners
  * are ONE unit because their relative order is the invariant, not an
- * implementation detail (PF-015). The manifest write is explicitly failable —
+ * implementation detail. The manifest write is explicitly failable —
  * init must not abort on it — so converging the sentinel ahead of it leaves the
  * two disagreeing in both directions: github→jira writes a sentinel naming a
  * provider the manifest never records, and jira→github removes the sentinel while
@@ -268,7 +269,7 @@ export function buildTrackerLifecycleIO() {
  * taken as a separate argument, so there is exactly one binding and the sentinel
  * cannot name a value other than the one on disk.
  *
- * Every step reports rather than aborts (PF-009's isolation posture): a
+ * Every step reports rather than aborts: a
  * feature-state change must never fail `devflow init`.
  */
 export async function persistManifestThenConvergeTracker(opts) {
@@ -302,7 +303,7 @@ export async function persistManifestThenConvergeTracker(opts) {
         messages.push({ level: 'warn', text });
     // D-TRACKER-PARALLEL: the two owners touch disjoint files — the attempt
     // counters and the sentinel — depend on nothing the other writes, and both
-    // report through TrackerResult instead of throwing (PF-014), so they run
+    // report through TrackerResult instead of throwing, so they run
     // concurrently and their warnings are pushed in a fixed order regardless of
     // which settles first.
     const [rearm, sentinel] = await Promise.all([
@@ -361,7 +362,7 @@ export async function drainDisabledFeatureQueues(opts, io = { drainMemoryQueue,
  * earlier shape rewrote the whole record as a HUD-only fresh install (ambient,
  * memory, learning, knowledge, rules and proxy all `false`, plugins `[]`) while
  * leaving those features' artifacts on disk: the record stopped describing the
- * machine, the next re-init seeded every feature off (ADR-014), and with
+ * machine, the next re-init seeded every feature off, and with
  * memory/learning/knowledge switched by the manifest alone
  * (D-FEATURES-NARROW-ONLY) a HUD install would have really disabled them
  * everywhere. `version` is kept too: --hud-only reinstalls no plugin, and a
@@ -759,7 +760,7 @@ export const initCommand = new Command('init')
     // modePromptShown: true only when the Setup-mode p.select actually ran (i.e. the user
     // was shown a live interactive prompt and made an active choice). Used by
     // shouldRunComplianceStep to preserve the promptless contracts of --recommended and !isTTY
-    // without re-checking the mode name (per PF-029).
+    // without re-checking the mode name.
     let modePromptShown = false;
     let useRecommended;
     if (options.recommended) {
@@ -877,7 +878,7 @@ export const initCommand = new Command('init')
         // ── Recommended path ──
         // B4: compliance wizard step — runs only when the Setup-mode prompt actually ran
         // (modePromptShown=true), preserving the promptless contracts of --recommended and !isTTY.
-        // shouldRunComplianceStep gates on modePromptShown rather than the mode name (PF-029).
+        // shouldRunComplianceStep gates on modePromptShown rather than the mode name.
         // Re-init never routes here (seedManifest !== null → banner path → Advanced), so this path
         // always sees fresh-install defaults.
         let wizardCompliance;
@@ -1131,9 +1132,9 @@ export const initCommand = new Command('init')
             isTTY: process.stdin.isTTY,
             hasCliOverride: cliComplianceOverride !== undefined,
         })) {
-            // runComplianceStep: note with "Current setting:" header (legible on re-init per PF-029),
+            // runComplianceStep: note with "Current setting:" header (legible on re-init),
             // labeled Yes/No select (immune to Enter-through muscle memory), and framework multiselect.
-            // Returns {kind:'cancelled'} on Escape — caller owns the cancel idiom (PF-014).
+            // Returns {kind:'cancelled'} on Escape — caller owns the cancel idiom.
             const complianceStep = await runComplianceStep({
                 seed: { enabled: complianceEnabled, frameworks: complianceFrameworks },
                 prompts: buildClackCompliancePrompts(),
@@ -1187,19 +1188,19 @@ export const initCommand = new Command('init')
         // silently carries the seeded value. The gate stays an explicit predicate call so the
         // documented gate table in attribution-prompts.ts remains the single authority.
         // isTTY is guaranteed true here (the non-TTY guard above exit-1'd); passing it keeps
-        // the promptless contract enforced at the predicate rather than by position (PF-029).
+        // the promptless contract enforced at the predicate rather than by position.
         if (shouldRunAttributionStep({
             // D27-GATE: bind to the resolved mode so all four documented gate-table rows
             // are reachable and the predicate — not lexical placement — enforces Advanced-only.
             // Using useRecommended ? 'recommended' : 'advanced' makes the gate testable from
             // both sides and prevents the Recommended path from accidentally running the step
-            // if this block is ever repositioned (applies PF-029).
+            // if this block is ever repositioned.
             mode: useRecommended ? 'recommended' : 'advanced',
             isTTY: process.stdin.isTTY,
         })) {
             const attributionStep = await runAttributionStep({
                 // attributionSeedFrom keeps the seed a real boolean regardless of the stored
-                // FlagsRecord value type — undefined/null/false all map to false (PF-018).
+                // FlagsRecord value type — undefined/null/false all map to false.
                 seed: attributionSeedFrom(enabledFlags),
                 prompts: buildClackAttributionPrompts(),
             });
@@ -1220,7 +1221,7 @@ export const initCommand = new Command('init')
         /**
          * D40: init applies seeded flag defaults non-interactively. Flags are customized
          * exclusively via `devflow flags`; re-init preserves existing values and adopts
-         * registry defaults only for absent flags (ADR-014). No TUI is opened during init.
+         * registry defaults only for absent flags. No TUI is opened during init.
          */
         {
             const activeCount = countActiveFlags(enabledFlags);
@@ -1474,10 +1475,10 @@ export const initCommand = new Command('init')
         p.log.error(`${error}`);
         process.exit(1);
     }
-    // Converge compliance artifacts (PF-015: always converge, never short-circuit).
+    // Converge compliance artifacts (always converge, never short-circuit).
     // Called unconditionally so that enabling/disabling compliance during init
     // is reflected in the installed artifacts without a separate devflow compliance run.
-    // Wrapped in its own try/catch (PF-009: warn-not-abort).
+    // Wrapped in its own try/catch (warn-not-abort).
     let convergeResult = null;
     try {
         convergeResult = await convergeFromManifest({
@@ -1525,7 +1526,7 @@ export const initCommand = new Command('init')
     }
     // Sweep orphaned *-teams.md workflow command variants left by the Agent Teams
     // refactor. None are ever re-installed, so a blanket sweep is safe on any
-    // install type (the full-install dir wipe only covers full installs). (PF-009)
+    // install type (the full-install dir wipe only covers full installs).
     try {
         for (const f of await fs.readdir(commandsDir)) {
             if (f.endsWith('-teams.md')) {
@@ -1598,6 +1599,7 @@ export const initCommand = new Command('init')
         'dream-procedure.md',
         'lib/staleness.cjs',
         'dream-lock',
+        'decisions-usage-scan.cjs',
     ];
     const hooksDir = path.join(devflowDir, 'scripts', 'hooks');
     for (const legacy of LEGACY_HOOK_FILES) {
@@ -1613,7 +1615,7 @@ export const initCommand = new Command('init')
     const settingsPath = path.join(claudeDir, 'settings.json');
     // === Proxy preflight (when enabled) ===
     // Runs before the settings mutation pass so that proxyEnabled reflects reality
-    // (preflight failure forces it off without aborting init — avoids PF-009).
+    // (preflight failure forces it off without aborting init).
     //
     // Read existing proxy state once to recover the remembered port.
     // Init has no --port option; the remembered port from proxy.json always
@@ -1660,7 +1662,7 @@ export const initCommand = new Command('init')
                     'Routing disabled for this init — run `devflow proxy --enable` after signing in.');
                 proxyEnabled = false;
                 // Write proxy.json disabled so runtime authority converges with the
-                // failed preflight outcome (avoids PF-015). Without this write,
+                // failed preflight outcome. Without this write,
                 // proxy.json stays enabled:true from the prior run, causing
                 // reapplyAgentMapping to write GPT model IDs into agent frontmatter
                 // with no relay — a dormancy inversion.
@@ -1695,7 +1697,7 @@ export const initCommand = new Command('init')
     }
     else {
         // Proxy disabled at entry: if proxy.json exists and is enabled, mark it disabled.
-        // avoids PF-015: runtime authority (proxy.json) must converge with proxyEnabled=false.
+        // Runtime authority (proxy.json) must converge with proxyEnabled=false.
         // Check the Result — write errors are surfaced rather than silently ignored
         // (consistent with the enable branch above).
         if (priorProxyStateResult.ok && priorProxyStateResult.value.enabled) {
@@ -1716,7 +1718,7 @@ export const initCommand = new Command('init')
     // MUST run AFTER the proxy preflight block above: preflight can force proxyEnabled=false
     // on failure, and reapply's dormancy (GPT models materialize only while proxy enabled)
     // depends on the FINAL proxyEnabled value — running earlier would leave GPT model lines
-    // in agent frontmatter after a preflight failure. Per-item failures are non-fatal (avoids PF-009).
+    // in agent frontmatter after a preflight failure. Per-item failures are non-fatal.
     //
     // Init-only optimization: skip reapply when mapping is empty AND proxy is off.
     // An empty mapping means every agent uses its shipped default; the file copy already
@@ -1776,7 +1778,7 @@ export const initCommand = new Command('init')
         // Strip Devflow-managed teammateMode ("auto"). User-set values (e.g. "tmux") are preserved.
         content = stripDevflowTeammateModeFromJson(content);
         // Claude Code flags — convergeFlagsIntoSettings is the single pipeline entry point
-        // (ARCH-H1, applies PF-015/PF-017/ADR-014): fold valued flags and view-mode from
+        // (ARCH-H1): fold valued flags and view-mode from
         // existing settings before strip, then strip all managed keys and apply the folded
         // record. ownedRecord=existingManifest?.features.flags??null distinguishes keys
         // devflow previously wrote (must not be overridden by fold) from keys newly adopted
@@ -1806,7 +1808,7 @@ export const initCommand = new Command('init')
         // would silently delete both their URL and the window-enforcement var.
         // Invariant: proxy.json always reflects the final settled state after the
         // preflight block above — all paths that force proxyEnabled=false also write
-        // proxy.json enabled:false (avoids PF-015), so managedPort == effectivePort.
+        // proxy.json enabled:false, so managedPort == effectivePort.
         if (await proxyJsonExists(devflowDir)) {
             const proxyStateForStrip = await readProxyState(devflowDir);
             const managedPort = proxyStateForStrip.ok ? proxyStateForStrip.value.port : DEFAULT_PROXY_PORT;
@@ -1838,14 +1840,14 @@ export const initCommand = new Command('init')
     // read-modify-write, not a whole-file write: init owns only reviewPublication,
     // and every other key in the file — the hand-written per-repo `tracker`
     // override first among them — is carried from disk, under --reset too
-    // (D-CONFIG-PRESERVE-UNMANAGED in feature-config.ts, avoids PF-071).
+    // (D-CONFIG-PRESERVE-UNMANAGED in feature-config.ts).
     // A malformed or unreadable file is left untouched and named (D-CONFIG-NO-REPAIR).
     if (gitRoot) {
         const configWrite = await writeManagedConfig(gitRoot, {
             // reviewPublication has no prompt, so it is carried over from the
             // reset-gated snapshot rather than re-read from disk: seedConfig is null
             // under --reset, which is what collapses the field back to 'auto' with
-            // every other feature (PF-015 — read the post-gate binding, not the file).
+            // every other feature (read the post-gate binding, not the file).
             reviewPublication: seedConfig?.reviewPublication ?? DEFAULT_CONFIG.reviewPublication,
         });
         if (!configWrite.ok)
@@ -1873,7 +1875,7 @@ export const initCommand = new Command('init')
     // Deterministically ensure .devflow/ is gitignored at the repo root — independent
     // of every feature toggle. The always-on ensure-root-gitignore
     // hook covers projects that never re-run init; this covers the init-time path so a
-    // fresh install never tracks .devflow/. Decoupled from memory (avoids PF-014).
+    // fresh install never tracks .devflow/. Decoupled from memory.
     if (gitRoot) {
         await ensureDevflowGitignore(gitRoot, verbose);
     }
@@ -1932,7 +1934,7 @@ export const initCommand = new Command('init')
                 s.start('Finalizing installation...');
             }
             else {
-                // applies ADR-010: user declined sudo and chose the settings.json fallback.
+                // User declined sudo and chose the settings.json fallback.
                 // securityMode is 'managed' (from resolveSecurityAction or interactive choice) but
                 // managedSettingsConfirmed is false — honor the "fall back to settings.json" label
                 // by writing to user settings. Manifest will record 'user' to match reality.
@@ -1987,7 +1989,7 @@ export const initCommand = new Command('init')
         }
         else {
             // Exhaustive guard — if TypeScript reaches here, a new SecurityMode variant was added
-            // without a matching branch. avoids PF-009 (stale references after rename/refactor).
+            // without a matching branch — guards against stale references after rename/refactor.
             const _exhaustive = securityMode;
             void _exhaustive;
         }
@@ -2038,7 +2040,7 @@ export const initCommand = new Command('init')
     // devflow:compliance is never swept here — no suppression predicate is needed.
     logSummaryLines(formatSweepSummary(installReport));
     // Reference-overlay reporting: the overlay rewrites files inside an installed skill
-    // the user may have shadowed, and reports any unit it had to leave alone (PF-015).
+    // the user may have shadowed, and reports any unit it had to leave alone.
     logSummaryLines(formatOverlaySummary(installReport));
     // Skill-scoping reporting: a deselected skill is deleted and a dormant shadow
     // is inert, and neither is distinguishable from "never installed" on disk.
@@ -2120,7 +2122,7 @@ export const initCommand = new Command('init')
             knowledge: knowledgeEnabled,
             learning: learningEnabled,
             rules: rulesEnabled,
-            // FlagsRecord written directly — key-presence encodes "known" (ADR-014).
+            // FlagsRecord written directly — key-presence encodes "known".
             // view-mode is encoded as flags['view-mode'] (the resolved final value).
             flags: enabledFlags,
             security: securityMode,
@@ -2141,7 +2143,7 @@ export const initCommand = new Command('init')
     // ── Manifest write + tracker selection lifecycle (the ONE call site) ──────
     // persistManifestThenConvergeTracker owns the ordering invariant: the
     // tracker file-lifecycle owners in src/core/tracker.ts converge only against
-    // a provider the manifest actually persisted (D-TRACKER-CONVERGE, PF-015).
+    // a provider the manifest actually persisted (D-TRACKER-CONVERGE).
     const trackerLifecycle = await persistManifestThenConvergeTracker({
         devflowDir,
         claudeDir,

package/dist/cli/commands/install-report.js

@@ -1,6 +1,6 @@
 /**
  * Rendering for the post-install summary — pure functions that turn an
- * {@link InstallReport} into lines, logging nothing (applies ADR-013).
+ * {@link InstallReport} into lines, logging nothing.
  *
  * Its own module rather than a section of init.ts because `devflow tracker --set`
  * renders the same overlay outcomes from a different command. A CLI command
@@ -18,18 +18,18 @@ import { prefixSkillName } from '../../core/plugins.js';
  * shadowed, and a unit it could not refresh is left in one of the states
  * {@link OverlayFailureState} enumerates — running on the previous install, half
  * replaced, absent, or recoverable only from a backup path. None of that is visible from
- * the filesystem at a glance, so all of it reaches the summary — PF-015: a report field
+ * the filesystem at a glance, so all of it reaches the summary — a report field
  * with no render site is not a report, and a render site that flattens four states into
  * one sentence is the same defect one layer up.
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  *
  * @param skillName - Bare name of the skill hosting the generated references,
  *   rendered `devflow:`-prefixed. Defaults to the core constant the build path and
  *   the installer's overlay trigger both read, so the renderer is never a third
- *   independent statement of which skill owns them — the divergence PF-013
- *   describes, where changing the answer means finding every retyped spelling and
- *   nothing fails if one is missed.
+ *   independent statement of which skill owns them — a divergence where changing
+ *   the answer means finding every retyped spelling and nothing fails if one is
+ *   missed.
  */
 export function formatOverlaySummary(report, skillName = SKILL_REFS_SKILL_NAME) {
     const lines = [];
@@ -59,7 +59,7 @@ export function formatOverlaySummary(report, skillName = SKILL_REFS_SKILL_NAME)
  * be told about.
  *
  * Exported because `devflow tracker --set` renders the same states when it aborts
- * on an overlay failure (applies PF-013 — one sentence per state, in one place,
+ * on an overlay failure (one sentence per state, in one place,
  * rather than a second wording that drifts).
  *
  * Exhaustive over {@link OverlayFailureState} — a new state added to the union without a
@@ -103,7 +103,7 @@ export function describeOverlayFailureState(state) {
  * The delta line is emitted only when something moved: on a steady-state re-init
  * the counts are noise.
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  *
  * @param previous - The provider recorded by the PRIOR manifest, or undefined on
  *   a first install. Rendered only when it differs from `provider`.
@@ -144,7 +144,7 @@ export function formatTrackerAssetSummary(input) {
  *     how the selection was assembled, and a duplicate name in either list is a
  *     manifest detail rather than a different selection.
  *
- * Pure function (applies ADR-013).
+ * Pure function.
  *
  * @param previousPlugins - `manifest.plugins` as it stands before this run, or
  *   `null` when there is no prior manifest.
@@ -176,7 +176,7 @@ export function isPluginListUnchanged(previousPlugins, effectivePluginNames) {
  * it is FALSE when there is no prior manifest: a first install removed nothing a
  * user had, so there is no upgrade to explain (design review L2).
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  */
 export function formatSkillScopeSummary(report, pluginListUnchanged) {
     const lines = [];