devflow-kit 1.8.3 → 2.0.1

package/dist/cli/commands/knowledge/index.js

@@ -0,0 +1,25 @@
+/**
+ * devflow knowledge — per-feature knowledge base management.
+ * Thin router that delegates to list (read-only) and toggle (enable/disable/status).
+ *
+ * The heavy CRUD subcommands (create/check/refresh/remove) are deleted — knowledge
+ * bases are created automatically via write-through (knowledge_writeback MDS partial).
+ */
+import { Command } from 'commander';
+import { handleToggle } from './toggle.js';
+import { handleList } from './list.js';
+export const knowledgeCommand = new Command('knowledge')
+    .description('Manage per-feature knowledge bases')
+    .option('--enable', 'Enable per-feature knowledge bases')
+    .option('--disable', 'Disable per-feature knowledge bases')
+    .option('--status', 'Show knowledge base feature status')
+    .action(async (options) => {
+    await handleToggle(options);
+});
+knowledgeCommand
+    .command('list')
+    .description('List all feature knowledge bases')
+    .action(async () => {
+    await handleList();
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/commands/knowledge/list.js

@@ -0,0 +1,115 @@
+/**
+ * devflow knowledge list — list feature knowledge bases.
+ *
+ * Reads .devflow/features/index.md directly (write-through cache), or falls back
+ * to globbing KNOWLEDGE.md frontmatter when index.md is absent or empty. Freshness
+ * comes from verify-against-code at read time in the consuming workflow.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+import { getGitRoot } from '../../../core/git.js';
+import { getFeaturesDir } from '../../../core/project-paths.js';
+/**
+ * Parse entries from index.md lines.
+ * Line format: `- **{slug}** — {areas} — {Use-when description}`
+ */
+function parseIndexMd(content) {
+    const entries = [];
+    for (const line of content.split('\n')) {
+        const m = line.match(/^-\s+\*\*([^*]+)\*\*\s+—\s+([^—]+)\s+—\s+(.+)$/);
+        if (m) {
+            entries.push({ slug: m[1].trim(), areas: m[2].trim(), description: m[3].trim() });
+        }
+    }
+    return entries;
+}
+/**
+ * Parse the slug and description from a KNOWLEDGE.md file's YAML frontmatter.
+ * Returns null when frontmatter is absent or unparseable.
+ */
+function parseFrontmatter(content) {
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch)
+        return null;
+    const fm = fmMatch[1];
+    const get = (key) => {
+        const m = fm.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+        return m ? m[1].trim().replace(/^"(.*)"$/, '$1') : '';
+    };
+    const getArr = (key) => {
+        const m = fm.match(new RegExp(`^${key}:\\s*\\[([^\\]]+)\\]`, 'm'));
+        if (!m)
+            return [];
+        return m[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, ''));
+    };
+    const slug = get('feature');
+    const name = get('name');
+    const description = get('description');
+    const directories = getArr('directories');
+    if (!slug)
+        return null;
+    return { slug, name, description, directories };
+}
+/**
+ * Resolve the git root for the current directory, falling back to cwd.
+ */
+async function getWorktreePath() {
+    return (await getGitRoot()) ?? process.cwd();
+}
+export async function handleList() {
+    p.intro(color.cyan('Feature Knowledge Bases'));
+    const worktreePath = await getWorktreePath();
+    const featuresDir = getFeaturesDir(worktreePath);
+    const indexMdPath = path.join(featuresDir, 'index.md');
+    let entries = [];
+    // Try index.md cache first
+    try {
+        const indexContent = await fs.readFile(indexMdPath, 'utf-8');
+        entries = parseIndexMd(indexContent);
+    }
+    catch {
+        /* index.md absent — fall through to frontmatter glob */
+    }
+    // Fallback: glob features/*/KNOWLEDGE.md and parse frontmatter
+    if (entries.length === 0) {
+        try {
+            const slugDirs = await fs.readdir(featuresDir, { withFileTypes: true });
+            for (const dirent of slugDirs) {
+                if (!dirent.isDirectory() || dirent.name.startsWith('.'))
+                    continue;
+                const kbPath = path.join(featuresDir, dirent.name, 'KNOWLEDGE.md');
+                try {
+                    const kbContent = await fs.readFile(kbPath, 'utf-8');
+                    const fm = parseFrontmatter(kbContent);
+                    if (fm) {
+                        entries.push({
+                            slug: fm.slug,
+                            areas: fm.directories.join(', ') || dirent.name,
+                            description: fm.description || fm.name,
+                        });
+                    }
+                }
+                catch { /* KNOWLEDGE.md absent or unreadable — skip */ }
+            }
+        }
+        catch { /* featuresDir absent — no KBs */ }
+    }
+    if (entries.length === 0) {
+        p.log.info('No feature knowledge bases found. Knowledge bases are created automatically ' +
+            'when workflows (implement, resolve, self-review, explore, debug) detect documented area changes.');
+        p.outro('');
+        return;
+    }
+    p.log.info(`Found ${entries.length} feature knowledge base${entries.length === 1 ? '' : 's'} in ${color.dim(worktreePath)}`);
+    console.log('');
+    for (const entry of entries) {
+        console.log(`  ${color.bold(entry.slug)}`);
+        console.log(`    areas:      ${color.dim(entry.areas)}`);
+        console.log(`    use when:   ${color.dim(entry.description)}`);
+        console.log('');
+    }
+    p.outro('');
+}
+//# sourceMappingURL=list.js.map

