@esneiderbravo/speclaw 0.1.10 → 0.1.12

package/README.md

@@ -106,10 +106,10 @@ non-trivial lands without a spec change. It's a loop of five steps:
 | Step | What happens |
 | :-- | :-- |
 | **explore** | Think an idea through *before* committing to it — should we do this, and how. Writes nothing. |
-| **draft** | Capture the intent as a change under `lawbook/changes/<name>/` — four artifacts, always (see below). |
-| **build** | Implement the tasks in order, keeping code and spec in agreement. |
-| **sync** | Promote the change's delta specs into the canonical `lawbook/specs/` — the always-true description of how the system behaves. |
-| **archive** | Validate, promote, and move the change to `lawbook/changes/archive/` — **in the same PR**, never a post-merge chore. |
+| **draft** | Capture the intent as a change under `lawbook/changes/<name>/` — four artifacts plus a `reports/` folder, always (see below). |
+| **build** | Implement the tasks in order, keeping code and spec in agreement, and record test results under `reports/`. |
+| **sync** | Reconcile the delta specs against what was actually built, then promote them into the canonical `lawbook/specs/` — the always-true description of how the system behaves. |
+| **archive** | Reconcile, then validate, promote, and move the change to `lawbook/changes/archive/` — **in the same PR**, never a post-merge chore. Gated: refused while any task is unchecked, `reports/` is empty, or the specs are unsynced. |
 
 **Every `draft` writes four artifacts under `lawbook/changes/<name>/` — none optional:**
 
@@ -120,6 +120,8 @@ non-trivial lands without a spec change. It's a loop of five steps:
 | `design.md` | The **how** — approach, alternatives weighed, and the trade-offs behind the decision. |
 | `tasks.md` | The **plan** — ordered, checkable steps, including the mandatory ones from `config.yaml`. |
 
+Plus a **`reports/`** folder — scaffolded at draft, filled at build with one report per discipline (`backend.md`, `frontend.md`, …) recording the real unit/integration/e2e results. Evidence of testing travels with the change, and `lawbook_archive` refuses to archive without it.
+
 > [!NOTE]
 > **Delta specs are normative and testable.** Requirements use `SHALL`/`MUST`
 > under `### Requirement:` headers, each with one or more `#### Scenario:` blocks
@@ -183,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/assets/AGENTS.template.md

@@ -16,9 +16,12 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    standards below. Open the standard that governs your change before making
    it. Conflicts resolve in favor of the standard; amendments go through a
    spec change, never silent deviation.
-2. **Use Compass before file scanning** — the `compass_explore` /
-   `compass_search` / `compass_recall` tools (run `compass_index` first if the
-   graph is missing). Cheat sheet: [`docs/compass.md`](docs/compass.md).
+2. **Compass first, always** — for any code question call `compass_explore` /
+   `compass_search` / `compass_recall` **before** any grep/sed/cat/Read,
+   including files you already know by name. Fall back to manual file tools only
+   after Compass returns nothing useful, the graph is missing (`compass_index`
+   first), or the target isn't indexed code (stylesheets, config, logs). Cheat
+   sheet: [`docs/compass.md`](docs/compass.md).
 3. **Follow the lawbook workflow** for every non-trivial change; archive
    within the same PR. Rules:
    [`docs/standards/lawbook.md`](docs/standards/lawbook.md).

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -27,13 +27,26 @@ When any instruction conflicts with a standard, **the standard wins** — and if
 you believe it is wrong, propose an amendment via a spec change; never silently
 ignore it.
 
