@esneiderbravo/speclaw 0.1.9 → 0.1.10

package/README.md

@@ -93,26 +93,38 @@ 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. |
+| **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. |
 
-**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.
+**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`. |
+
+> [!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/docs/standards/lawbook.template.md

@@ -10,7 +10,7 @@ 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`, and `tasks.md`.
 3. **build** — implement the tasks in order, keeping code and spec in
    agreement.
 4. **sync** — promote the change's delta specs into the canonical

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/skills/draft/SKILL.md

@@ -46,8 +46,8 @@ 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

package/dist/modules/lawbook/engine.js

@@ -38,7 +38,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.
 

package/package.json

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