@esneiderbravo/speclaw 0.1.11 → 0.1.13

package/README.md

@@ -185,9 +185,18 @@ speclaw update
 ```
 
 `update` upgrades the global package **and** brings the current project up to date
-without a re-init: any new standards, skills, commands, or feature steps are added
-**additively** — your existing files are never touched. It re-applies only the tool
-packs this project already uses.
+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, `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
+  speclaw-authored content, `update` prints a prompt for **the agent you're
+  using** to apply the change while preserving your project's specifics.
 
 - `speclaw update --check` — report whether an update exists, change nothing.
 - `NO_UPDATE_NOTIFIER=1` — silence the reminder.

package/dist/cli/commands/init.js

@@ -113,12 +113,12 @@ export async function runInit(flags) {
             c.bold(c.cream(String(stats.embeddings))) +
             c.muted(" embeddings"));
     }
-    // 3. Handoff prompt for the chosen agent — printed as a single flush-left
-    // line so it copy-pastes cleanly (no borders, no wrapping artifacts).
-    const primary = agentById(agents[0]);
+    // 3. Handoff prompt — printed as a single flush-left line so it copy-pastes
+    // cleanly (no borders, no wrapping artifacts). Agent-generic on purpose:
+    // speclaw supports any agent, so it addresses "the agent you're using".
     ui.step("You're set — one last step");
     ui.plain();
