agent-method 1.5.12

package/lib/cli/docs.js

@@ -0,0 +1,315 @@
+/** wwa docs — show docs coverage, staleness, and dependency graph from DOCS-MAP.md + doc-tokens.yaml. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { loadDocGraph, resolveDocsMapPath } from "../boundaries.js";
+import { printCliReport, writeLastRunSummary } from "./report-helpers.js";
+
+export function register(program) {
+  program
+    .command("docs [directory]")
+    .description("Show docs coverage report from .context/DOCS-MAP.md")
+    .option("--json", "Output as JSON")
+    .option("--deps", "Show document dependency graph from doc-tokens.yaml")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const docsMapPath = await resolveDocsMapPath(d);
+
+      if (!existsSync(docsMapPath)) {
+        if (opts.json) {
+          console.log(JSON.stringify({ error: "No .context/DOCS-MAP.md found" }, null, 2));
+          return;
+        }
+        console.log("\n  No .context/DOCS-MAP.md found.\n");
+        console.log("  This file maps project components to their documentation.");
+        console.log("  Create it by running: wwa init <type>");
+        console.log("  Or ask your agent to populate it during onboarding.\n");
+        return;
+      }
+
+      const content = readFileSync(docsMapPath, "utf-8");
+      const report = parseDocsMap(content, d);
+
+      // Load dependency graph if --deps requested or for JSON enrichment
+      const docGraph = await loadDocGraph(d);
+      if (docGraph) {
+        report.dependencyGraph = summarizeDocGraph(docGraph);
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      const s = report.summary;
+      const summary = [
+        `Docs inventory: ${s.totalDocs} files (${s.existingDocs} exist, ${s.missingDocs} missing).`,
+        `${s.mappedComponents} component mappings, ${s.scaffoldingRules} scaffolding rules.`,
+        s.missingDocs > 0 || s.unmappedDocs > 0 ? "Add or map docs in .context/DOCS-MAP.md." : "Run wwa docs --json for full report.",
+      ].join(" ");
+      const inputRef = `directory=${directory}`;
+      printCliReport({ command: "docs", inputRef, summary });
+      printReport(report);
+      if (opts.deps) {
+        printDepsReport(docGraph);
+      }
+      writeLastRunSummary(d, { command: "docs", inputRef, summary });
+    });
+}
+
+// ---------------------------------------------------------------------------
+// DOCS-MAP.md parsing
+// ---------------------------------------------------------------------------
+
+function parseDocsMap(content, projectDir) {
+  const inventory = [];
+  const mappings = [];
+  const scaffolding = [];
+
+  // Parse docs inventory table
+  const invSection = content.match(
+    /## Docs inventory\s*\n[\s\S]*?\n\|[^\n]+\n\|[-| :]+\n((?:\|[^\n]+\n)*)/
+  );
+  if (invSection) {
+    for (const row of invSection[1].trim().split("\n")) {
+      const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+      if (cols.length >= 3 && !cols[0].startsWith("<!--")) {
+        const path = cols[0];
+        const exists = existsSync(join(projectDir, path));
+        inventory.push({
+          path,
+          purpose: cols[1],
+          sources: cols[2],
+          status: cols[3] || (exists ? "active" : "missing"),
+          exists,
+        });
+      }
+    }
+  }
+
+  // Parse component-to-docs mapping table
+  const mapSection = content.match(
+    /## Component-to-docs mapping\s*\n[\s\S]*?\n\|[^\n]+\n\|[-| :]+\n((?:\|[^\n]+\n)*)/
+  );
+  if (mapSection) {
+    for (const row of mapSection[1].trim().split("\n")) {
+      const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+      if (cols.length >= 3 && !cols[0].startsWith("<!--")) {
+        mappings.push({
+          component: cols[0],
+          documentedIn: cols[1],
+          trigger: cols[2],
+        });
+      }
+    }
+  }
+
+  // Parse scaffolding rules table
+  const scaffSection = content.match(
+    /## Scaffolding rules\s*\n[\s\S]*?\n\|[^\n]+\n\|[-| :]+\n((?:\|[^\n]+\n)*)/
+  );
+  if (scaffSection) {
+    for (const row of scaffSection[1].trim().split("\n")) {
+      const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+      if (cols.length >= 3 && !cols[0].startsWith("<!--")) {
+        scaffolding.push({
+          condition: cols[0],
+          proposedDoc: cols[1],
+          seedFrom: cols[2],
+        });
+      }
+    }
+  }
+
+  // Check which docs actually exist on disk
+  const docsDir = join(projectDir, "docs");
+  const existingDocs = [];
+  const missingDocs = [];
+  const unmappedDocs = [];
+
+  for (const item of inventory) {
+    if (item.exists) {
+      existingDocs.push(item.path);
+    } else {
+      missingDocs.push(item.path);
+    }
+  }
+
+  // Find docs/ files that exist but aren't in the inventory
+  if (existsSync(docsDir)) {
+    const inventoryPaths = new Set(inventory.map((i) => i.path));
+    // Check common docs paths
+    const candidates = ["docs/index.md"];
+    for (const c of candidates) {
+      if (existsSync(join(projectDir, c)) && !inventoryPaths.has(c)) {
+        unmappedDocs.push(c);
+      }
+    }
+  }
+
+  // Count mapped vs unmapped components
+  const mappedComponents = mappings.length;
+  const docsWithMappings = new Set(mappings.map((m) => m.documentedIn));
+
+  return {
+    inventory,
+    mappings,
+    scaffolding,
+    summary: {
+      totalDocs: inventory.length,
+      existingDocs: existingDocs.length,
+      missingDocs: missingDocs.length,
+      unmappedDocs: unmappedDocs.length,
+      mappedComponents,
+      scaffoldingRules: scaffolding.length,
+    },
+    existingDocs,
+    missingDocs,
+    unmappedDocs,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Report output
+// ---------------------------------------------------------------------------
+
+function printReport(report) {
+  const s = report.summary;
+
+  console.log("\n  Docs Coverage Report\n");
+  console.log(`  Docs inventory: ${s.totalDocs} files (${s.existingDocs} exist, ${s.missingDocs} missing)`);
+  console.log(`  Component mappings: ${s.mappedComponents}`);
+  console.log(`  Scaffolding rules: ${s.scaffoldingRules}`);
+
+  if (report.inventory.length > 0) {
+    console.log("\n  Docs inventory:");
+    for (const item of report.inventory) {
+      const icon = item.exists ? "[x]" : "[ ]";
+      const status = item.status === "stale" ? " (stale)" : "";
+      console.log(`    ${icon} ${item.path} — ${item.purpose}${status}`);
+    }
+  }
+
+  if (report.missingDocs.length > 0) {
+    console.log("\n  Missing docs (in inventory but not on disk):");
+    for (const p of report.missingDocs) {
+      console.log(`    - ${p}`);
+    }
+  }
+
+  if (report.unmappedDocs.length > 0) {
+    console.log("\n  Unmapped docs (on disk but not in inventory):");
+    for (const p of report.unmappedDocs) {
+      console.log(`    - ${p}`);
+    }
+  }
+
+  if (report.mappings.length > 0) {
+    console.log("\n  Component mappings:");
+    for (const m of report.mappings) {
+      console.log(`    ${m.component} → ${m.documentedIn}`);
+    }
+  } else {
+    console.log("\n  No component-to-docs mappings defined yet.");
+    console.log("  Ask your agent to populate .context/DOCS-MAP.md during onboarding.");
+  }
+
+  if (report.scaffolding.length > 0) {
+    console.log("\n  Scaffolding rules (auto-propose new docs):");
+    for (const r of report.scaffolding) {
+      console.log(`    When: ${r.condition}`);
+      console.log(`    Create: ${r.proposedDoc}`);
+    }
+  }
+
+  console.log("");
+}
+
+// ---------------------------------------------------------------------------
+// Dependency graph from doc-tokens.yaml
+// ---------------------------------------------------------------------------
+
+function summarizeDocGraph(docGraph) {
+  const nodes = docGraph.nodes || [];
+  const edges = docGraph.edges || [];
+  const edgesByType = {};
+  for (const e of edges) {
+    edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+  }
+  // Find orphans (nodes with no edges)
+  const connected = new Set();
+  for (const e of edges) {
+    connected.add(e.from);
+    connected.add(e.to);
+  }
+  const orphans = nodes.filter((n) => !connected.has(n.path)).map((n) => n.path);
+  return {
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    edgesByType,
+    orphanCount: orphans.length,
+    orphans,
+    lastScan: docGraph.last_scan || null,
+    defaultsApplied: docGraph.defaults_applied || null,
+  };
+}
+
+function printDepsReport(docGraph) {
+  if (!docGraph) {
+    console.log("  No dependency graph found in token registry.");
+    console.log("  Run wwa init or complete brownfield onboarding to generate one.\n");
+    return;
+  }
+
+  const nodes = docGraph.nodes || [];
+  const edges = docGraph.edges || [];
+
+  console.log("  Document Dependency Graph\n");
+  console.log(`  Last scan: ${docGraph.last_scan || "unknown"}`);
+  console.log(`  Defaults: ${docGraph.defaults_applied || "none"}`);
+  console.log(`  Nodes: ${nodes.length}  Edges: ${edges.length}\n`);
+
+  // Group nodes by category
+  const byCategory = {};
+  for (const n of nodes) {
+    const cat = n.category || "unknown";
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push(n);
+  }
+
+  for (const [cat, catNodes] of Object.entries(byCategory)) {
+    console.log(`  [${cat}]`);
+    for (const n of catNodes) {
+      const outgoing = edges.filter((e) => e.from === n.path);
+      const incoming = edges.filter((e) => e.to === n.path);
+      const arrows = outgoing.map((e) => `→ ${e.to} (${e.type})`);
+      console.log(`    ${n.path} — ${n.role}`);
+      if (arrows.length > 0) {
+        for (const a of arrows) {
+          console.log(`      ${a}`);
+        }
+      }
+      if (incoming.length > 0 && outgoing.length === 0) {
+        console.log(`      ← ${incoming.length} incoming edge(s)`);
+      }
+    }
+  }
+
+  // Show orphans
+  const connected = new Set();
+  for (const e of edges) {
+    connected.add(e.from);
+    connected.add(e.to);
+  }
+  const orphans = nodes.filter((n) => !connected.has(n.path));
+  if (orphans.length > 0) {
+    console.log(`\n  Orphan nodes (no edges):`);
+    for (const o of orphans) {
+      console.log(`    - ${o.path}`);
+    }
+  }
+
+  console.log("");
+}

package/lib/cli/helpers.js

@@ -0,0 +1,198 @@
+/**
+ * Shared CLI helpers — project type resolution, registry loading,
+ * entry point discovery, output formatting.
+ */
+
+import { readFileSync, existsSync, writeFileSync, copyFileSync } from "node:fs";
+import { resolve, join, dirname, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Package metadata
+// ---------------------------------------------------------------------------
+
+const _pkg = JSON.parse(
+  readFileSync(resolve(__dirname, "..", "..", "package.json"), "utf-8")
+);
+export const pkg = _pkg;
+
+/** Package root directory (two levels up from lib/cli/). */
+export const packageRoot = resolve(__dirname, "..", "..");
+
+// ---------------------------------------------------------------------------
+// Project type aliases
+// ---------------------------------------------------------------------------
+
+export const PROJECT_TYPE_ALIASES = {
+  context: "analytical",
+  mix: "mixed",
+  all: "mixed",
+  code: "code",
+  data: "data",
+  analytical: "analytical",
+  mixed: "mixed",
+  general: "general",
+};
+
+export const VALID_TYPE_NAMES = Object.keys(PROJECT_TYPE_ALIASES).sort();
+
+export function resolveProjectType(name) {
+  const resolved = PROJECT_TYPE_ALIASES[name.toLowerCase()];
+  if (!resolved) {
+    console.error(
+      `Unknown project type: '${name}'\nValid types: ${VALID_TYPE_NAMES.join(", ")}`
+    );
+    process.exit(1);
+  }
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Lazy module loading
+// ---------------------------------------------------------------------------
+
+let _registryModule = null;
+let _pipelineModule = null;
+
+export async function getRegistry() {
+  if (!_registryModule) {
+    _registryModule = await import("../registry.js");
+  }
+  return _registryModule;
+}
+
+export async function getPipeline() {
+  if (!_pipelineModule) {
+    _pipelineModule = await import("../pipeline.js");
+  }
+  return _pipelineModule;
+}
+
+export async function loadRegistryData(registryPath) {
+  const { loadRegistry } = await getRegistry();
+  try {
+    return loadRegistry(registryPath || undefined);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+
+export function findEntryPoint(directory) {
+  const d = resolve(directory);
+  for (const name of ["CLAUDE.md", ".cursorrules", "AGENT.md"]) {
+    const p = join(d, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function findSessionLog(directory = ".") {
+  const d = resolve(directory);
+  for (const name of ["SESSION-LOG.md", "session-log.md"]) {
+    const p = join(d, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function readMethodVersion(entryPointPath) {
+  const content = readFileSync(entryPointPath, "utf-8");
+  const m = content.match(/method_version:\s*(\S+)/);
+  return m ? m[1] : null;
+}
+
+export function basename_of(filepath) {
+  return filepath.split(/[\\/]/).pop();
+}
+
+// ---------------------------------------------------------------------------
+// Write-safety invariant
+// ---------------------------------------------------------------------------
+
+/** Allowed file extensions for CLI write operations. */
+const SAFE_EXTENSIONS = new Set([".md", ".yaml", ".yml"]);
+
+/**
+ * Returns true if the file path has an allowed extension for writing.
+ * The CLI tool must NEVER modify user source code — only methodology
+ * files (.md) and agent-understanding files (.yaml/.yml) are writable.
+ */
+export function isSafeToWrite(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return SAFE_EXTENSIONS.has(ext);
+}
+
+/**
+ * Write a file, but only if the extension is safe.
+ * Throws if the path would modify user source code.
+ */
+export function safeWriteFile(filePath, content, encoding = "utf-8") {
+  if (!isSafeToWrite(filePath)) {
+    throw new Error(
+      `Safety invariant: refusing to write '${filePath}' — ` +
+      `only .md, .yaml, and .yml files are allowed. ` +
+      `The CLI tool never modifies user source code.`
+    );
+  }
+  writeFileSync(filePath, content, encoding);
+}
+
+/**
+ * Copy a file, but only if the destination extension is safe.
+ * Throws if the destination would modify user source code.
+ */
+export function safeCopyFile(src, dst) {
+  if (!isSafeToWrite(dst)) {
+    throw new Error(
+      `Safety invariant: refusing to copy to '${dst}' — ` +
+      `only .md, .yaml, and .yml files are allowed. ` +
+      `The CLI tool never modifies user source code.`
+    );
+  }
+  copyFileSync(src, dst);
+}
+
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+
+function formatValue(value) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    if (typeof value[0] === "object") {
+      return value.map((v) => JSON.stringify(v)).join(", ");
+    }
+    return `[${value.join(", ")}]`;
+  }
+  if (value && typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+export function outputData(data, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    for (const [key, value] of Object.entries(data)) {
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        console.log(`  ${key}:`);
+        for (const [k2, v2] of Object.entries(value)) {
+          console.log(`    ${k2}: ${formatValue(v2)}`);
+        }
+      } else if (Array.isArray(value)) {
+        console.log(`  ${key}: ${formatValue(value)}`);
+      } else {
+        console.log(`  ${key}: ${value}`);
+      }
+    }
+  }
+}

package/lib/cli/implement.js

@@ -0,0 +1,169 @@
+/** wwa implement — show implementation guidance for the current plan step. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { findEntryPoint } from "./helpers.js";
+import { printCliReport, writeLastRunSummary } from "./report-helpers.js";
+
+export function register(program) {
+  program
+    .command("implement [directory]")
+    .description("Show implementation guidance for the current plan step")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const planPath = join(d, "PLAN.md");
+      if (!existsSync(planPath)) {
+        console.error(
+          "No PLAN.md found. Run 'wwa init' to set up methodology files."
+        );
+        process.exit(1);
+      }
+
+      const planContent = readFileSync(planPath, "utf-8");
+      const steps = parseSteps(planContent);
+      const nextStep = steps.find((s) => s.status !== "done");
+
+      // Read STATE.md for context
+      const statePath = join(d, "STATE.md");
+      let position = null;
+      if (existsSync(statePath)) {
+        const stateContent = readFileSync(statePath, "utf-8");
+        position = extractPosition(stateContent);
+      }
+
+      // Read entry point for scoping and cascade rules
+      const ep = findEntryPoint(directory);
+      let scopingRules = [];
+      let cascadeRules = [];
+      if (ep) {
+        const epContent = readFileSync(ep, "utf-8");
+        scopingRules = extractTableRows(epContent, "Scoping rules");
+        cascadeRules = extractTableRows(epContent, "Dependency cascade");
+      }
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify(
+            { position, nextStep, totalSteps: steps.length, scopingRules, cascadeRules },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      const done = steps.filter((s) => s.status === "done").length;
+      const inputRef = `directory=${directory}`;
+      let summary;
+      if (!nextStep) {
+        summary =
+          "All plan steps complete. Verify criteria (wwa plan), update STATE.md/ROADMAP.md/SUMMARY.md, run wwa close.";
+        printCliReport({ command: "implement", inputRef, summary });
+        console.log("\n  All plan steps are complete.");
+        if (position) {
+          console.log(`  Phase: ${position.phase}`);
+          console.log(`  Status: ${position.status}`);
+        }
+        console.log(
+          "\n  Next actions:" +
+            "\n    - Verify all criteria pass: wwa plan" +
+            "\n    - Close the phase: update STATE.md, ROADMAP.md, SUMMARY.md" +
+            "\n    - Run session close: wwa close\n"
+        );
+        writeLastRunSummary(d, { command: "implement", inputRef, summary });
+        return;
+      }
+
+      summary = `Next step #${nextStep.num}: ${nextStep.deliverable}. ${nextStep.read ? `Read: ${nextStep.read}.` : ""} ${nextStep.produce ? `Produce: ${nextStep.produce}.` : ""} Progress: ${done}/${steps.length} steps.`;
+      printCliReport({ command: "implement", inputRef, summary });
+      console.log(`\n  Implementation guidance`);
+      console.log(`  Progress: ${done}/${steps.length} steps complete\n`);
+
+      console.log(`  Next step: #${nextStep.num}`);
+      console.log(`    Deliverable: ${nextStep.deliverable}`);
+      if (nextStep.read) console.log(`    Read first:  ${nextStep.read}`);
+      if (nextStep.produce) console.log(`    Produce:     ${nextStep.produce}`);
+
+      // Show relevant scoping rules
+      if (scopingRules.length > 0) {
+        console.log(`\n  Relevant scoping rules (from entry point):`);
+        for (const rule of scopingRules.slice(0, 5)) {
+          console.log(`    ${rule}`);
+        }
+      }
+
+      // Show cascade reminders
+      if (cascadeRules.length > 0) {
+        console.log(`\n  Cascade rules to remember:`);
+        for (const rule of cascadeRules.slice(0, 5)) {
+          console.log(`    ${rule}`);
+        }
+      }
+
+      console.log(
+        "\n  After completing this step:" +
+          "\n    - Record any decisions in STATE.md" +
+          "\n    - Check cascade table for dependent updates" +
+          "\n    - Mark step as 'done' in PLAN.md\n"
+      );
+      writeLastRunSummary(d, { command: "implement", inputRef, summary });
+    });
+}
+
+function parseSteps(content) {
+  const steps = [];
+  const stepPattern =
+    /\|\s*(\d+)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(\w+)\s*\|/g;
+  let m;
+  while ((m = stepPattern.exec(content)) !== null) {
+    steps.push({
+      num: parseInt(m[1], 10),
+      deliverable: m[2].trim(),
+      read: m[3].trim(),
+      produce: m[4].trim(),
+      status: m[5].trim().toLowerCase(),
+    });
+  }
+  return steps;
+}
+
+function extractPosition(stateContent) {
+  const phase =
+    stateContent.match(/\*\*Phase\*\*:\s*(.+)/)?.[1]?.trim() || "Unknown";
+  const status =
+    stateContent.match(/\*\*Status\*\*:\s*(.+)/)?.[1]?.trim() || "Unknown";
+  return { phase, status };
+}
+
+function extractTableRows(content, sectionName) {
+  const rows = [];
+  const sectionIdx = content.indexOf(sectionName);
+  if (sectionIdx === -1) return rows;
+
+  const afterSection = content.slice(sectionIdx);
+  const nextHeading = afterSection.indexOf("\n## ", 1);
+  const block =
+    nextHeading > 0 ? afterSection.slice(0, nextHeading) : afterSection;
+
+  for (const line of block.split("\n")) {
+    if (
+      line.startsWith("|") &&
+      !line.startsWith("| Query") &&
+      !line.startsWith("| When") &&
+      !line.startsWith("|--") &&
+      !line.startsWith("|-")
+    ) {
+      const cols = line
+        .split("|")
+        .map((c) => c.trim())
+        .filter((c) => c);
+      if (cols.length >= 2) {
+        rows.push(`${cols[0]} → ${cols[1]}`);
+      }
+    }
+  }
+  return rows;
+}