devflow-kit 2.0.1 → 2.2.0

package/dist/core/manifest.js

@@ -1,10 +1,69 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { LEGACY_PLUGIN_NAMES, DELETED_PLUGIN_NAMES } from './plugins.js';
-import { VIEW_MODES } from './flags.js';
+import { VIEW_MODES, migrateLegacyFlagsToRecord, sanitizeFlagsRecord, } from './flags.js';
 import { normalizeComplianceFeature } from './compliance.js';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+/**
+ * Parse features.flags across the three on-disk shapes; reports whether a heal is owed.
+ *
+ * Case A: string[]       — legacy format, migrated to FlagsRecord (fold viewMode in).
+ * Case B: object         — already a FlagsRecord, fold lingering viewMode if present.
+ * Case C: missing/other  — default to empty record.
+ *
+ * The returned `legacy` flag is true only for Case A (array). Callers use it as the
+ * flags-specific clause of needsHeal, keeping the legacy-artifact knowledge in one
+ * place and letting needsHeal derive from the parse result instead of re-inspecting
+ * features.flags after the fact.
+ */
+function parseManifestFlags(features, knownFlags) {
+    const rawFlags = features.flags;
+    if (Array.isArray(rawFlags)) {
+        // Case A: string[] → FlagsRecord migration.
+        // Filter to strings only (malformed elements are silently dropped).
+        const enabledIds = rawFlags.filter(e => typeof e === 'string');
+        // Extract legacyViewMode for the migration fold.
+        const rawViewMode = features.viewMode;
+        const legacyViewMode = typeof rawViewMode === 'string' && VIEW_MODES.includes(rawViewMode)
+            ? rawViewMode
+            : undefined;
+        return { flags: migrateLegacyFlagsToRecord(enabledIds, knownFlags, legacyViewMode), legacy: true };
+    }
+    if (rawFlags !== null && typeof rawFlags === 'object') {
+        // Case B: already a FlagsRecord. Spread to avoid mutating the parsed value.
+        // Single cast: rawFlags is already confirmed to be a non-null, non-array object.
+        // sanitizeFlagsRecord (called by the outer readManifest) validates all values,
+        // dropping invalid ones — so the double assertion is unnecessary here (applies TS-M3).
+        const flagsRecord = { ...rawFlags };
+        // Fold lingering viewMode into flags['view-mode'] when the record lacks a
+        // non-default value (e.g. a manifest written by an older init that stored viewMode
+        // as a separate deprecated field alongside a FlagsRecord with view-mode:null).
+        const rawViewMode = features.viewMode;
+        if (typeof rawViewMode === 'string' && VIEW_MODES.includes(rawViewMode)) {
+            const existing = flagsRecord['view-mode'];
+            if (existing === null || existing === undefined || existing === 'default') {
+                flagsRecord['view-mode'] = rawViewMode;
+            }
+        }
+        return { flags: flagsRecord, legacy: false };
+    }
+    // Case C: missing/malformed → empty record
+    return { flags: {}, legacy: false };
+}
 /**
  * Read and parse the manifest file. Returns null if missing or corrupt.
+ *
+ * Self-heals the following on-disk inconsistencies (applies ADR-014):
+ * - features.kb → features.knowledge rename
+ * - features.decisions → features.learning rename
+ * - features.flags as string[] → FlagsRecord (via migrateLegacyFlagsToRecord)
+ * - features.viewMode folded into flags['view-mode'] and stripped from result
+ * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
+ * - features.proxy absent → false
+ * - features.compliance absent/malformed → {enabled:false, frameworks:[]}
+ *
+ * D39: heal-write failure returns the migrated in-memory manifest (not null).
+ * The on-disk format remains unhealed; next read triggers another attempt.
  */
 export async function readManifest(devflowDir) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
