@esneiderbravo/speclaw 0.1.11 → 0.1.12

package/README.md

@@ -185,9 +185,17 @@ 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, your copy
+  is saved as `<file>.bak` before the refresh — nothing is lost.
+- **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,29 @@ 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.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:
@@ -84,23 +101,52 @@ 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,
+    });
+    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.");
     }
-    const pending = MIGRATIONS.filter((m) => isNewer(m.version, fromVersion));
+    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.`);
+    }
+    // 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/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,13 @@ 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, backing up local edits to
+ *   `<file>.bak`. 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 +86,26 @@ 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),
+        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);
     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/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,14 @@
+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: [], 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 +18,60 @@ 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) — preserve the user's copy.
+                fs.copyFileSync(dest, dest + ".bak");
+                report.backedUp.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.12",
   "publishConfig": {
     "access": "public"
   },