package/dist/cli/commands/knowledge/toggle.js

@@ -0,0 +1,84 @@
+/**
+ * Handle the enable/disable/status toggle actions for `devflow knowledge`.
+ *
+ * The sole opt-out mechanism is the feature config `knowledge` field (config-only gate per ADR-001).
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+import { getGitRoot } from '../../../core/git.js';
+import { getDevFlowDirectory } from '../../../targets/claude-code/claude-paths.js';
+import { readManifest, writeManifest } from '../../../core/manifest.js';
+import { updateFeature, isFeatureEnabled } from '../../../core/feature-config.js';
+import { getFeaturesDir } from '../../../core/project-paths.js';
+async function getWorktreePath() {
+    return (await getGitRoot()) ?? process.cwd();
+}
+/** Count KNOWLEDGE.md files present in features/ */
+async function countKnowledgeBases(worktreePath) {
+    const featuresDir = getFeaturesDir(worktreePath);
+    try {
+        const entries = await fs.readdir(featuresDir, { withFileTypes: true });
+        let count = 0;
+        for (const dirent of entries) {
+            if (!dirent.isDirectory() || dirent.name.startsWith('.'))
+                continue;
+            try {
+                await fs.access(path.join(featuresDir, dirent.name, 'KNOWLEDGE.md'));
+                count++;
+            }
+            catch { /* KNOWLEDGE.md absent */ }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function handleToggle(options) {
+    if (!options.enable && !options.disable && !options.status)
+        return;
+    const worktreePath = await getWorktreePath();
+    const devflowDir = getDevFlowDirectory();
+    if (options.enable) {
+        p.intro(color.cyan('Enable Feature Knowledge Bases'));
+        // Update feature config (the sole gate — config-only per ADR-001)
+        await updateFeature(worktreePath, 'knowledge', true);
+        // Update manifest
+        const manifest = await readManifest(devflowDir);
+        if (manifest) {
+            manifest.features.knowledge = true;
+            manifest.updatedAt = new Date().toISOString();
+            await writeManifest(devflowDir, manifest);
+        }
+        p.log.success('Feature knowledge bases enabled');
+        p.log.info('Knowledge bases are created automatically when workflows detect documented area changes.');
+        p.outro('');
+    }
+    else if (options.disable) {
+        p.intro(color.cyan('Disable Feature Knowledge Bases'));
+        // Update feature config (the sole gate — config-only per ADR-001)
+        await updateFeature(worktreePath, 'knowledge', false);
+        // Update manifest
+        const manifest = await readManifest(devflowDir);
+        if (manifest) {
+            manifest.features.knowledge = false;
+            manifest.updatedAt = new Date().toISOString();
+            await writeManifest(devflowDir, manifest);
+        }
+        p.log.success('Feature knowledge bases disabled');
+        p.log.info('Existing knowledge bases preserved. Write-back skipped while disabled.');
+        p.outro('');
+    }
+    else {
+        // options.status
+        p.intro(color.cyan('Feature Knowledge Status'));
+        const enabled = await isFeatureEnabled(worktreePath, 'knowledge');
+        const kbCount = await countKnowledgeBases(worktreePath);
+        p.log.info(`Status: ${enabled ? color.green('enabled') : color.yellow('disabled')}`);
+        p.log.info(`Knowledge bases: ${kbCount}`);
+        p.outro('');
+    }
+}
+//# sourceMappingURL=toggle.js.map

package/dist/cli/commands/learning.js

@@ -0,0 +1,311 @@
+import { Command } from 'commander';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+import { getLearningDir, getLearningTuningConfigPath, getDecisionsLogPath, getDecisionsLockDir, } from '../../core/project-paths.js';
+import { updateFeature, isFeatureEnabled } from '../../core/feature-config.js';
+import { syncManifestFeature } from '../../core/manifest.js';
+import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+import { getGitRoot } from '../../core/git.js';
+import { sweepLegacyDreamMarkers, drainLearningQueue } from '../../core/learning-queue-cleanup.js';
+import { readObservations, warnIfInvalid, } from '../../core/observation-io.js';
+// ---------------------------------------------------------------------------
+// Sub-command handlers
+// ---------------------------------------------------------------------------
+function printUsage() {
+    p.intro(color.bgCyan(color.black(' Learning ')));
+    p.note(`${color.cyan('devflow learning --enable')}      Enable learning (decision + pitfall detection)\n` +
+        `${color.cyan('devflow learning --disable')}     Disable learning (drains queue)\n` +
+        `${color.cyan('devflow learning --status')}      Show learning status\n` +
+        `${color.cyan('devflow learning --list')}        Show all observations\n` +
+        `${color.cyan('devflow learning --configure')}   Configuration wizard\n` +
+        `${color.cyan('devflow learning --clear')}       Truncate decisions log\n` +
+        `${color.cyan('devflow learning --reset')}       Remove all learning state files`, 'Usage');
+    p.outro(color.dim('Detects architectural decisions and known pitfalls from your sessions'));
+}
+/**
+ * Resolve the git root for a state-mutating subcommand, warning and
+ * returning null if the caller isn't inside a git project. `actionSuffix`
+ * completes "Could not resolve git root — {actionSuffix}".
+ */
+async function requireGitRoot(actionSuffix) {
+    const gitRoot = await getGitRoot();
+    if (!gitRoot) {
+        p.log.warn(`Could not resolve git root — ${actionSuffix}`);
+    }
+    return gitRoot;
+}
+async function handleStatus() {
+    const gitRoot = await getGitRoot();
+    if (!gitRoot) {
+        p.log.info('Learning: disabled (not in a git project)');
+        return;
+    }
+    const logPath = getDecisionsLogPath(gitRoot);
+    const enabled = await isFeatureEnabled(gitRoot, 'learning');
+    const { observations, invalidCount } = await readObservations(logPath);
+    const decisionObs = observations.filter(o => o.type === 'decision' || o.type === 'pitfall');
+    const decisions = observations.filter(o => o.type === 'decision');
+    const pitfalls = observations.filter(o => o.type === 'pitfall');
+    const created = decisionObs.filter(o => o.status === 'created');
+    const ready = decisionObs.filter(o => o.status === 'ready');
+    const observing = decisionObs.filter(o => o.status === 'observing');
+    const deprecated = decisionObs.filter(o => o.status === 'deprecated');
+    const lines = [`Learning: ${enabled ? 'enabled' : 'disabled'}`];
+    if (decisionObs.length === 0) {
+        lines.push('Observations: none');
+    }
+    else {
+        lines.push(`Observations: ${decisionObs.length} total`);
+        lines.push(`  Decisions: ${decisions.length}, Pitfalls: ${pitfalls.length}`);
+        lines.push(`  Status: ${observing.length} observing, ${ready.length} ready, ${created.length} promoted, ${deprecated.length} deprecated`);
+    }
+    p.log.info(lines.join('\n'));
+    warnIfInvalid(invalidCount);
+}
+async function handleList() {
+    // Resolve the log from the git root (matches --status, --clear, --reset,
+    // --disable) so `--list` run from a subdirectory finds the real log
+    // instead of a nonexistent one under process.cwd(). Falls back to cwd
+    // when not in a git project, preserving the prior behavior for that case.
+    const gitRoot = await getGitRoot();
+    const logPath = getDecisionsLogPath(gitRoot ?? process.cwd());
+    let logExists = true;
+    try {
+        await fs.access(logPath);
+    }
+    catch {
+        logExists = false;
+    }
+    if (!logExists) {
+        p.log.info('No observations yet. Decisions log not found.');
+        return;
+    }
+    const { observations, invalidCount } = await readObservations(logPath);
+    const filtered = observations.filter(o => o.type === 'decision' || o.type === 'pitfall');
+    if (filtered.length === 0) {
+        p.log.info('No decision/pitfall observations recorded yet.');
+        return;
+    }
+    // Sort by confidence descending
+    filtered.sort((a, b) => b.confidence - a.confidence);
+    p.intro(color.bgCyan(color.black(' Learning Observations ')));
+    for (const obs of filtered) {
+        const typeIcon = obs.type === 'decision' ? 'D' : 'F';
+        const statusIcon = obs.status === 'created' ? color.green('created')
+            : obs.status === 'ready' ? color.yellow('ready')
+                : obs.status === 'deprecated' ? color.dim('deprecated')
+                    : color.dim('observing');
+        const conf = (obs.confidence * 100).toFixed(0);
+        p.log.info(`[${typeIcon}] ${color.cyan(obs.pattern)} (${conf}% | ${obs.observations}x | ${statusIcon})`);
+    }
+    warnIfInvalid(invalidCount);
+    p.outro(color.dim(`${filtered.length} observation(s) total`));
+}
+async function handleConfigure() {
+    p.intro(color.bgCyan(color.black(' Learning Configuration ')));
+    const model = await p.select({
+        message: 'Model for decision detection',
+        options: [
+            { value: 'opus', label: 'Opus', hint: 'Recommended — highest quality for detection + curation judgment' },
+            { value: 'sonnet', label: 'Sonnet', hint: 'Good balance of quality and speed' },
+            { value: 'haiku', label: 'Haiku', hint: 'Fastest, lowest cost' },
+        ],
+    });
+    if (p.isCancel(model)) {
+        p.cancel('Configuration cancelled.');
+        return;
+    }
+    const debugMode = await p.confirm({
+        message: 'Enable debug logging? (logs session content excerpts to ~/.devflow/logs/)',
+        initialValue: false,
+    });
+    if (p.isCancel(debugMode)) {
+        p.cancel('Configuration cancelled.');
+        return;
+    }
+    const scope = await p.select({
+        message: 'Configuration scope',
+        options: [
+            { value: 'project', label: 'Project', hint: 'This project only (.devflow/learning/learning.json)' },
+            { value: 'global', label: 'Global', hint: 'All projects (~/.devflow/learning.json)' },
+        ],
+    });
+    if (p.isCancel(scope)) {
+        p.cancel('Configuration cancelled.');
+        return;
+    }
+    const config = {
+        model,
+        debug: debugMode,
+    };
+    const configJson = JSON.stringify(config, null, 2) + '\n';
+    if (scope === 'global') {
+        const globalDir = getDevFlowDirectory();
+        await fs.mkdir(globalDir, { recursive: true });
+        await fs.writeFile(path.join(globalDir, 'learning.json'), configJson, 'utf-8');
+        p.log.success(`Global config written to ${color.dim(path.join(globalDir, 'learning.json'))}`);
+    }
+    else {
+        const learningDir = getLearningDir(process.cwd());
+        await fs.mkdir(learningDir, { recursive: true });
+        const projectConfigPath = getLearningTuningConfigPath(process.cwd());
+        await fs.writeFile(projectConfigPath, configJson, 'utf-8');
+        p.log.success(`Project config written to ${color.dim(projectConfigPath)}`);
+    }
+    p.outro(color.green('Configuration saved.'));
+}
+async function handleReset() {
+    const gitRoot = await requireGitRoot('reset not performed');
+    if (!gitRoot)
+        return;
+    const lockDir = getDecisionsLockDir(gitRoot);
+    // Ensure the parent directory exists so a second reset (after .devflow/learning/
+    // was already removed) does not fail with ENOENT and emit a false contention error.
+    await fs.mkdir(path.dirname(lockDir), { recursive: true });
+    // Acquire lock to prevent conflict with a concurrent `devflow learning` invocation.
+    // Non-recursive: EEXIST still means genuine contention.
+    try {
+        await fs.mkdir(lockDir);
+    }
+    catch {
+        p.log.error('Learning system is currently running. Try again in a moment.');
+        return;
+    }
+    try {
+        if (process.stdin.isTTY) {
+            const confirm = await p.confirm({
+                message: 'Remove all learning state files? This cannot be undone.',
+                initialValue: false,
+            });
+            if (p.isCancel(confirm) || !confirm) {
+                p.log.info('Reset cancelled.');
+                return;
+            }
+        }
+        // Remove the entire learning directory (contains queue files, content files,
+        // ledger, and tuning config). Single-dir semantics: all learning state lives here.
+        try {
+            await fs.rm(getLearningDir(gitRoot), { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        // Clean legacy dream marker-pipeline stamps from old installs.
+        // Best-effort: sweeps the now-absent dir silently (ENOENT-tolerant).
+        try {
+            await sweepLegacyDreamMarkers(getLearningDir(gitRoot));
+        }
+        catch { /* best effort */ }
+        p.log.success('Reset complete — removed .devflow/learning/ state.');
+    }
+    finally {
+        try {
+            await fs.rmdir(lockDir);
+        }
+        catch { /* already cleaned */ }
+    }
+}
+async function handleClear() {
+    const gitRoot = await requireGitRoot('clear not performed');
+    if (!gitRoot)
+        return;
+    const decisionsLogPath = getDecisionsLogPath(gitRoot);
+    try {
+        await fs.access(decisionsLogPath);
+    }
+    catch {
+        p.log.info('No decisions log to clear.');
+        return;
+    }
+    if (process.stdin.isTTY) {
+        const confirm = await p.confirm({
+            message: 'Clear all decision/pitfall observations? This cannot be undone.',
+            initialValue: false,
+        });
+        if (p.isCancel(confirm) || !confirm) {
+            p.log.info('Clear cancelled.');
+            return;
+        }
+    }
+    await fs.writeFile(decisionsLogPath, '', 'utf-8');
+    // Drain the learning (decisions-detection) queue so stale turns don't process
+    // on the next session — mirrors memory.ts's drain-on-disable behavior for
+    // the sibling memory queue. A mid-run Learning agent whose claimed batch
+    // vanishes aborts without changes — the desired outcome of clearing.
+    await drainLearningQueue(gitRoot);
+    p.log.success('Decisions log cleared.');
+}
+async function handleEnable() {
+    const gitRoot = await requireGitRoot('configuration not updated');
+    if (!gitRoot)
+        return;
+    await updateFeature(gitRoot, 'learning', true);
+    await syncManifestFeature(getDevFlowDirectory(), 'learning', true);
+    p.log.success('Learning enabled — configuration updated');
+    p.log.info(color.dim('Architectural decisions and pitfalls will be detected from your sessions'));
+}
+async function handleDisable() {
+    const gitRoot = await requireGitRoot('configuration not updated');
+    if (!gitRoot)
+        return;
+    await updateFeature(gitRoot, 'learning', false);
+    // Drain the learning (decisions-detection) queue so stale turns don't process
+    // on re-enable — mirrors memory.ts's drain-on-disable behavior for the
+    // sibling memory queue. Unconditional: a mid-run Learning agent whose claimed
+    // batch vanishes aborts without changes — the desired outcome of disabling.
+    await drainLearningQueue(gitRoot);
+    await syncManifestFeature(getDevFlowDirectory(), 'learning', false);
+    p.log.success('Learning disabled — configuration updated');
+}
+export const learningCommand = new Command('learning')
+    .description('Enable or disable learning (decision/pitfall detection + knowledge base)')
+    .option('--enable', 'Enable learning')
+    .option('--disable', 'Disable learning')
+    .option('--status', 'Show learning status and observation counts')
+    .option('--list', 'Show all decision/pitfall observations sorted by confidence')
+    .option('--configure', 'Interactive configuration wizard for learning.json')
+    .option('--clear', 'Truncate decisions log (removes all observations)')
+    .option('--reset', 'Remove all learning state files and artifacts')
+    .action(async (options) => {
+    const knownFlags = [
+        'enable', 'disable', 'status', 'list', 'configure',
+        'clear', 'reset',
+    ];
+    const hasFlag = knownFlags.some((f) => options[f]);
+    if (!hasFlag) {
+        printUsage();
+        return;
+    }
+    // Thin router — dispatch order matches the precedence of the original
+    // inline implementation (status, list, configure, reset, clear, enable,
+    // disable). Each handler owns its own path resolution and I/O.
+    if (options.status) {
+        await handleStatus();
+        return;
+    }
+    if (options.list) {
+        await handleList();
+        return;
+    }
+    if (options.configure) {
+        await handleConfigure();
+        return;
+    }
+    if (options.reset) {
+        await handleReset();
+        return;
+    }
+    if (options.clear) {
+        await handleClear();
+        return;
+    }
+    if (options.enable) {
+        await handleEnable();
+        return;
+    }
+    if (options.disable) {
+        await handleDisable();
+        return;
+    }
+});
+//# sourceMappingURL=learning.js.map

package/dist/cli/commands/legacy-hooks.js

@@ -0,0 +1,40 @@
+// ─── Dream worker hook cleanup ──────────────────────────────────────────────
+//
+// The spawn-dream-worker SessionStart hook belonged to the retired detached
+// dream worker. Decisions processing runs as the directive-spawned Learning agent
+// (session-start-context Section 2), which needs no hook registration of its
+// own. remove/has exist for upgrade cleanup: init and uninstall strip any
+// stale entry left in settings.json by a prior install.
+const SPAWN_DREAM_WORKER_MARKER = 'spawn-dream-worker';
+/**
+ * Remove the spawn-dream-worker hook from settings JSON.
+ * Idempotent — returns unchanged JSON if hook not present.
+ * Preserves all other SessionStart hooks (session-start-memory, session-start-context).
+ */
+export function removeDreamHook(settingsJson) {
+    const settings = JSON.parse(settingsJson);
+    if (!settings.hooks?.SessionStart) {
+        return settingsJson;
+    }
+    const before = settings.hooks.SessionStart.length;
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter((matcher) => !matcher.hooks.some((h) => h.command.includes(SPAWN_DREAM_WORKER_MARKER)));
+    if (settings.hooks.SessionStart.length === before) {
+        return settingsJson;
+    }
+    if (settings.hooks.SessionStart.length === 0) {
+        delete settings.hooks.SessionStart;
+    }
+    if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Check if the spawn-dream-worker hook is present in settings JSON.
+ * Accepts either a JSON string or a parsed Settings object.
+ */
+export function hasDreamHook(input) {
+    const settings = typeof input === 'string' ? JSON.parse(input) : input;
+    return settings.hooks?.SessionStart?.some((matcher) => matcher.hooks.some((h) => h.command.includes(SPAWN_DREAM_WORKER_MARKER))) ?? false;
+}
+//# sourceMappingURL=legacy-hooks.js.map