wdi-method 0.5.0 → 0.5.2

package/README.md

@@ -228,19 +228,26 @@ It prints the version it replaced, what it wrote, what it kept, and what to do n
 
 ---
 
-## Carrying a change back into this package
+## Changing the method
 
-The published source is this repository. A product repo that holds a newer working copy of the method
-promotes it here before the change counts as published:
+**This repository is where a method change is authored** — a guide, a template, a skill wrapper, a
+validator. It is proven here before publishing, against a fixture corpus the three registry scripts
+actually run against:
 
 ```bash
-npx wdi-method promote /path/to/the/product-repo
-npm test
-git commit && git push
+npm test        # includes validate.py, timeline.py and inventory.py over tests/fixture/
 ```
 
-`promote` copies the portable method, replaces product-named files with their generic versions, scrubs
-initiative slugs, and **skips `.constitution/project/`** so a product's own rules can never be published.
+The fixture is small but complete, and kept **green**, so a new finding is a regression rather than
+noise. One test plants a defect in a copy and requires the matching validator to name it — a green
+baseline is worthless if it is green because every check is broken.
+
+A consuming repo then takes the change with `npx wdi-method update`, and that is where the judgement
+half gets tested: whether a guide actually helps a person at G3 is only provable in use.
+
+`promote` — pulling the method back out of a consumer — is a **rescue tool**, not the workflow. It
+overwrites the whole kit from one copy, so it refuses to run without `--rescue`.
+[`CONTRIBUTING.md`](CONTRIBUTING.md) records why the direction was reversed and what it cost.
 
 **Patch releases are routine; minor and major are the maintainer's call.** This package overwrites files
 in repos that already hold months of work, and the version is the only signal a reader has for how

package/bin/wdi-method.js

