agent-method 1.5.13 → 1.5.15

package/lib/cli/upgrade.js

@@ -1,4 +1,9 @@
-/** wwa upgrade — brownfield-safe methodology update. */
+/**
+ * wwa upgrade — brownfield-safe methodology update.
+ *
+ * Invariant (all wwa commands): canonical names persist in the working directory;
+ * versioned/archived copies live only under .wwa-archive/ (see helpers.WWA_ARCHIVE_DIR).
+ */
 
 import {
   readFileSync, existsSync, mkdirSync, copyFileSync, unlinkSync,
@@ -6,7 +11,7 @@ import {
 import { resolve, join, dirname } from "node:path";
 import {
   findEntryPoint, readMethodVersion, basename_of, pkg, packageRoot,
-  safeWriteFile, safeCopyFile,
+  safeWriteFile, safeCopyFile, WWA_ARCHIVE_DIR,
 } from "./helpers.js";
 
 export function register(program) {
@@ -206,12 +211,12 @@ export function register(program) {
         }
       }
 
-      // 6. Non-destructive template/schema upgrades (versioned files + backlog)
+      // 6. Non-destructive template/schema upgrades (archived originals + live latest)
       //
-      // 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.
+      // When templates or schemas change, we never delete user content. Instead we:
+      //  - Archive the existing file into a subdirectory (e.g. .wwa-archive/entry-points/CLAUDE.md)
+      //  - Replace the live file with the latest template/schema
+      //  - Add a backlog entry pointing to the archived copy so migration can be reviewed.
 
       // 6a. Entry point templates (CLAUDE.md / .cursorrules / AGENT.md)
       if (ep) {
@@ -220,19 +225,20 @@ export function register(program) {
         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);
-              }
+            const archiveDir = join(d, WWA_ARCHIVE_DIR, "entry-points");
+            const baseArchivePath = join(archiveDir, entryName);
+            const archivePath = nextVersionedPathInsideArchive(archiveDir, entryName);
+            const relArchive = archivePath.replace(d, "").replace(/^[\\/]/, "");
+            actions.push(`Archive existing entry point to ${relArchive} and replace with latest template`);
+            if (!opts.dryRun) {
+              mkdirSync(dirname(archivePath), { recursive: true });
+              safeCopyFile(ep, archivePath);
+              safeCopyFile(templatePath, ep);
             }
             ensureBacklogEntry(
               d,
-              relV2,
-              `- [ ] **Review new entry point template** — A new version of ${relV2} is available. Review differences and migrate conventions when convenient.`
+              relArchive,
+              `- [ ] **Review upgraded entry point** — Existing entry point archived at ${relArchive}. Compare with current ${entryName} and reconcile any custom conventions.`
             );
           }
         }
@@ -249,19 +255,19 @@ export function register(program) {
       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);
-            }
+          const archiveDir = join(d, WWA_ARCHIVE_DIR, "registry");
+          const archivePath = nextVersionedPathInsideArchive(archiveDir, "doc-tokens.yaml");
+          const relArchive = archivePath.replace(d, "").replace(/^[\\/]/, "");
+          actions.push(`Archive existing registry/doc-tokens.yaml to ${relArchive} and replace with latest schema`);
+          if (!opts.dryRun) {
+            mkdirSync(dirname(archivePath), { recursive: true });
+            safeCopyFile(projectTokensPath, archivePath);
+            safeCopyFile(templateTokensPath, projectTokensPath);
           }
           ensureBacklogEntry(
             d,
-            relV2,
-            `- [ ] **Migrate doc-tokens schema** — New schema written to ${relV2}. Plan migration and update tooling as needed.`
+            relArchive,
+            `- [ ] **Review doc-tokens schema migration** — Previous schema archived at ${relArchive}. Confirm that tooling and docs are compatible with the updated registry/doc-tokens.yaml.`
           );
         }
       }
@@ -282,8 +288,12 @@ export function register(program) {
 }
 
 // ---------------------------------------------------------------------------
-// Helper functions — change classification, versioned paths, backlog entries
+// Helper functions — change classification, archive paths, backlog entries
 // ---------------------------------------------------------------------------
+//
+// Versioned filenames are only ever created inside the archive subdirectory,
+// never in the working directory, so canonical names (CLAUDE.md, doc-tokens.yaml)
+// always persist in place.
 
 function classifyMarkdownChange(templatePath, projectPath) {
   if (!existsSync(projectPath) || !existsSync(templatePath)) return "missing";
@@ -303,16 +313,17 @@ function classifyYamlChange(templatePath, projectPath) {
   return "schema_changed";
 }
 
-function nextVersionedPath(projectPath) {
-  const match = projectPath.match(/^(.*)(\.[^./\\]+)$/);
-  const stem = match ? match[1] : projectPath;
+/**
+ * Return a path for an archived copy, with a version suffix only inside the archive dir.
+ * Ensures we never write *.v2.* in the working directory — only under archiveDir.
+ */
+function nextVersionedPathInsideArchive(archiveDir, filename) {
+  const match = filename.match(/^(.*)(\.[^./\\]+)$/);
+  const stem = match ? match[1] : filename;
   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}`;
+  for (;;) {
+    const candidate = join(archiveDir, `${stem}.v${counter}${ext}`);
     if (!existsSync(candidate)) return candidate;
     counter += 1;
   }

package/lib/init.js

@@ -57,8 +57,7 @@ export async function initProject(projectType, directory, opts = {}) {
 
   const templateDir = join(methodRoot, "templates", tier);
   if (!existsSync(templateDir)) {
-    console.error(`Template directory not found: ${templateDir}`);
-    process.exit(1);
+    throw new Error(`Template directory not found: ${templateDir}`);
   }
 
   console.log(`\nSetting up ${FRIENDLY_NAMES[projectType] || projectType} project`);