@esneiderbravo/speclaw 0.1.9 → 0.1.11

package/README.md

@@ -93,26 +93,40 @@ Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) an
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The spec-driven workflow (Lawbook)
 
 Lawbook is speclaw's answer to the biggest risk with AI agents: **code that
-drifts from intent.** No non-trivial change lands without a spec change — the
-intent is written first, the code is made to match it, and the spec is promoted
-to the project's canonical record. It's a loop of five steps:
+drifts from intent.** The intent is written first, the code is made to match it,
+and the spec is promoted to the project's canonical record — so nothing
+non-trivial lands without a spec change. It's a loop of five steps:
 
 ```
-explore  →  draft  →  build  →  sync  →  archive
+   ┌─────────┐    ┌───────┐    ┌───────┐    ┌──────┐    ┌─────────┐
+   │ explore │ ─▶ │ draft │ ─▶ │ build │ ─▶ │ sync │ ─▶ │ archive │
+   └─────────┘    └───────┘    └───────┘    └──────┘    └─────────┘
 ```
 
 | Step | What happens |
 | :-- | :-- |
 | **explore** | Think an idea through *before* committing to it — should we do this, and how. Writes nothing. |
-| **draft** | Create the change under `lawbook/changes/<name>/`: a `proposal.md` (why · what · non-goals), **delta specs** in `specs/<capability>/spec.md`, an optional `design.md`, and a `tasks.md` checklist. |
-| **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. |
-
-**Delta specs are normative and testable.** Requirements use `SHALL`/`MUST`
-under `### Requirement:` headers, each with one or more `#### Scenario:` blocks
-whose acceptance criteria hold without production integrations. `lawbook_validate`
-checks that the code matches what the spec promises before you sync or archive.
+| **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:**
+
+| Artifact | What it captures |
+| :-- | :-- |
+| `proposal.md` | The **why** — motivation, what changes, non-goals, and whether migrations are needed. |
+| `specs/<capability>/spec.md` | The **delta specs** — one per affected capability, normative and testable. |
+| `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
+> whose acceptance criteria hold without production integrations. `lawbook_validate`
+> checks that the code matches what the spec promises before you sync or archive.
 
 **Three ways to drive it — same engine, no external CLI:**
 

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`, optional `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/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/draft.md

@@ -7,6 +7,6 @@ Draft a new change under `lawbook/changes/<name>/` for: $ARGUMENTS
 Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate the
 code with `compass_explore`/`compass_recall`, read the governing
 `docs/standards/`, then write `proposal.md`, `specs/<capability>/spec.md`
-(normative `SHALL`/`MUST` + `#### Scenario:`), optional `design.md`, and
+(normative `SHALL`/`MUST` + `#### Scenario:`), `design.md`, and
 `tasks.md` (with the mandatory steps from `lawbook/config.yaml`). Finish by
 running `lawbook_validate` and fixing every issue.

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

@@ -46,12 +46,16 @@ Create under `lawbook/changes/<name>/`:
   - When <action>
   - Then <observable outcome>
   ```
-- **design.md** (optional) — for non-trivial changes: approach, alternatives,
-  trade-offs.
+- **design.md** — always: approach, alternatives weighed, and the trade-offs
+  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)."
 
@@ -38,7 +39,7 @@ This directory is managed by speclaw's **lawbook** module.
 
 - \`specs/\` — the canonical specifications (the current source of truth).
 - \`changes/<name>/\` — an in-flight change: \`proposal.md\`, \`tasks.md\`,
-  optional \`design.md\`, and \`specs/<capability>/spec.md\` delta specs.
+  \`design.md\`, and \`specs/<capability>/spec.md\` delta specs.
 - \`changes/archive/\` — completed, archived changes.
 - \`config.yaml\` — mandatory task steps and workflow rules.
 
@@ -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/package.json

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