-## Rule 1 — Compass before grep
-
-This repo is indexed by Compass, speclaw's local code graph (`.speclaw/`). Use
-the `compass_explore`, `compass_search`, and `compass_recall` tools **BEFORE**
-grep/find or reading files at random; run `compass_index` first if the graph
-is missing. See [`docs/compass.md`](docs/compass.md). Fall back to Grep/Read
-only when the graph doesn't cover what you need.
+## Rule 1 — Compass first, always
+
+This repo is indexed by Compass, speclaw's local code graph (`.speclaw/`). For
+**any** question about code — what a symbol is, what it uses, who calls it,
+where it lives, how a value flows — call Compass **first**: `compass_search` /
+`compass_recall` to locate, `compass_explore` to read a symbol with its callers
+and callees, `compass_impact` / `compass_trace` for blast radius and call paths.
+Run `compass_index` first if the graph is missing.
+
+This includes files you already know the name of: to learn what `Foo` imports,
+uses, or depends on, run `compass_explore Foo` — do **not** `cat`/`sed`/`grep`/
+Read the file to work it out by hand. "I know which file it is" is not an
+exemption.
+
+Fall back to Grep / Read / `sed` / `cat` **only after** you can name which of
+these holds: (1) a Compass call actually ran and returned nothing useful for the
+query, (2) the graph is missing and `compass_index` can't be run, or (3) the
+target is not indexed code — stylesheets, JSON/config, markdown, logs,
+generated files, lockfiles. Never skip Compass because grep "feels faster."
+See [`docs/compass.md`](docs/compass.md).
 
 ## Rule 2 — Spec-driven, always
 

package/dist/modules/foundation/assets/LAWS.template.md

@@ -22,7 +22,7 @@
 | Documentation | [`docs/standards/documentation.md`](docs/standards/documentation.md) | Docstring/API-comment convention per language |
 | Conventions | [`docs/standards/conventions.md`](docs/standards/conventions.md) | Branches, PRs, tracker, versioning |
 | Lawbook | [`docs/standards/lawbook.md`](docs/standards/lawbook.md) | Spec-driven workflow, mandatory task steps, archiving |
-| Compass | [`docs/compass.md`](docs/compass.md) | Using the code knowledge graph before grep |
+| Compass | [`docs/compass.md`](docs/compass.md) | Using the code knowledge graph first — before any grep/read |
 
 ## Binding rules
 

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -2,8 +2,12 @@
 
 **Compass** is speclaw's local code graph: a pre-indexed map of every symbol
 (node) and relationship (edge) in this workspace, plus a local vector store for
-semantic recall. Agents MUST use it **before** manual grep/read loops when
-exploring or editing code — this is Rule 1 of the agent contract (`AGENTS.md`).
+semantic recall. Agents **MUST** call Compass first for any code question —
+before any `grep`/`sed`/`cat`/Read, and before opening a file whose name they
+already know. Manual file tools are a fallback used **only after** a Compass
+call returns nothing useful, the graph is missing, or the target isn't indexed
+code (stylesheets, config, logs). This is Rule 1 of the agent contract
+(`AGENTS.md`).
 
 It runs entirely on your machine, needs no LLM and no external service, and
 stores everything in `.speclaw/` (gitignored). It ships inside speclaw — there
@@ -33,8 +37,10 @@ a request, not whole files.
 | `compass_trace` | Trace a call path between two nodes — how an entrypoint reaches a sink. |
 | `compass_watch` | Keep the index fresh automatically (start/stop a debounced incremental re-index on file change). |
 
-If the graph is missing (no `.speclaw/index.db`), run `compass_index` first;
-until then, fall back to Grep/Read.
+If the graph is missing (no `.speclaw/index.db`), run `compass_index` first —
+a missing graph is not license to skip Compass. The only legitimate fallbacks
+to Grep/Read: a Compass call returned nothing useful for your query, or the
+target isn't indexed code (stylesheets, JSON/config, markdown, logs).
 
 ## Project-specific starting points
 

package/dist/modules/foundation/assets/docs/standards/lawbook.template.md

@@ -10,20 +10,32 @@ No non-trivial change lands without a spec change:
 
 1. **explore** — think an idea through before committing (writes nothing).
 2. **draft** — create `lawbook/changes/<name>/`: `proposal.md`, delta specs under
