devflow-kit 3.0.1 → 3.2.0

package/dist/cli/commands/flags.js

@@ -5,14 +5,14 @@
  *   - createFlagsCommand() factory — fresh Commander instance per call;
  *     used by tests; src/cli.ts consumes the flagsCommand singleton export.
  *   - Persist pipeline: convergeFlagsIntoSettings (fold-before-strip) — the
- *     single pipeline entry point shared with init.ts (ARCH-H1, PF-015/017).
- *   - PF-014 (process.exit swallows async work): all error paths set
+ *     single pipeline entry point shared with init.ts (ARCH-H1).
+ *   - process.exit swallows async work: all error paths set
  *     process.exitCode = 1 and return; never call process.exit().
- *   - PF-015 (multi-artifact fan-out): compute record first; settings write
+ *   - Multi-artifact fan-out: compute record first; settings write
  *     and manifest write handled independently with their own error paths.
- *   - PF-022 (applies-on-restart): bare non-TTY invocation prints status table
+ *   - Applies-on-restart: bare non-TTY invocation prints status table
  *     with a note that changes apply on restart.
- *   - PF-023 (validate at the sink): parseFlagValueInput → coerceFlagValue
+ *   - Validate at the sink: parseFlagValueInput → coerceFlagValue
  *     runs inside the core helpers before any write.
  */
 import { Command } from 'commander';
