agent-method 1.5.12 → 1.5.15

package/lib/cli/close.js

@@ -10,173 +10,196 @@ import { resolveTokensPath, resolveDocsMapPath, resolveIndexPath, resolveFeature
 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")
-    .option("--internal-registry", "Include docs/internal/doc-registry.yaml health in management output")
-    .action(async (directory, opts) => {
-      directory = directory || ".";
-      const d = resolve(directory);
+export async function runClose(directory, options = {}) {
+  const d = resolve(directory || ".");
 
-      const checklist = [];
-      const warnings = [];
+  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");
-      }
+  // 1. Check SESSION-LOG.md exists
+  const sessionLog = findSessionLog(d);
+  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");
-      }
+  // 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 });
-        }
-      }
+  // 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 });
-      }
+  // 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 });
-      }
+  // 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 from PROTOCOL.yaml or fallback to defaults.
-      // If PROTOCOL.yaml has an empty close_check list, fall back to defaults so
-      // the user always sees helpful reminders.
-      let cascadeReminders;
-      const protocolPath = join(d, ".context", "PROTOCOL.yaml");
-      if (existsSync(protocolPath)) {
-        try {
-          const yaml = (await import("js-yaml")).default;
-          let raw = readFileSync(protocolPath, "utf-8");
-          const parsed = yaml.load(raw);
-          cascadeReminders = parsed?.close_check || getDefaultReminders();
-          // Update last_verified timestamp (comment-preserving)
-          const today = new Date().toISOString().slice(0, 10);
-          const lvPattern = /^(last_verified:) .+$/m;
-          if (lvPattern.test(raw)) {
-            raw = raw.replace(lvPattern, `$1 "${today}"`);
-          } else {
-            const vLine = /^(version: .+)$/m;
-            raw = raw.replace(vLine, `$1\nlast_verified: "${today}"`);
-          }
-          safeWriteFile(protocolPath, raw, "utf-8");
-        } catch (_) {
-          cascadeReminders = getDefaultReminders();
-        }
+  // Build cascade reminders from PROTOCOL.yaml or fallback to defaults.
+  // If PROTOCOL.yaml has an empty close_check list, fall back to defaults so
+  // the user always sees helpful reminders.
+  let cascadeReminders;
+  const protocolPath = join(d, ".context", "PROTOCOL.yaml");
+  if (existsSync(protocolPath)) {
+    try {
+      const yaml = (await import("js-yaml")).default;
+      let raw = readFileSync(protocolPath, "utf-8");
+      const parsed = yaml.load(raw);
+      cascadeReminders = parsed?.close_check || getDefaultReminders();
+      // Update last_verified timestamp (comment-preserving)
+      const today = new Date().toISOString().slice(0, 10);
+      const lvPattern = /^(last_verified:) .+$/m;
+      if (lvPattern.test(raw)) {
+        raw = raw.replace(lvPattern, `$1 "${today}"`);
       } else {
-        cascadeReminders = getDefaultReminders();
+        const vLine = /^(version: .+)$/m;
+        raw = raw.replace(vLine, `$1\nlast_verified: "${today}"`);
       }
+      safeWriteFile(protocolPath, raw, "utf-8");
+    } catch (_) {
+      cascadeReminders = getDefaultReminders();
+    }
+  } else {
+    cascadeReminders = getDefaultReminders();
+  }
 
-      // If we still have no reminders (empty array), use defaults.
-      if (!cascadeReminders || cascadeReminders.length === 0) {
-        cascadeReminders = getDefaultReminders();
-      }
+  // If we still have no reminders (empty array), use defaults.
+  if (!cascadeReminders || cascadeReminders.length === 0) {
+    cascadeReminders = getDefaultReminders();
+  }
 
-      // Compute project snapshot — methodology reference data
-      const snapshot = await computeProjectSnapshot(d);
+  // 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);
+  // Update project doc-tokens.yaml regardless of output mode
+  const tokenUpdateResult = await updateProjectTokens(d, snapshot);
 
-      // Update INDEX.yaml metrics
-      const indexUpdateResult = await updateIndexMetrics(d, snapshot);
+  // Update INDEX.yaml metrics
+  const indexUpdateResult = await updateIndexMetrics(d, snapshot);
 
-      // Load internal registry if requested
-      let internalRegistry = null;
-      if (opts.internalRegistry) {
-        try {
-          const { loadInternalRegistry } = await import("./doc-review.js");
-          internalRegistry = await loadInternalRegistry(d);
-          if (!internalRegistry) {
-            console.log("  Note: No docs/internal/doc-registry.yaml found — run `wwa doc-review` to generate it.");
-          }
-        } catch {
-          // doc-review module not available — skip silently
-        }
-      }
+  // Load internal registry if requested
+  let internalRegistry = null;
+  if (options.internalRegistry) {
+    try {
+      const { loadInternalRegistry } = await import("./doc-review.js");
+      internalRegistry = await loadInternalRegistry(d);
+    } catch {
+      // doc-review module not available — skip silently
+    }
+  }
 
-      // Always write management files (close-snapshot.yaml + STATUS.md) at close.
-      const writeResults = await writeManagementFiles(
-        d,
-        snapshot,
-        checklist,
-        cascadeReminders,
-        internalRegistry
-      );
+  // Always write management files (close-snapshot.yaml + STATUS.md) at close.
+  const writeResults = await writeManagementFiles(
+    d,
+    snapshot,
+    checklist,
+    cascadeReminders,
+    internalRegistry
+  );
 
-      if (opts.json) {
-        console.log(
-          JSON.stringify({ checklist, warnings, cascadeReminders, snapshot, tokensUpdated: !!tokenUpdateResult, indexUpdated: !!indexUpdateResult, writeResults }, null, 2)
-        );
-        return;
-      }
+  return {
+    directory: d,
+    checklist,
+    warnings,
+    cascadeReminders,
+    snapshot,
+    tokensUpdated: !!tokenUpdateResult,
+    indexUpdated: !!indexUpdateResult,
+    writeResults,
+    internalRegistryLoaded: !!internalRegistry,
+  };
+}
+
+export function register(program) {
+  program
+    .command("close [directory]")
+    .description("Show session close checklist, cascade reminders, and project snapshot")
+    .option("--json", "Output as JSON")
+    .option(
+      "--internal-registry",
+      "Include docs/internal/doc-registry.yaml health in management output"
+    )
+    .action(async (directory, opts) => {
+      const d = directory || ".";
+      try {
+        const result = await runClose(d, {
+          internalRegistry: opts.internalRegistry,
+        });
 
-      console.log("\n  Session Close Checklist\n");
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
 
-      for (const item of checklist) {
-        const icon = item.ok ? "[x]" : "[ ]";
-        console.log(`    ${icon} ${item.item}`);
-      }
+        console.log("\n  Session Close Checklist\n");
 
-      if (warnings.length > 0) {
-        console.log("\n  Warnings:");
-        for (const w of warnings) {
-          console.log(`    ! ${w}`);
+        for (const item of result.checklist) {
+          const icon = item.ok ? "[x]" : "[ ]";
+          console.log(`    ${icon} ${item.item}`);
         }
-      }
 
-      console.log("\n  Cascade reminders:");
-      for (const r of cascadeReminders) {
-        console.log(`    - ${r}`);
-      }
+        if (result.warnings.length > 0) {
+          console.log("\n  Warnings:");
+          for (const w of result.warnings) {
+            console.log(`    ! ${w}`);
+          }
+        }
 
-      // Print project snapshot
-      printSnapshot(snapshot);
+        console.log("\n  Cascade reminders:");
+        for (const r of result.cascadeReminders) {
+          console.log(`    - ${r}`);
+        }
 
-      if (tokenUpdateResult) {
-        console.log("\n  Updated doc-tokens.yaml with current project metrics.");
-      }
+        // Print project snapshot
+        printSnapshot(result.snapshot);
 
-      if (indexUpdateResult) {
-        console.log("  Updated INDEX.yaml with current project metrics.");
-      }
+        if (result.tokensUpdated) {
+          console.log("\n  Updated doc-tokens.yaml with current project metrics.");
+        }
 
-      if (writeResults) {
-        console.log("\n  Management files written:");
-        if (writeResults.snapshotYaml) console.log(`    - ${writeResults.snapshotYaml}`);
-        if (writeResults.statusMd) console.log(`    - ${writeResults.statusMd}`);
-      }
+        if (result.indexUpdated) {
+          console.log("  Updated INDEX.yaml with current project metrics.");
+        }
+
+        if (result.writeResults) {
+          console.log("\n  Management files written:");
+          if (result.writeResults.snapshotYaml)
+            console.log(`    - ${result.writeResults.snapshotYaml}`);
+          if (result.writeResults.statusMd)
+            console.log(`    - ${result.writeResults.statusMd}`);
+        }
 
-      console.log("");
+        console.log("");
+      } catch (e) {
+        console.error(e.message || "wwa close failed.");
+        process.exit(1);
+      }
     });
 }
 

package/lib/cli/helpers.js

@@ -22,6 +22,19 @@ export const pkg = _pkg;
 /** Package root directory (two levels up from lib/cli/). */
 export const packageRoot = resolve(__dirname, "..", "..");
 
+// ---------------------------------------------------------------------------
+// Archive and naming invariant (all wwa commands)
+// ---------------------------------------------------------------------------
+//
+// Canonical names persist in the working directory: CLAUDE.md, .cursorrules,
+// AGENT.md, registry/doc-tokens.yaml, etc. Wwa never writes versioned names
+// (e.g. CLAUDE.v2.md or doc-tokens.v2.yaml) into the project root. When we
+// need to keep a previous version, we put it under the archive subdirectory
+// only (e.g. .wwa-archive/entry-points/CLAUDE.v2.md).
+
+/** Archive root for versioned/archived copies. Versioned filenames exist only under this tree. */
+export const WWA_ARCHIVE_DIR = ".wwa-archive";
+
 // ---------------------------------------------------------------------------
 // Project type aliases
 // ---------------------------------------------------------------------------

package/lib/cli/record.js

@@ -11,6 +11,71 @@ import {
   parseLastRunContent,
 } from "./report-helpers.js";
 
+/**
+ * Core implementation for `wwa record` and MCP write-safe tools.
+ */
+export async function runRecord(directory, options = {}) {
+  const dir = resolve(directory || ".");
+  const dryRun = !!options.dryRun;
+
+  const content = readLastRunSummary(dir);
+  if (!content) {
+    const msg =
+      "No recent CLI output to record. Run a wwa command (e.g. wwa route '…', wwa scan) first.";
+    const error = new Error(msg);
+    error.code = "NO_LAST_RUN";
+    throw error;
+  }
+
+  const parsed = parseLastRunContent(content);
+  if (!parsed) {
+    const msg = "Last run file was invalid; nothing to record.";
+    const error = new Error(msg);
+    error.code = "INVALID_LAST_RUN";
+    throw error;
+  }
+
+  const date = parsed.timestamp.slice(0, 10);
+  const block = [
+    "",
+    `### CLI run — ${date} — ${parsed.command}`,
+    "",
+    `Command: wwa ${parsed.command}`,
+    `Input: ${parsed.inputRef}`,
+    `Summary: ${parsed.summary}`,
+    "",
+  ].join("\n");
+
+  const sessionLog = findSessionLog(dir);
+  if (!sessionLog) {
+    const msg = "No SESSION-LOG.md found. Create it or run from project root.";
+    const error = new Error(msg);
+    error.code = "NO_SESSION_LOG";
+    throw error;
+  }
+
+  if (dryRun) {
+    return {
+      directory: dir,
+      target: sessionLog,
+      block: block.trim(),
+      dryRun: true,
+      recorded: false,
+    };
+  }
+
+  const existing = readFileSync(sessionLog, "utf-8");
+  safeWriteFile(sessionLog, existing + block, "utf-8");
+  clearLastRunSummary(dir);
+
+  return {
+    directory: dir,
+    target: sessionLog,
+    dryRun: false,
+    recorded: true,
+  };
+}
+
 export function register(program) {
   program
     .command("record [directory]")
@@ -19,80 +84,37 @@ export function register(program) {
     .option("--dry-run", "Show what would be appended without writing")
     .option("--json", "Output as JSON")
     .action(async (directory, cmd) => {
-      const opts = typeof cmd?.opts === "function" ? cmd.opts() : (cmd || {});
-      const dir = resolve(opts.directory || directory || ".");
-      const content = readLastRunSummary(dir);
+      const opts = typeof cmd?.opts === "function" ? cmd.opts() : cmd || {};
+      // Prefer explicit directory argument over option default so tests and callers
+      // can target a specific project root without being affected by cwd state.
+      const dir = resolve(directory || opts.directory || ".");
 
-      if (!content) {
-        const msg =
-          "No recent CLI output to record. Run a wwa command (e.g. wwa route '…', wwa scan) first.";
-        if (opts.json) {
-          console.log(JSON.stringify({ recorded: false, error: msg }, null, 2));
-        } else {
-          console.log(`\n  ${msg}\n`);
-        }
-        return;
-      }
+      try {
+        const result = await runRecord(dir, { dryRun: opts.dryRun });
 
-      const parsed = parseLastRunContent(content);
-      if (!parsed) {
-        const msg = "Last run file was invalid; nothing to record.";
         if (opts.json) {
-          console.log(JSON.stringify({ recorded: false, error: msg }, null, 2));
-        } else {
-          console.log(`\n  ${msg}\n`);
+          console.log(JSON.stringify(result, null, 2));
+          return;
         }
-        return;
-      }
-
-      const date = parsed.timestamp.slice(0, 10);
-      const block = [
-        "",
-        `### CLI run — ${date} — ${parsed.command}`,
-        "",
-        `Command: wwa ${parsed.command}`,
-        `Input: ${parsed.inputRef}`,
-        `Summary: ${parsed.summary}`,
-        "",
-      ].join("\n");
 
-      const sessionLog = findSessionLog(dir);
-      if (!sessionLog) {
-        const msg = "No SESSION-LOG.md found. Create it or run from project root.";
-        if (opts.json) {
-          console.log(JSON.stringify({ recorded: false, error: msg }, null, 2));
-        } else {
-          console.log(`\n  ${msg}\n`);
+        if (result.dryRun) {
+          console.log("\n  Dry run — would append to", result.target);
+          console.log(result.block);
+        } else if (result.recorded) {
+          console.log("\n  Recorded last CLI run to SESSION-LOG.md.\n");
         }
-        return;
-      }
-
-      if (opts.dryRun) {
+      } catch (e) {
         if (opts.json) {
           console.log(
             JSON.stringify(
-              { dryRun: true, target: sessionLog, block: block.trim() },
+              { recorded: false, error: e.message, code: e.code || null },
               null,
               2
             )
           );
         } else {
-          console.log("\n  Dry run — would append to", sessionLog);
-          console.log(block);
+          console.log(`\n  ${e.message}\n`);
         }
-        return;
-      }
-
-      const existing = readFileSync(sessionLog, "utf-8");
-      safeWriteFile(sessionLog, existing + block, "utf-8");
-      clearLastRunSummary(dir);
-
-      if (opts.json) {
-        console.log(
-          JSON.stringify({ recorded: true, target: sessionLog }, null, 2)
-        );
-      } else {
-        console.log("\n  Recorded last CLI run to SESSION-LOG.md.\n");
       }
     });
 }