agent-method 1.5.12

package/lib/cli/init.js

@@ -0,0 +1,280 @@
+/** wwa init — set up a new project with methodology templates. */
+
+import {
+  resolveProjectType,
+  getPipeline,
+  loadRegistryData,
+  outputData,
+  PROJECT_TYPE_ALIASES,
+  packageRoot,
+  safeCopyFile,
+} from "./helpers.js";
+import { existsSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve as pathResolve } from "node:path";
+
+export function register(program) {
+  program
+    .command("init [project-type] [directory]")
+    .description("Set up a new project with methodology templates")
+    .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("--validate-after", "Run wwa check after init")
+    .option("--auto-configure", "Use defaults for optional settings (boundaries enabled, standard paths)")
+    .option("--project-name <name>", "Project name for entry point")
+    .option("--description <text>", "Short project description for entry point")
+    .option(
+      "--describe",
+      "Only describe what the entry point should contain (no file creation)"
+    )
+    .action(async (projectTypeArg, directory, opts) => {
+      // If describe mode with a type, show entry point spec
+      if (opts.describe && projectTypeArg) {
+        const projectType = resolveProjectType(projectTypeArg);
+        const { generateEntryPoint } = await getPipeline();
+        const reg = await loadRegistryData(opts.registry);
+        const result = generateEntryPoint(projectType, opts.tier || "starter", reg);
+
+        let friendly = projectType;
+        for (const [alias, internal] of Object.entries(PROJECT_TYPE_ALIASES)) {
+          if (internal === projectType && alias !== projectType) {
+            friendly = `${alias} (${projectType})`;
+            break;
+          }
+        }
+
+        console.log(
+          `Entry point specification for: ${friendly} (${opts.tier || "starter"})`
+        );
+        outputData(result, opts.json);
+        return;
+      }
+
+      // Interactive mode — prompt for missing values
+      if (!projectTypeArg || !directory) {
+        const inquirer = (await import("inquirer")).default;
+
+        console.log("\n  wwa — Set up AI-agent-assisted development\n");
+
+        const answers = {};
+
+        if (!projectTypeArg) {
+          const { type } = await inquirer.prompt([
+            {
+              type: "list",
+              name: "type",
+              message: "Project type:",
+              choices: [
+                { name: "Code            — software project", value: "code" },
+                { name: "Data            — data index/querying", value: "data" },
+                { name: "Analytical      — prompts, chains, evaluation", value: "context" },
+                { name: "Mixed           — multiple types combined", value: "mix" },
+                { name: "General         — universal rules only", value: "general" },
+              ],
+            },
+          ]);
+          answers.type = type;
+        }
+
+        if (!directory) {
+          const { dir } = await inquirer.prompt([
+            {
+              type: "input",
+              name: "dir",
+              message: "Project directory:",
+              default: ".",
+            },
+          ]);
+          answers.dir = dir;
+        }
+
+        if (!opts.runtime) {
+          const { runtime } = await inquirer.prompt([
+            {
+              type: "list",
+              name: "runtime",
+              message: "Agent runtime:",
+              choices: [
+                { 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" },
+              ],
+            },
+          ]);
+          answers.runtime = runtime;
+        }
+
+        if (!opts.tier) {
+          const { tier } = await inquirer.prompt([
+            {
+              type: "list",
+              name: "tier",
+              message: "Template tier:",
+              choices: [
+                { name: "Starter (7 files)   — recommended for most projects", value: "starter" },
+                { name: "Full (11+ files)    — complex or long-running projects", value: "full" },
+              ],
+            },
+          ]);
+          answers.tier = tier;
+        }
+
+        if (!opts.profile) {
+          const { profile } = await inquirer.prompt([
+            {
+              type: "list",
+              name: "profile",
+              message: "Integration profile:",
+              choices: [
+                { 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;
+        }
+
+        // Phase 7q: Optional project name and description (skip if --auto-configure or flags set)
+        if (!opts["project-name"] && !opts.autoConfigure) {
+          const { projectName } = await inquirer.prompt([
+            {
+              type: "input",
+              name: "projectName",
+              message: "Project name (for entry point):",
+              default: "My project",
+            },
+          ]);
+          answers.projectName = projectName;
+        }
+        if (!opts.description && !opts.autoConfigure) {
+          const { description } = await inquirer.prompt([
+            {
+              type: "input",
+              name: "description",
+              message: "Short project description (1 line):",
+              default: "AI-agent-assisted project using wwa methodology.",
+            },
+          ]);
+          answers.description = description;
+        }
+
+        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;
+        opts.projectName = opts["project-name"] || answers.projectName;
+        opts.description = opts.description || answers.description;
+      }
+
+      const projectType = resolveProjectType(projectTypeArg);
+
+      // Phase 7r: Brownfield onboarding questionnaire (project purpose, audience, spec location)
+      // Always run when onboarding=brownfield and not auto-configured, even if other args were provided.
+      if (opts.onboarding === "brownfield" && !opts.autoConfigure && !opts.brownfieldQuestionnaire) {
+        const inquirer = (await import("inquirer")).default;
+        const brownfieldAnswers = await inquirer.prompt([
+          {
+            type: "list",
+            name: "projectPurpose",
+            message: "What is this project for?",
+            choices: [
+              { name: "Review / audit", value: "review" },
+              { name: "Production / ongoing development", value: "production" },
+              { name: "Case study / methodology validation", value: "case study" },
+              { name: "Other", value: "other" },
+            ],
+          },
+          {
+            type: "list",
+            name: "audience",
+            message: "Who is the primary audience?",
+            choices: [
+              { name: "Reviewers (read-only)", value: "reviewers" },
+              { name: "Maintainers (editing)", value: "maintainers" },
+              { name: "Both", value: "both" },
+            ],
+          },
+          {
+            type: "list",
+            name: "specLocation",
+            message: "Is the methodology spec local or remote?",
+            choices: [
+              { name: "Local (in this repo)", value: "local" },
+              { name: "Remote (external reference)", value: "remote" },
+            ],
+          },
+        ]);
+        opts.brownfieldQuestionnaire = brownfieldAnswers;
+      }
+
+      // Setup mode
+      const { initProject } = await import("../init.js");
+      await initProject(projectType, directory, {
+        tier: opts.tier || "starter",
+        runtime: opts.runtime || "all",
+        profile: opts.profile || "standard",
+        onboarding: opts.onboarding || "auto",
+        registryPath: opts.registry,
+        projectName: opts["project-name"] || opts.projectName,
+        description: opts.description,
+        autoConfigure: opts["auto-configure"],
+        brownfieldQuestionnaire: opts.brownfieldQuestionnaire,
+      });
+
+      // Ensure CLI command metadata is available in the new project.
+      // Only docs/internal/cli-commands.yaml is copied from the package;
+      // all other docs/internal files remain dev-only.
+      try {
+        const projectDir = pathResolve(directory);
+        const src = join(packageRoot, "docs", "internal", "cli-commands.yaml");
+        const dst = join(projectDir, "docs", "internal", "cli-commands.yaml");
+        if (existsSync(src) && !existsSync(dst)) {
+          mkdirSync(dirname(dst), { recursive: true });
+          safeCopyFile(src, dst);
+        }
+      } catch {
+        // Best-effort; init should not fail if CLI metadata copy fails.
+      }
+
+      // Phase 7q: Optional post-init validation
+      if (opts["validate-after"]) {
+        const { execSync } = await import("node:child_process");
+        const path = await import("node:path");
+        const { fileURLToPath } = await import("node:url");
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        const binPath = path.join(__dirname, "..", "..", "bin", "wwa.js");
+        const targetDir = path.resolve(directory);
+        console.log("\nRunning wwa check (--validate-after)...\n");
+        try {
+          execSync(`node "${binPath}" check "${targetDir}"`, {
+            stdio: "inherit",
+            cwd: targetDir,
+          });
+        } catch (err) {
+          console.warn("wwa check reported issues. Fix any validation failures above.");
+        }
+      }
+    });
+}

package/lib/cli/pipeline.js

@@ -0,0 +1,206 @@
+/** wwa pipeline — advanced subcommands for debugging and testing. */
+
+import { resolve, dirname, join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import {
+  resolveProjectType,
+  getPipeline,
+  getRegistry,
+  loadRegistryData,
+  outputData,
+} from "./helpers.js";
+import { printCliReport, writeLastRunSummary } from "./report-helpers.js";
+
+export function register(program) {
+  const pipeline = program
+    .command("pipeline")
+    .description(
+      "Advanced pipeline commands for debugging and testing.\n" +
+        "Most users should use check, scan, route instead."
+    );
+
+  pipeline
+    .command("classify <query>")
+    .description("Classify a natural language query (S1)")
+    .option(
+      "-p, --project-type <type>",
+      "Project type: code, context, data, mix, general",
+      "general"
+    )
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (query, opts) => {
+      const { classify } = await getPipeline();
+      const reg = await loadRegistryData(opts.registry);
+      const projectType = resolveProjectType(opts.projectType);
+      const result = classify(query, projectType, reg);
+      const queryType = result.query_type || result.classified_as || "—";
+      if (opts.json) {
+        console.log(`Query: "${query}"`);
+        outputData(result, true);
+      } else {
+        const summary = `Classified as query_type: ${queryType}.`;
+        const inputRef = `query="${query}", project type=${projectType}`;
+        printCliReport({ command: "pipeline classify", inputRef, summary });
+        console.log("  Detail — Query: \"" + query + "\"");
+        outputData(result, false);
+        writeLastRunSummary(".", { command: "pipeline classify", inputRef, summary });
+      }
+    });
+
+  pipeline
+    .command("select <query-type> <project-type>")
+    .description("Select workflow for a query type (S2)")
+    .option("--first-session", "Force WF-04 bootstrap workflow")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (queryType, projectType, opts) => {
+      const { selectWorkflow } = await getPipeline();
+      await loadRegistryData(opts.registry);
+      const result = selectWorkflow(
+        queryType,
+        projectType,
+        opts.firstSession || false
+      );
+      const wfId = result.workflow_id || result.workflow || "—";
+      if (opts.json) {
+        outputData(result, true);
+      } else {
+        const summary = `Workflow selected: ${wfId}.`;
+        const inputRef = `query-type=${queryType}, project-type=${projectType}`;
+        printCliReport({ command: "pipeline select", inputRef, summary });
+        console.log("  Detail");
+        outputData(result, false);
+        writeLastRunSummary(".", { command: "pipeline select", inputRef, summary });
+      }
+    });
+
+  pipeline
+    .command("resolve <workflow-id> <stage>")
+    .description("Resolve features for a workflow stage (S3)")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (workflowId, stage, opts) => {
+      const { resolveFeatures } = await getPipeline();
+      const reg = await loadRegistryData(opts.registry);
+      const result = resolveFeatures(workflowId, stage, reg);
+      const features = result.features || result.read_set || [];
+      const n = Array.isArray(features) ? features.length : 0;
+      if (opts.json) {
+        console.log(`Workflow: ${workflowId} | Stage: ${stage}`);
+        outputData(result, true);
+      } else {
+        const summary = `Features resolved for ${workflowId} @ ${stage}: ${n} item(s).`;
+        const inputRef = `workflow=${workflowId}, stage=${stage}`;
+        printCliReport({ command: "pipeline resolve", inputRef, summary });
+        console.log("  Detail — Workflow: " + workflowId + " | Stage: " + stage);
+        outputData(result, false);
+        writeLastRunSummary(".", { command: "pipeline resolve", inputRef, summary });
+      }
+    });
+
+  pipeline
+    .command("cascade <trigger>")
+    .description("Compute cascade chain from a trigger (S5)")
+    .option(
+      "--context <context>",
+      "Cascade context: code, context, data, mix, universal",
+      "universal"
+    )
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (trigger, opts) => {
+      const { resolveCascade } = await getPipeline();
+      await loadRegistryData(opts.registry);
+      const context =
+        opts.context !== "universal"
+          ? resolveProjectType(opts.context)
+          : opts.context;
+      const result = resolveCascade([], trigger, context);
+      const chain = result.chain || result.targets || result.files || [];
+      const n = Array.isArray(chain) ? chain.length : 0;
+      if (opts.json) {
+        outputData(result, true);
+      } else {
+        const summary = `Cascade for trigger "${trigger}": ${n} step(s).`;
+        const inputRef = `trigger=${trigger}, context=${context}`;
+        printCliReport({ command: "pipeline cascade", inputRef, summary });
+        console.log("  Detail");
+        outputData(result, false);
+        writeLastRunSummary(".", { command: "pipeline cascade", inputRef, summary });
+      }
+    });
+
+  pipeline
+    .command("test [fixtures...]")
+    .description("Run YAML test fixtures against the pipeline")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .action(async (fixtures, opts) => {
+      const { runFixture } = await getPipeline();
+      const { findRegistry } = await getRegistry();
+      const reg = await loadRegistryData(opts.registry);
+
+      let files;
+      if (fixtures && fixtures.length > 0) {
+        files = fixtures.map((f) => resolve(f));
+      } else {
+        let regPath;
+        try {
+          regPath = opts.registry ? resolve(opts.registry) : findRegistry();
+        } catch {
+          regPath = ".";
+        }
+        const fixtureDir = resolve(
+          dirname(regPath), "..", "..", "tests", "fixtures"
+        );
+        const altDir = resolve(
+          dirname(new URL(import.meta.url).pathname), "..", "..", "tests", "fixtures"
+        );
+        const searchDir = existsSync(fixtureDir) ? fixtureDir : altDir;
+
+        if (existsSync(searchDir)) {
+          files = readdirSync(searchDir)
+            .filter((f) => f.startsWith("pipeline-") && f.endsWith(".yaml"))
+            .sort()
+            .map((f) => join(searchDir, f));
+        } else {
+          files = [];
+        }
+      }
+
+      if (files.length === 0) {
+        console.error("No fixture files found.");
+        process.exit(1);
+      }
+
+      let totalPassed = 0;
+      let totalFailed = 0;
+      for (const fpath of files) {
+        if (!existsSync(fpath)) {
+          console.log(`  Fixture not found: ${fpath}`);
+          continue;
+        }
+        const result = runFixture(fpath, reg);
+        const fileStatus = result.failed === 0 ? "PASS" : "FAIL";
+        console.log(
+          `  ${result.stage.padEnd(12)} ${result.passed}/${result.total} passed  [${fileStatus}]`
+        );
+        totalPassed += result.passed;
+        totalFailed += result.failed;
+
+        for (const detail of result.details) {
+          if (detail.status === "FAIL") {
+            console.log(`    FAIL ${detail.id}: ${detail.description}`);
+            if (detail.actual) {
+              console.log(`         actual: ${JSON.stringify(detail.actual)}`);
+            }
+          }
+        }
+      }
+
+      console.log(
+        `\n  Total: ${totalPassed} passed, ${totalFailed} failed, ${totalPassed + totalFailed} total`
+      );
+      process.exit(totalFailed > 0 ? 1 : 0);
+    });
+}

package/lib/cli/plan.js

@@ -0,0 +1,140 @@
+/** wwa plan — display current plan status. */
+
+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("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 {
+        const done = parsed.steps.filter((s) => s.status === "done").length;
+        const total = parsed.steps.length;
+        const summary = [
+          position ? `Phase: ${position.phase}, status: ${position.status}.` : "No STATE.md position.",
+          position?.next ? `Next: ${position.next}.` : "",
+          `${done}/${total} steps complete. Plan: ${parsed.title}`,
+        ]
+          .filter(Boolean)
+          .join(" ");
+        const inputRef = `directory=${directory}`;
+        printCliReport({ command: "plan", inputRef, summary });
+        console.log("  Detail");
+        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) {
+          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("");
+        writeLastRunSummary(d, { command: "plan", inputRef, summary });
+      }
+    });
+}
+
+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 };
+}