-   `specs/<capability>/spec.md`, `design.md`, and `tasks.md`.
+   `specs/<capability>/spec.md`, `design.md`, `tasks.md`, and a `reports/`
+   folder.
 3. **build** — implement the tasks in order, keeping code and spec in
-   agreement.
-4. **sync** — promote the change's delta specs into the canonical
-   `lawbook/specs/` (`lawbook_sync`).
-5. **archive** — finalize: sync + move the change to `lawbook/changes/archive/`
-   (`lawbook_archive`), **within the same PR** — never a post-merge chore.
+   agreement, and write the discipline reports under `reports/`.
+4. **sync** — reconcile the delta specs against what was actually built, then
+   promote them into the canonical `lawbook/specs/` (`lawbook_sync`). The tool
+   is a deterministic copy; the agent does the code↔spec reconciliation first.
+5. **archive** — finalize: reconcile, sync, then move the change to
+   `lawbook/changes/archive/` (`lawbook_archive`), **within the same PR** —
+   never a post-merge chore. The archive is gated (see below).
 
 ## Mandatory task steps
 
 `tasks.md` MUST include the steps defined in `lawbook/config.yaml` and the
 `spec-tasks-mandatory-steps` rule: feature branch first, tests reviewed and
-run, manual verification executed by the agent, docs updated, archive within
-the PR. The agent performs the manual testing itself — never delegates it.
+run, manual verification executed by the agent, discipline reports produced,
+docs updated, archive within the PR. The agent performs the manual testing
+itself — never delegates it.
+
+## Reports
+
+Every change carries a `reports/` folder. `build` writes one report per
+discipline it touched (`backend.md`, `frontend.md`, …) recording what was tested
+and the real results — unit, integration, and end-to-end as applicable — with
+the commands run and their output. It is evidence of testing that travels with
+the change; the archive is blocked until at least one discipline report exists.
 
 ## Delta specs
 
@@ -39,6 +51,17 @@ the PR. The agent performs the manual testing itself — never delegates it.
 Always archive with the `archive` command / `lawbook_archive` tool, never a manual
 `mv` — the tool performs the spec promotion and validation a manual move skips.
 
+Before archiving, the agent runs a reconciliation review: it compares what was
+built against the delta specs and, when the code has drifted past the original
+contracts, shows short insights and reconciles the delta specs.
+
+`lawbook_archive` is then **gated in the engine** — it refuses to archive (and
+reports the reason) while any task is unchecked, while `reports/` holds no
+discipline report, or while the delta specs are not yet synced into the
+canonical specs. Because the gate covers both the tool and the CLI, a change
+reaches the archive only when it is genuinely complete: reconcile, `sync`, then
+archive.
+
 ## Amendments to the law
 
 The standards in `docs/standards/` are amended like code: through a spec change

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/assets/commands/archive.md

@@ -4,7 +4,8 @@ description: Finalize a completed change — sync specs into canonical, then arc
 
 Archive the completed change: $ARGUMENTS
 
-Follow the `archive` skill: confirm every task is done and gates are green,
-run `lawbook_validate`, then `lawbook_archive` with today's date (YYYY-MM-DD). It
-syncs the specs and moves the change to `lawbook/changes/archive/`. Never move
-the folder by hand.
+Follow the `archive` skill: confirm every task is done and gates are green, run
+the reconciliation review (recommend a sync with short insights if the code
+drifted past the contracts), run `lawbook_validate`, then `lawbook_archive` with
+today's date (YYYY-MM-DD). It syncs the specs and moves the change to
+`lawbook/changes/archive/`. Never move the folder by hand.

package/dist/modules/lawbook/assets/commands/sync.md

@@ -4,6 +4,7 @@ description: Promote a change's delta specs into the canonical specs, without ar
 
 Sync the change's specs into canonical: $ARGUMENTS
 
