agent-method 1.5.0

package/lib/cli/check.js

@@ -0,0 +1,71 @@
+/** agent-method check — validate entry point and project setup. */
+
+import { dirname, resolve } from "node:path";
+import {
+  findEntryPoint,
+  resolveProjectType,
+  getPipeline,
+  loadRegistryData,
+} from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("check [entry-point]")
+    .description("Validate your entry point and project setup")
+    .option(
+      "-p, --project-type <type>",
+      "Project type: code, context, data, mix, general (auto-detected if omitted)"
+    )
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (entryPoint, opts) => {
+      const { validateEntryPoint, detectProjectType } = await getPipeline();
+      const reg = await loadRegistryData(opts.registry);
+
+      if (!entryPoint) {
+        entryPoint = findEntryPoint(".");
+        if (!entryPoint) {
+          console.error(
+            "No entry point found in current directory " +
+              "(looked for CLAUDE.md, .cursorrules, AGENT.md).\n" +
+              "Specify a path: agent-method check path/to/CLAUDE.md"
+          );
+          process.exit(1);
+        }
+      }
+
+      let projectType;
+      if (opts.projectType) {
+        projectType = resolveProjectType(opts.projectType);
+      } else {
+        const detected = detectProjectType(dirname(resolve(entryPoint)));
+        projectType = detected.project_type || "general";
+      }
+
+      const result = validateEntryPoint(entryPoint, projectType, reg);
+      console.log(`Checking: ${entryPoint} (type: ${projectType})`);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const overall = result.valid ? "PASS" : "FAIL";
+        console.log(`  Overall: ${overall}`);
+        for (const [checkId, chk] of Object.entries(result.checks)) {
+          const cStatus = chk.pass ? "PASS" : "FAIL";
+          let extra = "";
+          if (chk.missing && chk.missing.length > 0) {
+            extra = ` (missing: ${chk.missing.join(", ")})`;
+          }
+          console.log(`  ${checkId}: ${cStatus}${extra}`);
+        }
+        if (result.issues && result.issues.length > 0) {
+          console.log("\n  Issues:");
+          for (const issue of result.issues) {
+            console.log(
+              `    [${issue.severity}] ${issue.check}: ${issue.description}`
+            );
+          }
+        }
+      }
+    });
+}

package/lib/cli/helpers.js

