agent-method 1.5.3 → 1.5.6

package/lib/cli/check.js

@@ -1,71 +1,71 @@
-/** wwa 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: npx wwa 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}`
-            );
-          }
-        }
-      }
-    });
-}
+/** wwa 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: wwa 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/close.js

@@ -0,0 +1,446 @@
+/** wwa close — session close checklist, cascade reminders, and project snapshot. */
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { resolve, join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findEntryPoint, findSessionLog, readMethodVersion, packageRoot, safeWriteFile } from "./helpers.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function register(program) {
+  program
+    .command("close [directory]")
+    .description("Show session close checklist, cascade reminders, and project snapshot")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const checklist = [];
+      const warnings = [];
+
+      // 1. Check SESSION-LOG.md exists
+      const sessionLog = findSessionLog(directory);
+      if (sessionLog) {
+        checklist.push({ item: "SESSION-LOG.md exists", ok: true });
+      } else {
+        checklist.push({ item: "SESSION-LOG.md exists", ok: false });
+        warnings.push("No SESSION-LOG.md found — create one to track session metrics");
+      }
+
+      // 2. Check STATE.md exists and has current position
+      const statePath = join(d, "STATE.md");
+      if (existsSync(statePath)) {
+        checklist.push({ item: "STATE.md exists", ok: true });
+      } else {
+        checklist.push({ item: "STATE.md exists", ok: false });
+        warnings.push("No STATE.md found — decisions may be lost between sessions");
+      }
+
+      // 3. Check PLAN.md for incomplete steps
+      const planPath = join(d, "PLAN.md");
+      if (existsSync(planPath)) {
+        const planContent = readFileSync(planPath, "utf-8");
+        const todoSteps = (planContent.match(/\|\s*todo\s*\|/gi) || []).length;
+        if (todoSteps > 0) {
+          checklist.push({
+            item: `PLAN.md has ${todoSteps} incomplete step(s)`,
+            ok: false,
+          });
+        } else {
+          checklist.push({ item: "PLAN.md — all steps complete", ok: true });
+        }
+      }
+
+      // 4. Check Management files
+      const digestPath = join(d, "Management", "DIGEST.md");
+      if (existsSync(digestPath)) {
+        checklist.push({ item: "Management/DIGEST.md exists", ok: true });
+      }
+
+      // 5. Check SUMMARY.md
+      const summaryPath = join(d, "SUMMARY.md");
+      if (existsSync(summaryPath)) {
+        checklist.push({ item: "SUMMARY.md exists for audit entry", ok: true });
+      }
+
+      // Build cascade reminders
+      const cascadeReminders = [
+        "Append metrics entry to SESSION-LOG.md",
+        "Update STATE.md current position",
+        "For high-effort tasks: append row to Management/DIGEST.md",
+        "If milestone: update Management/STATUS.md",
+        "If phase complete: mark ROADMAP.md, write SUMMARY.md entry",
+      ];
+
+      // Compute project snapshot — methodology reference data
+      const snapshot = await computeProjectSnapshot(d);
+
+      // Update project doc-tokens.yaml regardless of output mode
+      const tokenUpdateResult = await updateProjectTokens(d, snapshot);
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify({ checklist, warnings, cascadeReminders, snapshot, tokensUpdated: !!tokenUpdateResult }, null, 2)
+        );
+        return;
+      }
+
+      console.log("\n  Session Close Checklist\n");
+
+      for (const item of checklist) {
+        const icon = item.ok ? "[x]" : "[ ]";
+        console.log(`    ${icon} ${item.item}`);
+      }
+
+      if (warnings.length > 0) {
+        console.log("\n  Warnings:");
+        for (const w of warnings) {
+          console.log(`    ! ${w}`);
+        }
+      }
+
+      console.log("\n  Cascade reminders:");
+      for (const r of cascadeReminders) {
+        console.log(`    - ${r}`);
+      }
+
+      // Print project snapshot
+      printSnapshot(snapshot);
+
+      if (tokenUpdateResult) {
+        console.log("\n  Updated .context/doc-tokens.yaml with current project metrics.");
+      }
+
+      console.log("");
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Project snapshot — computed at close, chunked for large projects
+// ---------------------------------------------------------------------------
+
+async function computeProjectSnapshot(dir) {
+  const snapshot = {
+    project: {},
+    methodologyFiles: { present: [], missing: [] },
+    decisions: { count: 0, recent: [] },
+    sessions: { count: 0, latestDate: null },
+    features: [],
+    registry: null,
+    docsMap: null,
+    fileStats: {},
+  };
+
+  // --- Chunk 1: Project identity ---
+  const entryPoint = findEntryPoint(dir);
+  if (entryPoint) {
+    snapshot.project.entryPoint = relative(dir, entryPoint) || entryPoint;
+    snapshot.project.methodVersion = readMethodVersion(entryPoint);
+    const epContent = readFileSync(entryPoint, "utf-8");
+    const tierMatch = epContent.match(/tier:\s*(\S+)/);
+    if (tierMatch) snapshot.project.tier = tierMatch[1];
+    const modeMatch = epContent.match(/mode:\s*(\S+)/);
+    if (modeMatch) snapshot.project.interactionLevel = modeMatch[1];
+  }
+
+  const projectPath = join(dir, "PROJECT.md");
+  if (existsSync(projectPath)) {
+    const content = readFileSync(projectPath, "utf-8");
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    if (titleMatch) snapshot.project.name = titleMatch[1].trim();
+  }
+
+  const profilePath = join(dir, "PROJECT-PROFILE.md");
+  if (existsSync(profilePath)) {
+    const content = readFileSync(profilePath, "utf-8");
+    const typeMatch = content.match(/project.?type[:\s|]+(\S+)/i);
+    if (typeMatch) snapshot.project.type = typeMatch[1].toLowerCase();
+    const stageMatch = content.match(/lifecycle.?stage[:\s|]+(\S+)/i);
+    if (stageMatch) snapshot.project.lifecycleStage = stageMatch[1].toLowerCase();
+  }
+
+  // --- Chunk 2: Methodology file inventory ---
+  const expectedFiles = [
+    "STATE.md", "PLAN.md", "ROADMAP.md", "SUMMARY.md",
+    "PROJECT.md", "PROJECT-PROFILE.md", "SESSION-LOG.md",
+    ".context/BASE.md", ".context/METHODOLOGY.md",
+  ];
+  for (const f of expectedFiles) {
+    const p = join(dir, f);
+    if (existsSync(p)) {
+      const stat = statSync(p);
+      const lines = readFileSync(p, "utf-8").split("\n").length;
+      snapshot.methodologyFiles.present.push({ file: f, lines, bytes: stat.size });
+      // Track files approaching 300-line threshold
+      if (lines > 250) {
+        snapshot.fileStats[f] = { lines, nearThreshold: lines >= 280 };
+      }
+    } else {
+      snapshot.methodologyFiles.missing.push(f);
+    }
+  }
+
+  // --- Chunk 3: Decisions from STATE.md ---
+  const statePath = join(dir, "STATE.md");
+  if (existsSync(statePath)) {
+    const content = readFileSync(statePath, "utf-8");
+    const decisionSection = content.match(
+      /##\s*Decisions?\s*\n([\s\S]*?)(?=\n##|\n$|$)/i
+    );
+    if (decisionSection) {
+      const rows = decisionSection[1].match(/\|[^|\n]+\|[^|\n]+\|/g) || [];
+      const decisions = [];
+      for (const row of rows) {
+        const cols = row.split("|").map((c) => c.trim()).filter((c) => c && !c.match(/^[-:]+$/));
+        if (cols.length >= 2 && !cols[0].toLowerCase().includes("date")) {
+          decisions.push({ date: cols[0], decision: cols.slice(1).join(" — ") });
+        }
+      }
+      snapshot.decisions.count = decisions.length;
+      snapshot.decisions.recent = decisions.slice(-5); // last 5
+    }
+  }
+
+  // --- Chunk 4: Session count from SESSION-LOG.md ---
+  const sessionLog = findSessionLog(dir);
+  if (sessionLog) {
+    const content = readFileSync(sessionLog, "utf-8");
+    const entries = content.match(/###\s+S\d+/g) || [];
+    snapshot.sessions.count = entries.length;
+    // Find the latest date
+    const dates = content.match(/###\s+S\d+\s*(?:—|--)\s*(\S+)/g) || [];
+    if (dates.length > 0) {
+      const lastDate = dates[dates.length - 1].match(/(\d{4}-\d{2}-\d{2})/);
+      if (lastDate) snapshot.sessions.latestDate = lastDate[1];
+    }
+  }
+
+  // --- Chunk 5: Feature registry (from project .context/ or installed package) ---
+  const localRegistry = join(dir, ".context", "feature-registry.yaml");
+  const pkgRegistry = join(packageRoot, "docs", "internal", "feature-registry.yaml");
+  const registryPath = existsSync(localRegistry) ? localRegistry : (existsSync(pkgRegistry) ? pkgRegistry : null);
+
+  if (registryPath) {
+    try {
+      const yaml = (await import("js-yaml")).default;
+      const raw = readFileSync(registryPath, "utf-8");
+      const parsed = yaml.load(raw);
+      if (parsed) {
+        snapshot.registry = {
+          source: existsSync(localRegistry) ? "project" : "package",
+          version: parsed.version || null,
+          featureCount: parsed.features ? Object.keys(parsed.features).length : 0,
+          workflowCount: parsed.guided_workflows ? parsed.guided_workflows.length : 0,
+        };
+        // Collect active features from project entry point scoping
+        if (entryPoint) {
+          const epContent = readFileSync(entryPoint, "utf-8");
+          const featureRefs = epContent.match(/[A-Z]{2,5}-\d{2}/g) || [];
+          snapshot.features = [...new Set(featureRefs)].sort();
+        }
+      }
+    } catch (_) {
+      // Registry parse failed — skip silently
+    }
+  }
+
+  // --- Chunk 6: Docs map status ---
+  const docsMapPath = join(dir, ".context", "DOCS-MAP.md");
+  if (existsSync(docsMapPath)) {
+    const content = readFileSync(docsMapPath, "utf-8");
+    const inventoryRows = (content.match(/^\|[^|]+\|[^|]+\|[^|]+\|[^|]+\|$/gm) || [])
+      .filter((r) => !r.includes("---") && !r.includes("Path") && !r.includes("Purpose"));
+    const mappingRows = (content.match(/^\|[^|]+\|[^|]+\|[^|]+\|$/gm) || [])
+      .filter((r) => !r.includes("---") && !r.includes("Project component") && !r.includes("When this"));
+
+    // Check which docs actually exist on disk
+    let docsExist = 0;
+    let docsTotal = 0;
+    for (const row of inventoryRows) {
+      const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+      if (cols.length >= 1) {
+        docsTotal++;
+        if (existsSync(join(dir, cols[0]))) docsExist++;
+      }
+    }
+
+    snapshot.docsMap = {
+      inventoryCount: docsTotal,
+      docsOnDisk: docsExist,
+      docsMissing: docsTotal - docsExist,
+      componentMappings: mappingRows.length,
+    };
+  }
+
+  return snapshot;
+}
+
+// ---------------------------------------------------------------------------
+// Display
+// ---------------------------------------------------------------------------
+
+function printSnapshot(snapshot) {
+  console.log("\n  Project Snapshot\n");
+
+  // Project identity
+  if (snapshot.project.name) {
+    console.log(`    Project: ${snapshot.project.name}`);
+  }
+  if (snapshot.project.type) {
+    console.log(`    Type: ${snapshot.project.type} | Stage: ${snapshot.project.lifecycleStage || "unknown"}`);
+  }
+  if (snapshot.project.methodVersion) {
+    console.log(`    Method: v${snapshot.project.methodVersion} | Tier: ${snapshot.project.tier || "unknown"}`);
+  }
+
+  // File inventory
+  const present = snapshot.methodologyFiles.present.length;
+  const missing = snapshot.methodologyFiles.missing.length;
+  console.log(`\n    Methodology files: ${present} present, ${missing} missing`);
+  if (missing > 0) {
+    console.log(`    Missing: ${snapshot.methodologyFiles.missing.join(", ")}`);
+  }
+
+  // Threshold warnings
+  const nearThreshold = Object.entries(snapshot.fileStats)
+    .filter(([, s]) => s.nearThreshold);
+  if (nearThreshold.length > 0) {
+    console.log(`    Scale warnings:`);
+    for (const [file, stats] of nearThreshold) {
+      console.log(`      ! ${file}: ${stats.lines} lines (threshold: 300)`);
+    }
+  }
+
+  // Decisions
+  if (snapshot.decisions.count > 0) {
+    console.log(`\n    Decisions: ${snapshot.decisions.count} total`);
+    if (snapshot.decisions.recent.length > 0) {
+      console.log(`    Recent:`);
+      for (const d of snapshot.decisions.recent) {
+        const text = d.decision.length > 60 ? d.decision.slice(0, 57) + "..." : d.decision;
+        console.log(`      ${d.date}: ${text}`);
+      }
+    }
+  }
+
+  // Sessions
+  if (snapshot.sessions.count > 0) {
+    console.log(`\n    Sessions: ${snapshot.sessions.count} logged (latest: ${snapshot.sessions.latestDate || "unknown"})`);
+  }
+
+  // Registry
+  if (snapshot.registry) {
+    console.log(`\n    Registry: ${snapshot.registry.source} (${snapshot.registry.featureCount} features, ${snapshot.registry.workflowCount} workflows)`);
+  }
+  if (snapshot.features.length > 0) {
+    console.log(`    Features referenced: ${snapshot.features.length} (${snapshot.features.slice(0, 8).join(", ")}${snapshot.features.length > 8 ? "..." : ""})`);
+  }
+
+  // Docs
+  if (snapshot.docsMap) {
+    const dm = snapshot.docsMap;
+    console.log(`\n    Docs: ${dm.docsOnDisk}/${dm.inventoryCount} exist | ${dm.componentMappings} component mappings`);
+    if (dm.docsMissing > 0) {
+      console.log(`    Missing docs: ${dm.docsMissing} (run \`wwa docs\` for details)`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Update project doc-tokens.yaml
+// ---------------------------------------------------------------------------
+
+async function updateProjectTokens(dir, snapshot) {
+  const tokensPath = join(dir, ".context", "doc-tokens.yaml");
+  if (!existsSync(tokensPath)) return null;
+
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const raw = readFileSync(tokensPath, "utf-8");
+    const parsed = yaml.load(raw) || {};
+    const tokens = parsed.tokens || {};
+
+    const today = new Date().toISOString().slice(0, 10);
+    tokens.last_close = today;
+
+    // File counts — count methodology files (.md/.yaml/.yml) in project
+    let methodologyCount = 0;
+    let docsCount = 0;
+    let contextCount = 0;
+    const countFiles = (base) => {
+      if (!existsSync(base)) return;
+      for (const entry of readdirSync(base, { withFileTypes: true })) {
+        const p = join(base, entry.name);
+        if (entry.isDirectory()) {
+          // Track docs/ and .context/ separately
+          if (entry.name === "docs" && base === dir) {
+            docsCount += countDir(p);
+          } else if (entry.name === ".context" && base === dir) {
+            contextCount += countDir(p);
+          } else {
+            countFiles(p);
+          }
+        } else if (/\.(md|yaml|yml)$/i.test(entry.name)) {
+          methodologyCount++;
+        }
+      }
+    };
+    const countDir = (d) => {
+      let c = 0;
+      if (!existsSync(d)) return c;
+      for (const entry of readdirSync(d, { withFileTypes: true })) {
+        if (entry.isDirectory()) c += countDir(join(d, entry.name));
+        else if (/\.(md|yaml|yml)$/i.test(entry.name)) c++;
+      }
+      return c;
+    };
+    countFiles(dir);
+    tokens.methodology_file_count = methodologyCount;
+    tokens.docs_file_count = docsCount;
+    tokens.context_file_count = contextCount;
+
+    // Session metrics
+    tokens.session_count = snapshot.sessions.count;
+    tokens.decision_count = snapshot.decisions.count;
+    tokens.total_features_referenced = snapshot.features.length;
+
+    // Scale indicators
+    let nearThreshold = 0;
+    let overThreshold = 0;
+    for (const f of snapshot.methodologyFiles.present) {
+      if (f.lines >= 300) overThreshold++;
+      else if (f.lines >= 250) nearThreshold++;
+    }
+    tokens.files_near_threshold = nearThreshold;
+    tokens.files_over_threshold = overThreshold;
+
+    // Docs coverage
+    if (snapshot.docsMap) {
+      tokens.docs_inventory_count = snapshot.docsMap.inventoryCount;
+      tokens.docs_on_disk = snapshot.docsMap.docsOnDisk;
+      tokens.docs_missing = snapshot.docsMap.docsMissing;
+      tokens.component_mappings = snapshot.docsMap.componentMappings;
+    }
+
+    // Rebuild YAML output preserving structure
+    parsed.tokens = tokens;
+    const output = yaml.dump(parsed, { lineWidth: 120, noRefs: true, quotingType: '"' });
+
+    // Prepend header comment
+    const header = [
+      "# Project Token Registry",
+      "# Computed by wwa init. Updated by wwa close.",
+      "# Used by wwa casestudy for methodology reference data.",
+      "#",
+      `# Last updated: ${today}`,
+      "",
+    ].join("\n");
+
+    safeWriteFile(tokensPath, header + output, "utf-8");
+    return tokens;
+  } catch (_) {
+    return null;
+  }
+}