@@ -25,7 +25,7 @@ import { FLAG_REGISTRY, findFlag, convergeFlagsIntoSettings, parseFlagValueInput
 import { readManifest, writeManifest } from '../../core/manifest.js';
 import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { sanitizeCell } from '../tui/cells.js';
-// Static imports for pure view-state helpers — no TTY machinery (applies PF-017).
+// Static imports for pure view-state helpers — no TTY machinery.
 // runFlagsTui stays lazily imported in handleBare to keep TTY module out of
 // --list/--status code paths; buildFlagRows and collectFlagRecord are pure.
 import { buildFlagRows, collectFlagRecord } from '../flags-view/state.js';
@@ -36,7 +36,7 @@ import { buildFlagRows, collectFlagRecord } from '../flags-view/state.js';
  * Malformed JSON → returns `{ ok: false, reason: string }`.
  *
  * NEVER silently falls back to '{}' on malformed JSON — that would clobber the
- * user's settings. The caller must abort with exit code 1 on !ok (avoids PF-023).
+ * user's settings. The caller must abort with exit code 1 on !ok.
  */
 async function readSettingsSafe(settingsPath) {
     let raw;
@@ -51,7 +51,7 @@ async function readSettingsSafe(settingsPath) {
     }
     // REL-M2 + PERF-L4: single parse — validate root shape and return raw string.
     // The plain-object guard catches null/array roots before they reach applyFlags/stripFlags
-    // (applies PF-023 — validate at the sink; early rejection gives actionable error messages).
+    // (validate at the sink; early rejection gives actionable error messages).
     let parsed;
     try {
         parsed = JSON.parse(raw);
@@ -69,18 +69,19 @@ async function readSettingsSafe(settingsPath) {
  *
  * Uses `convergeFlagsIntoSettings` (ARCH-H1: fold-before-strip pipeline) so the
  * invariant lives in the pipeline, not at call sites. This ensures that:
- *   - An externally-set /focus survives unless viewModeExplicit is true (PF-015).
+ *   - An externally-set /focus survives unless viewModeExplicit is true.
  *   - Valued flags not yet claimed by devflow (absent from the manifest record)
  *     have their existing settings values preserved rather than stripped (REG-H1,
- *     SEC-M3, ADR-014).
+ *     SEC-M3).
  *
- * PF-015: settings write and manifest write are evaluated independently.
+ * Settings write and manifest write are evaluated independently.
  * Each failure is reported with its own message and exit code 1.
  * The second write is never skipped due to the first succeeding or failing.
  *
  * Returns a discriminated PersistResult (never a boolean — avoids the two-state
  * lie that cannot express the third "manifest absent" outcome). Success is tracked
- * in LOCALS, never read back off `process.exitCode` (avoids PF-014, PF-015).
+ * in LOCALS, never read back off `process.exitCode`, which is process-wide and
+ * may already have been set by an earlier, unrelated failure.
  */
 async function persistFlagConfig(claudeDir, devflowDir, settingsContent, newRecord, 
 // ARCH-M2 + PERF-L1: caller passes the already-read manifest so this function
@@ -88,14 +89,14 @@ async function persistFlagConfig(claudeDir, devflowDir, settingsContent, newReco
 // = extra write). null → {ok:false,reason:'no-manifest'} (C2 discriminant intact).
 manifest, opts = { viewModeExplicit: false }) {
     // D15: convergeFlagsIntoSettings is the fold-before-strip pipeline entry point
-    // (applies PF-015, PF-017, REG-H1, ARCH-H1). ownedRecord is omitted so the
+    // (REG-H1, ARCH-H1). ownedRecord is omitted so the
     // `newRecord` (the manifest record) serves as the owned set — a key present in
     // the manifest means devflow previously claimed it; absent = never written by
     // devflow, so the existing settings value is adopted.
     const { settings: updatedSettings, record: foldedRecord } = convergeFlagsIntoSettings(settingsContent, newRecord, opts);
-    // PF-015: accumulate each artifact's failure independently; combine at the end.
+    // Accumulate each artifact's failure independently; combine at the end.
     const failed = [];
-    // Settings write — independent error path (avoids PF-015 fan-out).
+    // Settings write — independent error path.
     const settingsPath = path.join(claudeDir, 'settings.json');
     try {
         await writeSettingsFileAtomic(settingsPath, updatedSettings);
@@ -104,9 +105,9 @@ manifest, opts = { viewModeExplicit: false }) {
         p.log.error(`Failed to write settings.json: ${err instanceof Error ? err.message : String(err)}`);
         failed.push('settings');
         process.exitCode = 1;
-        // PF-015: still attempt the manifest write — evaluate each artifact independently.
+        // Still attempt the manifest write — evaluate each artifact independently.
     }
-    // Manifest write — independent error path (avoids PF-015 fan-out).
+    // Manifest write — independent error path.
     // Uses foldedRecord (not newRecord) so adopted values are persisted to the
     // manifest, keeping manifest ↔ settings.json in sync.
     //
@@ -129,17 +130,17 @@ manifest, opts = { viewModeExplicit: false }) {
         failed.push('manifest');
         process.exitCode = 1;
     }
-    // PF-015: OR the locals afterwards — never compose required side effects with ||/&&.
+    // OR the locals afterwards — never compose required side effects with ||/&&.
     return failed.length > 0 ? { ok: false, failed } : { ok: true };
 }
 /**
  * Load manifest and settings.json for the mutating CLI branches.
  *
  * Returns a discriminated result — never exits itself. The dispatcher or handler
- * reports the reason and sets process.exitCode = 1 on failure (avoids PF-014).
- * One shared load path means a fix lands once, not four times (applies PF-017 —
- * the four copies of the same preamble are exactly the "fix on one site, miss the
- * other three" shape).
+ * reports the reason and sets process.exitCode = 1 on failure.
+ * One shared load path means a fix lands once, not four times (the four copies
+ * of the same preamble are exactly the "fix on one site, miss the other three"
+ * shape).
  */
 async function loadFlagContext(claudeDir, devflowDir) {
     const manifest = await readManifest(devflowDir);
@@ -225,7 +226,7 @@ async function handleStatus(devflowDir) {
  * Collapsed from two identical 50-line branches into one handler parameterized by
  * `value: boolean` — the only deltas were the record assignment (true vs false)
  * and one error-message string (--set vs --unset as the suggested alternative)
- * (CPLX-H2 — applies PF-017: one fix lands once, not twice).
+ * (CPLX-H2: one fix lands once, not twice).
  */
 async function handleSetBooleans(claudeDir, devflowDir, ids, value) {
     // Validate: must be known boolean flags only.
@@ -255,7 +256,7 @@ async function handleSetBooleans(claudeDir, devflowDir, ids, value) {
         process.exitCode = 1;
         return;
     }
-    // PF-015: compute new record before any write
+    // Compute new record before any write
     const newRecord = { ...ctx.value.manifest.features.flags };
     for (const flag of flagDefs) {
         newRecord[flag.id] = value;
@@ -283,7 +284,7 @@ async function handleSet(claudeDir, devflowDir, setValues) {
         }
         const id = assignment.slice(0, eqIdx);
         const text = assignment.slice(eqIdx + 1);
-        // Prototype pollution guard (applies PF-023)
+        // Prototype pollution guard
         if (id === '__proto__' || id === 'constructor' || id === 'prototype') {
             p.log.error(`Unknown flag: ${color.bold(id)}`);
             process.exitCode = 1;
@@ -314,7 +315,7 @@ async function handleSet(claudeDir, devflowDir, setValues) {
         process.exitCode = 1;
         return;
     }
-    // PF-015: compute final record before any write
+    // Compute final record before any write
     const newRecord = { ...ctx.value.manifest.features.flags };
     for (const { id, flag, value } of assignments) {
         // null from parseFlagValueInput for literal 'unset' → use neutral value
@@ -355,7 +356,7 @@ async function handleUnset(claudeDir, devflowDir, ids) {
         process.exitCode = 1;
         return;
     }
-    // PF-015: compute new record before any write
+    // Compute new record before any write
     const newRecord = { ...ctx.value.manifest.features.flags };
     for (const flag of flagDefs) {
         newRecord[flag.id] = neutralValueOf(flag);
@@ -373,9 +374,9 @@ async function handleUnset(claudeDir, devflowDir, ids) {
  * Apply a TUI result to disk — the save/persist seam extracted from handleBare.
  *
  * Enables seam testing of the TUI→persist wiring without a real TTY (closes
- * the interactive-surface coverage gap per PF-017(c)). The test drives
+ * the interactive-surface coverage gap). The test drives
  * runFlagsTui with PassThrough streams, feeds its result here, and asserts
- * the whole post-state of both artifacts (manifest + settings.json) per PF-015.
+ * the whole post-state of both artifacts (manifest + settings.json).
  *
  * @param result       TUI result from runFlagsTui — action 'save', 'cancel', or 'abort'.
  * @param freshSettingsContent Settings.json content re-read AFTER the TUI closed
@@ -441,7 +442,8 @@ async function handleBare(claudeDir, devflowDir) {
         // ── Launch TUI ────────────────────────────────────────────────────
         const { runFlagsTui } = await import('../flags-view/index.js');
         // Wrap: runTui rejects on initial-render failure or handler throw.
-        // On rejection: log and bail — no settings write (avoids PF-014 process.exit).
+        // On rejection: log and bail — no settings write; set process.exitCode
+        // rather than calling process.exit(), which would skip pending cleanup.
         let result;
         try {
             result = await runFlagsTui(initialRows);
@@ -458,7 +460,7 @@ async function handleBare(claudeDir, devflowDir) {
             // Code /config) that ran during the session would be silently overwritten by
             // the atomic rename in writeSettingsFileAtomic. Re-reading rebases the flag
             // write onto current content and ensures convergeFlagsIntoSettings sees the
-            // fresh viewMode (applies PF-022 — file state, not config state, is reality).
+            // fresh viewMode (file state, not config state, is reality).
             const freshSettings = await readSettingsSafe(path.join(claudeDir, 'settings.json'));
             if (!freshSettings.ok) {
                 p.log.error(freshSettings.reason);

package/dist/cli/commands/hud.js

@@ -71,7 +71,7 @@ const DEVFLOW_STATUSLINE_SUFFIXES = [
  * any parent directory — so installs from the custom-directory and local-scope era
  * are still recognised. A bare `statusline.sh` (the Claude Code docs' own example,
  * `~/.claude/statusline.sh`) or a path that merely contains a `devflow` segment is
- * the user's (applies ADR-024: remove or replace only what devflow provably wrote).
+ * the user's (remove or replace only what devflow provably wrote).
  * Backslashes are read as slashes so a Windows install is matched the same way. A
  * hand-edited command that is not a string is the user's, as in `endsWithAny`.
  *

package/dist/cli/commands/init-seed.js

@@ -8,7 +8,7 @@
  *
  * All exported functions are pure — no I/O, no side effects.
  *
- * Applies ADR-013: seeding helpers are CLI-init-specific logic, so they live
+ * Seeding helpers are CLI-init-specific logic, so they live
  * beside init.ts in src/cli/commands/ rather than in src/core/ (which holds
  * agent-neutral, target-agnostic utilities).
  */
@@ -36,8 +36,8 @@ export const FEATURE_DEFAULTS = {
  * memory, learning and knowledge are recorded in the manifest alone (a repository
  * only narrows them at read time), so the seed takes no per-repo input at all. Seeding from whatever repo init happens to run in
  * would flip the switch for EVERY repo as a side effect — a stale per-repo
- * `true` would silently re-enable a feature the user turned off. ADR-014's
- * state-aware re-init preserves the prior machine-wide choice, the manifest's.
+ * `true` would silently re-enable a feature the user turned off. State-aware
+ * re-init preserves the prior machine-wide choice, the manifest's.
  */
 export function resolveSeedFeatures(manifest) {
     const ambient = manifest?.features.ambient ?? FEATURE_DEFAULTS.ambient;
@@ -63,7 +63,7 @@ export function resolveSeedFeatures(manifest) {
  * Resolve the flag record for the init seed.
  *
  * Returns a FlagsRecord containing ALL registry flags at their resolved values.
- * FlagsRecord key-presence encodes the "known" concept (ADR-014): present key =
+ * FlagsRecord key-presence encodes the "known" concept: present key =
  * known at last install, absent key = new to this install → adopt default on seed.
  *
  * @param manifestFlags - FlagsRecord from the manifest, or null for fresh install.
@@ -72,11 +72,11 @@ export function resolveSeedFeatures(manifest) {
  * Rules:
  *   - null manifestFlags (fresh install) → all flags at registry defaults
  *   - Entry present                      → keep (coerceFlagValue is applied at read
- *                                          time via sanitizeFlagsRecord; PF-023)
- *   - Entry absent                       → adopt registry default (ADR-014)
+ *                                          time via sanitizeFlagsRecord)
+ *   - Entry absent                       → adopt registry default
  *   - Unknown IDs from old manifest      → pass through unchanged (forward-compat)
  *
- * Applies ADR-014: absent key = unknown to this install → adopt default.
+ * Absent key = unknown to this install → adopt default.
  * view-mode is not set here; resolveInitSeed sets flags['view-mode'] after composing.
  */
 export function resolveSeedFlags(manifestFlags, registry = FLAG_REGISTRY) {
@@ -222,7 +222,7 @@ export function resolveExistingAttributionSuppression(settingsJson) {
  * view-mode priority: existing settings.json (non-default) → manifest → 'default'.
  * suppress-attribution priority: settings.json exact devflow shape → manifest → false.
  * All flag overrides are encoded into flags so all flag state lives in one FlagsRecord
- * (applying PF-015: fold before strip — the fold happens here).
+ * (fold before strip — the fold happens here).
  *
  * This is the single composition point; callers (init.ts hoist block) call this
  * once and pass `seed` down to prompt wiring.
@@ -236,7 +236,7 @@ export function resolveInitSeed(seedManifest, settingsSnapshot, plugins) {
     const flags = resolveSeedFlags(manifestFlags);
     const manifestPlugins = seedManifest !== null ? seedManifest.plugins : null;
     const { workflowPlugins, languagePlugins } = resolveSeedPlugins(manifestPlugins, seedManifest?.knownPlugins, plugins);
-    // Encode the resolved view mode into flags['view-mode'] (PF-015: all flag state in FlagsRecord).
+    // Encode the resolved view mode into flags['view-mode'] (all flag state in FlagsRecord).
     // Priority: existing settings.json (non-default) → flags['view-mode'] from manifest → 'default'.
     // resolveExistingViewMode returns undefined when absent or 'default' — treated as no-opinion.
     const existingViewMode = resolveExistingViewMode(settingsSnapshot);