agent-method 1.5.3 → 1.5.6

package/lib/cli/digest.js

@@ -0,0 +1,66 @@
+/** wwa digest — show management digest and project health. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+export function register(program) {
+  program
+    .command("digest [directory]")
+    .description("Show management digest from Management/DIGEST.md")
+    .option("--status", "Show Management/STATUS.md instead of digest")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const digestPath = join(d, "Management", "DIGEST.md");
+      const statusPath = join(d, "Management", "STATUS.md");
+
+      const target = opts.status ? statusPath : digestPath;
+      const label = opts.status ? "STATUS" : "DIGEST";
+
+      if (!existsSync(target)) {
+        // Try to synthesize from SUMMARY.md or STATE.md
+        const summaryPath = join(d, "SUMMARY.md");
+        const statePath = join(d, "STATE.md");
+
+        if (opts.json) {
+          console.log(
+            JSON.stringify(
+              {
+                error: `Management/${label}.md not found`,
+                hasSummary: existsSync(summaryPath),
+                hasState: existsSync(statePath),
+              },
+              null,
+              2
+            )
+          );
+          return;
+        }
+
+        console.log(`\n  Management/${label}.md not found.\n`);
+        if (existsSync(summaryPath) || existsSync(statePath)) {
+          console.log("  Available alternatives:");
+          if (existsSync(summaryPath))
+            console.log("    - SUMMARY.md (session audit trail)");
+          if (existsSync(statePath))
+            console.log("    - STATE.md (current position + decisions)");
+        }
+        console.log(
+          "\n  To get management reports, use the starter or full template tier:" +
+            "\n    wwa init <type>\n"
+        );
+        return;
+      }
+
+      const content = readFileSync(target, "utf-8");
+
+      if (opts.json) {
+        console.log(JSON.stringify({ file: target, content }, null, 2));
+        return;
+      }
+
+      console.log(content);
+    });
+}

package/lib/cli/docs.js

@@ -0,0 +1,207 @@
+/** wwa docs — show docs coverage and staleness from DOCS-MAP.md. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+export function register(program) {
+  program
+    .command("docs [directory]")
+    .description("Show docs coverage report from .context/DOCS-MAP.md")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const docsMapPath = join(d, ".context", "DOCS-MAP.md");
+
+      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);
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      printReport(report);
+    });
+}
+
+// ---------------------------------------------------------------------------
+// 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("");
+}

package/lib/cli/helpers.js

@@ -3,8 +3,8 @@
  * entry point discovery, output formatting.
  */
 
-import { readFileSync, existsSync } from "node:fs";
-import { resolve, join, dirname } from "node:path";
+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);
@@ -113,6 +113,53 @@ 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
 // ---------------------------------------------------------------------------

package/lib/cli/implement.js

