@esneiderbravo/speclaw 2.0.13 → 2.0.15

package/dist/cli/commands/init.js

@@ -24,17 +24,16 @@ export function detectProjectName(cwd) {
     return path.basename(cwd);
 }
 /**
- * Interactive setup: pick agents (and packs when any exist), scaffold, index,
+ * Setup: create `.agents/` (plus any `--agents`), pick packs when any exist, scaffold, index,
  * and print the handoff prompt.
  *
- * @param flags - Parsed flags; runs interactively on a TTY unless `--agents`, `--yes`, or
- *   `-y` is set. Honors `--project-name`, `--packs`, and `--no-index`.
+ * @param flags - Parsed flags; only the pack picker is interactive (on a TTY unless
+ *   `--agents`, `--yes`, or `-y` is set). Honors `--project-name`, `--packs`, and `--no-index`.
  */
 export async function runInit(flags) {
     const cwd = process.cwd();
     const projectName = flags["project-name"] || detectProjectName(cwd);
     const interactive = Boolean(process.stdin.isTTY) && !flags.agents && !flags.yes && !flags.y;
-    let agents;
     let packs;
     const availablePacks = loadPacks();
     const packIds = Object.keys(availablePacks);
@@ -50,35 +49,26 @@ export async function runInit(flags) {
             `Later, ${ui.code("speclaw update")} upgrades itself through npx.`);
         ui.plain();
     }
