agent-method 1.5.12 → 1.5.13

package/bin/wwa.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * wwa CLI — methodology tools for AI-agent-assisted development.

package/lib/cli/upgrade.js

@@ -206,6 +206,66 @@ export function register(program) {
         }
       }
 
+      // 6. Non-destructive template/schema upgrades (versioned files + backlog)
+      //
+      // When templates or schemas change, we never overwrite existing project files.
+      // Instead we:
+      //  - Write a versioned file alongside the original (e.g. CLAUDE.v2.md, doc-tokens.v2.yaml)
+      //  - Add a backlog entry pointing to the new file so the user/agent can migrate.
+
+      // 6a. Entry point templates (CLAUDE.md / .cursorrules / AGENT.md)
+      if (ep) {
+        const entryName = basename_of(ep); // e.g. CLAUDE.md
+        const templatePath = join(srcDir, entryName);
+        if (existsSync(templatePath)) {
+          const change = classifyMarkdownChange(templatePath, ep);
+          if (change === "present_diverged_user") {
+            const v2Path = nextVersionedPath(ep);
+            const relV2 = v2Path.replace(d, "").replace(/^[\\/]/, "");
+            if (!existsSync(v2Path)) {
+              actions.push(`Write versioned entry point template ${relV2}`);
+              if (!opts.dryRun) {
+                mkdirSync(dirname(v2Path), { recursive: true });
+                safeCopyFile(templatePath, v2Path);
+              }
+            }
+            ensureBacklogEntry(
+              d,
+              relV2,
+              `- [ ] **Review new entry point template** — A new version of ${relV2} is available. Review differences and migrate conventions when convenient.`
+            );
+          }
+        }
+      }
+
+      // 6b. Registry/doc-tokens schema (YAML)
+      const projectTokensPath = join(d, "registry", "doc-tokens.yaml");
+      const templateTokensPath = join(
+        packageRoot,
+        "docs",
+        "internal",
+        "doc-tokens.yaml"
+      );
+      if (existsSync(projectTokensPath) && existsSync(templateTokensPath)) {
+        const change = classifyYamlChange(templateTokensPath, projectTokensPath);
+        if (change === "schema_changed" || change === "present_diverged_user") {
+          const v2Path = nextVersionedPath(projectTokensPath);
+          const relV2 = v2Path.replace(d, "").replace(/^[\\/]/, "");
+          if (!existsSync(v2Path)) {
+            actions.push(`Write versioned schema ${relV2}`);
+            if (!opts.dryRun) {
+              mkdirSync(dirname(v2Path), { recursive: true });
+              safeCopyFile(templateTokensPath, v2Path);
+            }
+          }
+          ensureBacklogEntry(
+            d,
+            relV2,
+            `- [ ] **Migrate doc-tokens schema** — New schema written to ${relV2}. Plan migration and update tooling as needed.`
+          );
+        }
+      }
+
       // Report
       if (actions.length === 0) {
         console.log(`Project at ${directory} is up to date (v${pkg.version}).`);
@@ -220,3 +280,74 @@ export function register(program) {
       }
     });
 }
+
+// ---------------------------------------------------------------------------
+// Helper functions — change classification, versioned paths, backlog entries
+// ---------------------------------------------------------------------------
+
+function classifyMarkdownChange(templatePath, projectPath) {
+  if (!existsSync(projectPath) || !existsSync(templatePath)) return "missing";
+  const tmpl = readFileSync(templatePath, "utf-8");
+  const proj = readFileSync(projectPath, "utf-8");
+  if (tmpl === proj) return "present_identical";
+  return "present_diverged_user";
+}
+
+function classifyYamlChange(templatePath, projectPath) {
+  if (!existsSync(projectPath) || !existsSync(templatePath)) return "missing";
+  const tmpl = readFileSync(templatePath, "utf-8");
+  const proj = readFileSync(projectPath, "utf-8");
+  if (tmpl === proj) return "present_identical";
+  // Treat any content difference as a schema-level change for now; this is
+  // conservative but guarantees we keep the original file intact.
+  return "schema_changed";
+}
+
+function nextVersionedPath(projectPath) {
+  const match = projectPath.match(/^(.*)(\.[^./\\]+)$/);
+  const stem = match ? match[1] : projectPath;
+  const ext = match ? match[2] : "";
+  let counter = 2;
+  // Generate stem.v2.ext, stem.v3.ext, ... until we find a free path
+  // (e.g. CLAUDE.v2.md, doc-tokens.v2.yaml).
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = `${stem}.v${counter}${ext}`;
+    if (!existsSync(candidate)) return candidate;
+    counter += 1;
+  }
+}
+
+function ensureBacklogEntry(projectDir, markerPath, line) {
+  const backlogCandidates = [
+    join(projectDir, "todos", "backlog.md"),
+    join(projectDir, "backlog.md"),
+  ];
+
+  let targetPath = null;
+  let content = "";
+
+  for (const p of backlogCandidates) {
+    if (existsSync(p)) {
+      const existing = readFileSync(p, "utf-8");
+      if (existing.includes(markerPath)) {
+        return; // entry already present
+      }
+      targetPath = p;
+      content = existing;
+      break;
+    }
+  }
+
+  if (!targetPath) {
+    targetPath = backlogCandidates[0];
+    mkdirSync(dirname(targetPath), { recursive: true });
+    content = "# Backlog\n\n";
+  }
+
+  if (content && !content.endsWith("\n")) {
+    content += "\n";
+  }
+  content += `${line}\n`;
+  safeWriteFile(targetPath, content, "utf-8");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-method",
-  "version": "1.5.12",
+  "version": "1.5.13",
   "description": "CLI tools for the wwa methodology — registry-driven routing, validation, and project setup for AI-agent-assisted development",
   "keywords": [
     "ai-agents",