@esneiderbravo/speclaw 0.2.0 → 0.3.0

package/README.md

@@ -162,6 +162,19 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
   <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-tree.png" width="800" alt="what speclaw writes into your project">
 </p>
 
+**Committed vs. local.** Your **personalized source** is committed — `LAWS.md`,
+`CLAUDE.md`, `AGENTS.md`, `docs/standards/*`, `docs/compass.md`, and the
+`lawbook/` workspace. speclaw's **regenerable workflow content is local, not
+committed**: only `ai-specs/` (skills, commands, rules, agent packs, and its
+`.speclaw.json` manifest) is gitignored, because `init`/`update` reconstruct it
+from the package — like a dependency. So **after cloning a speclaw project, run
+`speclaw init` (or `speclaw update`)** to regenerate `ai-specs/` locally, which
+the agent IDE symlinks point into. If a project committed `ai-specs/` before
+this behavior existed, `init`/`update` print the exact `git rm -r --cached
+ai-specs` command to stop tracking it (they never touch your git index
+themselves). The agent directories (`.claude/`, `.cursor/`, …) are **left to
+you** — commit your own skills and commands there if you want to.
+
 <br/>
 
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Philosophy — why "laws"?
@@ -189,9 +202,10 @@ without a re-init, splitting files by who owns them:
 
 - **Managed files** (speclaw's workflow machinery — the skills, commands, rules,
   and agent packs under `ai-specs/`) are **refreshed** to the new version, so
-  improvements actually reach your project. If you edited one locally, `update`
-  reports the overwrite so you can recover your copy from git; pass `--backup` to
-  also keep a `<file>.bak`. Any `*.bak` is gitignored.
+  improvements actually reach your project. They live locally (gitignored, see
+  *What lands in your project*) and are reconstructed from the package. If you
+  edited one locally, `update` reports the overwrite; pass `--backup` to keep a
+  `<file>.bak` (itself gitignored) before it is refreshed.
 - **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

package/dist/cli/commands/init.js

@@ -9,6 +9,7 @@ import { loadPacks } from "../../modules/tools/packs.js";
 import { list } from "../lib/args.js";
 import { ui, c, banner, renderProgress, clearProgress } from "../lib/ui.js";
 import { checkForUpdates } from "../lib/update-check.js";
+import { reportTrackedLocalContent } from "../lib/untrack.js";
 const PACK_LABELS = {
     agents: "dev-agents (backend · frontend · product)",
 };
