agent-method 1.5.12

package/lib/cli/upgrade.js

@@ -0,0 +1,222 @@
+/** wwa upgrade — brownfield-safe methodology update. */
+
+import {
+  readFileSync, existsSync, mkdirSync, copyFileSync, unlinkSync,
+} from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import {
+  findEntryPoint, readMethodVersion, basename_of, pkg, packageRoot,
+  safeWriteFile, safeCopyFile,
+} from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("upgrade [directory]")
+    .description("Update your project to the latest methodology version")
+    .option("--dry-run", "Show what would change without modifying files")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+      const ep = findEntryPoint(directory);
+      const actions = [];
+
+      const templateDirs = {
+        starter: join(packageRoot, "templates", "starter"),
+        full: join(packageRoot, "templates", "full"),
+      };
+
+      // Determine which template tier this project uses
+      let tier = "starter";
+      if (existsSync(join(d, ".context", "REGISTRY.md"))) {
+        tier = "full";
+      } else if (
+        existsSync(join(d, "REQUIREMENTS.md")) &&
+        existsSync(join(d, "SUMMARY.md"))
+      ) {
+        tier = "full";
+      }
+      const srcDir = templateDirs[tier] || templateDirs.starter;
+
+      if (!existsSync(srcDir)) {
+        console.error(
+          `Template directory not found: ${srcDir}. ` +
+            "Run from the wwa repo or install from source."
+        );
+        process.exit(1);
+      }
+
+      // 1. Update method_version in entry point
+      if (ep) {
+        let content = readFileSync(ep, "utf-8");
+        const currentVer = readMethodVersion(ep);
+        const newVer = pkg.version.split(".").slice(0, 2).join(".");
+        if (currentVer && currentVer !== newVer) {
+          actions.push(
+            `Update ${basename_of(ep)}: method_version ${currentVer} -> ${newVer}`
+          );
+          if (!opts.dryRun) {
+            content = content.replace(/(method_version:\s*)\S+/, `$1${newVer}`);
+            safeWriteFile(ep, content, "utf-8");
+          }
+        } else if (!currentVer) {
+          actions.push(`Add method_version: ${newVer} to ${basename_of(ep)}`);
+          if (!opts.dryRun) {
+            if (content.includes("## Conventions")) {
+              const insert =
+                `## Method version\n\n` +
+                `method_version: ${newVer}\n` +
+                `<!-- Tracks which methodology version generated this entry point -->\n` +
+                `<!-- Use \`wwa status\` to compare against latest -->\n\n`;
+              content = content.replace("## Conventions", insert + "## Conventions");
+              safeWriteFile(ep, content, "utf-8");
+            }
+          }
+        }
+      }
+
+      // 2. Add missing methodology files (brownfield-safe: skip existing)
+      const methodologyFiles = ["SESSION-LOG.md", "PROJECT-PROFILE.md"];
+      if (tier === "full") {
+        methodologyFiles.push(join(".context", "METHODOLOGY.md"));
+      }
+
+      for (const fname of methodologyFiles) {
+        const src = join(srcDir, fname);
+        const dst = join(d, fname);
+        if (existsSync(src) && !existsSync(dst)) {
+          actions.push(`Create ${fname} (new)`);
+          if (!opts.dryRun) {
+            mkdirSync(dirname(dst), { recursive: true });
+            safeCopyFile(src, dst);
+          }
+        }
+      }
+
+      // 2b. Ensure CLI command metadata file exists in project (safe to add).
+      // Only docs/internal/cli-commands.yaml is copied from the package; all other
+      // docs/internal files remain dev-only.
+      try {
+        const cliSrc = join(packageRoot, "docs", "internal", "cli-commands.yaml");
+        const cliDst = join(d, "docs", "internal", "cli-commands.yaml");
+        if (existsSync(cliSrc) && !existsSync(cliDst)) {
+          actions.push("Create docs/internal/cli-commands.yaml (CLI metadata)");
+          if (!opts.dryRun) {
+            mkdirSync(dirname(cliDst), { recursive: true });
+            safeCopyFile(cliSrc, cliDst);
+          }
+        }
+      } catch {
+        // Best-effort; upgrade should not fail if CLI metadata copy fails.
+      }
+
+      // 3. Check for session close cascade (add if missing)
+      if (ep) {
+        let content = readFileSync(ep, "utf-8");
+        if (!content.toLowerCase().includes("session close")) {
+          actions.push(`Add session close cascade rule to ${basename_of(ep)}`);
+          if (!opts.dryRun) {
+            if (content.includes("<!-- INSTRUCTION: Add project-specific cascade")) {
+              content = content.replace(
+                "<!-- INSTRUCTION: Add project-specific cascade",
+                "| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry" +
+                  " \u2014 effort, ambiguity, context level, tokens, time, user response, refinement delta, workflow, features, cascades, friction, findings) " +
+                  "|\n\n<!-- INSTRUCTION: Add project-specific cascade"
+              );
+              safeWriteFile(ep, content, "utf-8");
+            }
+          }
+        }
+
+        // 4. Check for session observation convention
+        content = readFileSync(ep, "utf-8");
+        if (!content.toLowerCase().includes("session-log")) {
+          actions.push(
+            `Add session observation convention to ${basename_of(ep)}`
+          );
+          if (!opts.dryRun) {
+            if (content.includes("## Do not")) {
+              content = content.replace(
+                "## Do not",
+                "- At session close or after any high-effort task, append a metrics entry to " +
+                  "SESSION-LOG.md \u2014 include effort level, question ambiguity, context level, " +
+                  "estimated tokens, time, user response (accepted/edited/revised/rejected/redirected), " +
+                  "and for medium/high effort tasks: revision count, refinement magnitude " +
+                  "(none/minor/moderate/major/rework), delta categories, and survival rate. Never skip, never read " +
+                  "previous entries during normal work\n\n" +
+                  "## Do not"
+              );
+              safeWriteFile(ep, content, "utf-8");
+            }
+          }
+        }
+      }
+
+      // 5. Migrate registry files from .context/ to registry/
+      const legacyTokens = join(d, ".context", "doc-tokens.yaml");
+      const legacyFeatures = join(d, ".context", "feature-registry.yaml");
+      const registryDir = join(d, "registry");
+      const hasLegacy = existsSync(legacyTokens) || existsSync(legacyFeatures);
+      const hasRegistry = existsSync(registryDir);
+
+      if (hasLegacy && !hasRegistry) {
+        actions.push("Create registry/ directory");
+        if (!opts.dryRun) mkdirSync(registryDir, { recursive: true });
+
+        if (existsSync(legacyTokens)) {
+          const newTokens = join(registryDir, "doc-tokens.yaml");
+          actions.push("Move .context/doc-tokens.yaml → registry/doc-tokens.yaml");
+          if (!opts.dryRun) {
+            copyFileSync(legacyTokens, newTokens);
+            unlinkSync(legacyTokens);
+          }
+        }
+
+        if (existsSync(legacyFeatures)) {
+          const newFeatures = join(registryDir, "feature-registry.yaml");
+          actions.push("Move .context/feature-registry.yaml → registry/feature-registry.yaml");
+          if (!opts.dryRun) {
+            copyFileSync(legacyFeatures, newFeatures);
+            unlinkSync(legacyFeatures);
+          }
+        }
+
+        // Update path references in PROTOCOL.yaml and INDEX.yaml
+        const protocolPath = join(d, ".context", "PROTOCOL.yaml");
+        const indexPath = join(d, ".context", "INDEX.yaml");
+        const replacements = [
+          [".context/doc-tokens.yaml", "registry/doc-tokens.yaml"],
+          [".context/feature-registry.yaml", "registry/feature-registry.yaml"],
+        ];
+
+        for (const filePath of [protocolPath, indexPath]) {
+          if (existsSync(filePath)) {
+            let content = readFileSync(filePath, "utf-8");
+            let changed = false;
+            for (const [oldRef, newRef] of replacements) {
+              if (content.includes(oldRef)) {
+                content = content.replaceAll(oldRef, newRef);
+                changed = true;
+              }
+            }
+            if (changed) {
+              actions.push(`Update path references in ${filePath.replace(d, "").replace(/^[\\/]/, "")}`);
+              if (!opts.dryRun) safeWriteFile(filePath, content, "utf-8");
+            }
+          }
+        }
+      }
+
+      // Report
+      if (actions.length === 0) {
+        console.log(`Project at ${directory} is up to date (v${pkg.version}).`);
+      } else if (opts.dryRun) {
+        console.log(`Dry run \u2014 ${actions.length} changes needed:`);
+        for (const a of actions) console.log(`  - ${a}`);
+      } else {
+        console.log(
+          `Upgraded ${directory} to methodology v${pkg.version} (${actions.length} changes):`
+        );
+        for (const a of actions) console.log(`  - ${a}`);
+      }
+    });
+}