-Follow the `sync` skill: validate the change (`lawbook_validate`), then run
-`lawbook_sync` to promote each delta spec into `lawbook/specs/`. Report what was
-promoted; leave the change active.
+Follow the `sync` skill: reconcile the delta specs against what was actually
+built (branch diff + code graph), validate the change (`lawbook_validate`), then
+run `lawbook_sync` to promote each delta spec into `lawbook/specs/`. Report what
+you reconciled and what was promoted; leave the change active.

package/dist/modules/lawbook/assets/rules/spec-tasks-mandatory-steps.md

@@ -21,6 +21,9 @@ steps, branch convention, and testing/documentation requirements.
   (see `docs/standards/testing-standards.md`).
 - Perform manual verification of the behavior — **the agent executes this
   itself, never the user.**
+- Produce the discipline reports under `reports/` (`backend.md`, `frontend.md`,
+  … as relevant) with the unit/integration/e2e results for what the feature
+  touched.
 - Update the technical documentation the change touches.
 - Archive the change within the same PR (the `archive` command / `lawbook_archive`
   tool).
@@ -35,3 +38,8 @@ not complete until the agent has verified it.
 
 A change is not done until it is archived with `lawbook_archive` (never a manual
 `mv`). The archive lands in the same PR that implements the change.
+
+`lawbook_archive` is gated: it refuses to archive while any task is unchecked,
+while `reports/` has no discipline report, or while the delta specs are not yet
+synced into the canonical specs. Resolve those first — the gate is enforced in
+the engine, so a manual `mv` only hides an incomplete change.

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

@@ -9,14 +9,39 @@ Close out a completed change: its delta specs become canonical and the change
 folder moves to `lawbook/changes/archive/`. This is part of the PR that
 implements the change, not a post-merge chore.
 
+`lawbook_archive` is **gated** — the engine refuses to archive (and reports the
+reason) while any task is unchecked, while `reports/` holds no discipline report,
+or while the delta specs are not yet synced into the canonical specs. So archive
+is the last step of a completed change: reconcile, sync, then archive.
+
 ## Steps
 
 1. Confirm the change is truly done: every task in `tasks.md` checked, quality
-   gates green, behavior verified.
-2. Run `lawbook_validate` for the change; resolve any issues first.
-3. Run the `lawbook_archive` tool with the change name and today's date
-   (`YYYY-MM-DD`). It syncs the delta specs into `lawbook/specs/` and then moves
-   `lawbook/changes/<name>/` to `lawbook/changes/archive/<date>-<name>/`.
-4. Report the archive path and the promoted specs. Never move the folder by
-   hand — always use `lawbook_archive`, which performs the sync and validation a
-   manual move would skip.
+   gates green, behavior verified, and the discipline reports written under
+   `reports/`.
+
+2. **Reconciliation review (agent-executed).** Run the reconciliation from the
+   `sync` skill: reconstruct what was built (branch diff since draft +
+   `compass_explore` / `compass_impact`) and compare it to the change's delta
+   specs.
+   - **If the code drifted past the contracts:** show short insights — a tight
+     bullet list of what was built outside the delta specs and why it matters
+     (e.g. "DB path renamed to `data/app.db` + auto-migration — infra behavior
+     absent from the spec") — and reconcile the delta specs (write the drift
+     in). Drift left unreconciled cannot be archived: the specs-synced gate will
+     block it.
+   - **If nothing drifted:** say so and continue.
+
+3. Run `lawbook_validate`, then `lawbook_sync` to promote the delta specs into
+   `lawbook/specs/`. This is required, not optional: `lawbook_archive` refuses
+   unless the canonical specs already match the delta specs.
+
+4. Run the `lawbook_archive` tool with the change name and today's date
+   (`YYYY-MM-DD`). It re-checks the gate deterministically and, if it passes,
+   moves `lawbook/changes/<name>/` to `lawbook/changes/archive/<date>-<name>/`.
+   If it refuses, resolve the reported blockers (unchecked tasks, missing
+   reports, unsynced specs) and retry.
+
+5. Report the archive path, what you reconciled (or that nothing drifted), and
+   the promoted specs. Never move the folder by hand — a manual `mv` skips the
+   gate and hides an incomplete change.

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