@@ -99,6 +100,9 @@ export async function runInit(flags) {
     ui.step("Configuring agents");
     for (const id of agents)
         ui.ok(`${agentById(id).label} ${c.muted("— symlinks + MCP")}`);
+    // ai-specs/ is gitignored (regenerated by init/update). If a prior setup
+    // already committed it, tell the user how to untrack it.
+    reportTrackedLocalContent(cwd);
     // 2. Compass index with progress
     if (!flags["no-index"]) {
         ui.step("Indexing your code with Compass");
@@ -132,4 +136,6 @@ export async function runInit(flags) {
     ui.info(`Refresh index:  ${ui.code("speclaw index")}`);
     ui.info(`Health check:   ${ui.code("speclaw doctor")}`);
     ui.plain();
+    ui.info(`${c.muted("ai-specs/ is local (gitignored) — teammates run")} ${ui.code("speclaw init")} ${c.muted("after cloning to regenerate it.")}`);
+    ui.plain();
 }

package/dist/cli/commands/update.js

@@ -10,6 +10,7 @@ import { detectConfiguredAgents } from "../../shared/agents.js";
 import { readManifest } from "../../shared/manifest.js";
 import { loadPacks } from "../../modules/tools/packs.js";
 import { detectProjectName } from "./init.js";
+import { reportTrackedLocalContent } from "../lib/untrack.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.
@@ -196,6 +197,10 @@ function applyProjectMigrations(cwd, backup) {
         console.log(c.cream(prompt));
         ui.plain();
     }
+    // This release makes ai-specs/ local (gitignored). A project that committed
+    // it before now still tracks it — point out how to untrack (speclaw never
+    // touches the git index itself).
+    reportTrackedLocalContent(cwd);
     ui.plain();
     ui.ok(`On ${c.cyan(pkgVersion())}. No re-init needed.`);
 }

package/dist/cli/lib/untrack.js

@@ -0,0 +1,25 @@
+import { ui, c } from "./ui.js";
+import { listTrackedPaths } from "../../shared/git.js";
+/**
+ * If `ai-specs/` is still tracked by git, print the exact `git rm -r --cached`
+ * command to untrack it. `ai-specs/` is regenerable from the package, so
+ * init/update gitignore it — but adding a `.gitignore` entry does not stop git
+ * tracking a directory it already tracks, so this is how an already-installed
+ * project makes that content local. It only prints — it never modifies the git
+ * index — and no-ops silently outside a git repository or when nothing is
+ * tracked. The agents' IDE directories (`.claude/`, …) are deliberately left
+ * alone, so a user's own skills/commands there stay committable.
+ *
+ * @param projectPath - Project root to inspect and address.
+ */
+export function reportTrackedLocalContent(projectPath) {
+    const tracked = listTrackedPaths(projectPath, ["ai-specs"]);
+    if (!tracked.length)
+        return;
+    ui.step("Make ai-specs/ local-only");
+    ui.info("git still tracks ai-specs/ (regenerable). To stop tracking it (it stays on disk):");
+    ui.plain();
+    console.log("  " + c.cream(`git rm -r --cached ${tracked.join(" ")}`));
+    console.log("  " + c.cream('git commit -m "chore: stop tracking speclaw local content"'));
+    ui.plain();
+}

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

@@ -32,7 +32,9 @@ 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
+discipline it touched, named for that discipline — an open set (`backend.md`,
+`frontend.md`, `api.md`, `database.md`, `infra.md`, … — `api.md` required
+whenever the change touches an API surface) 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.

package/dist/modules/foundation/assets/docs/standards/testing-standards.template.md

@@ -45,9 +45,18 @@ suppressing a linter or deleting a test.
 ## Reports — evidence travels with the change
 
 Every change records its testing under `lawbook/changes/<name>/reports/`, one
-file per discipline it touched (`backend.md`, `frontend.md`, …). `build`
-produces them; archiving is blocked until the change has at least one discipline
-report.
+file per discipline it touched, named for that discipline. The set is open, not
+fixed: `backend.md`, `frontend.md`, and `api.md` are the common ones, but write
+`database.md`, `infra.md`, `security.md`, `performance.md`, `e2e.md`, etc. when
+the change exercises those concerns. `build` produces them; archiving is blocked
+until the change has at least one discipline report.
+
+`api.md` is **mandatory whenever the change touches an API surface** — a new or
+modified endpoint, its contract, its status codes, or its auth/permission or
+ordering guarantees — and a `backend.md` unit report does not substitute for it.
+It documents the method and path, the auth/permissions, the response shape and
+every status code the change governs, any ordering guarantee, and how the
+contract was exercised (test client and/or `curl`) kept isolated from live data.
 
 Each report MUST follow a fixed structure, so the evidence is reproducible rather
 than improvised:

package/dist/modules/foundation/scaffold.js

@@ -104,6 +104,10 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
         installPack(projectPath, name, vars, report, managedOpts); // managed
     ensureGitignore(projectPath, ".speclaw/", "speclaw local code Compass (never commit)", report);
     ensureGitignore(projectPath, "*.bak", "speclaw managed-file refresh backups", report);
+    // ai-specs/ is regenerable from the package (installWorkflow/installPack copy
+    // it out of the module assets) plus the local .speclaw.json manifest — local,
+    // per-checkout content, reconstructed by init/update, never committed.
+    ensureGitignore(projectPath, "ai-specs/", "speclaw workflow content (regenerated by init/update; 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 these packs and

package/dist/modules/lawbook/assets/rules/spec-reports-disciplines.md

@@ -0,0 +1,78 @@
+---
+description: Require one test report per discipline a change touches (an open set — backend, frontend, api, database, infra, security, performance, e2e, …), with the api report mandatory whenever the change touches an API surface.
+alwaysApply: true
+---
+
+# Spec Reports: Discipline Coverage
+
+A change's evidence of testing lives under `lawbook/changes/<name>/reports/`, as
+**one file per discipline the change actually touched**, named for that
+discipline (`<discipline>.md`) — never a single lumped report.
+
+## 1. The set of disciplines is open — name what the change touched
+
+There is no fixed list. Write a report for each area of concern the change
+exercised, and omit the ones it did not. Common disciplines include, but are
+**not limited to**:
+
+- **`backend.md`** — domain/service logic, persistence, jobs.
+- **`frontend.md`** — UI flows, components, client state.
+- **`api.md`** — the endpoint contract itself (see §2).
+- **`database.md`** — schema changes, migrations, data integrity.
+- **`infra.md`** — IaC, CI/CD pipelines, deployment/runtime config.
+- **`security.md`** — authn/authz, secrets, attack surface.
+- **`performance.md`** — benchmarks, load, latency budgets.
+- **`e2e.md`** — full cross-service or cross-layer journeys.
+- **`mobile.md`**, **`contract.md`**, **`data.md`**, **`accessibility.md`**, …
+
+When a change touches a concern none of these names fit, coin a clear
+`<discipline>.md` for it rather than folding it into an ill-fitting bucket. The
+goal is that the evidence a reviewer needs for each concern is where they expect
+it — not that reports match a checklist.
+
+## 2. The API report is mandatory whenever an API surface is touched
+
+`api` is called out because it is the discipline most often (wrongly) absorbed
+into `backend` and lost. When a change **adds or modifies an API surface** — a
+new or changed endpoint, its request/response contract, its status codes, or its
+auth/permission or ordering guarantees — you MUST write `api.md`. This is not
+optional:
+
+- A `backend.md` unit report does **not** substitute for it — the contract
+  (shape, status codes, auth, ordering) is a distinct concern a service-unit
+  report does not capture.
+- A `frontend.md` report does **not** substitute for it either.
+
+A change that touches no endpoint or contract MAY omit `api.md`.
+
+`api.md` MUST document the contract: the method and path, the auth and
+permissions required, the response shape and **every** status code the change
+governs (e.g. `200`/`401`/`403`/`404`), and any ordering or consistency
+guarantee. It MUST record how the contract was exercised — a test client and/or a
+live request such as `curl` — and, per the verification-safety rule, how that
+exercise stayed isolated from any live data store (read-only, ephemeral store, or
+rolled-back transaction — never a write to real data without authorization).
+
+## 3. Every report follows the required structure
+
+Regardless of discipline, each report keeps the fixed structure so evidence is
+reproducible, not improvised: title + header (discipline · change · date ·
+branch · cwd) → gates-and-results table (each check, exact command, real result
+with pass/fail counts) → tests added/updated → spec-scenario coverage table
+(every `#### Scenario` mapped to how it was verified) → pre-existing/unrelated
+failures (with proof, or "none") → pending manual steps (or "none") → one-line
+verdict. See the `build` skill (Step 5) and
+`docs/standards/testing-standards.md`.
+
+When a test kind does not yet apply (e.g. no unit runner), the report says so in
+place of that evidence and records the gates and manual verification that stood
+in.
+
+## 4. Reports gate the archive
+
+`lawbook_archive` refuses to archive while `reports/` holds no discipline report
+(the `reports/README.md` scaffold does not count). Which disciplines a change
+touched — and therefore which reports are owed, including `api.md` for any
+API-touching change — is the agent's responsibility to judge and satisfy before
+archiving; the engine gate counts files but cannot infer the set of concerns a
+change exercised.

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

@@ -21,9 +21,11 @@ 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.
+- Produce the discipline reports under `reports/` — one per discipline the change
+  touched, from an open set (`backend.md`, `frontend.md`, `api.md`, `database.md`,
+  `infra.md`, … — `api.md` is required whenever the change touches an API surface;
+  see the `spec-reports-disciplines` rule) 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).

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

@@ -62,9 +62,21 @@ authorization you obtained).
 ## 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`, …). Omit