@@ -89,7 +89,7 @@ function usage() {
   install [dir]             first install (TUI unless --yes)
   update  [dir]             update      (TUI unless --yes)
   verify  [dir]
-  promote <live-dir>
+  promote <live-dir> --rescue   pull a method change back out of a consumer (not the normal flow)
 
   --yes                     non-interactive
   --agents a,b              claude,cursor,codex,antigravity
@@ -109,6 +109,7 @@ function parseArgs(argv) {
     dir: null,
     agents: null,
     skipBmad: false,
+    rescue: false,
     yes: false,
     product: null,
     client: null,
@@ -136,6 +137,7 @@ function parseArgs(argv) {
   while (rest.length) {
     const t = rest.shift();
     if (t === "--skip-bmad-check") args.skipBmad = true;
+    else if (t === "--rescue") args.rescue = true;
     else if (t === "--yes" || t === "-y") args.yes = true;
     else if (t === "--agents") {
       const raw = rest.shift();
@@ -324,6 +326,77 @@ function mv(from, to) {
   fs.renameSync(from, to);
 }
 
+/** Article numbers that belong to the method half. The product keeps 1, 2, and 5. */
+const METHOD_ARTICLES = [3, 4, 6, 7];
+
+/**
+ * Cut the method's articles out of a product's constitution.md, and repoint its relative links.
+ *
+ * Returns {cut, kept, relinked}, or null when the file does not look like a constitution at all —
+ * in which case it is left ALONE rather than guessed at.
+ *
+ * 0.5.0 moved the file whole and printed "delete Articles 3, 4, 6, 7 yourself", on the grounds that
+ * no script can tell an edited copy from the original. That reasoning was wrong in the way that
+ * matters: the split does not need to know whether a section was edited, only which article numbers
+ * are the method's — and the file states them in its own headings. Leaving it whole left every
+ * migrated repo carrying those articles in TWO files, one of them frozen and drifting, plus relative
+ * links that no longer resolve one level down. It is all in git, so cutting is reversible; not
+ * cutting is what nobody notices.
+ */
+function splitProductConstitution(file) {
+  const raw = fs.readFileSync(file, "utf8");
+  const crlf = raw.includes("\r\n");
+  const text = crlf ? raw.replaceAll("\r\n", "\n") : raw;
+  const marks = [...text.matchAll(/^## Article (\d+)\b.*$/gm)];
+  if (marks.length < 2) return null;   // not the shape we know; do not touch it
+
+  const kept = [];
+  const cut = [];
+  let out = text.slice(0, marks[0].index);
+  for (let i = 0; i < marks.length; i += 1) {
+    const n = Number(marks[i][1]);
+    const end = i + 1 < marks.length ? marks[i + 1].index : text.length;
+    if (METHOD_ARTICLES.includes(n)) cut.push(n);
+    else {
+      kept.push(n);
+      out += text.slice(marks[i].index, end);
+    }
+  }
+  if (!cut.length) return { cut, kept, relinked: 0 };
+
+  // The file sits one level deeper than it did, and its former siblings moved into method/. A link
+  // left as `repo-guide.md` now resolves to .constitution/project/repo-guide.md, which does not exist.
+  let relinked = 0;
+  const bump = (re, to) => {
+    out = out.replace(re, (m, ...rest) => {
+      relinked += 1;
+      return typeof to === "function" ? to(m, ...rest) : to + m;
+    });
+  };
+  for (const name of ["repo-guide.md", "structure-guide.md", "language-guide.md",
+                      "method-glossary.md"]) {
+    bump(new RegExp(`(?<![\\w./-])${name.replace(".", "\\.")}`, "g"), "../method/");
+  }
+  bump(/(?<![\w./-])document\//g, "../method/");
+  bump(/(?<![\w./-])codebase\/([a-z]+)-guide\.md/g, (_m, kind) => `codebase-${kind}-guide.md`);
+  out = out.replaceAll("../method/../method/", "../method/");
+
+  const banner = [
+    "",
+    `> **Articles ${cut.join(", ")} were removed from this file on migration to the two-folder layout.**`,
+    "> They are the method's and live in [`../method/constitution.md`](../method/constitution.md), which",
+    `> \`update\` replaces. Only Articles ${kept.join(", ")} are yours. The removed text is in git.`,
+    "",
+  ].join("\n");
+  const firstArticle = out.search(/^## Article /m);
+  out = firstArticle === -1
+    ? out + banner
+    : out.slice(0, firstArticle) + banner.trimStart() + "\n" + out.slice(firstArticle);
+
+  fs.writeFileSync(file, crlf ? out.replaceAll("\n", "\r\n") : out, "utf8");
+  return { cut, kept, relinked };
+}
+
 function migrateToTwoFolders(target) {
   const c = path.join(target, ".constitution");
   if (!fs.existsSync(c)) return false;          // a first install has nothing to migrate
@@ -375,11 +448,18 @@ function migrateToTwoFolders(target) {
   }
   // 6. The product's constitution.md moves WHOLE into the room, so its Articles 1, 2, and 5 survive
   //    exactly as written. The generic half then arrives fresh at method/constitution.md.
-  let split = false;
+  let split = null;
   if (fs.existsSync(at("constitution.md")) && !fs.existsSync(at("project", "constitution.md"))) {
     mv(at("constitution.md"), at("project", "constitution.md"));
-    note("  moved constitution.md → project/constitution.md (your Articles 1, 2, 5)");
-    split = true;
+    note("  moved constitution.md → project/constitution.md");
+    split = splitProductConstitution(at("project", "constitution.md"));
+    if (split && split.cut.length) {
+      note(`    kept Articles ${split.kept.join(", ")}, removed ${split.cut.join(", ")} `
+           + "(the method's — they arrive in method/constitution.md)");
+      if (split.relinked) note(`    repointed ${split.relinked} relative links one level up`);
+    } else if (split === null) {
+      note("    it does not carry `## Article N` headings, so it was moved but NOT split — yours to check");
+    }
   }
   // Anything else loose at the root is a file this product ADDED. It is NOT moved: it may be routed
   // from AGENTS.md by its current path, and guessing a destination would break that silently.
@@ -390,6 +470,8 @@ function migrateToTwoFolders(target) {
     : [];
   if (stray.length) {
     note(`  left at .constitution/ root, yours to place: ${stray.join(", ")}`);
+    note("    a file you added belongs in project/ — but moving it would break any pointer that");
+    note("    names its current path, so the choice is yours. repo-guide.md states the rule.");
   }
   return split;
 }
@@ -745,10 +827,14 @@ function apply(target, agents,
   const splitConstitution = migrateToTwoFolders(target);
   const { written, skipped } = syncConstitution(target);
   note(`constitution wrote ${written}, kept ${skipped}`);
+  // A migrated repo also carries derived output stamped against the OLD layout: .control/generated/*
+  // still names the pre-0.5.0 script path, and the two structure maps still draw the old tree. The
+  // installer MUST NOT write either — one is generated, the other is re-derived by a skill — so it
+  // says so instead of leaving them to be found by whoever trusts them next.
   if (splitConstitution) {
-    note("  your constitution.md still carries Articles 3, 4, 6, 7 — now also in method/constitution.md.");
-    note("  Delete them from project/constitution.md; only 1, 2, 5 are yours. Not automated: your");
-    note("  copy may have been edited, and no script can tell an edit from the original.");
+    note("  derived output still describes the OLD layout, and neither is mine to write:");
+    note("    uv run .constitution/method/scripts/validate.py --generate   → .control/generated/");
+    note("    then the wdi-init skill, intent `structure`                  → the two structure maps");
   }
   const skills = syncSkills(target, agents);
   note(`skills ${skills.files} files`);
@@ -1100,6 +1186,20 @@ async function main() {
   }
   if (args.cmd === "promote") {
     if (!args.dir) die("promote needs a path to the working copy");
+    // `promote` used to BE the workflow: author a rule in a product repo, run it, carry it here.
+    // It is now a rescue tool, and the flag is what makes that structural rather than a paragraph
+    // nobody rereads. Running it by habit overwrites the whole kit with one consumer's copy —
+    // silently reverting every change made here since that repo last updated.
+    if (!args.rescue) {
+      die([
+        "promote overwrites the whole kit from a consumer's copy, and this package is now where a",
+        "       method change is authored — see CONTRIBUTING.md. If a change really was made in a",
+        "       product repo by mistake and needs rescuing, say so:",
+        "",
+        "         npx wdi-method promote <dir> --rescue",
+      ].join("\n"));
+    }
+    note("--rescue: pulling the method back out of a consumer. Read the diff before committing.");
     promote(args.dir);
     return;
   }

package/kit/.constitution/method/README.md

@@ -2,31 +2,37 @@
 status: Reference
 ---
 
-# `.constitution/` — index
+# `.constitution/method/` — index
 
-Method files arrive from the public WDI Method package via `npx wdi-method install`
-or `update`. Load [`constitution.md`](constitution.md) before acting. Guides are
-loaded **lazily** — only when the task matches, and every guide states when on its
-own **Loaded when:** line.
+`.constitution/` holds **exactly two folders**, and the folder is what says who owns a file:
+
+| Folder | Owner | `update` | `promote` |
+|---|---|---|---|
+| `method/` — you are in it | the method | **overwritten** in full | carries it into the package |
+| [`../project/`](../project/) | this product | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
+
+Load [`constitution.md`](constitution.md) and [`../project/constitution.md`](../project/constitution.md)
+before acting: Articles 3, 4, 6, 7 are here, Articles 1, 2, 5 are yours. Guides are loaded **lazily** —
+only when the task matches, and every guide states when on its own **Loaded when:** line.
 
 Every file here carries a `status:` — Article 4 owns the five values. Only `Accepted` binds;
 `Reference` explains and MUST NOT be cited to reject a change. A template carries no status of its
 own, because its frontmatter belongs to the artifact it produces.
 
-A file this product added (one that is not in the snapshot) stays here across `update` and MUST be
-listed from `constitution.md` Article 2 or from `AGENTS.md` routing — this index is overwritten on
-every update.
+**A file this product adds MUST go in [`../project/`](../project/), not here** — anything in `method/`
+is replaced on the next update, without warning, because that is what `method/` means. This index is
+overwritten too.
 
-## `method/` — the explanation, `status: Reference`
+## `why/` — the explanation, `status: Reference`
 
 Never a rule. When it disagrees with a guide, the guide wins and the disagreement is a defect.
 
 | File | Opened when |
 |---|---|
-| [`method/README.md`](method/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
-| [`method/artifact-map.md`](method/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
-| [`method/rationale.md`](method/rationale.md) | Before changing a rule, to know what you would break |
-| [`method/portability.md`](method/portability.md) | Which files are the method and which are the product; how promote and install move them |
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
+| [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
+| [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |
+| [`why/portability.md`](why/portability.md) | Which files are the method and which are the product; how promote and install move them |
 
 ## Cross-domain
 
@@ -51,12 +57,13 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 | [`decision-guide.md`](document/decision-guide.md) | `DEC-`: the one test for recording at all, shape, global numbering, the `draft → accepted → applied` ladder, supersession |
 | [`templates/`](document/templates/) | Templates, one per kind of document; they MUST be copied, and MUST NOT be reproduced from memory |
 
-## `codebase/` — code rules
+## Code rules — in the room, not here
 
-All three are written by the **project**, not the kit. While `Draft`, their contents MAY be read as
-guidance but MUST NOT be used to reject a change.
+All three are written by the **product**, so they live in [`../project/`](../project/) and no update
+touches them at any `status:`. While `Draft`, their contents MAY be read as guidance but MUST NOT be
+used to reject a change.
 
-[`stack-guide.md`](codebase/stack-guide.md) · [`conventions-guide.md`](codebase/conventions-guide.md) · [`brownfield-guide.md`](codebase/brownfield-guide.md)
+[`stack-guide.md`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
 
 ## `scripts/`