-    ui.info(`Copy this and paste it into ${c.cyan(primary.label)}:`);
+    ui.info(`Copy this and paste it into ${c.cyan("the agent you're using")}:`);
     ui.plain();
     console.log(c.cream("Complete speclaw's foundation: analyze this repo and fill LAWS.md and " +
         "docs/standards/* with its real architecture, quality gates and conventions. " +

package/dist/cli/commands/update.js

@@ -5,12 +5,44 @@ import { ui, c } from "../lib/ui.js";
 import { checkForUpdates, isNewer } from "../lib/update-check.js";
 import { pkgName, pkgVersion } from "../../shared/version.js";
 import { scaffold } from "../../modules/foundation/scaffold.js";
+import { PERSONALIZED } from "../../modules/foundation/ownership.js";
 import { detectConfiguredAgents } from "../../shared/agents.js";
 import { readManifest } from "../../shared/manifest.js";
 import { loadPacks } from "../../modules/tools/packs.js";
 import { detectProjectName } from "./init.js";
+// The first migration must be tagged at the version that introduces this
+// mechanism (0.1.12): `isNewer` is strict, so an entry tagged at an already-
+// shipped version (e.g. 0.1.11) would never fire for projects already on it.
 const MIGRATIONS = [
-// e.g. { version: "0.3.0", describe: "…", run: (p, r) => { … } }
+    {
+        version: "0.1.12",
+        describe: "Compass-first rule + reports mandatory step in personalized files",
+        agentPrompt: "- In CLAUDE.md and AGENTS.md, change the Compass rule to 'Compass first, always': " +
+            "call Compass (compass_explore/search/recall) before grep/sed/cat/Read for any code " +
+            "question — including files you already know by name — and fall back to manual file " +
+            "tools only after a Compass call returns nothing useful, the graph is missing, or the " +
+            "target isn't indexed code (CSS/JSON/logs). Update the matching Compass row in LAWS.md " +
+            "and the intro of docs/compass.md the same way.\n" +
+            "- In lawbook/config.yaml, add this mandatory task step before the docs/archive steps: " +
+            '"Produce the discipline reports under reports/ (unit/integration/e2e results for what ' +
+            '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:
@@ -25,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");
@@ -49,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,
             });
@@ -66,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");
@@ -84,23 +124,62 @@ function applyProjectMigrations(cwd) {
     const agents = detectConfiguredAgents(cwd);
     const known = loadPacks();
     const packs = (readManifest(cwd)?.packs ?? []).filter((p) => p in known);
-    // scaffold is non-destructive: only missing files are written, and it refreshes
-    // the manifest to the current version. Existing files are left exactly as-is.
-    const report = scaffold(cwd, { project_name: detectProjectName(cwd) }, packs, agents);
-    const newFiles = report.written.filter((w) => !w.includes(".gitignore"));
-    if (newFiles.length) {
-        for (const w of newFiles)
-            ui.ok(c.cream(path.relative(cwd, w.split(" (")[0])));
-        ui.info(`${newFiles.length} new file(s) added · ${report.skipped.length} left untouched.`);
+    // Managed files (skills/commands/rules/agents) are refreshed to the current
+    // version; personalized files (constitution/standards/config) are never
+    // 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) {
+        for (const w of changed)
+            ui.ok(c.cream(path.relative(cwd, w)));
+        ui.info(`${changed.length} file(s) added/refreshed · ${report.skipped.length} left untouched.`);
     }
     else {
-        ui.ok("Content already up to date — nothing new to add.");
+        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 pending = MIGRATIONS.filter((m) => isNewer(m.version, fromVersion));
+    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
+    // delete a shipped migration, or a laggard crossing it later would miss it.
+    const pending = MIGRATIONS.filter((m) => isNewer(m.version, fromVersion)).sort((a, b) => isNewer(a.version, b.version) ? 1 : isNewer(b.version, a.version) ? -1 : 0);
     for (const m of pending) {
+        if (!m.run)
+            continue;
         ui.step(`Step for ${m.version}: ${m.describe}`);
         m.run(cwd, report);
     }
+    // Personalized files can't be auto-edited (they hold project specifics), so
+    // hand their changes to whatever agent the user runs — never a hardcoded one.
+    const prompt = pending
+        .map((m) => m.agentPrompt)
+        .filter(Boolean)
+        .join("\n");
+    if (prompt) {
+        ui.plain();
+        ui.step("One step for the agent you're using");
+        ui.info(`Personalized files (${PERSONALIZED.join(", ")}) hold your project specifics, so ` +
+            `speclaw won't edit them. Paste this into the agent you're using to apply this ` +
+            `release's changes while keeping your content:`);
+        ui.plain();
+        console.log(c.cream(prompt));
+        ui.plain();
+    }
     ui.plain();
     ui.ok(`On ${c.cyan(pkgVersion())}. No re-init needed.`);
 }

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/ownership.js

@@ -0,0 +1,32 @@
+// Which scaffolded files speclaw owns vs the user owns. `speclaw update` uses
+// this split to decide what it may overwrite automatically (managed) and what it
+// must leave to the user's agent via a prompt (personalized).
+/**
+ * Project-relative trees that hold speclaw's workflow machinery. The user is not
+ * meant to edit these, so `speclaw update` overwrites them with the current
+ * version (backing up any local edits to `<file>.bak` first).
+ */
+export const MANAGED_TREES = [
+    "ai-specs/skills",
+    "ai-specs/commands",
+    "ai-specs/rules",
+    "ai-specs/agents",
+];
+/**
+ * Files filled with project specifics at init. `speclaw update` never rewrites
+ * these; when a release changes their speclaw-authored content, update emits an
+ * agent prompt to apply the change while preserving the user's content.
+ */
+export const PERSONALIZED = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "LAWS.md",
+    "docs/standards",
+    "docs/compass.md",
+    "lawbook/config.yaml",
+];
+/** True if a project-relative path sits under a managed tree. */
+export function isManaged(relPath) {
+    const norm = relPath.split("\\").join("/");
+    return MANAGED_TREES.some((t) => norm === t || norm.startsWith(t + "/"));
+}

package/dist/modules/foundation/scaffold.js

@@ -6,7 +6,7 @@ import { emptyReport, ensureGitignore } from "../../shared/install.js";
 import { configureAgent } from "../../shared/agents.js";
 import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
-import { writeManifest } from "../../shared/manifest.js";
+import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
@@ -70,10 +70,15 @@ function renderFoundation(projectPath, vars, report) {
  * @param profile - Project identity and conventions for template rendering.
  * @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; `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.
  */
-export function scaffold(projectPath, profile, packNames, agents = []) {
+export function scaffold(projectPath, profile, packNames, agents = [], opts = {}) {
     if (!fs.existsSync(projectPath)) {
         throw new Error(`projectPath does not exist: ${projectPath}`);
     }
@@ -83,16 +88,28 @@ export function scaffold(projectPath, profile, packNames, agents = []) {
         throw new Error(`Unknown packs: ${unknown.join(", ")}`);
     const report = { ...emptyReport(), nextSteps: [] };
     const vars = { ...FOUNDATION_DEFAULTS, ...profile };
-    renderFoundation(projectPath, vars, report);
-    installWorkflow(projectPath, vars, report); // spec module — always
+    // Managed trees (MANAGED_TREES) carry speclaw's workflow logic and may be
+    // overwritten on update; the foundation (personalized) is always additive.
+    const record = {};
+    const managedOpts = {
+        overwrite: Boolean(opts.refreshManaged),
+        backup: Boolean(opts.backup),
+        projectPath,
+        baselines: readManifest(projectPath)?.baselines ?? {},
+        record,
+    };
+    renderFoundation(projectPath, vars, report); // personalized — never overwritten
+    installWorkflow(projectPath, vars, report, managedOpts); // managed
     for (const name of packNames)
-        installPack(projectPath, name, vars, report); // tools module
+        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 only these packs
-    // (additively) and gate feature migrations by version — no full re-init.
-    writeManifest(projectPath, pkgVersion(), packNames);
+    // Record what was installed so `speclaw update` can re-apply these packs and
+    // gate feature migrations by version, plus the managed-file baselines that let
+    // a later update tell user edits from stale files.
+    writeManifest(projectPath, pkgVersion(), packNames, record);
     report.nextSteps = [
         "Run the `lawbook_init` tool to set up the spec-driven workflow (creates lawbook/). No external CLI needed — it's built into speclaw.",
         "Run the `compass_index` tool to build the local code graph (.speclaw/). No install, no LLM — it's built into speclaw. Re-run it after significant edits.",

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/modules/lawbook/register.js

@@ -10,11 +10,11 @@ const ASSETS = assetsDir(import.meta.url);
  * the draft/build/sync/archive/explore skills, the /spec commands, and the
  * mandatory-task-steps rule. Always installed — it's the core workflow.
  */
-export function installWorkflow(projectPath, vars, report) {
+export function installWorkflow(projectPath, vars, report, opts) {
     const aiSpecs = path.join(projectPath, "ai-specs");
-    copyRendered(path.join(ASSETS, "skills"), path.join(aiSpecs, "skills"), vars, report);
-    copyRendered(path.join(ASSETS, "commands"), path.join(aiSpecs, "commands", "lawbook"), vars, report);
-    copyRendered(path.join(ASSETS, "rules"), path.join(aiSpecs, "rules"), vars, report);
+    copyRendered(path.join(ASSETS, "skills"), path.join(aiSpecs, "skills"), vars, report, opts);
+    copyRendered(path.join(ASSETS, "commands"), path.join(aiSpecs, "commands", "lawbook"), vars, report, opts);
+    copyRendered(path.join(ASSETS, "rules"), path.join(aiSpecs, "rules"), vars, report, opts);
 }
 // ─── The spec module: speclaw's own spec-driven workflow (no external OpenSpec) ───
 // Mechanical operations behind the draft/build/sync/archive/explore commands.

package/dist/modules/tools/packs.js

@@ -21,9 +21,11 @@ export function loadPacks() {
  * @param name - Pack name to install (key in the manifest).
  * @param vars - Template variables applied while copying the pack's assets.
  * @param report - Mutated in place with the copy results.
+ * @param opts - Overwrite/baseline behavior forwarded to {@link copyRendered}
+ *   (packs write into managed trees, so update refreshes them).
  * @throws If no pack with the given name exists in the manifest.
  */
-export function installPack(projectPath, name, vars, report) {
+export function installPack(projectPath, name, vars, report, opts) {
     const packs = loadPacks();
     const def = packs[name];
     if (!def) {
@@ -33,11 +35,11 @@ export function installPack(projectPath, name, vars, report) {
     const aiSpecs = path.join(projectPath, "ai-specs");
     for (const sub of fs.readdirSync(packRoot, { withFileTypes: true })) {
         if (sub.isDirectory()) {
-            copyRendered(path.join(packRoot, sub.name), path.join(aiSpecs, sub.name), vars, report);
+            copyRendered(path.join(packRoot, sub.name), path.join(aiSpecs, sub.name), vars, report, opts);
         }
         else if (sub.name.endsWith(".md")) {
             // loose .md at pack root = agent definitions
-            copyRendered(packRoot, path.join(aiSpecs, "agents"), vars, report);
+            copyRendered(packRoot, path.join(aiSpecs, "agents"), vars, report, opts);
             break;
         }
     }

package/dist/shared/install.js

@@ -1,9 +1,21 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 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: [], 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) {
+    return crypto.createHash("sha256").update(content).digest("hex");
 }
 /**
  * Recursively copy a source tree into a destination, rendering {{var}}
@@ -13,33 +25,65 @@ export function emptyReport() {
  * @param srcDir - Source directory tree to copy from.
  * @param destDir - Destination directory (created if missing).
  * @param vars - Placeholder values used to render `.md`/`.mdc` files.
- * @param report - Report mutated in place with written, skipped, and unresolved-var entries.
+ * @param report - Report mutated in place with written, skipped, backed-up, and
+ *   unresolved-var entries.
+ * @param opts - Overwrite/baseline behavior; omitted means additive (skip existing).
  */
-export function copyRendered(srcDir, destDir, vars, report) {
+export function copyRendered(srcDir, destDir, vars, report, opts) {
     fs.mkdirSync(destDir, { recursive: true });
     for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
         const src = path.join(srcDir, entry.name);
         const dest = path.join(destDir, entry.name);
         if (entry.isDirectory()) {
-            copyRendered(src, dest, vars, report);
-            continue;
-        }
-        if (fs.existsSync(dest)) {
-            report.skipped.push(dest);
+            copyRendered(src, dest, vars, report, opts);
             continue;
         }
+        // Compute the content speclaw wants at dest (rendered for md/mdc, raw otherwise).
+        let content;
         if (entry.name.endsWith(".md") || entry.name.endsWith(".mdc")) {
             const { output, unresolved } = render(fs.readFileSync(src, "utf8"), vars);
             unresolved.forEach((v) => {
                 if (!report.unresolvedVars.includes(v))
                     report.unresolvedVars.push(v);
             });
-            fs.writeFileSync(dest, output);
+            content = output;
+        }
+        else {
+            content = fs.readFileSync(src);
+        }
+        const rel = opts?.projectPath ? path.relative(opts.projectPath, dest) : dest;
+        const newSha = sha256(content);
+        if (fs.existsSync(dest)) {
+            if (!opts?.overwrite) {
+                report.skipped.push(dest);
+                continue;
+            }
+            const current = fs.readFileSync(dest);
+            if (sha256(current) === newSha) {
+                // Already the current version — nothing to write, but keep the baseline.
+                if (opts.record)
+                    opts.record[rel] = newSha;
+                continue;
+            }
+            const baseline = opts.baselines?.[rel];
+            if (!baseline || sha256(current) !== baseline) {
+                // 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);
         }
         else {
-            fs.copyFileSync(src, dest);
+            fs.writeFileSync(dest, content);
         }
         report.written.push(dest);
+        if (opts?.record)
+            opts.record[rel] = newSha;
     }
 }
 /**

package/dist/shared/manifest.js

@@ -15,6 +15,9 @@ export function readManifest(projectPath) {
         return {
             version: String(m.version ?? "0.0.0"),
             packs: Array.isArray(m.packs) ? m.packs.map(String) : [],
+            baselines: m.baselines && typeof m.baselines === "object"
+                ? m.baselines
+                : {},
         };
     }
     catch {
@@ -28,11 +31,13 @@ export function readManifest(projectPath) {
  * @param projectPath - Project root to write into.
  * @param version - The speclaw version doing the write.
  * @param packs - Pack names installed in this run.
+ * @param baselines - Managed-file hashes to merge over the recorded ones.
  */
-export function writeManifest(projectPath, version, packs) {
+export function writeManifest(projectPath, version, packs, baselines = {}) {
     const prev = readManifest(projectPath);
     const merged = Array.from(new Set([...(prev?.packs ?? []), ...packs]));
+    const mergedBaselines = { ...(prev?.baselines ?? {}), ...baselines };
     const p = manifestPath(projectPath);
     fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify({ version, packs: merged }, null, 2) + "\n");
+    fs.writeFileSync(p, JSON.stringify({ version, packs: merged, baselines: mergedBaselines }, null, 2) + "\n");
 }

package/package.json

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