-disciplines the change did not touch; the archive is blocked until at least one
-discipline report exists.
+per discipline the change touched, named for that discipline. The set is **open,
+not a fixed list** — `backend.md`, `frontend.md`, and `api.md` are the common
+ones, but write `database.md`, `infra.md`, `security.md`, `performance.md`,
+`e2e.md`, etc. when the change exercises those concerns, and coin a clear
+`<discipline>.md` for anything none of them fit. Omit disciplines the change did
+not touch; the archive is blocked until at least one discipline report exists.
+
+**`api.md` is mandatory whenever the change touches an API surface** — a new or
+modified endpoint, its request/response contract, its status codes, or its
+auth/permission or ordering guarantees. A `backend.md` unit report does not
+substitute for it: the contract is a distinct concern. In `api.md` document the
+method and path, the auth/permissions, the response shape and every status code
+the change governs (e.g. `200`/`401`/`403`/`404`), any ordering guarantee, and
+how the contract was exercised (test client and/or `curl`) — kept isolated from
+any live data store per Step 4.
 
 Each report MUST follow this structure, in order — the fixed shape is what makes
 the evidence trustworthy and reproducible, rather than left to improvisation:

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

@@ -68,8 +68,11 @@ Create under `lawbook/changes/<name>/`:
   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, following the required report structure (header · gates table ·
+  discipline reports the change will need — one per discipline it touches, from an
+  open set (`backend.md`, `frontend.md`, `api.md`, `database.md`, `infra.md`,
+  `security.md`, … — and `api.md` is required when the change touches any API
+  surface) that `build` will fill, following the required report structure
+  (header · gates table ·
   tests added · spec-scenario coverage · pre-existing failures · pending manual ·
   verdict — see the `build` skill, Step 5). Every change ships this folder;
   archive is blocked until it holds at least one discipline report.

package/dist/modules/lawbook/engine.js

@@ -26,7 +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)."
+  - "Produce the discipline reports under reports/ — one per discipline touched, from an open set (e.g. backend.md, frontend.md, api.md, database.md, infra.md, security.md; api.md is required whenever the change touches an API surface) — with the 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)."
 

