@esneiderbravo/speclaw 0.1.15 → 0.2.1

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/lawbook.js

@@ -40,17 +40,22 @@ export async function runSpec(flags) {
                     ui.warn(`${r.change} has ${r.issues.length} issue(s):`);
                     r.issues.forEach((i) => ui.info(i));
                 }
+                if (r.warnings.length > 0) {
+                    ui.warn(`${r.warnings.length} advisory warning(s):`);
+                    r.warnings.forEach((w) => ui.info(w));
+                }
                 return;
             }
             case "sync": {
                 const r = specSync(cwd, req(change, "spec sync <change>"));
                 ui.ok(`promoted ${r.promoted.length} spec(s)`);
-                r.promoted.forEach((p) => ui.info(p));
+                r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 return;
             }
             case "archive": {
                 const r = specArchive(cwd, req(change, "spec archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
+                r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 return;
             }
             default:

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

@@ -15,17 +15,27 @@ If `lawbook/` is missing, run the `lawbook_init` tool once to create it.
 
 ## Step 1 — Understand the request and the code
 
+- **Refresh the index first.** Run `compass_index` before reasoning about the
+  code — it is incremental (unchanged files are skipped by hash), so this is
+  cheap and guarantees your decisions rest on the current graph, not a stale one.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
 - Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
   grep/read to locate the real code the change touches and its blast radius.
-  If the index is stale or missing, run `compass_index` first.
 - Read the governing standards in `docs/standards/` (architecture, backend,
   frontend, testing) so the change complies with the project's law.
 
-## Step 2 — Pick a change name
+## Step 2 — Pick a change name and its capabilities
 
-Kebab-case, action-oriented (e.g. `add-login`, `fix-shift-overlap`). This is
-the folder under `lawbook/changes/`.
+- **Change name:** kebab-case, action-oriented (e.g. `add-login`,
+  `fix-shift-overlap`). This is the folder under `lawbook/changes/`, and it is
+  per-feature — always distinct.
+- **Capabilities:** run `lawbook_list` to see the canonical capabilities. A
+  capability is the living contract for an area of behavior — it is *not* the
+  change. When your change modifies behavior an existing capability already
+  governs, reuse that capability's **exact** name so `sync` updates its spec.
+  Introduce a new capability only as a deliberate choice for a genuinely distinct
+  area of behavior — never as a near-duplicate (`transfer` next to an existing
+  `transfers`) of one that already exists.
 
 ## Step 3 — Write the artifacts
 
@@ -34,7 +44,12 @@ Create under `lawbook/changes/<name>/`:
 - **proposal.md** — the why, the what, non-goals, and whether migrations are
   needed. Reference the team's tracker ticket if there is one.
 - **specs/<capability>/spec.md** — the delta spec for each affected capability.
-  Use normative language and testable scenarios:
+  `sync` promotes this by overwriting the whole canonical file, so the delta must
+  carry the capability's **full** intended spec. When you are updating an existing
+  capability, **start from the current `lawbook/specs/<capability>/spec.md`** and
+  edit on top of it, so its existing requirements are carried forward — do not
+  author it from scratch, or promotion will silently drop them. Use normative
+  language and testable scenarios:
   ```markdown
   # <Capability>
 
@@ -63,7 +78,11 @@ Create under `lawbook/changes/<name>/`:
 
 Run the `lawbook_validate` tool for the change and fix every issue it reports
 (missing artifacts, non-normative specs, missing scenarios) before handing off
-to implementation.
+to implementation. Read its advisory **warnings** too: a near-duplicate
+capability name usually means you should reuse the existing capability's exact
+name, and a dropped-requirement warning means the delta should start from the
+canonical. Warnings do not block, but resolve them unless the divergence is
+intentional.
 
 ## Step 5 — Hand off
 

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

@@ -11,9 +11,12 @@ understanding and a recommended direction.
 
 ## How to explore
 
+- **Refresh the index first.** Run `compass_index` before investigating — it is
+  incremental (unchanged files skipped by hash), so it is cheap and keeps your
+  reasoning on the current graph rather than a stale one.
 - **Understand the code first.** Use `compass_recall` to find relevant code by
   meaning and `compass_explore` to read a symbol's source plus its callers and
-  callees — before grep/read. Run `compass_index` if the graph is missing.
+  callees — before grep/read.
 - **Ask sharp questions** to surface hidden assumptions, constraints, and edge
   cases. Confirm scope and non-goals.
 - **Check the law.** Read the relevant `docs/standards/` so any direction you

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

@@ -35,7 +35,11 @@ specs that become canonical describe reality, not just the original draft.
 
 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.
+   `lawbook/specs/<capability>/spec.md` and reports what it promoted, flagging
+   each as **created** (new capability) or **updated** (overwrote an existing
+   one). A capability you expected to update showing up as *created* means the
+   delta forked a near-duplicate — fix the name before promoting.
 
 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.
+   promoted files (created vs updated). The change stays active — `archive` it
+   when it's fully done.

package/dist/modules/lawbook/engine.js

@@ -84,6 +84,47 @@ export function specInit(projectPath) {
     ensure("README.md", README_MD);
     return { created, alreadyExisted };
 }
+/** Names of the canonical capabilities (directories under lawbook/specs/). */
+function canonicalCapabilities(root) {
+    const specsDir = path.join(root, "specs");
+    if (!fs.existsSync(specsDir))
+        return [];
+    return fs
+        .readdirSync(specsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+/** The "### Requirement:" titles declared in a spec markdown document. */
+function requirementHeaders(markdown) {
+    const out = [];
+    for (const m of markdown.matchAll(/^###\s+Requirement:\s*(.+?)\s*$/gm))
+        out.push(m[1]);
+    return out;
+}
+/** Levenshtein edit distance between two strings (small, dependency-free). */
+function editDistance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i++) {
+        const curr = [i];
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[cols - 1];
+}
+/**
+ * The existing canonical capability that a name is a near-match of (edit
+ * distance ≤ 2 and not equal), or undefined when the name is exact or unrelated.
+ */
+function nearMatchCapability(name, capabilities) {
+    if (capabilities.includes(name))
+        return undefined;
+    return capabilities.find((c) => editDistance(name, c) <= 2);
+}
 /** Recursively collect every .md file under a change's specs/ directory. */
 function deltaSpecFiles(changeDir) {
     const specsDir = path.join(changeDir, "specs");
@@ -120,6 +161,7 @@ export function specValidate(projectPath, change) {
             change,
             valid: false,
             issues: [`change "${change}" not found under lawbook/changes/`],
+            warnings: [],
             deltaSpecs: [],
         };
     }
@@ -131,6 +173,10 @@ export function specValidate(projectPath, change) {
     const deltas = deltaSpecFiles(changeDir);
     if (deltas.length === 0)
         issues.push("no delta specs under specs/ (a change should specify what it changes)");
+    const root = specRoot(projectPath);
+    const changeSpecs = path.join(changeDir, "specs");
+    const capabilities = canonicalCapabilities(root);
+    const warnings = [];
     for (const file of deltas) {
         const rel = path.relative(changeDir, file);
         const content = fs.readFileSync(file, "utf8");
@@ -143,21 +189,46 @@ export function specValidate(projectPath, change) {
         if (!/^###\s+Requirement:/m.test(content)) {
             issues.push(`${rel}: no "### Requirement:" header`);
         }
+        // Advisory divergence checks against the canonical specs.
+        const relFromSpecs = path.relative(changeSpecs, file);
+        const capability = relFromSpecs.split(path.sep)[0];
+        const nearMatch = nearMatchCapability(capability, capabilities);
+        if (nearMatch) {
+            warnings.push(`${rel}: capability "${capability}" is not canonical but resembles ` +
+                `"${nearMatch}" — did you mean to update it? Reuse the exact name to ` +
+                `update the existing spec instead of forking a near-duplicate.`);
+        }
+        else if (capabilities.includes(capability)) {
+            const canonicalFile = path.join(root, "specs", relFromSpecs);
+            if (fs.existsSync(canonicalFile)) {
+                const deltaReqs = new Set(requirementHeaders(content));
+                const dropped = requirementHeaders(fs.readFileSync(canonicalFile, "utf8")).filter((r) => !deltaReqs.has(r));
+                if (dropped.length > 0) {
+                    warnings.push(`${rel}: delta drops ${dropped.length} requirement(s) present in the ` +
+                        `canonical "${capability}" spec (${dropped.join("; ")}) — start the ` +
+                        `delta from the canonical unless the removal is intentional.`);
+                }
+            }
+        }
     }
     return {
         change,
         valid: issues.length === 0,
         issues,
+        warnings,
         deltaSpecs: deltas.map((f) => path.relative(projectPath, f)),
     };
 }
 /**
  * Promote a change's delta specs into the canonical specs/, overwriting the
- * file for each affected capability.
+ * file for each affected capability. Each promoted path is also classified as
+ * `created` (no canonical file existed) or `updated` (one was overwritten) so an
+ * unintended new capability is visible in the result — a pure path check that
+ * keeps this a deterministic, code-blind copy.
  *
  * @param projectPath - Absolute path to the project root.
  * @param change - Change name (folder under lawbook/changes/).
- * @returns The change name and the list of promoted spec paths.
+ * @returns The change name, the promoted spec paths, and the created/updated split.
  * @throws If the change directory does not exist.
  */
 export function specSync(projectPath, change) {
@@ -167,8 +238,10 @@ export function specSync(projectPath, change) {
         throw new Error(`change "${change}" not found`);
     const changeSpecs = path.join(changeDir, "specs");
     const promoted = [];
+    const created = [];
+    const updated = [];
     if (!fs.existsSync(changeSpecs))
-        return { change, promoted };
+        return { change, promoted, created, updated };
     const walk = (dir) => {
         for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
             const full = path.join(dir, e.name);
@@ -177,14 +250,17 @@ export function specSync(projectPath, change) {
             else if (e.name.endsWith(".md")) {
                 const rel = path.relative(changeSpecs, full);
                 const dest = path.join(root, "specs", rel);
+                const existed = fs.existsSync(dest);
                 fs.mkdirSync(path.dirname(dest), { recursive: true });
                 fs.copyFileSync(full, dest);
-                promoted.push(path.join("lawbook/specs", rel));
+                const promotedPath = path.join("lawbook/specs", rel);
+                promoted.push(promotedPath);
+                (existed ? updated : created).push(promotedPath);
             }
         }
     };
     walk(changeSpecs);
-    return { change, promoted };
+    return { change, promoted, created, updated };
 }
 /**
  * Deterministic completeness checks that gate archiving a change. Returns the
@@ -256,13 +332,13 @@ export function specArchive(projectPath, change, date) {
     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 { promoted, created, updated } = specSync(projectPath, change);
     const archiveDir = path.join(root, "changes", "archive", `${date}-${change}`);
     fs.mkdirSync(path.dirname(archiveDir), { recursive: true });
     if (fs.existsSync(archiveDir))
         throw new Error(`archive target already exists: ${archiveDir}`);
     fs.renameSync(changeDir, archiveDir);
-    return { change, promoted, archivedTo: path.relative(projectPath, archiveDir) };
+    return { change, promoted, created, updated, archivedTo: path.relative(projectPath, archiveDir) };
 }
 /**
  * List the spec workspace: active changes, archived changes, and canonical

package/dist/modules/lawbook/register.js

@@ -29,14 +29,14 @@ export function registerSpec(server) {
         inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
     }, async ({ projectPath }) => text(specList(projectPath)));
     server.registerTool("lawbook_validate", {
-        description: "Validate a change's artifacts: proposal.md and tasks.md present, and delta specs use normative language (SHALL/MUST), '### Requirement:' headers, and '#### Scenario:' acceptance criteria. Returns the issues to fix. Used by the draft/build commands before proceeding.",
+        description: "Validate a change's artifacts: proposal.md and tasks.md present, and delta specs use normative language (SHALL/MUST), '### Requirement:' headers, and '#### Scenario:' acceptance criteria. Returns the blocking issues to fix plus advisory (non-blocking) warnings — a capability name that resembles an existing canonical one, or requirements dropped versus the canonical. Used by the draft/build commands before proceeding.",
         inputSchema: {
             projectPath: z.string().describe("Absolute path to the project"),
             change: z.string().describe("Change name (folder under lawbook/changes/)"),
         },
     }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
     server.registerTool("lawbook_sync", {
-        description: "Promote a change's delta specs into the canonical lawbook/specs/ (per capability), without archiving. Backs the `sync` command.",
+        description: "Promote a change's delta specs into the canonical lawbook/specs/ (per capability), without archiving. Reports each promoted spec as created (new capability) or updated (overwrote an existing one). Backs the `sync` command.",
         inputSchema: {
             projectPath: z.string().describe("Absolute path to the project"),
             change: z.string().describe("Change name (folder under lawbook/changes/)"),

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