@@ -0,0 +1,159 @@
+/** 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";
+
+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;
+      }
+
+      if (!nextStep) {
+        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"
+        );
+        return;
+      }
+
+      const done = steps.filter((s) => s.status === "done").length;
+      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"
+      );
+    });
+}
+
+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;
+}

package/lib/cli/init.js

@@ -15,6 +15,7 @@ export function register(program) {
     .option("--tier <tier>", "Template tier (starter/full)")
     .option("--runtime <runtime>", "Agent runtime (claude/cursor/all)")
     .option("--profile <profile>", "Integration profile (lite/standard/full)")
+    .option("--onboarding <mode>", "Onboarding mode (greenfield/brownfield/auto)")
     .option("--registry <path>", "Path to feature-registry.yaml")
     .option("--json", "Output as JSON")
     .option(
@@ -89,9 +90,9 @@ export function register(program) {
               name: "runtime",
               message: "Agent runtime:",
               choices: [
-                { name: "Claude Code     — creates CLAUDE.md", value: "claude" },
-                { name: "Cursor          — creates .cursorrules", value: "cursor" },
-                { name: "Other / All     — keeps all entry points", value: "all" },
+                { name: "Claude Code          — creates CLAUDE.md", value: "claude" },
+                { name: "Cursor / Composer    — creates .cursorrules", value: "cursor" },
+                { name: "Other (Gemini, Codex, Cline, Aider, etc.) — creates AGENT.md + all entry points", value: "all" },
               ],
             },
           ]);
@@ -120,20 +121,37 @@ export function register(program) {
               name: "profile",
               message: "Integration profile:",
               choices: [
-                { name: "Standard (Sonnet)   — recommended", value: "standard" },
-                { name: "Lite (Haiku)        — minimal rules, simple projects", value: "lite" },
-                { name: "Full (Opus)         — all rules inline, complex projects", value: "full" },
+                { name: "Standard (Sonnet, GPT-4, Gemini Pro, Codex)  — recommended", value: "standard" },
+                { name: "Lite (Haiku, GPT-3.5, Gemini Flash)          — minimal rules, simple projects", value: "lite" },
+                { name: "Full (Opus, o1, Gemini Ultra)                — all rules inline, complex projects", value: "full" },
               ],
             },
           ]);
           answers.profile = profile;
         }
 
+        if (!opts.onboarding) {
+          const { onboarding } = await inquirer.prompt([
+            {
+              type: "list",
+              name: "onboarding",
+              message: "Project scenario:",
+              choices: [
+                { name: "Greenfield         — new project, no existing code", value: "greenfield" },
+                { name: "Brownfield         — existing codebase, add methodology", value: "brownfield" },
+                { name: "Agent decides      — let the agent detect on first session", value: "auto" },
+              ],
+            },
+          ]);
+          answers.onboarding = onboarding;
+        }
+
         projectTypeArg = projectTypeArg || answers.type;
         directory = directory || answers.dir;
         opts.runtime = opts.runtime || answers.runtime;
         opts.tier = opts.tier || answers.tier;
         opts.profile = opts.profile || answers.profile;
+        opts.onboarding = opts.onboarding || answers.onboarding;
       }
 
       const projectType = resolveProjectType(projectTypeArg);
@@ -144,6 +162,7 @@ export function register(program) {
         tier: opts.tier || "starter",
         runtime: opts.runtime || "all",
         profile: opts.profile || "standard",
+        onboarding: opts.onboarding || "auto",
         registryPath: opts.registry,
       });
     });

package/lib/cli/plan.js

@@ -0,0 +1,128 @@
+/** wwa plan — display current plan status. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { findEntryPoint } from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("plan [directory]")
+    .description("Display current plan status from PLAN.md")
+    .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 in current directory.\n" +
+            "Run 'wwa init' to set up methodology files, or specify a directory."
+        );
+        process.exit(1);
+      }
+
+      const content = readFileSync(planPath, "utf-8");
+      const parsed = parsePlan(content);
+
+      // Also read STATE.md for current position
+      const statePath = join(d, "STATE.md");
+      let position = null;
+      if (existsSync(statePath)) {
+        const stateContent = readFileSync(statePath, "utf-8");
+        position = extractPosition(stateContent);
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify({ position, plan: parsed }, null, 2));
+      } else {
+        if (position) {
+          console.log(`\n  Current position:`);
+          console.log(`    Phase:  ${position.phase}`);
+          console.log(`    Status: ${position.status}`);
+          if (position.next) console.log(`    Next:   ${position.next}`);
+        }
+
+        console.log(`\n  Plan: ${parsed.title}`);
+
+        if (parsed.objective) {
+          console.log(`\n  Objective: ${parsed.objective}`);
+        }
+
+        if (parsed.steps.length > 0) {
+          const done = parsed.steps.filter((s) => s.status === "done").length;
+          const total = parsed.steps.length;
+          console.log(`\n  Progress: ${done}/${total} steps complete`);
+          console.log("");
+
+          for (const step of parsed.steps) {
+            const icon = step.status === "done" ? "[x]" : "[ ]";
+            console.log(`    ${icon} Step ${step.num}: ${step.deliverable}`);
+          }
+        }
+
+        if (parsed.verification.length > 0) {
+          const passed = parsed.verification.filter((v) => v.checked).length;
+          console.log(
+            `\n  Verification: ${passed}/${parsed.verification.length} criteria met`
+          );
+        }
+
+        console.log("");
+      }
+    });
+}
+
+function parsePlan(content) {
+  const lines = content.split("\n");
+
+  // Extract title from first heading
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1].trim() : "Unknown";
+
+  // Extract phase heading
+  const phaseMatch = content.match(/^##\s+(.+)$/m);
+  const phase = phaseMatch ? phaseMatch[1].trim() : title;
+
+  // Extract objective paragraph
+  let objective = null;
+  const objMatch = content.match(/###\s+Objective\s*\n\s*\n(.+?)(?:\n\n|\n###)/s);
+  if (objMatch) {
+    objective = objMatch[1].trim().split("\n")[0];
+  }
+
+  // Parse implementation table
+  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(),
+      status: m[3].trim().toLowerCase(),
+    });
+  }
+
+  // Parse verification criteria
+  const verification = [];
+  const verPattern = /- \[([ x])\]\s*(.+)/g;
+  while ((m = verPattern.exec(content)) !== null) {
+    verification.push({
+      checked: m[1] === "x",
+      criterion: m[2].trim(),
+    });
+  }
+
+  return { title, phase, objective, steps, verification };
+}
+
+function extractPosition(stateContent) {
+  const phase =
+    stateContent.match(/\*\*Phase\*\*:\s*(.+)/)?.[1]?.trim() || "Unknown";
+  const status =
+    stateContent.match(/\*\*Status\*\*:\s*(.+)/)?.[1]?.trim() || "Unknown";
+  const next =
+    stateContent.match(/\*\*Next\*\*:\s*(.+)/)?.[1]?.trim() || null;
+  return { phase, status, next };
+}