package/dist/shared/git.js

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+/**
+ * True when `projectPath` is inside a git working tree.
+ *
+ * Best-effort: shells `git rev-parse --is-inside-work-tree` and treats any
+ * failure (git not installed, not a repository) as "not a repo" rather than
+ * throwing — callers use this only to decide whether to attempt further git
+ * queries.
+ *
+ * @param projectPath - Directory to test.
+ * @returns `true` only when git reports the path is inside a work tree.
+ */
+export function isGitRepo(projectPath) {
+    const res = spawnSync("git", ["-C", projectPath, "rev-parse", "--is-inside-work-tree"], {
+        encoding: "utf8",
+    });
+    return res.status === 0 && res.stdout.trim() === "true";
+}
+/**
+ * Of `candidates` (project-relative paths), the subset git currently tracks.
+ *
+ * Adding a path to `.gitignore` does not stop git tracking a file it already
+ * tracks; this reports which speclaw paths are still tracked so a command can
+ * tell the user how to untrack them. Returns an empty array when `projectPath`
+ * is not a git repository (or git is unavailable).
+ *
+ * @param projectPath - Project root to query.
+ * @param candidates - Project-relative paths (files, directories, or symlinks).
+ * @returns The candidates for which `git ls-files` reports at least one tracked
+ *   entry, in the order given.
+ */
+export function listTrackedPaths(projectPath, candidates) {
+    if (!isGitRepo(projectPath))
+        return [];
+    return candidates.filter((rel) => {
+        const res = spawnSync("git", ["-C", projectPath, "ls-files", "--", rel], { encoding: "utf8" });
+        return res.status === 0 && res.stdout.trim().length > 0;
+    });
+}

package/package.json

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