package/lib/cli/watch.js

@@ -0,0 +1,32 @@
+/** wwa watch — file watcher for proactive validation. */
+
+export function register(program) {
+  program
+    .command("watch [directory]")
+    .description("Watch entry points and markdown files for changes, validate on save")
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .action(async (directory, opts) => {
+      const dir = directory || ".";
+
+      console.log(`Watching: ${dir}`);
+      console.log("Monitoring entry points, registry, and markdown files...");
+      console.log("Press Ctrl+C to stop.\n");
+
+      try {
+        const { createWatcher } = await import("../watcher.js");
+        const watcher = createWatcher(dir, {
+          registryPath: opts.registry || undefined,
+        });
+
+        // Keep process alive
+        process.on("SIGINT", () => {
+          watcher.close();
+          console.log("\nWatcher stopped.");
+          process.exit(0);
+        });
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}

package/lib/dependencies.js

@@ -0,0 +1,196 @@
+/**
+ * Document dependency graph operations — build, query, and sort.
+ * Used by: wwa init (seeding), wwa close (growth tracking),
+ *          wwa route (dependency ordering), wwa deps (visualization).
+ */
+
+// ---------------------------------------------------------------------------
+// Project-type default edges (derived from pipeline.js cascade tables)
+// ---------------------------------------------------------------------------
+
+const UNIVERSAL_EDGES = [
+  { from: "STATE.md", to: "ROADMAP.md", type: "cascades_to", trigger: "phase_complete" },
+  { from: "STATE.md", to: "PLAN.md", type: "cascades_to", trigger: "requirements_change" },
+  { from: "SUMMARY.md", to: "STATE.md", type: "cascades_to", trigger: "phase_complete" },
+  { from: ".context/BASE.md", to: ".context/DOCS-MAP.md", type: "cascades_to", trigger: "structure_changed" },
+  { from: ".context/PROTOCOL.yaml", to: "STATE.md", type: "validates", trigger: "close_check" },
+  { from: "ROADMAP.md", to: "PLAN.md", type: "reads_from" },
+  { from: "PLAN.md", to: "STATE.md", type: "reads_from" },
+];
+
+const CODE_EDGES = [
+  { from: ".context/DATABASE.md", to: ".context/BASE.md", type: "cascades_to", trigger: "database_schema" },
+  { from: ".context/API.md", to: ".context/BASE.md", type: "cascades_to", trigger: "api_route" },
+  { from: ".context/BASE.md", to: ".context/API.md", type: "reads_from" },
+  { from: ".context/BASE.md", to: ".context/DATABASE.md", type: "reads_from" },
+];
+
+const DATA_EDGES = [
+  { from: ".context/SCHEMA.md", to: ".context/BASE.md", type: "cascades_to", trigger: "schema_change" },
+  { from: ".context/SCHEMA.md", to: ".context/RELATIONSHIPS.md", type: "cascades_to", trigger: "schema_change" },
+  { from: ".context/DOCUMENTS.md", to: ".context/BASE.md", type: "cascades_to", trigger: "new_document" },
+  { from: ".context/BASE.md", to: ".context/SCHEMA.md", type: "reads_from" },
+];
+
+const ANALYTICAL_EDGES = [
+  { from: ".context/COMPOSITION.md", to: ".context/EVALUATION.md", type: "cascades_to", trigger: "prompt_template" },
+  { from: ".context/DOMAIN.md", to: ".context/COMPOSITION.md", type: "cascades_to", trigger: "domain_knowledge" },
+  { from: ".context/EXECUTION.md", to: ".context/BASE.md", type: "cascades_to", trigger: "pipeline_stage" },
+  { from: ".context/BASE.md", to: ".context/EXECUTION.md", type: "reads_from" },
+];
+
+export const DOC_GRAPH_DEFAULTS = {
+  universal: UNIVERSAL_EDGES,
+  code: CODE_EDGES,
+  data: DATA_EDGES,
+  analytical: ANALYTICAL_EDGES,
+};
+
+// ---------------------------------------------------------------------------
+// Node/edge builders
+// ---------------------------------------------------------------------------
+
+const STARTER_FILES = [
+  { path: "STATE.md", category: "intelligence", role: "decisions and position" },
+  { path: "PLAN.md", category: "intelligence", role: "current task" },
+  { path: "ROADMAP.md", category: "intelligence", role: "phase breakdown" },
+  { path: "SUMMARY.md", category: "intelligence", role: "audit trail" },
+  { path: "PROJECT.md", category: "intelligence", role: "project vision" },
+  { path: "PROJECT-PROFILE.md", category: "intelligence", role: "type/stage/extensions" },
+  { path: "SESSION-LOG.md", category: "intelligence", role: "session metrics" },
+  { path: ".context/BASE.md", category: "context", role: "system model" },
+  { path: ".context/PROTOCOL.yaml", category: "context", role: "agent rules" },
+  { path: ".context/INDEX.yaml", category: "context", role: "file inventory" },
+  { path: ".context/METHODOLOGY.md", category: "context", role: "onboarding protocol" },
+  { path: ".context/DOCS-MAP.md", category: "context", role: "docs navigation" },
+  { path: "registry/doc-tokens.yaml", category: "registry", role: "token registry" },
+  { path: "registry/feature-registry.yaml", category: "registry", role: "feature catalog" },
+  { path: "Management/DIGEST.md", category: "management", role: "high-effort task digest" },
+  { path: "Management/STATUS.md", category: "management", role: "project health snapshot" },
+];
+
+const FULL_EXTRA_FILES = [
+  { path: "REQUIREMENTS.md", category: "intelligence", role: "formal requirements" },
+  { path: ".context/REGISTRY.md", category: "context", role: "navigation for split files" },
+  { path: ".context/COMPOSITION.md", category: "context", role: "extension composition" },
+  { path: "todos/backlog.md", category: "intelligence", role: "future ideas" },
+];
+
+/** Return default node list for a template tier. */
+export function buildDefaultNodes(tier) {
+  const nodes = [...STARTER_FILES];
+  if (tier === "full") nodes.push(...FULL_EXTRA_FILES);
+  return nodes;
+}
+
+/** Return default edge list for a project type (universal + type-specific). */
+export function buildDefaultEdges(projectType) {
+  const edges = [...UNIVERSAL_EDGES];
+  if (projectType === "code" || projectType === "mixed") edges.push(...CODE_EDGES);
+  if (projectType === "data" || projectType === "mixed") edges.push(...DATA_EDGES);
+  if (projectType === "analytical" || projectType === "mixed") edges.push(...ANALYTICAL_EDGES);
+  return edges;
+}
+
+// ---------------------------------------------------------------------------
+// Graph operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Topological sort of a file set by reads_from edges.
+ * Files that are read by others come first. Falls back to original order for
+ * files not in the graph or when no graph is provided.
+ */
+export function orderByDependencies(fileSet, docGraph) {
+  if (!docGraph || !docGraph.edges || docGraph.edges.length === 0) {
+    return [...fileSet].sort();
+  }
+
+  // Build adjacency: for reads_from edges, "from" depends on "to"
+  // So "to" should come before "from" in reading order
+  const dependsOn = new Map(); // file -> set of files it depends on
+  for (const edge of docGraph.edges) {
+    if (edge.type === "reads_from") {
+      if (!dependsOn.has(edge.from)) dependsOn.set(edge.from, new Set());
+      dependsOn.get(edge.from).add(edge.to);
+    }
+  }
+
+  const fileSetLower = new Set(fileSet.map(f => f.toLowerCase()));
+  const inSet = (f) => fileSetLower.has(f.toLowerCase());
+
+  // Kahn's algorithm for topological sort
+  const inDegree = new Map();
+  const adj = new Map();
+  const relevant = fileSet.filter(f => dependsOn.has(f) || [...dependsOn.values()].some(s => s.has(f)));
+
+  for (const f of fileSet) {
+    inDegree.set(f, 0);
+    adj.set(f, []);
+  }
+
+  for (const [file, deps] of dependsOn) {
+    if (!inSet(file)) continue;
+    for (const dep of deps) {
+      if (!inSet(dep)) continue;
+      adj.get(dep)?.push(file);
+      inDegree.set(file, (inDegree.get(file) || 0) + 1);
+    }
+  }
+
+  const queue = [];
+  for (const [f, deg] of inDegree) {
+    if (deg === 0) queue.push(f);
+  }
+  queue.sort(); // stable alphabetical within same level
+
+  const result = [];
+  while (queue.length > 0) {
+    const f = queue.shift();
+    result.push(f);
+    for (const next of (adj.get(f) || [])) {
+      const newDeg = (inDegree.get(next) || 1) - 1;
+      inDegree.set(next, newDeg);
+      if (newDeg === 0) queue.push(next);
+    }
+  }
+
+  // Add any files not reached by the sort (disconnected from graph)
+  for (const f of fileSet) {
+    if (!result.includes(f)) result.push(f);
+  }
+
+  return result;
+}
+
+/** Find orphan nodes — nodes with no incoming or outgoing edges. */
+export function findOrphans(docGraph) {
+  if (!docGraph || !docGraph.nodes || !docGraph.edges) return [];
+
+  const connected = new Set();
+  for (const edge of docGraph.edges) {
+    connected.add(edge.from);
+    connected.add(edge.to);
+  }
+
+  return docGraph.nodes
+    .map(n => n.path)
+    .filter(p => !connected.has(p));
+}
+
+/** Detect files on disk that are not yet in the dependency graph nodes. */
+export function detectNewFiles(existingNodes, currentFiles) {
+  const nodePaths = new Set((existingNodes || []).map(n => n.path));
+  return currentFiles.filter(f => !nodePaths.has(f));
+}
+
+/** Infer node category from file path. */
+export function inferCategory(filePath) {
+  const p = filePath.replace(/\\/g, "/").toLowerCase();
+  if (p.startsWith("docs/")) return "docs";
+  if (p.startsWith(".context/")) return "context";
+  if (p.startsWith("management/")) return "management";
+  if (p.startsWith("reviews/") || p.startsWith("agentworkflows/")) return "reporting";
+  if (p.startsWith("intro/")) return "docs";
+  return "unknown";
+}