@esneiderbravo/speclaw 0.1.12 → 0.1.13

package/README.md

@@ -189,8 +189,9 @@ without a re-init, splitting files by who owns them:
 
 - **Managed files** (speclaw's workflow machinery — the skills, commands, rules,
   and agent packs under `ai-specs/`) are **refreshed** to the new version, so
-  improvements actually reach your project. If you edited one locally, your copy
-  is saved as `<file>.bak` before the refresh — nothing is lost.
+  improvements actually reach your project. If you edited one locally, `update`
+  reports the overwrite so you can recover your copy from git; pass `--backup` to
+  also keep a `<file>.bak`. Any `*.bak` is gitignored.
 - **Personalized files** (your constitution and standards — `CLAUDE.md`,
   `AGENTS.md`, `LAWS.md`, `docs/standards/*`, `docs/compass.md`,
   `lawbook/config.yaml`) are **never auto-edited**. When a release changes their

package/dist/cli/commands/update.js

@@ -28,6 +28,21 @@ const MIGRATIONS = [
             'the feature touched)."\n' +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.1.13",
+        describe: "Required report structure in the testing standard (personalized file)",
+        agentPrompt: "- In docs/standards/testing-standards.md, strengthen the 'Reports' section so a " +
+            "discipline report MUST follow a fixed structure (evidence reproducible, not improvised): " +
+            "(1) a header — discipline, change, date, branch, and the environment/working directory " +
+            "the commands ran in; (2) a gates-and-results table with each check, the exact command, " +
+            "and the real result including pass/fail counts; (3) the tests added or updated and what " +
+            "each asserts; (4) a spec-scenario coverage table mapping every '#### Scenario' in the " +
+            "change's delta specs to how it was verified (a test, a gate, or a manual step); (5) an " +
+            "honest declaration of any pre-existing or unrelated failures with proof, or 'none'; " +
+            "(6) the manual steps not automated, or 'none'; (7) a one-line verdict. Keep the existing " +
+            "'test kind does not yet apply' escape hatch. If the section is missing, add it.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:
@@ -42,6 +57,7 @@ export async function runUpdate(flags) {
     const cwd = process.cwd();
     const migrateOnly = Boolean(flags["migrate-only"]);
     const checkOnly = Boolean(flags.check);
+    const backup = Boolean(flags.backup);
     const winShell = process.platform === "win32";
     if (!migrateOnly) {
         ui.step("Checking for updates");
@@ -66,8 +82,10 @@ export async function runUpdate(flags) {
             }
             ui.ok(`Updated to ${latest}`);
             // Re-exec the NEWLY installed binary so migrations run with the new assets
-            // and any new feature steps — not this (now-stale) process.
-            const re = spawnSync("speclaw", ["update", "--migrate-only"], {
+            // and any new feature steps — not this (now-stale) process. Carry --backup
+            // through so the refresh honors it after the upgrade.
+            const reArgs = ["update", "--migrate-only", ...(backup ? ["--backup"] : [])];
+            const re = spawnSync("speclaw", reArgs, {
                 stdio: "inherit",
                 shell: winShell,
             });
@@ -83,13 +101,18 @@ export async function runUpdate(flags) {
                 return;
         }
     }
-    applyProjectMigrations(cwd);
+    applyProjectMigrations(cwd, backup);
 }
 /**
  * Additively apply the current version's content and feature steps to a project.
  * No-op with a hint when the directory isn't a speclaw project.
+ *
+ * @param cwd - Project root to update.
+ * @param backup - When true, a locally edited managed file is copied to
+ *   `<file>.bak` before it is refreshed; the default overwrites it in place
+ *   (recoverable from git) and only reports the overwrite.
  */
-function applyProjectMigrations(cwd) {
+function applyProjectMigrations(cwd, backup) {
     const initialized = fs.existsSync(path.join(cwd, "ai-specs")) || fs.existsSync(path.join(cwd, "LAWS.md"));
     if (!initialized) {
         ui.step("Project");
@@ -106,6 +129,7 @@ function applyProjectMigrations(cwd) {
     // rewritten — those changes are handed to the user's agent below.
     const report = scaffold(cwd, { project_name: detectProjectName(cwd) }, packs, agents, {
         refreshManaged: true,
+        backup,
     });
     const changed = report.written.filter((w) => !w.includes(".gitignore"));
     if (changed.length) {
@@ -116,10 +140,19 @@ function applyProjectMigrations(cwd) {
     else {
         ui.ok("Managed content already up to date — nothing to refresh.");
     }
+    // A diverged managed file is always reported so the user can recover their
+    // edits; with --backup it is also kept as a `.bak`, otherwise it is overwritten
+    // in place (git holds the prior content).
     for (const b of report.backedUp) {
         const rel = path.relative(cwd, b);
         ui.warn(`${c.cream(rel)} had local edits — saved as ${rel}.bak before refreshing.`);
     }
+    const overwritten = report.refreshedDiverged.filter((f) => !report.backedUp.includes(f));
+    for (const f of overwritten) {
+        const rel = path.relative(cwd, f);
+        ui.warn(`${c.cream(rel)} had local edits — overwritten with the current version. ` +
+            `Recover from git, or re-run with ${ui.code("--backup")} to keep a .bak.`);
+    }
     // A project several releases behind jumps straight to @latest, so apply EVERY
     // migration newer than its recorded version — not just the next one — oldest
     // first (sorted, so array order can't matter). Entries are cumulative: never

package/dist/modules/foundation/assets/docs/standards/testing-standards.template.md

@@ -32,3 +32,30 @@ suppressing a linter or deleting a test.
 - The mandatory spec task steps
   ([`lawbook.md`](lawbook.md)) define which manual checks
   the agent must execute itself.
+
+## Reports — evidence travels with the change
+
+Every change records its testing under `lawbook/changes/<name>/reports/`, one
+file per discipline it touched (`backend.md`, `frontend.md`, …). `build`
+produces them; archiving is blocked until the change has at least one discipline
+report.
+
+Each report MUST follow a fixed structure, so the evidence is reproducible rather
+than improvised:
+
+1. a **header** — discipline, change, date, branch, and the environment or
+   working directory the commands ran in;
+2. a **gates-and-results table** — each check, the exact command, and its real
+   result with pass/fail counts;
+3. the **tests added or updated** and what each asserts (TDD evidence where it
+   applies);
+4. a **spec-scenario coverage table** mapping every `#### Scenario` in the
+   change's delta specs to how it was verified (a test, a gate, or a manual step);
+5. an honest declaration of any **pre-existing or unrelated failures** with proof
+   they are not caused by the change — or "none";
+6. the **manual steps not automated** — or "none";
+7. a one-line **verdict**.
+
+When a test kind does not yet apply (e.g. no unit runner), the report says so in
+place of that evidence and records the gates and manual verification that stood
+in.

package/dist/modules/foundation/scaffold.js

@@ -71,8 +71,10 @@ function renderFoundation(projectPath, vars, report) {
  * @param packNames - Tool pack names to install (the spec workflow is always installed).
  * @param agents - Agent ids to configure with symlinks + MCP; empty writes content only.
  * @param opts - `refreshManaged: true` overwrites the managed trees (skills,
- *   commands, rules, agents) with the current version, backing up local edits to
- *   `<file>.bak`. Default (init) is additive — existing files are kept.
+ *   commands, rules, agents) with the current version; `backup: true` also keeps
+ *   a `<file>.bak` of any locally edited managed file before overwriting it (the
+ *   default overwrites in place — git preserves the prior content). Default
+ *   (init) is additive — existing files are kept.
  * @returns The install report augmented with the ordered next steps to run.
  * @throws If `projectPath` does not exist, or any pack name is unknown.
  */
@@ -91,6 +93,7 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     const record = {};
     const managedOpts = {
         overwrite: Boolean(opts.refreshManaged),
+        backup: Boolean(opts.backup),
         projectPath,
         baselines: readManifest(projectPath)?.baselines ?? {},
         record,
@@ -100,6 +103,7 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     for (const name of packNames)
         installPack(projectPath, name, vars, report, managedOpts); // managed
     ensureGitignore(projectPath, ".speclaw/", "speclaw local code Compass (never commit)", report);
+    ensureGitignore(projectPath, "*.bak", "speclaw managed-file refresh backups", report);
     for (const id of agents)
         configureAgent(projectPath, id, report); // only the chosen agents
     // Record what was installed so `speclaw update` can re-apply these packs and

package/dist/modules/lawbook/assets/skills/build/SKILL.md

@@ -46,12 +46,33 @@ delegate manual testing to the user. Record what you verified.
 ## Step 5 — Write the discipline reports (mandatory)
 
 Record the evidence of testing under `lawbook/changes/<name>/reports/`, one file
-per discipline the change touched (`backend.md`, `frontend.md`, …). Each report
-states what was tested and the real results — unit, integration, and end-to-end
-as applicable — with the commands run and their output and a one-line verdict.
-If a test kind does not yet apply (e.g. no unit runner), say so and record the
-gates and manual verification that stood in. Omit disciplines the change did not
-touch. The archive is blocked until at least one discipline report exists.
+per discipline the change touched (`backend.md`, `frontend.md`, …). Omit
+disciplines the change did not touch; the archive is blocked until at least one
+discipline report exists.
+
+Each report MUST follow this structure, in order — the fixed shape is what makes
+the evidence trustworthy and reproducible, rather than left to improvisation:
+
+1. **Title + header** — `# <Discipline> checks — <change> (<date>)`, then a line
+   `Date · Branch · Environment/cwd` naming where the commands ran.
+2. **Gates & results** — a `| Check | Command | Result |` table: each gate, the
+   exact command, and its real result with pass/fail counts (e.g. "62 files, 434
+   passed") and ✅/⚠️/❌. Quote real output — never paraphrase a green you did
+   not see.
+3. **Tests added / updated** — each new or changed test and what it asserts; note
+   TDD evidence ("failed before the fix, passes after") where it applies.
+4. **Spec-scenario coverage** — a table mapping each `#### Scenario` in this
+   change's delta specs to how it was verified (a test id, a gate, or a manual
+   step). Every scenario must appear.
+5. **Pre-existing / unrelated failures** — any failing check not caused by this
+   change, with proof it is pre-existing (e.g. it reproduces with the change
+   stashed) — or state "none".
+6. **Pending manual steps** — anything not automated, stated plainly — or "none".
+7. **Verdict** — one line.
+
+If a test kind does not yet apply (e.g. no unit runner), the report says so in
+place of that evidence and records the gates and manual verification that stood
+in.
 
 ## Step 6 — Hand off
 

package/dist/modules/lawbook/assets/skills/draft/SKILL.md

@@ -54,8 +54,10 @@ Create under `lawbook/changes/<name>/`:
   updated; archive within the PR).
 - **reports/** — create the folder with a short `reports/README.md` naming the
   discipline reports (`backend.md`, `frontend.md`, … as relevant) that `build`
-  will fill with real test results. Every change ships this folder; archive is
-  blocked until it holds at least one discipline report.
+  will fill, following the required report structure (header · gates table ·
+  tests added · spec-scenario coverage · pre-existing failures · pending manual ·
+  verdict — see the `build` skill, Step 5). Every change ships this folder;
+  archive is blocked until it holds at least one discipline report.
 
 ## Step 4 — Validate
 

package/dist/shared/install.js

@@ -4,7 +4,14 @@ import path from "node:path";
 import { render } from "./render.js";
 /** Create a fresh, empty {@link InstallReport} to accumulate results into. */
 export function emptyReport() {
-    return { written: [], skipped: [], backedUp: [], symlinks: [], unresolvedVars: [] };
+    return {
+        written: [],
+        skipped: [],
+        refreshedDiverged: [],
+        backedUp: [],
+        symlinks: [],
+        unresolvedVars: [],
+    };
 }
 /** SHA-256 of a file's intended content, used to track managed-file baselines. */
 export function sha256(content) {
@@ -60,9 +67,14 @@ export function copyRendered(srcDir, destDir, vars, report, opts) {
             }
             const baseline = opts.baselines?.[rel];
             if (!baseline || sha256(current) !== baseline) {
-                // Diverged from what we last wrote (or unknown) — preserve the user's copy.
-                fs.copyFileSync(dest, dest + ".bak");
-                report.backedUp.push(dest);
+                // Diverged from what we last wrote (or unknown). Record it so update can
+                // report it; keep a `.bak` only when asked — git already preserves the
+                // prior content, so the backup is opt-in, not the default.
+                if (opts.backup) {
+                    fs.copyFileSync(dest, dest + ".bak");
+                    report.backedUp.push(dest);
+                }
+                report.refreshedDiverged.push(dest);
             }
             fs.writeFileSync(dest, content);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "publishConfig": {
     "access": "public"
   },