@@ -0,0 +1,151 @@
+/**
+ * Shared CLI helpers — project type resolution, registry loading,
+ * entry point discovery, output formatting.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, dirname } 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();
+}
+
+// ---------------------------------------------------------------------------
+// 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/init.js

@@ -0,0 +1,60 @@
+/** agent-method init — set up a new project or describe entry point contents. */
+
+import {
+  resolveProjectType,
+  getPipeline,
+  loadRegistryData,
+  outputData,
+  PROJECT_TYPE_ALIASES,
+} from "./helpers.js";
+
+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)", "starter")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .option(
+      "--describe",
+      "Only describe what the entry point should contain (no file creation)"
+    )
+    .action(async (projectTypeArg, directory, opts) => {
+      const projectType = resolveProjectType(projectTypeArg);
+
+      if (opts.describe || !directory) {
+        // Describe mode
+        const { generateEntryPoint } = await getPipeline();
+        const reg = await loadRegistryData(opts.registry);
+        const result = generateEntryPoint(projectType, opts.tier, reg);
+
+        // Show friendly name
+        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})`
+        );
+        outputData(result, opts.json);
+        if (!directory) {
+          console.log(
+            "\nTo create a project, specify a directory:\n" +
+              `  agent-method init ${projectTypeArg} ~/my-project`
+          );
+        }
+        return;
+      }
+
+      // Interactive setup mode
+      const { initProject } = await import("../init.js");
+      await initProject(projectType, directory, {
+        tier: opts.tier,
+        registryPath: opts.registry,
+      });
+    });
+}

package/lib/cli/pipeline.js

@@ -0,0 +1,163 @@
+/** agent-method 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";
+
+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);
+      console.log(`Query: "${query}"`);
+      outputData(result, opts.json);
+    });
+
+  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
+      );
+      outputData(result, opts.json);
+    });
+
+  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);
+      console.log(`Workflow: ${workflowId} | Stage: ${stage}`);
+      outputData(result, opts.json);
+    });
+
+  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);
+      outputData(result, opts.json);
+    });
+
+  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/refine.js

@@ -0,0 +1,202 @@
+/** agent-method refine — extract refinement report from session history. */
+
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { findSessionLog } from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("refine [session-log]")
+    .description("Extract a refinement report from session history")
+    .option("-o, --output <path>", "Output file (default: stdout)")
+    .option("--json", "Output as JSON")
+    .action(async (sessionLog, opts) => {
+      if (!sessionLog) {
+        sessionLog = findSessionLog(".");
+        if (!sessionLog) {
+          console.error(
+            "No SESSION-LOG.md found in current directory.\n" +
+              "Specify a path: agent-method refine path/to/SESSION-LOG.md"
+          );
+          process.exit(1);
+        }
+      }
+
+      if (!existsSync(sessionLog)) {
+        console.error(`File not found: ${sessionLog}`);
+        process.exit(1);
+      }
+
+      const content = readFileSync(sessionLog, "utf-8");
+      const parsed = parseSessionLog(content);
+
+      let result;
+      if (opts.json) {
+        result = JSON.stringify(parsed, null, 2);
+      } else {
+        result = generateRefinementReport(parsed);
+      }
+
+      if (opts.output) {
+        writeFileSync(opts.output, result, "utf-8");
+        console.log(
+          `Refinement report written to ${opts.output} (${parsed.entries.length} sessions)`
+        );
+      } else {
+        console.log(result);
+      }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Session log parsing
+// ---------------------------------------------------------------------------
+
+function parseSessionLog(content) {
+  const context = {};
+  const ctxMatch = content.match(
+    /## Project context\s*\n\s*\|[^\n]+\n\s*\|[-| ]+\n((?:\|[^\n]+\n)*)/
+  );
+  if (ctxMatch) {
+    for (const row of ctxMatch[1].trim().split("\n")) {
+      const cols = row
+        .split("|")
+        .map((c) => c.trim())
+        .filter((c) => c);
+      if (cols.length >= 2) {
+        context[cols[0].toLowerCase()] = cols[1];
+      }
+    }
+  }
+
+  const entries = [];
+  const entryPattern =
+    /###\s+S(\d+)\s*(?:\u2014|--)\s*(\S+)\s*(?:\u2014|--)\s*(.+?)$(.*?)(?=###\s+S\d+|$)/gms;
+  let m;
+  while ((m = entryPattern.exec(content)) !== null) {
+    const [, num, date, title, body] = m;
+    const entry = { session: parseInt(num, 10), date, title: title.trim() };
+
+    for (const line of body.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const segments = trimmed.split("|").map((s) => s.trim());
+      for (const seg of segments) {
+        if (seg.includes(":")) {
+          const idx = seg.indexOf(":");
+          const key = seg.slice(0, idx).trim().toLowerCase();
+          const val = seg.slice(idx + 1).trim();
+          if (
+            [
+              "model", "profile", "workflow", "queries",
+              "features", "cascades", "decisions", "friction", "finding",
+            ].includes(key)
+          ) {
+            entry[key] = val;
+          }
+        }
+      }
+    }
+    entries.push(entry);
+  }
+
+  return { context, entries };
+}
+
+function generateRefinementReport(parsed) {
+  const ctx = parsed.context;
+  const entries = parsed.entries;
+
+  const project = ctx["project name"] || "Unknown";
+  const ptype = ctx["project type"] || "unknown";
+  const profile = ctx["integration profile"] || "unknown";
+  const extensions = ctx["extension(s)"] || "none";
+
+  const workflows = new Set();
+  let totalFriction = 0;
+  let totalFindings = 0;
+  const findingsList = [];
+  const frictionList = [];
+
+  for (const e of entries) {
+    if (e.workflow) workflows.add(e.workflow);
+    const friction = e.friction || "none";
+    if (friction.toLowerCase() !== "none" && friction) {
+      totalFriction++;
+      frictionList.push(`S${e.session} (${e.date}): ${friction}`);
+    }
+    const finding = e.finding || "none";
+    if (finding.toLowerCase() !== "none" && finding) {
+      totalFindings++;
+      findingsList.push(`S${e.session} (${e.date}): ${finding}`);
+    }
+  }
+
+  const wfSorted = [...workflows].sort().join(", ") || "none";
+  const lines = [
+    `# Refinement Report: ${project}`,
+    "",
+    "Auto-generated from SESSION-LOG.md by `agent-method refine`.",
+    "",
+    "## Source",
+    "",
+    "| Field | Value |",
+    "|-------|-------|",
+    `| Project type | ${ptype} |`,
+    `| Extension(s) | ${extensions} |`,
+    `| Workflow(s) exercised | ${wfSorted} |`,
+    `| Integration profile | ${profile} |`,
+    `| Sessions | ${entries.length} |`,
+    "",
+    "## Session summary",
+    "",
+    "| # | Date | Title | Workflow | Friction | Finding |",
+    "|---|------|-------|----------|----------|---------|",
+  ];
+
+  for (const e of entries) {
+    const friction = e.friction || "none";
+    const finding = e.finding || "none";
+    const wf = e.workflow || "\u2014";
+    lines.push(
+      `| S${e.session} | ${e.date} | ${e.title} | ${wf} | ${friction} | ${finding} |`
+    );
+  }
+
+  lines.push(
+    "", "## Statistics", "",
+    `- **Total sessions**: ${entries.length}`,
+    `- **Workflows used**: ${wfSorted}`,
+    `- **Sessions with friction**: ${totalFriction}`,
+    `- **Sessions with findings**: ${totalFindings}`,
+    ""
+  );
+
+  if (frictionList.length > 0) {
+    lines.push("## Friction points", "");
+    for (const f of frictionList) lines.push(`- ${f}`);
+    lines.push("");
+  }
+
+  if (findingsList.length > 0) {
+    lines.push("## Findings", "");
+    for (const f of findingsList) lines.push(`- ${f}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "## Dimension scores", "",
+    "Fill in after reviewing the session data above:", "",
+    "| Dimension | Score | One-line summary |",
+    "|-----------|:-----:|-----------------|",
+    "| Context quality | \u2014 | |",
+    "| Decision preservation | \u2014 | |",
+    "| Scope discipline | \u2014 | |",
+    "| Cascade coverage | \u2014 | |",
+    "| Audit completeness | \u2014 | |",
+    "| Bootstrap speed | \u2014 | |",
+    "| Lifecycle fit | \u2014 | |",
+    "| Model adequacy | \u2014 | |"
+  );
+
+  return lines.join("\n") + "\n";
+}