-    if (interactive) {
-        // Covers: req~remove-agents-pack~1
-        const prompts = {
-            agents: () => clack.multiselect({
-                message: "Which agents do you use? (space to select)",
-                options: AGENTS.map((a) => ({ value: a.id, label: a.label })),
-                initialValues: ["claude"],
-                required: true,
-            }),
-        };
-        if (packIds.length > 0) {
-            prompts.packs = () => clack.multiselect({
-                message: "Which tool packs to install?",
-                options: packIds.map((id) => ({
-                    value: id,
-                    label: id,
-                    hint: availablePacks[id].description.slice(0, 50),
-                })),
-                initialValues: [],
-                required: false,
-            });
-        }
-        const answers = await clack.group(prompts, { onCancel: () => process.exit(1) });
-        agents = answers.agents;
-        packs = answers.packs ?? [];
-    }
-    else {
-        agents = list(flags.agents).length ? list(flags.agents) : ["claude"];
-        packs = list(flags.packs);
+    // Agents are never prompted for: init creates one agent-facing folder,
+    // `.agents/`, linked into ai-specs/. Other IDE folders only via `--agents`
+    // or `speclaw agent add`.
+    const agents = list(flags.agents).length ? list(flags.agents) : ["agents"];
+    packs = list(flags.packs);
+    // Covers: req~remove-agents-pack~1
+    if (interactive && packIds.length > 0 && !packs.length) {
+        const answer = await clack.multiselect({
+            message: "Which tool packs to install?",
+            options: packIds.map((id) => ({
+                value: id,
+                label: id,
+                hint: availablePacks[id].description.slice(0, 50),
+            })),
+            initialValues: [],
+            required: false,
+        });
+        if (clack.isCancel(answer))
+            process.exit(1);
+        packs = answer;
     }
     const unknownAgents = agents.filter((a) => !agentById(a));
     if (unknownAgents.length) {

package/dist/cli/lib/help.js

@@ -13,7 +13,7 @@ Install globally so the command is always available:
   npm i -g @esneiderbravo/speclaw     (or run npx @esneiderbravo/speclaw@latest init)
 
 Setup
-  init                     Interactive setup: pick agents, scaffold, index, get the prompt
+  init                     Setup: .agents/ linked into ai-specs/, scaffold, index, get the prompt
                            (--minimal omits setup/lifecycle MCP tools)
   update                   Re-run itself at the latest version via npx, then apply project
                            migrations (--check reports version only; --no-self-update
@@ -123,13 +123,14 @@ you rarely run it by hand.
         name: "init",
         usage: `Usage: speclaw init [options]
 
-Interactive setup: pick agents, scaffold the constitution and lawbook, build the
-Compass index, and print the starting prompt. Prefer
+Setup without an agent picker: create .agents/ linked into ai-specs/ (gitignored),
+scaffold the constitution and lawbook, build the Compass index, and print the
+starting prompt. Prefer
 npx @esneiderbravo/speclaw@latest init so the scaffold matches the latest release.
 
 Options
   --yes, -y               Accept the defaults without prompting
-  --agents <ids>          Comma-separated agents to configure (claude, cursor, …)
+  --agents <ids>          Agents to configure (default: agents → only .agents/; also claude, cursor, codex, windsurf)
   --packs <ids>           Comma-separated tool packs to install
   --project-name <name>   Project name for the templates
   --minimal               Omit setup/lifecycle MCP tools

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

@@ -42,8 +42,8 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    [`docs/standards/base-standards.md`](docs/standards/base-standards.md) and
    [`docs/standards/conventions.md`](docs/standards/conventions.md).
 6. **Use the skills and role agents.** `ai-specs/` is the canonical home for
-   skills, commands, rules, and agents, mirrored to each IDE directory via
-   symlinks.
+   skills, commands, rules, and agents; agents read them through the symlinks
+   in `.agents/` (plus an IDE folder only for an agent added explicitly).
 7. **Ask before irreversible or outward-facing actions** — destructive commands;
    writing to a real data store (DB rows or files with real user data, including
    for tests — verify against an isolated/throwaway store); publishing

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

@@ -82,8 +82,9 @@ its neighbors, comments that carry constraints (never ticket IDs). Full rules:
 
 ## Rule 5 — Skills and role agents are law-adjacent
 
-Skills, commands, rules, and agents live in `ai-specs/` (symlinked into
-`.claude/`, `.cursor/`, `.codex/`, `.agents/`). When a skill or role matches
+Skills, commands, rules, and agents live in `ai-specs/`, read through the
+symlinks in `.agents/` (an IDE folder such as `.claude/` exists only for an
+agent added explicitly with `speclaw agent add`). When a skill or role matches
 the task, use it — do not improvise a parallel process.
 
 ## Rule 6 — Stop conditions

package/dist/modules/foundation/dialects/copilot.js

@@ -6,11 +6,9 @@ import { frontmatter, lawSlug, } from "./types.js";
 export const copilotDialect = {
     id: "copilot-instructions",
     compile(laws, ctx) {
-        // Emit when explicitly wanted: agent id "copilot" or always if .github exists —
-        // orchestrator passes agents; treat missing copilot as skip unless "agents" generic.
-        const want = ctx.agents.includes("copilot") ||
-            ctx.agents.includes("github-copilot") ||
-            ctx.agents.includes("agents");
+        // Only for Copilot: the generic agent reads scoped laws from AGENTS.md
+        // (agentsmd dialect), so it gets no `.github/instructions/` folder.
+        const want = ctx.agents.includes("copilot") || ctx.agents.includes("github-copilot");
         if (!want)
             return [];
         const scoped = laws.filter((l) => (l.status ?? "active") !== "draft" && l.scope.length > 0);

package/dist/modules/foundation/scaffold.js

@@ -50,21 +50,6 @@ function ensureLawManifest(projectPath, report) {
     }
     return manifest;
 }
-/**
- * Write `.github/workflows/speclaw.yml` from the shipped template when the
- * path does not exist. Never overwrite — the user's CI is theirs.
- */
-function ensureVerifyWorkflow(projectPath, report) {
-    const dest = path.join(projectPath, ".github", "workflows", "speclaw.yml");
-    if (fs.existsSync(dest)) {
-        report.skipped.push(dest);
-        return;
-    }
-    const src = path.join(ASSETS, "workflows", "speclaw.yml");
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(src, dest);
-    report.written.push(dest);
-}
 /**
  * Render the foundation: walk the module's assets/, mirror its structure into
  * the project, stripping the `.template` marker (foo.template.md -> foo.md).
@@ -163,6 +148,9 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // 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);
+    // The integrity lock is local tool state: it guards this checkout's rule
+    // files and is rebuilt by init/update, so it is not committed.
+    ensureGitignore(projectPath, "speclaw.lock", "speclaw local integrity lock (never commit)", report);
     for (const id of agents)
         configureAgent(projectPath, id, report); // only the chosen agents
     // Compile the declared laws into agent hooks for every hook-capable agent just
@@ -185,7 +173,6 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
             report.lockError = err.message;
         }
     }
-    ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {
         baselines: managedOpts.baselines,
         backup: managedOpts.backup,

package/dist/modules/lawbook/anchors.js

@@ -241,7 +241,8 @@ export function sealCapability(projectPath, capability, markdown, opts = {}) {
         const now = opts.now ?? new Date().toISOString();
         const sha = headSha(projectPath);
         const specId = opts.specId ?? capability;
-        const rows = resolveCandidates(db, projectPath, extractCandidates(markdown), specId, now, sha);
+        const fresh = resolveCandidates(db, projectPath, extractCandidates(markdown), specId, now, sha);
+        const rows = keepUnchangedStamps(readAnchorsFile(projectPath, capability), fresh);
         const dest = writeAnchorsFile(projectPath, {
             anchorsVersion: 1,
             capability,
@@ -262,6 +263,42 @@ export function sealCapability(projectPath, capability, markdown, opts = {}) {
         db.close();
     }
 }
+/** Fields that identify one anchor across seals. */
+function anchorKey(a) {
+    return [a.requirementId, a.scenarioId, a.symbolName, a.anchorKind, a.source].join("\0");
+}
+/** Fields whose change means the anchor was really re-sealed. */
+function sealedState(a) {
+    return JSON.stringify([
+        a.specId,
+        a.filePath,
+        a.resolution,
+        a.contentHash,
+        a.rawHash,
+        a.normalizerVersion,
+    ]);
+}
+/**
+ * Keep the previous `archivedAt` / `commitSha` of every anchor whose sealed
+ * state did not change, so a reseal rewrites only the anchors that moved —
+ * an unchanged capability stays byte-identical and the drift age of an
+ * untouched anchor still counts from when it was really sealed.
+ *
+ * @param previous - The capability's anchors file before this seal, if any.
+ * @param fresh - The anchors just resolved, stamped with this seal's time and sha.
+ * @returns The anchors to write.
+ */
+function keepUnchangedStamps(previous, fresh) {
+    if (!previous)
+        return fresh;
+    const old = new Map(previous.anchors.map((a) => [anchorKey(a), a]));
+    return fresh.map((a) => {
+        const prior = old.get(anchorKey(a));
+        return prior && sealedState(prior) === sealedState(a)
+            ? { ...a, archivedAt: prior.archivedAt, commitSha: prior.commitSha }
+            : a;
+    });
+}
 /** Seal every canonical capability under lawbook/specs/ that has a spec.md. */
 export function resealAll(projectPath) {
     const specsRoot = path.join(projectPath, "lawbook", "specs");

package/dist/shared/agents.js

@@ -11,6 +11,7 @@ export const AGENTS = [
         linkTargets: ["skills", "commands", "agents"],
         mcpFile: ".mcp.json",
         hooks: { file: ".claude/settings.json", key: "hooks" },
+        ownedPaths: [".claude/rules/speclaw"],
     },
     {
         id: "cursor",
@@ -37,7 +38,7 @@ export const AGENTS = [
         id: "agents",
         label: "Generic (AGENTS.md)",
         ideDir: ".agents",
-        linkTargets: ["skills", "agents"],
+        linkTargets: ["skills", "commands", "agents", "rules"],
     },
 ];
 /**
@@ -141,6 +142,24 @@ export function configureAgent(projectPath, agentId, report) {
     if (!agent)
         throw new Error(`Unknown agent "${agentId}". Known: ${AGENTS.map((a) => a.id).join(", ")}`);
     const ideRoot = path.join(projectPath, agent.ideDir);
+    // Everything speclaw puts in an agent folder is links into the gitignored
+    // ai-specs/ plus per-developer wiring: keep it out of version control. A
+    // folder speclaw creates is ignored whole; in a folder that already existed
+    // (the IDE's own, e.g. `.claude/settings.local.json`) only speclaw's entries are.
+    const comment = `speclaw ${agent.label} links (regenerated by init; never commit)`;
+    if (!fs.existsSync(ideRoot)) {
+        ensureGitignore(projectPath, `${agent.ideDir}/`, comment, report);
+    }
+    else {
+        const owned = agent.linkTargets
+            .filter((t) => fs.existsSync(path.join(projectPath, "ai-specs", t)))
+            .map((t) => `${agent.ideDir}/${t}`)
+            .concat(agent.ownedPaths ?? []);
+        if (agent.hooks && !fs.existsSync(path.join(projectPath, agent.hooks.file)))
+            owned.push(agent.hooks.file);
+        for (const entry of owned)
+            ensureGitignore(projectPath, entry, comment, report);
+    }
     for (const target of agent.linkTargets) {
         const sourceDir = path.join(projectPath, "ai-specs", target);
         if (!fs.existsSync(sourceDir))
@@ -158,13 +177,25 @@ export function configureAgent(projectPath, agentId, report) {
         writeMcpConfig(projectPath, agent.mcpFile, report);
 }
 /**
- * List the agents already set up in this project (their IDE dir exists).
+ * List the agents speclaw set up in this project: those whose IDE dir holds at
+ * least one speclaw link into ai-specs/. A bare IDE dir is not enough — Claude
+ * Code and Cursor create `.claude/` / `.cursor/` on their own, and treating
+ * that as "configured" made `update` populate folders nobody chose.
  *
  * @param projectPath - Project root to inspect.
- * @returns The ids of agents whose IDE directory is present.
+ * @returns The ids of agents with a speclaw link in their IDE directory.
  */
 export function detectConfiguredAgents(projectPath) {
-    return AGENTS.filter((a) => fs.existsSync(path.join(projectPath, a.ideDir))).map((a) => a.id);
+    return AGENTS.filter((a) => a.linkTargets.some((t) => isAiSpecsLink(path.join(projectPath, a.ideDir, t), t))).map((a) => a.id);
+}
+/** True when `p` is a symlink whose target ends in `ai-specs/<target>`. */
+function isAiSpecsLink(p, target) {
+    try {
+        return fs.readlinkSync(p).replace(/\\/g, "/").endsWith(`ai-specs/${target}`);
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Re-run configuration for every already-configured agent (e.g. after adding a pack).

package/package.json

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

package/dist/modules/foundation/assets/workflows/speclaw.yml

@@ -1,26 +0,0 @@
-# Consumer template. init/update write this only when the path is missing.
-# Never the untrusted PR trigger. The verify job has no secrets.
-name: ⚖️ speclaw
-on: pull_request
-
-permissions: {}
-
-jobs:
-  verify:
-    name: ⚖️ Verify laws
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      security-events: write
-    steps:
-      - name: 📥 Checkout
-        uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-      - name: ⚖️ Verify
-        uses: esneiderbravo/speclaw@v2
-      - name: 🛡️ Upload SARIF
-        uses: github/codeql-action/upload-sarif@v4
-        if: always()
-        with:
-          sarif_file: speclaw.sarif