@@ -32,14 +91,27 @@ export async function readManifest(devflowDir) {
         const learning = typeof features.learning === 'boolean' ? features.learning
             : typeof features.decisions === 'boolean' ? features.decisions
                 : false;
-        const needsHeal = features.kb !== undefined || features.decisions !== undefined;
-        const SECURITY_MODES = ['none', 'user', 'managed'];
         // Self-heal: non-string-array or absent knownFlags/knownPlugins → undefined (never partial/garbage)
         const asStringArray = (val) => Array.isArray(val) && val.every(e => typeof e === 'string')
             ? val
             : undefined;
-        const knownFlags = asStringArray(features.knownFlags);
         const knownPlugins = asStringArray(data.knownPlugins);
+        // knownFlags is consumed here for migration; NOT carried into the returned manifest
+        const knownFlags = asStringArray(features.knownFlags);
+        // ── Parse flags ────────────────────────────────────────────────────────────
+        // Delegates to parseManifestFlags (three cases: A=string[], B=object, C=missing).
+        // `flagsWereLegacy` is true only when the on-disk shape was a string[] (Case A),
+        // keeping the needsHeal predicate in lockstep with the parse branch above.
+        const { flags: parsedFlags, legacy: flagsWereLegacy } = parseManifestFlags(features, knownFlags);
+        // PF-023 + D39: sanitize all values; block prototype pollution keys.
+        const sanitizedFlags = sanitizeFlagsRecord(parsedFlags);
+        // needsHeal when any legacy artifact is present on disk
+        const needsHeal = features.kb !== undefined ||
+            features.decisions !== undefined ||
+            flagsWereLegacy ||
+            features.knownFlags !== undefined ||
+            features.viewMode !== undefined;
+        const SECURITY_MODES = ['none', 'user', 'managed'];
         const manifest = {
             version: data.version,
             plugins: data.plugins,
@@ -52,25 +124,34 @@ export async function readManifest(devflowDir) {
                 knowledge,
                 learning,
                 rules: typeof features.rules === 'boolean' ? features.rules : true,
-                flags: Array.isArray(features.flags) ? features.flags : [],
-                knownFlags,
-                viewMode: typeof features.viewMode === 'string' && VIEW_MODES.includes(features.viewMode)
-                    ? features.viewMode
-                    : undefined,
+                flags: sanitizedFlags,
+                // knownFlags and viewMode are NOT carried into the result.
+                // - knownFlags: its semantic (which flags are "known") is encoded in
+                //   FlagsRecord key-presence (present key = known, absent = new/adopt-on-seed).
+                // - viewMode: folded into flags['view-mode'] above.
+                // Leaving them out prevents them from being echoed back on the next write
+                // and causing a spurious needsHeal on every read.
                 security: typeof features.security === 'string' && SECURITY_MODES.includes(features.security)
                     ? features.security
                     : undefined,
                 // Self-heal: absent proxy field defaults to false (applies ADR-014 self-heal idiom)
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
-                // (applies ADR-014 self-heal idiom; normalizeComplianceFeature is in TOLERANT section)
                 compliance: normalizeComplianceFeature(features.compliance),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,
         };
         if (needsHeal) {
-            await writeManifest(devflowDir, manifest);
+            // D39: wrap the heal-write in its own try/catch so a write failure does NOT
+            // propagate to the caller. The migrated in-memory manifest is returned even
+            // when the on-disk heal fails. The next read will retry the heal.
+            try {
+                await writeManifest(devflowDir, manifest);
+            }
+            catch {
+                // heal-write failed — return migrated in-memory manifest unchanged
+            }
         }
         return manifest;
     }
@@ -79,12 +160,15 @@ export async function readManifest(devflowDir) {
     }
 }
 /**
- * Write manifest to disk. Creates parent directory if needed.
+ * Write manifest to disk atomically. Creates parent directory if needed.
+ *
+ * Uses writeFileAtomicExclusive (tmp+rename) to prevent readers from seeing
+ * partial writes. Applies D34 atomic-write semantics across all manifest updates.
  */
 export async function writeManifest(devflowDir, data) {
     await fs.mkdir(devflowDir, { recursive: true });
     const manifestPath = path.join(devflowDir, 'manifest.json');
-    await fs.writeFile(manifestPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    await writeFileAtomicExclusive(manifestPath, JSON.stringify(data, null, 2) + '\n');
 }
 /**
  * Update a single feature field in the manifest. No-op when no manifest exists.

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

@@ -2,8 +2,8 @@
  * Strip `teammateMode: "auto"` from a freshly parsed copy of the settings JSON.
  * Returns the serialised JSON string (with trailing newline).
  *
- * Pure string→string — matches the pipeline pattern used by stripFlags /
- * stripViewMode so uninstall.ts can chain it without a separate parse/stringify.
+ * Pure string→string — matches the pipeline pattern used by stripFlags so
+ * uninstall.ts can chain it without a separate parse/stringify.
  * Only removes the key when the value is exactly `"auto"`; user-set values
  * (`"tmux"`, `"in-process"`, etc.) are preserved as-is.
  *

package/dist/hud/colors.js

@@ -1,73 +1,9 @@
 /**
- * ANSI color helpers — no dependencies, precompiled escape sequences.
- * Used by HUD components for direct terminal output (not @clack/prompts).
+ * 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
+ * component call sites continue to resolve `../colors.js` without change.
  */
-const ESC = '\x1b[';
-const RESET = `${ESC}0m`;
-export function bold(s) {
-    return `${ESC}1m${s}${RESET}`;
-}
-export function dim(s) {
-    return `${ESC}2m${s}${RESET}`;
-}
-export function red(s) {
-    return `${ESC}31m${s}${RESET}`;
-}
-export function green(s) {
-    return `${ESC}32m${s}${RESET}`;
-}
-export function yellow(s) {
-    return `${ESC}33m${s}${RESET}`;
-}
-export function blue(s) {
-    return `${ESC}34m${s}${RESET}`;
-}
-export function magenta(s) {
-    return `${ESC}35m${s}${RESET}`;
-}
-export function cyan(s) {
-    return `${ESC}36m${s}${RESET}`;
-}
-export function gray(s) {
-    return `${ESC}90m${s}${RESET}`;
-}
-export function white(s) {
-    return `${ESC}37m${s}${RESET}`;
-}
-export function orange(s) {
-    return `${ESC}38;5;208m${s}${RESET}`;
-}
-export function brightRed(s) {
-    return `${ESC}91m${s}${RESET}`;
-}
-export function boldRed(s) {
-    return `${ESC}1;31m${s}${RESET}`;
-}
-export function bgGreen(s) {
-    return `${ESC}42m${s}${RESET}`;
-}
-export function bgYellow(s) {
-    return `${ESC}43m${s}${RESET}`;
-}
-export function bgRed(s) {
-    return `${ESC}41m${s}${RESET}`;
-}
-export function truncate(s, max) {
-    return s.length > max ? s.slice(0, max - 1) + '\u2026' : s;
-}
-// S2 — Terminal-escape and control-character sanitization (HIGH, pre-existing defect).
-//
-// The prior pattern (/\x1b\[[0-9;]*m/g) matched only SGR sequences (colour).
-// The broadened ANSI_PATTERN also covers:
-//   CSI sequences  — \x1b[ ... with intermediate bytes, any final byte
-//   OSC sequences  — \x1b] ... terminated by BEL (\x07) or ST (\x1b\\)
-//   Two-byte C1    — \x1b followed by any single character in the C1 range
-// CTRL_PATTERN removes non-printable C0 control chars that are not TAB (\x09)
-// or standard newlines (\x0a, \x0d).  Together they prevent agent names
-// embedded in model IDs from injecting escape sequences into --list output.
-const ANSI_PATTERN = /\x1b(?:\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
-const CTRL_PATTERN = /[\x00-\x08\x0b-\x1f\x7f]/g;
-export function stripAnsi(s) {
-    return s.replace(ANSI_PATTERN, '').replace(CTRL_PATTERN, '');
-}
+export { bold, dim, red, green, yellow, blue, magenta, cyan, gray, white, orange, brightRed, boldRed, bgGreen, bgYellow, bgRed, inverse, truncate, stripAnsi, } from '../core/ansi.js';
 //# sourceMappingURL=colors.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "build:mds": "npx tsx scripts/build-mds.ts",
     "dev": "tsc --watch",
     "cli": "node dist/cli.js",
-    "prepublishOnly": "rm -rf dist && npm run build:cli && npm run build:mds",
+    "prepublishOnly": "rm -rf dist && npm run build:cli && npm run build:mds && chmod +x dist/cli.js",
     "version:bump": "npx tsx scripts/bump-version.ts",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/assets/agents/skim.md

@@ -9,7 +9,7 @@ skills:
 
 # Skim Agent
 
-You are a codebase orientation specialist. You use `npx rskim` exclusively for code exploration — never Grep, Glob, or manual file searches. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
+You are a codebase orientation specialist. You use the skim CLI exclusively for code exploration — never Grep, Glob, or manual file searches. Prefer the `skim` binary when on PATH (`command -v skim`); fall back to `npx rskim`. Examples below show `npx rskim` — substitute `skim` when available. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
 
 ## Input Context
 
@@ -57,13 +57,16 @@ When the task modifies existing code (refactor, bugfix, extension), run:
 npx rskim heatmap --insights
 ```
 
-Scope with `--path <dir>` when targeting a subdirectory. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
+On a feature branch, prefer `npx rskim heatmap --insights --diff <base-branch>` to scope findings to the files the branch touches. Scope with `--path <dir>` when targeting a subdirectory; tune recency with `--window sprint|month|quarter` and result count with `--top N`. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
 
 ### Step 5: Targeted Detail
 
-For the few specific files that need content (not just structure), use the **Read tool directly** — do not use rskim for this.
+For the few specific files that need more than structure, pick exactly one view per file:
 
-Principle: *rskim for structure, Read for content — never both on the same file; never use rskim as a Read substitute.*
+- Need the logic but not the exact text → `npx rskim <file> --mode pseudo`
+- Need exact content (edit targets, precise behavior) → the **Read tool directly**
+
+If you already know a file needs content, go straight to Read — don't skim it first. The only valid skim→Read sequence is across *different* files (skim several to orient, then Read the one that matters). Skimming and then Reading the same file pays for it twice.
 
 ### Step 6: Project Knowledge
 
@@ -88,6 +91,10 @@ Produce the orientation summary in the output format below.
 | `--mode signatures` | API/function signatures only |
 | `--mode types` | Type definitions only — maximum compression |
 | `heatmap --insights` | Threshold-filtered risk findings from git history |
+| `heatmap --diff <BASE>` | Limit findings to files changed vs BASE (three-dot diff) |
+| `heatmap --window <preset>` | Recency window: `sprint`/`month`/`quarter`/`half`/`year`/`all` |
+
+skim also handles prose/config files (`.md`, `.json`, `.yaml`, `.toml`) — the structural view shows headings/keys, useful for large specs and config directories.
 
 ## Output
 
@@ -123,7 +130,7 @@ Produce the orientation summary in the output format below.
 ## Principles
 
 1. **Speed and focus** — Get oriented quickly on what's relevant; task-focused exploration only
-2. **rskim for structure, Read for content** — never both on the same file
+2. **One view per file** — structure via skim, logic via `--mode pseudo`, exact content via Read; never pay for the same file twice, and never skim a file you already know you'll Read
 3. **Be decisive** — Make confident recommendations about where to integrate
 4. **Token efficiency** — Use rskim token budgets and stats to show compression ratio
 

package/src/assets/scripts/hooks/assets/orchestrator-charter.md

@@ -16,6 +16,7 @@ Stays mainline (judgment work): conversation, decisions, routing, synthesizing a
 
 Operating rules:
 - Decompose mainline. Subagents cannot spawn subagents — you own task breakdown, then delegate leaf tasks.
+- Subagents see none of this conversation. Make every delegation self-contained: goal, constraints, relevant session decisions and facts, exact paths. A deliverable that draws on the conversation (issue, PR, report) needs the substance in the prompt — not a pointer to it.
 - Parallelize independent delegations in one message. Git operations stay sequential.
 - Feature knowledge (direct delegations only — workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass matching KNOWLEDGE.md content as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge (sonnet) to refresh that KB.
 - Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with the full plan. Do not pause to ask.