@@ -43,7 +43,20 @@ Run them yourself and report real output. A red gate blocks completion.
 Exercise the behavior (endpoint/UI/CLI) yourself where feasible — do not
 delegate manual testing to the user. Record what you verified.
 
-## Step 5 — Hand off
+## 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.
+
+## Step 6 — Hand off
 
 When every task is checked and gates are green, tell the user the change is
-ready to `sync` and `archive`.
+ready to `sync` and `archive`. Keep the delta specs current as you build, but
+know that `sync` formally reconciles the delta specs against what was actually
+built — so behavior that drifted past the original spec is caught there, not
+left to chance.

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

@@ -50,8 +50,12 @@ Create under `lawbook/changes/<name>/`:
   behind the decision. For a small change, keep it short — but write it.
 - **tasks.md** — ordered, checkable steps. MUST include the mandatory steps
   from `lawbook/config.yaml` (feature branch first; tests reviewed and run;
-  manual verification executed by the agent; docs updated; archive within the
-  PR).
+  manual verification executed by the agent; discipline reports produced; docs
+  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.
 
 ## Step 4 — Validate
 

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

@@ -9,13 +9,33 @@ Update the project's canonical specifications (`lawbook/specs/`) with a change's
 delta specs, without archiving the change. Use this when the specs should
 become the source of truth but the change isn't finished (e.g. multi-PR work).
 
+`lawbook_sync` is a deterministic copy — it is blind to the code. So before
+promoting, YOU reconcile the delta specs against what was actually built, so the
+specs that become canonical describe reality, not just the original draft.
+
 ## Steps
 
 1. Confirm which change to sync (run `lawbook_list` if unsure).
-2. Run `lawbook_validate` for the change; do not sync a change whose specs are
+
+2. **Reconcile code → delta specs (agent-executed).** Before promoting, compare
+   what was built against the change's delta specs:
+   - Reconstruct what shipped: `git diff <branch-point>...HEAD` for the change's
+     branch, then `compass_explore` / `compass_impact` on the touched symbols to
+     understand behavior, not just changed lines.
+   - Diff intent vs reality: list behavior that is implemented but missing from,
+     or contradicted by, `lawbook/changes/<name>/specs/**`.
+   - Write the gaps into the delta specs — normative `SHALL`/`MUST` requirements
+     under `### Requirement:` and `#### Scenario:` acceptance criteria — so the
+     contract matches what was built. Capture only behavior that actually
+     exists; never invent scope that was not implemented.
+   - If nothing drifted, make no edits and say so.
+
+3. Run `lawbook_validate` for the change; do not sync a change whose specs are
    invalid.
-3. Run the `lawbook_sync` tool for the change. It copies each
+
+4. Run the `lawbook_sync` tool for the change. It copies each
    `lawbook/changes/<name>/specs/<capability>/spec.md` over the canonical
    `lawbook/specs/<capability>/spec.md` and reports what it promoted.
-4. Report the promoted files to the user. The change stays active — `archive`
-   it when it's fully done.
+
+5. Report to the user what you reconciled (or that nothing drifted) and the
+   promoted files. The change stays active — `archive` it when it's fully done.

package/dist/modules/lawbook/engine.js

@@ -26,6 +26,7 @@ mandatory_task_steps:
   - "Review and update the affected tests."
   - "Run the quality gates and verify they pass (see docs/standards/testing-standards.md)."
   - "Perform manual verification of the behavior — the agent executes this itself, never the user."
+  - "Produce the discipline reports under reports/ (unit/integration/e2e results for what the feature touched)."
   - "Update the technical documentation touched by the change."
   - "Archive the change within the same PR (lawbook:archive)."
 
