@imix-js/taproot 0.2.0

package/dist/commands/overview.js

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { loadConfig } from '../core/config.js';
+import { walkHierarchy } from '../core/fs-walker.js';
+import { parseMarkdown } from '../core/markdown-parser.js';
+import { parseImplData } from '../core/impl-reader.js';
+// ─── Extraction helpers ───────────────────────────────────────────────────────
+function readSection(filePath, section) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const doc = parseMarkdown(filePath, content);
+        return doc.sections.get(section)?.rawBody.trim() ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+function readState(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const doc = parseMarkdown(filePath, content);
+        const status = doc.sections.get('status');
+        const match = /\*\*State:\*\*\s*(\S+)/.exec(status?.rawBody ?? '');
+        return match?.[1]?.trim() ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function buildImpl(node) {
+    const filePath = join(node.absolutePath, 'impl.md');
+    const state = readState(filePath);
+    let commitCount = 0;
+    let testCount = 0;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const doc = parseMarkdown(filePath, content);
+        const data = parseImplData(doc);
+        commitCount = data.commits.length;
+        testCount = data.testFiles.length;
+    }
+    catch { /* use defaults */ }
+    return { name: node.name, path: `./${node.relativePath}/impl.md`, state, commitCount, testCount };
+}
+function buildBehaviour(node) {
+    const filePath = join(node.absolutePath, 'usecase.md');
+    const state = readState(filePath);
+    const actorRaw = readSection(filePath, 'actor');
+    const actor = actorRaw.replace(/<[^>]+>/g, '').split('\n')[0]?.trim() ?? '';
+    const implementations = [];
+    const subBehaviours = [];
+    for (const child of node.children) {
+        if (child.marker === 'impl')
+            implementations.push(buildImpl(child));
+        else if (child.marker === 'behaviour')
+            subBehaviours.push(buildBehaviour(child));
+    }
+    return { name: node.name, path: `./${node.relativePath}/usecase.md`, actor, state, implementations, subBehaviours };
+}
+function buildIntent(node) {
+    const filePath = join(node.absolutePath, 'intent.md');
+    const state = readState(filePath);
+    const goalRaw = readSection(filePath, 'goal');
+    // Strip template placeholders, take first sentence
+    const goal = goalRaw.replace(/<[^>]+>/g, '').split(/\.\s+/)[0]?.trim() ?? '';
+    const behaviours = [];
+    for (const child of node.children) {
+        if (child.marker === 'behaviour')
+            behaviours.push(buildBehaviour(child));
+    }
+    return { name: node.name, path: `./${node.relativePath}/intent.md`, goal, state, behaviours };
+}
+// ─── Formatters ───────────────────────────────────────────────────────────────
+function implCounts(b) {
+    let total = b.implementations.length;
+    let complete = b.implementations.filter(i => i.state === 'complete').length;
+    for (const sub of b.subBehaviours) {
+        const c = implCounts(sub);
+        total += c.total;
+        complete += c.complete;
+    }
+    return { total, complete };
+}
+function renderBehaviour(b, indent) {
+    const lines = [];
+    const actor = b.actor ? ` — Actor: ${b.actor}` : '';
+    lines.push(`${indent}- **[${b.name}](${b.path})** \`[${b.state}]\`${actor}`);
+    for (const impl of b.implementations) {
+        const tests = impl.testCount > 0
+            ? `, ${impl.testCount} test${impl.testCount !== 1 ? 's' : ''}`
+            : ' ⚠ no tests';
+        lines.push(`${indent}  - [${impl.name}](${impl.path}) \`[${impl.state}]\` (${impl.commitCount} commit${impl.commitCount !== 1 ? 's' : ''}${tests})`);
+    }
+    for (const sub of b.subBehaviours) {
+        lines.push(...renderBehaviour(sub, indent + '  '));
+    }
+    return lines;
+}
+function formatOverview(intents) {
+    const now = new Date().toISOString().slice(0, 10);
+    const lines = [];
+    lines.push('# Project Overview');
+    lines.push('');
+    lines.push('<!-- Auto-generated by `taproot overview` — do not edit manually -->');
+    lines.push(`<!-- Last updated: ${now} -->`);
+    lines.push('');
+    lines.push('Compact summary for AI agents. Read this before diving into individual taproot documents.');
+    lines.push('');
+    if (intents.length === 0) {
+        lines.push('_No intents defined yet. Run `/tr-intent` to create one._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    let totalBehaviours = 0;
+    let totalImpls = 0;
+    let totalComplete = 0;
+    for (const intent of intents) {
+        lines.push(`## [${intent.name}](${intent.path}) \`[${intent.state}]\``);
+        lines.push('');
+        if (intent.goal) {
+            lines.push(`**Goal:** ${intent.goal}`);
+            lines.push('');
+        }
+        if (intent.behaviours.length === 0) {
+            lines.push('_No behaviours yet._');
+            lines.push('');
+        }
+        else {
+            for (const b of intent.behaviours) {
+                lines.push(...renderBehaviour(b, ''));
+                const c = implCounts(b);
+                totalBehaviours++;
+                totalImpls += c.total;
+                totalComplete += c.complete;
+                // count sub-behaviours toward totals
+                const countSubs = (sub) => {
+                    totalBehaviours++;
+                    for (const s of sub.subBehaviours)
+                        countSubs(s);
+                };
+                for (const sub of b.subBehaviours)
+                    countSubs(sub);
+            }
+            lines.push('');
+        }
+    }
+    lines.push('---');
+    lines.push(`${intents.length} intent${intents.length !== 1 ? 's' : ''} · ` +
+        `${totalBehaviours} behaviour${totalBehaviours !== 1 ? 's' : ''} · ` +
+        `${totalImpls} implementation${totalImpls !== 1 ? 's' : ''} · ` +
+        `${totalComplete}/${totalImpls} complete`);
+    lines.push('');
+    return lines.join('\n');
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export async function runOverview(options) {
+    const { taprootDir } = options;
+    if (!existsSync(taprootDir))
+        return [];
+    const tree = walkHierarchy(taprootDir);
+    const intents = tree.children
+        .filter(c => c.marker === 'intent')
+        .map(buildIntent);
+    if (intents.length === 0)
+        return [];
+    const content = formatOverview(intents);
+    const outputPath = join(taprootDir, 'OVERVIEW.md');
+    writeFileSync(outputPath, content, 'utf-8');
+    const rel = options.cwd
+        ? outputPath.replace(options.cwd + '/', '').replace(options.cwd + '\\', '')
+        : outputPath;
+    return [`updated  ${rel}`];
+}
+export function registerOverview(program) {
+    program
+        .command('overview')
+        .description('Generate OVERVIEW.md — compact project summary for AI context')
+        .option('--path <path>', 'Taproot root directory (overrides config)')
+        .action(async (options) => {
+        const { config } = loadConfig();
+        const taprootDir = options.path ? resolve(options.path) : config.root;
+        const msgs = await runOverview({ taprootDir });
+        if (msgs.length === 0) {
+            process.stdout.write('No intents found — nothing to summarize.\n');
+        }
+        else {
+            for (const msg of msgs)
+                process.stdout.write(msg + '\n');
+        }
+    });
+}
+//# sourceMappingURL=overview.js.map

package/dist/commands/overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.js","sourceRoot":"","sources":["../../src/commands/overview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AA8BvD,iFAAiF;AAEjF,SAAS,WAAW,CAAC,QAAgB,EAAE,OAAe;IACpD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC7C,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;AACxB,CAAC;AAED,SAAS,SAAS,CAAC,QAAgB;IACjC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,wBAAwB,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;AAC/B,CAAC;AAED,SAAS,SAAS,CAAC,IAAgB;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAChC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QAClC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAC9B,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC,YAAY,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AACpG,CAAC;AAED,SAAS,cAAc,CAAC,IAAgB;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5E,MAAM,eAAe,GAAmB,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAwB,EAAE,CAAC;IAC9C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;aAC/D,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;YAAE,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC,YAAY,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AACtH,CAAC;AAED,SAAS,WAAW,CAAC,IAAgB;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,mDAAmD;IACnD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC7E,MAAM,UAAU,GAAwB,EAAE,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;YAAE,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC,YAAY,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAChG,CAAC;AAED,iFAAiF;AAEjF,SAAS,UAAU,CAAC,CAAoB;IACtC,IAAI,KAAK,GAAG,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC;IACrC,IAAI,QAAQ,GAAG,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,MAAM,CAAC;IAC5E,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC1B,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC;QACjB,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAED,SAAS,eAAe,CAAC,CAAoB,EAAE,MAAc;IAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,KAAK,MAAM,KAAK,EAAE,CAAC,CAAC;IAC7E,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC;YAC9B,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC9D,CAAC,CAAC,aAAa,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,QAAQ,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,WAAW,UAAU,IAAI,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IACvJ,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,OAAyB;IAC/C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;IACnF,KAAK,CAAC,IAAI,CAAC,sBAAsB,GAAG,MAAM,CAAC,CAAC;IAC5C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,2FAA2F,CAAC,CAAC;IACxG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;QACxE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,aAAa,GAAG,CAAC,CAAC;IAEtB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,QAAQ,MAAM,CAAC,KAAK,KAAK,CAAC,CAAC;QACxE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBAClC,KAAK,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;gBACtC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;gBACxB,eAAe,EAAE,CAAC;gBAClB,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC;gBACtB,aAAa,IAAI,CAAC,CAAC,QAAQ,CAAC;gBAC5B,qCAAqC;gBACrC,MAAM,SAAS,GAAG,CAAC,GAAsB,EAAE,EAAE;oBAC3C,eAAe,EAAE,CAAC;oBAClB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,aAAa;wBAAE,SAAS,CAAC,CAAC,CAAC,CAAC;gBAClD,CAAC,CAAC;gBACF,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,aAAa;oBAAE,SAAS,CAAC,GAAG,CAAC,CAAC;YACpD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CACR,GAAG,OAAO,CAAC,MAAM,UAAU,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;QAC/D,GAAG,eAAe,aAAa,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;QACpE,GAAG,UAAU,kBAAkB,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;QAC/D,GAAG,aAAa,IAAI,UAAU,WAAW,CAC1C,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA6C;IAC7E,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,MAAM,IAAI,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC;SAClC,GAAG,CAAC,WAAW,CAAC,CAAC;IAEpB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACnD,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG;QACrB,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,EAAE,EAAE,CAAC;QAC3E,CAAC,CAAC,UAAU,CAAC;IACf,OAAO,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,+DAA+D,CAAC;SAC5E,MAAM,CAAC,eAAe,EAAE,2CAA2C,CAAC;SACpE,MAAM,CAAC,KAAK,EAAE,OAA0B,EAAE,EAAE;QAC3C,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;QAChC,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QACtE,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAC/C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;QACrE,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,GAAG,IAAI,IAAI;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/plan.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+export type Classification = 'afk' | 'hitl';
+export type PlanFormat = 'tree' | 'json';
+export interface PlanCandidate {
+    behaviourPath: string;
+    behaviourName: string;
+    intentName: string;
+    intentGoal: string;
+    specState: string;
+    classification: Classification;
+    classificationReason: string;
+    inProgressImpls: number;
+}
+export interface PlanReport {
+    candidates: PlanCandidate[];
+    allImplemented: boolean;
+}
+export declare function runPlan(options: {
+    path?: string;
+    cwd?: string;
+}): Promise<PlanReport>;
+export declare function formatPlan(report: PlanReport, format: PlanFormat): string;
+export declare function registerPlan(program: Command): void;

package/dist/commands/plan.js

@@ -0,0 +1,167 @@
+import { readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { loadConfig } from '../core/config.js';
+import { walkHierarchy } from '../core/fs-walker.js';
+import { parseMarkdown } from '../core/markdown-parser.js';
+// ─── State reading ────────────────────────────────────────────────────────────
+function readState(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const doc = parseMarkdown(filePath, content);
+        const match = /\*\*State:\*\*\s*(\S+)/.exec(doc.sections.get('status')?.rawBody ?? '');
+        return match?.[1]?.trim() ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function readGoal(intentPath) {
+    try {
+        const content = readFileSync(intentPath, 'utf-8');
+        const doc = parseMarkdown(intentPath, content);
+        const goalBody = doc.sections.get('goal')?.rawBody ?? '';
+        return goalBody.replace(/<[^>]+>/g, '').split(/\.\s+/)[0]?.trim() ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+// ─── Classification ───────────────────────────────────────────────────────────
+function classify(specState, hasInProgressImpls) {
+    if (specState === 'specified') {
+        return { classification: 'afk', reason: 'spec is complete and unambiguous' };
+    }
+    if (specState === 'implemented' && hasInProgressImpls) {
+        return { classification: 'afk', reason: 'spec is done; existing implementation is in-progress' };
+    }
+    if (specState === 'proposed') {
+        return { classification: 'hitl', reason: 'spec is only proposed — needs human review before implementing' };
+    }
+    return { classification: 'hitl', reason: `spec state "${specState}" — review before implementing` };
+}
+// ─── Hierarchy walk ───────────────────────────────────────────────────────────
+function collectCandidates(node, intentName, intentGoal) {
+    const candidates = [];
+    if (node.marker === 'intent') {
+        const intentPath = join(node.absolutePath, 'intent.md');
+        const name = node.name;
+        const goal = readGoal(intentPath);
+        for (const child of node.children) {
+            candidates.push(...collectCandidates(child, name, goal));
+        }
+        return candidates;
+    }
+    if (node.marker === 'behaviour') {
+        const implChildren = node.children.filter(c => c.marker === 'impl');
+        const subBehaviours = node.children.filter(c => c.marker === 'behaviour');
+        // Recurse into sub-behaviours
+        for (const sub of subBehaviours) {
+            candidates.push(...collectCandidates(sub, intentName, intentGoal));
+        }
+        const specState = readState(join(node.absolutePath, 'usecase.md'));
+        // Skip deferred behaviours entirely
+        if (specState === 'deferred')
+            return candidates;
+        // Check impl status — exclude deferred impls from completion accounting
+        const activeImplStates = implChildren
+            .map(c => readState(join(c.absolutePath, 'impl.md')))
+            .filter(s => s !== 'deferred');
+        const allComplete = activeImplStates.length > 0 && activeImplStates.every(s => s === 'complete');
+        const inProgressCount = activeImplStates.filter(s => s === 'in-progress').length;
+        // Skip if fully implemented
+        if (allComplete)
+            return candidates;
+        const { classification, reason } = classify(specState, inProgressCount > 0);
+        candidates.push({
+            behaviourPath: node.relativePath,
+            behaviourName: node.name,
+            intentName,
+            intentGoal,
+            specState,
+            classification,
+            classificationReason: reason,
+            inProgressImpls: inProgressCount,
+        });
+        return candidates;
+    }
+    // Root or unknown node — recurse
+    for (const child of node.children) {
+        candidates.push(...collectCandidates(child, intentName, intentGoal));
+    }
+    return candidates;
+}
+// ─── Core logic ───────────────────────────────────────────────────────────────
+export async function runPlan(options) {
+    const { config } = loadConfig(options.cwd);
+    const rootPath = options.path ? resolve(options.path) : config.root;
+    const tree = walkHierarchy(rootPath);
+    const candidates = collectCandidates(tree, '', '');
+    // Sort: AFK before HITL, then alphabetically by path
+    candidates.sort((a, b) => {
+        if (a.classification !== b.classification) {
+            return a.classification === 'afk' ? -1 : 1;
+        }
+        return a.behaviourPath.localeCompare(b.behaviourPath);
+    });
+    return {
+        candidates,
+        allImplemented: candidates.length === 0,
+    };
+}
+// ─── Formatters ───────────────────────────────────────────────────────────────
+export function formatPlan(report, format) {
+    if (format === 'json') {
+        return JSON.stringify(report, null, 2) + '\n';
+    }
+    return formatTree(report);
+}
+function formatTree(report) {
+    const lines = [];
+    if (report.allImplemented) {
+        lines.push('All behaviours are implemented. Consider running `taproot check-orphans` or `/tr-review-all`.');
+        lines.push('');
+        return lines.join('\n');
+    }
+    const afk = report.candidates.filter(c => c.classification === 'afk');
+    const hitl = report.candidates.filter(c => c.classification === 'hitl');
+    if (afk.length > 0) {
+        lines.push('AFK — ready to implement:');
+        for (const c of afk) {
+            lines.push(`  ${c.behaviourPath} [${c.specState}]`);
+            if (c.intentGoal)
+                lines.push(`    Intent: ${c.intentGoal}`);
+            if (c.inProgressImpls > 0)
+                lines.push(`    (${c.inProgressImpls} impl${c.inProgressImpls > 1 ? 's' : ''} in progress)`);
+            lines.push(`    ▸ /tr-implement ${c.behaviourPath}/`);
+        }
+        lines.push('');
+    }
+    if (hitl.length > 0) {
+        lines.push('HITL — needs human input first:');
+        for (const c of hitl) {
+            lines.push(`  ${c.behaviourPath} [${c.specState}]`);
+            if (c.intentGoal)
+                lines.push(`    Intent: ${c.intentGoal}`);
+            lines.push(`    Reason: ${c.classificationReason}`);
+            lines.push(`    ▸ /tr-behaviour ${c.behaviourPath}/usecase.md`);
+        }
+        lines.push('');
+    }
+    const total = report.candidates.length;
+    lines.push(`${total} candidate${total !== 1 ? 's' : ''} (${afk.length} AFK, ${hitl.length} HITL)`);
+    lines.push('');
+    return lines.join('\n');
+}
+// ─── CLI registration ─────────────────────────────────────────────────────────
+export function registerPlan(program) {
+    program
+        .command('plan')
+        .description('Show next implementable behaviours, classified as AFK or HITL')
+        .option('--path <path>', 'Root path (overrides config)')
+        .option('--format <format>', 'Output format: tree, json', 'tree')
+        .action(async (options) => {
+        const report = await runPlan({ path: options.path });
+        process.stdout.write(formatPlan(report, (options.format ?? 'tree')));
+    });
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"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"}

package/dist/commands/sync-check.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+import type { Violation } from '../validators/types.js';
+export declare function registerSyncCheck(program: Command): void;
+export declare function runSyncCheck(options: {
+    path?: string;
+    since?: string;
+    cwd?: string;
+}): Promise<Violation[]>;

package/dist/commands/sync-check.js

@@ -0,0 +1,118 @@
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { loadConfig } from '../core/config.js';
+import { walkHierarchy, flattenTree } from '../core/fs-walker.js';
+import { parseMarkdown } from '../core/markdown-parser.js';
+import { parseImplData } from '../core/impl-reader.js';
+import { fileLastCommitDate, fileMtime, isGitRepo, getRepoRoot } from '../core/git.js';
+import { renderViolations, exitCode } from '../core/reporter.js';
+export function registerSyncCheck(program) {
+    program
+        .command('sync-check')
+        .description('Detect potential staleness between specs and code')
+        .option('--path <path>', 'Root path (overrides config)')
+        .option('--since <date>', 'Only consider changes after this date')
+        .action(async (options) => {
+        const violations = await runSyncCheck({ path: options.path, since: options.since });
+        process.stdout.write(renderViolations(violations));
+        process.exit(exitCode(violations));
+    });
+}
+export async function runSyncCheck(options) {
+    const { config } = loadConfig(options.cwd);
+    const rootPath = options.path ? resolve(options.path) : config.root;
+    const cwd = options.cwd ?? process.cwd();
+    const repoRoot = isGitRepo(cwd) ? (getRepoRoot(cwd) ?? cwd) : null;
+    const tree = walkHierarchy(rootPath);
+    const nodes = flattenTree(tree);
+    const violations = [];
+    for (const node of nodes) {
+        if (node.marker === 'impl') {
+            violations.push(...checkImplStaleness(node, repoRoot));
+        }
+        if (node.marker === 'behaviour') {
+            violations.push(...checkBehaviourSpecDrift(node, repoRoot));
+        }
+    }
+    return violations;
+}
+/**
+ * If source files or test files in an impl.md changed more recently
+ * than the impl.md itself, the implementation record may be stale.
+ */
+function checkImplStaleness(node, repoRoot) {
+    const filePath = join(node.absolutePath, 'impl.md');
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const doc = parseMarkdown(filePath, content);
+    const data = parseImplData(doc);
+    const violations = [];
+    // Get the last commit date for impl.md itself
+    const implCommitDate = repoRoot ? fileLastCommitDate(filePath, repoRoot) : null;
+    const implMtime = fileMtime(filePath);
+    const implDate = implCommitDate ?? implMtime;
+    if (!implDate)
+        return [];
+    const allTrackedFiles = [...data.sourceFiles, ...data.testFiles];
+    for (const trackedFile of allTrackedFiles) {
+        const resolved = repoRoot ? resolve(repoRoot, trackedFile) : null;
+        if (!resolved || !existsSync(resolved))
+            continue;
+        // Check if file was committed more recently than impl.md
+        const fileCommitDate = repoRoot ? fileLastCommitDate(resolved, repoRoot) : null;
+        const fileDate = fileCommitDate ?? fileMtime(resolved);
+        if (!fileDate)
+            continue;
+        if (fileDate > implDate) {
+            violations.push({
+                type: 'warning',
+                filePath,
+                code: 'IMPL_STALE',
+                message: `Source file "${trackedFile}" was modified after impl.md — implementation record may be stale`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * If a usecase.md was edited after its child impl.md files, the
+ * implementations may not reflect the latest spec.
+ */
+function checkBehaviourSpecDrift(node, repoRoot) {
+    const usecasePath = join(node.absolutePath, 'usecase.md');
+    if (!existsSync(usecasePath))
+        return [];
+    const usecaseCommitDate = repoRoot ? fileLastCommitDate(usecasePath, repoRoot) : null;
+    const usecaseMtime = fileMtime(usecasePath);
+    const usecaseDate = usecaseCommitDate ?? usecaseMtime;
+    if (!usecaseDate)
+        return [];
+    const violations = [];
+    for (const child of node.children) {
+        if (child.marker !== 'impl')
+            continue;
+        const implPath = join(child.absolutePath, 'impl.md');
+        if (!existsSync(implPath))
+            continue;
+        const implCommitDate = repoRoot ? fileLastCommitDate(implPath, repoRoot) : null;
+        const implMtime = fileMtime(implPath);
+        const implDate = implCommitDate ?? implMtime;
+        if (!implDate)
+            continue;
+        if (usecaseDate > implDate) {
+            violations.push({
+                type: 'warning',
+                filePath: implPath,
+                code: 'SPEC_UPDATED',
+                message: `usecase.md was updated after impl.md — review implementation against current spec`,
+            });
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=sync-check.js.map

package/dist/commands/sync-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-check.js","sourceRoot":"","sources":["../../src/commands/sync-check.ts"],"names":[],"mappings":"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"}

package/dist/commands/update.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+export declare function refreshLinks(cwd: string, taprootDir: string): string[];
+export declare function runUpdate(options: {
+    cwd?: string;
+    withHooks?: boolean;
+}): Promise<string[]>;
+export declare function registerUpdate(program: Command): void;