@@ -185,6 +186,56 @@ export function specSync(projectPath, change) {
     walk(changeSpecs);
     return { change, promoted };
 }
+/**
+ * Deterministic completeness checks that gate archiving a change. Returns the
+ * blocking reasons; an empty array means the change may be archived.
+ *
+ * A change is blocked when any task is still unchecked, when it has no discipline
+ * report under reports/, or when its delta specs are not synced — the canonical
+ * spec is missing for, or differs from, a delta (meaning sync was not run after
+ * the last spec edit). The reports/README.md scaffold does not count as a report.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name (folder under lawbook/changes/).
+ * @returns Human-readable blockers; empty when the change is ready to archive.
+ */
+export function specArchivePreconditions(projectPath, change) {
+    const root = specRoot(projectPath);
+    const changeDir = path.join(root, "changes", change);
+    if (!fs.existsSync(changeDir))
+        return [`change "${change}" not found under lawbook/changes/`];
+    const blockers = [];
+    // 1. Every task must be checked.
+    const tasksPath = path.join(changeDir, "tasks.md");
+    if (!fs.existsSync(tasksPath)) {
+        blockers.push("missing tasks.md");
+    }
+    else {
+        const unchecked = (fs.readFileSync(tasksPath, "utf8").match(/^\s*[-*]\s+\[ \]/gm) ?? []).length;
+        if (unchecked > 0)
+            blockers.push(`${unchecked} unchecked task(s) in tasks.md`);
+    }
+    // 2. At least one discipline report must exist (README.md scaffold aside).
+    const reportsDir = path.join(changeDir, "reports");
+    const reports = fs.existsSync(reportsDir)
+        ? fs.readdirSync(reportsDir).filter((n) => n.endsWith(".md") && n.toLowerCase() !== "readme.md")
+        : [];
+    if (reports.length === 0) {
+        blockers.push("no discipline report under reports/ (build must record what was tested)");
+    }
+    // 3. Delta specs must already be synced into the canonical specs.
+    for (const file of deltaSpecFiles(changeDir)) {
+        const rel = path.relative(path.join(changeDir, "specs"), file);
+        const canonical = path.join(root, "specs", rel);
+        if (!fs.existsSync(canonical)) {
+            blockers.push(`spec not synced: lawbook/specs/${rel} missing (run sync first)`);
+        }
+        else if (fs.readFileSync(file, "utf8") !== fs.readFileSync(canonical, "utf8")) {
+            blockers.push(`spec not synced: lawbook/specs/${rel} differs from the delta (run sync first)`);
+        }
+    }
+    return blockers;
+}
 /**
  * Finalize a change: promote its delta specs (via {@link specSync}), then move
  * it to changes/archive/<date>-<name>/.
@@ -193,13 +244,18 @@ export function specSync(projectPath, change) {
  * @param change - Change name (folder under lawbook/changes/).
  * @param date - Archive date prefix, formatted YYYY-MM-DD.
  * @returns The promoted specs and the archive destination path.
- * @throws If the change does not exist, or the archive target already exists.
+ * @throws If the change does not exist, the archive target already exists, or
+ *   any archive precondition (see {@link specArchivePreconditions}) is unmet.
  */
 export function specArchive(projectPath, change, date) {
     const root = specRoot(projectPath);
     const changeDir = path.join(root, "changes", change);
     if (!fs.existsSync(changeDir))
         throw new Error(`change "${change}" not found`);
+    const blockers = specArchivePreconditions(projectPath, change);
+    if (blockers.length > 0) {
+        throw new Error(`cannot archive "${change}" — resolve first:\n${blockers.map((b) => `  - ${b}`).join("\n")}`);
+    }
     const { promoted } = specSync(projectPath, change);
     const archiveDir = path.join(root, "changes", "archive", `${date}-${change}`);
     fs.mkdirSync(path.dirname(archiveDir), { recursive: true });

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.10",
+  "version": "0.1.12",
   "publishConfig": {
     "access": "public"
   },