@esneiderbravo/speclaw 1.0.0 → 1.0.1

package/README.md

@@ -238,7 +238,10 @@ regenerate `ai-specs/` locally. Optional **`team.owners`** in
 **Enforcement artifacts.** For agents that support hooks, speclaw merges its law
 hooks into that agent's settings **by identity** — it never touches hooks you
 added yourself. The compiled law manifest lives in `.speclaw/laws-manifest.json`
-(gitignored), and a context-coverage log feeds `speclaw doctor`.
+(gitignored) and is **adapted to the target tree** on `init`/`update` — speclaw's
+own architecture laws are seeded only when those paths exist, and the cycle law
+follows `apps/*/src`, `packages/*/src`, or `src/` rather than copying
+`src/modules/**` from this package. A context-coverage log feeds `speclaw doctor`.
 
 <br/>
 

package/dist/cli/commands/update.js

@@ -173,6 +173,17 @@ const MIGRATIONS = [
             "`npx @esneiderbravo/speclaw@latest init`. CI consumers use `esneiderbravo/speclaw@v1`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "1.0.1",
+        describe: "Seed laws match the target repository layout",
+        agentPrompt: "- After this update, speclaw rewrites `.speclaw/laws-manifest.json` from the " +
+            "target tree: dogfood laws (compass/foundation, ATTRIBUTION.md, local-first, " +
+            "protect-templates, shared-stays-inner) are dropped when those paths do not exist; " +
+            "the cycle law is scoped to detected source roots (`apps/*/src`, `packages/*/src`, " +
+            "`src/`, `lib/`) excluding test files, and considers import edges only. Run " +
+            "`speclaw laws compile` if agent rule files look stale, then `speclaw index`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/modules/foundation/assets/laws/laws-manifest.json

@@ -21,7 +21,8 @@
       "prose": "Justify any new dependency in the PR: it must not break 'runs offline with no API keys'.",
       "verification": { "kind": "path" },
       "enforcement": "feedback",
-      "source": { "file": "LAWS.md" }
+      "source": { "file": "LAWS.md" },
+      "requires": ["src/modules/compass", "src/modules/foundation"]
     },
     {
       "id": "law~protect-templates~1",
@@ -32,7 +33,8 @@
       "prose": "Assets under src/modules/*/assets/** are product output — keep the {{placeholder}} and speclaw-init contracts intact, and let the build copy them (never hand-copy into dist/).",
       "verification": { "kind": "path" },
       "enforcement": "feedback",
-      "source": { "file": "LAWS.md" }
+      "source": { "file": "LAWS.md" },
+      "requires": ["src/modules/foundation/assets"]
     },
     {
       "id": "law~honest-attribution~1",
@@ -43,7 +45,8 @@
       "prose": "Keep ATTRIBUTION.md accurate as the Compass and Lawbook modules evolve.",
       "verification": { "kind": "path" },
       "enforcement": "feedback",
-      "source": { "file": "LAWS.md" }
+      "source": { "file": "LAWS.md" },
+      "requires": ["ATTRIBUTION.md"]
     },
     {
       "id": "law~shared-stays-inner~1",
@@ -62,7 +65,8 @@
         }
       },
       "enforcement": "gate",
-      "source": { "file": "docs/standards/architecture.md" }
+      "source": { "file": "docs/standards/architecture.md" },
+      "requires": ["src/shared", "src/modules", "src/cli"]
     },
     {
       "id": "law~compass-does-not-import-foundation~1",
@@ -81,7 +85,8 @@
         }
       },
       "enforcement": "gate",
-      "source": { "file": "docs/standards/architecture.md" }
+      "source": { "file": "docs/standards/architecture.md" },
+      "requires": ["src/modules/compass", "src/modules/foundation"]
     },
     {
       "id": "law~no-module-cycles~1",
@@ -90,9 +95,13 @@
       "severity": "error",
       "scope": ["src/modules/**"],
       "prose": "There are no circular dependencies between modules.",
-      "verification": { "kind": "graph", "rule": { "circular": true } },
+      "verification": {
+        "kind": "graph",
+        "rule": { "circular": true, "edgeKinds": ["import"] }
+      },
       "enforcement": "gate",
-      "source": { "file": "docs/standards/architecture.md" }
+      "source": { "file": "docs/standards/architecture.md" },
+      "adaptScope": "source-roots"
     }
   ]
 }

package/dist/modules/foundation/compile-laws.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { globError, isActiveLaw, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
+import { globError, isActiveLaw, readLawManifest, seedManifestFor, mergeSeedLaws, writeLawManifest, } from "./laws.js";
 import { parseLawsFromStandards } from "./laws-parse.js";
 import { agentsmdDialect, claudeRulesDialect, coderabbitDialect, copilotDialect, cursorMdcDialect, patchDelimited, } from "./dialects/index.js";
 import { detectConfiguredAgents } from "../../shared/agents.js";
@@ -17,6 +17,7 @@ const DIALECTS = [
  * Throws if standards declare duplicate ids.
  */
 export function mergeLawSources(projectPath) {
+    // Covers: req~adapt-seed-to-repo~1
     const parsed = parseLawsFromStandards(projectPath);
     if (parsed.duplicates.size > 0) {
         const detail = [...parsed.duplicates.entries()]
@@ -24,18 +25,15 @@ export function mergeLawSources(projectPath) {
             .join("; ");
         throw new Error(`duplicate law id(s) in docs/standards: ${detail}`);
     }
+    const disk = readLawManifest(projectPath);
+    const base = disk ? mergeSeedLaws(disk, projectPath).manifest : seedManifestFor(projectPath);
     const byId = new Map();
-    for (const law of seedManifest().laws)
+    for (const law of base.laws)
         byId.set(law.id, law);
     for (const law of parsed.laws) {
         if (!byId.has(law.id))
             byId.set(law.id, law);
     }
-    const disk = readLawManifest(projectPath);
-    if (disk) {
-        for (const law of disk.laws)
-            byId.set(law.id, law);
-    }
     return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
 }
 function validateScopes(laws) {

package/dist/modules/foundation/graph.js

@@ -1,6 +1,7 @@
+import { matchesScope } from "./laws.js";
 import { underPaths } from "./verify-model.js";
-/** Build the cross-file dependency graph, restricted to `paths` when given. */
-function buildGraph(db, paths, edgeKinds) {
+/** Build the cross-file dependency graph, restricted to `paths` and `scope`. */
+function buildGraph(db, paths, edgeKinds, scope) {
     const kindFilter = edgeKinds && edgeKinds.length > 0
         ? ` AND e.kind IN (${edgeKinds.map(() => "?").join(", ")})`
         : "";
@@ -16,6 +17,8 @@ function buildGraph(db, paths, edgeKinds) {
     for (const { src, dst } of rows) {
         if (!underPaths(src, paths) || !underPaths(dst, paths))
             continue;
+        if (!matchesScope(scope, src) || !matchesScope(scope, dst))
+            continue;
         const list = adj.get(src);
         if (list)
             list.push(dst);
@@ -205,8 +208,9 @@ function reachableFindings(law, rule, adj) {
  *   resolved graph, so a graph law never reports an unknown here).
  */
 export function runGraphLaw(db, law, paths) {
+    // Covers: req~graph-honours-scope~1
     const rule = law.verification.rule;
-    const adj = buildGraph(db, paths, rule.edgeKinds);
+    const adj = buildGraph(db, paths, rule.edgeKinds, law.scope);
     const findings = [];
     const wantReachable = rule.reachable === true && rule.from != null && rule.to != null;
     const wantCircular = rule.circular === true || (!rule.circular && !wantReachable);

package/dist/modules/foundation/laws.js

@@ -1,13 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { assetsDir } from "../../shared/paths.js";
-// The machine-readable law model and its manifest. This is the contract seam
-// (`.speclaw/laws-manifest.json`) between where laws come from and how they are
-// enforced: check-dispatcher owns the schema and the single `path` verification
-// backend; executable-laws extends the same model with `ast`/`deps`/`process`
-// backends by filling in more `verification.kind` cases — it never rewrites it.
-const ASSETS = assetsDir(import.meta.url);
+import { adaptedLaws, catalogLaws, mergeAdaptedSeed } from "./seed-laws.js";
 const depsRuleSchema = z.object({
     name: z.string().optional(),
     from: z.string(),
@@ -144,46 +138,50 @@ export function writeLawManifest(projectPath, manifest) {
     fs.writeFileSync(p, JSON.stringify(validated, null, 2) + "\n");
 }
 /**
- * The starter law manifest shipped with speclaw, seeded from a speclaw-style
- * project's own `path`-verifiable Project-specific laws. It is the source the
- * MVP compiles into `.speclaw/laws-manifest.json`; once executable-laws lands,
- * laws are authored in `docs/standards/*` and compiled here instead. Laws whose
- * scope does not match a given repo are simply inert there.
+ * The full shipped catalog as persistable laws (adapter metadata stripped).
+ * Prefer {@link seedManifestFor} at init/verify time so consumer repos do not
+ * inherit speclaw-dogfood paths that do not exist there.
  *
- * @returns The validated seed manifest read from the module's assets.
- * @throws If the seed asset is missing or fails validation.
+ * @returns The validated catalog.
+ * @throws If the catalog fails the law schema.
  */
 export function seedManifest() {
-    const raw = JSON.parse(fs.readFileSync(path.join(ASSETS, "laws", "laws-manifest.json"), "utf8"));
-    return manifestSchema.parse(raw);
+    return manifestSchema.parse({ version: 1, laws: catalogLaws() });
+}
+/**
+ * Catalog laws adapted to `projectPath`: only laws whose `requires` paths exist,
+ * with the cycle law scoped to detected source roots.
+ *
+ * @param projectPath - Project root whose tree is inspected.
+ * @returns The validated adapted manifest.
+ */
+export function seedManifestFor(projectPath) {
+    // Covers: req~adapt-seed-to-repo~1
+    return manifestSchema.parse({ version: 1, laws: adaptedLaws(projectPath) });
 }
 /**
  * The manifest the batch verifier should use: the project's file when present,
- * otherwise the shipped seed (so a clean CI clone does not silently pass).
+ * otherwise the **adapted** seed (so a clean CI clone does not silently pass,
+ * and does not evaluate inapplicable dogfood laws).
  *
  * @param projectPath - Project root to read from.
  */
 export function loadManifestForVerify(projectPath) {
-    return readLawManifest(projectPath) ?? seedManifest();
+    return readLawManifest(projectPath) ?? seedManifestFor(projectPath);
 }
 /**
- * Append shipped seed laws whose `id` is not already in `existing`. Existing
- * entries are never overwritten — a curated law keeps its prose, scope, and
- * enforcement across `update`.
+ * Merge an on-disk manifest with the adapted catalog. Existing curated entries
+ * (title or prose differs from the catalog) are never overwritten. Unmodified
+ * shipped laws whose required paths are absent are removed; unmodified cycle
+ * laws are replaced with the adapted scope.
  *
  * @param existing - The project's current manifest.
- * @returns The merged manifest and the ids that were added.
+ * @param projectPath - Project root used to adapt the catalog.
+ * @returns The merged manifest and the ids that were added or removed.
  */
-export function mergeSeedLaws(existing) {
-    const seed = seedManifest();
-    const have = new Set(existing.laws.map((l) => l.id));
-    const extra = seed.laws.filter((l) => !have.has(l.id));
-    if (extra.length === 0)
-        return { manifest: existing, added: [] };
-    return {
-        manifest: { ...existing, laws: [...existing.laws, ...extra] },
-        added: extra.map((l) => l.id),
-    };
+export function mergeSeedLaws(existing, projectPath) {
+    const { manifest, added, removed } = mergeAdaptedSeed({ version: existing.version, laws: existing.laws }, projectPath);
+    return { manifest: manifestSchema.parse(manifest), added, removed };
 }
 // ─── Glob matching (the `path` backend) ──────────────────────────────────────
 /**

package/dist/modules/foundation/scaffold.js

@@ -8,7 +8,7 @@ import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
 import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
-import { mergeSeedLaws, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
+import { mergeSeedLaws, readLawManifest, seedManifestFor, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
 import { compileLaws } from "./compile-laws.js";
 import { refreshLockfile } from "./lock.js";
@@ -28,19 +28,22 @@ const FOUNDATION_DEFAULTS = {
     documentation_extra: "",
 };
 /**
- * Ensure the project has a law manifest. Missing → seed. Present → append any
- * shipped seed law whose `id` is absent (never overwrite a curated entry).
+ * Ensure the project has a law manifest. Missing → adapted seed for this tree.
+ * Present → merge the adapted catalog (never overwrite a curated entry; prune
+ * unmodified dogfood laws whose required paths are absent).
  */
 function ensureLawManifest(projectPath, report) {
     const existing = readLawManifest(projectPath);
     if (!existing) {
-        const seed = seedManifest();
+        const seed = seedManifestFor(projectPath);
         writeLawManifest(projectPath, seed);
         report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
         return seed;
     }
-    const { manifest, added } = mergeSeedLaws(existing);
-    if (added.length > 0) {
+    const { manifest, added, removed } = mergeSeedLaws(existing, projectPath);
+    if (added.length > 0 ||
+        removed.length > 0 ||
+        JSON.stringify(manifest.laws) !== JSON.stringify(existing.laws)) {
         writeLawManifest(projectPath, manifest);
         report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
     }

package/dist/modules/foundation/seed-laws.js

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assetsDir } from "../../shared/paths.js";
+// Catalog adapter: the shipped JSON is speclaw's own architecture plus a few
+// portable laws. Consumer repos get only what their tree can actually host —
+// never compass/foundation/ATTRIBUTION rules copied from this package.
+//
+// Types are declared here (not imported from laws.ts) so the adapter and the
+// schema do not form a file-level import cycle.
+const ASSETS = assetsDir(import.meta.url);
+const CATALOG_PATH = path.join(ASSETS, "laws", "laws-manifest.json");
+/** Globs that drop test doubles from the cycle-law graph. */
+export const TEST_SCOPE_EXCLUSIONS = [
+    "!**/*.{spec,test}.{ts,tsx,js,jsx}",
+    "!**/test/**",
+    "!**/__tests__/**",
+];
+let cachedCatalog = null;
+/**
+ * Read the shipped law catalog (including adapter metadata). Cached for the
+ * process; tests that mutate the asset are not a supported path.
+ *
+ * @returns The parsed catalog.
+ * @throws If the asset is missing or not an object with a `laws` array.
+ */
+export function readLawCatalog() {
+    if (cachedCatalog)
+        return cachedCatalog;
+    const raw = JSON.parse(fs.readFileSync(CATALOG_PATH, "utf8"));
+    if (!raw || !Array.isArray(raw.laws)) {
+        throw new Error(`invalid law catalog at ${CATALOG_PATH}`);
+    }
+    cachedCatalog = raw;
+    return raw;
+}
+/** Drop adapter-only fields so the result is a persistable law. */
+export function asLaw(entry) {
+    const law = {
+        id: entry.id,
+        title: entry.title,
+        severity: entry.severity,
+        scope: [...entry.scope],
+        prose: entry.prose,
+        verification: structuredClone(entry.verification),
+        enforcement: entry.enforcement,
+        source: { ...entry.source },
+    };
+    if (entry.rationale !== undefined)
+        law.rationale = entry.rationale;
+    if (entry.status !== undefined)
+        law.status = entry.status;
+    return law;
+}
+/**
+ * Whether `req` names an existing file, directory, or glob under `projectPath`.
+ *
+ * @param projectPath - Project root.
+ * @param req - Relative path or glob (`*` / `**` in a segment).
+ */
+export function pathRequirementExists(projectPath, req) {
+    const trimmed = req.replace(/^!/, "").replace(/\/\*\*$/, "");
+    return globExists(projectPath, trimmed.split("/").filter(Boolean));
+}
+function globExists(dir, parts) {
+    if (parts.length === 0)
+        return fs.existsSync(dir);
+    if (!fs.existsSync(dir))
+        return false;
+    const head = parts[0];
+    const rest = parts.slice(1);
+    if (head === "**") {
+        if (globExists(dir, rest))
+            return true;
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isDirectory())
+            return false;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith("."))
+                continue;
+            if (globExists(path.join(dir, name), parts))
+                return true;
+        }
+        return false;
+    }
+    if (head === "*") {
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isDirectory())
+            return false;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith("."))
+                continue;
+            if (globExists(path.join(dir, name), rest))
+                return true;
+        }
+        return false;
+    }
+    return globExists(path.join(dir, head), rest);
+}
+function childSrcExists(projectPath, parent) {
+    const dir = path.join(projectPath, parent);
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    for (const name of fs.readdirSync(dir)) {
+        if (name.startsWith("."))
+            continue;
+        try {
+            if (fs.statSync(path.join(dir, name, "src")).isDirectory())
+                return true;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return false;
+}
+/**
+ * Source-root globs inferred from a repository layout.
+ *
+ * @param projectPath - Project root.
+ * @returns Globs covering app/package `src` trees, plus top-level `src/` or `lib/`, when they exist.
+ */
+export function detectSourceRootGlobs(projectPath) {
+    const out = [];
+    if (childSrcExists(projectPath, "apps"))
+        out.push("apps/*/src/**");
+    if (childSrcExists(projectPath, "packages"))
+        out.push("packages/*/src/**");
+    if (pathRequirementExists(projectPath, "src"))
+        out.push("src/**");
+    if (pathRequirementExists(projectPath, "lib"))
+        out.push("lib/**");
+    return out;
+}
+function positivesSatisfied(projectPath, scope) {
+    const positives = scope.filter((g) => !g.startsWith("!"));
+    if (positives.length === 0)
+        return true;
+    return positives.some((g) => pathRequirementExists(projectPath, g));
+}
+function withTestExclusions(scope) {
+    const have = new Set(scope);
+    const out = [...scope];
+    for (const g of TEST_SCOPE_EXCLUSIONS) {
+        if (!have.has(g))
+            out.push(g);
+    }
+    return out;
+}
+function adaptCycleLaw(projectPath, entry) {
+    const law = asLaw(entry);
+    const catalogHits = positivesSatisfied(projectPath, entry.scope);
+    const roots = catalogHits
+        ? entry.scope.filter((g) => !g.startsWith("!"))
+        : detectSourceRootGlobs(projectPath);
+    if (roots.length === 0)
+        return null;
+    law.scope = withTestExclusions(roots);
+    if (law.verification.kind === "graph") {
+        law.verification = {
+            kind: "graph",
+            rule: { ...(law.verification.rule ?? {}), circular: true, edgeKinds: ["import"] },
+        };
+    }
+    return law;
+}
+function isApplicable(projectPath, entry) {
+    const reqs = entry.requires ?? [];
+    return reqs.every((r) => pathRequirementExists(projectPath, r));
+}
+/**
+ * Catalog laws stripped of adapter metadata — the full shipped set, unfiltered.
+ *
+ * @returns Persistable laws in catalog order.
+ */
+export function catalogLaws() {
+    return readLawCatalog().laws.map(asLaw);
+}
+/**
+ * Laws from the catalog that apply to `projectPath`, with cycle-law scope
+ * rewritten to the repo's real source roots when needed.
+ *
+ * @param projectPath - Project root whose tree is inspected.
+ * @returns Persistable laws; adapter fields omitted.
+ */
+export function adaptedLaws(projectPath) {
+    // Covers: req~adapt-seed-to-repo~1
+    const out = [];
+    for (const entry of readLawCatalog().laws) {
+        if (!isApplicable(projectPath, entry))
+            continue;
+        if (entry.adaptScope === "source-roots") {
+            const adapted = adaptCycleLaw(projectPath, entry);
+            if (adapted)
+                out.push(adapted);
+            continue;
+        }
+        out.push(asLaw(entry));
+    }
+    return out;
+}
+/** True when `existing` is still the shipped catalog text (title + prose). */
+export function isUnmodifiedCatalogLaw(existing, catalog) {
+    return existing.title === catalog.title && existing.prose === catalog.prose;
+}
+/**
+ * Merge an on-disk manifest with the adapted catalog: append applicable ids,
+ * rewrite unmodified cycle-law scope, drop unmodified inapplicable dogfood.
+ *
+ * @param existing - The project's current manifest.
+ * @param projectPath - Project root used to adapt the catalog.
+ * @returns The merged manifest and the ids that were added or removed.
+ */
+export function mergeAdaptedSeed(existing, projectPath) {
+    const catalog = readLawCatalog();
+    const byId = new Map(catalog.laws.map((l) => [l.id, l]));
+    const adapted = adaptedLaws(projectPath);
+    const adaptedById = new Map(adapted.map((l) => [l.id, l]));
+    const added = [];
+    const removed = [];
+    const result = [];
+    const seen = new Set();
+    for (const law of existing.laws) {
+        const cat = byId.get(law.id);
+        if (!cat || !isUnmodifiedCatalogLaw(law, cat)) {
+            result.push(law);
+            seen.add(law.id);
+            continue;
+        }
+        const next = adaptedById.get(law.id);
+        if (next) {
+            result.push(next);
+            seen.add(law.id);
+        }
+        else {
+            removed.push(law.id);
+        }
+    }
+    for (const law of adapted) {
+        if (seen.has(law.id))
+            continue;
+        result.push(law);
+        added.push(law.id);
+        seen.add(law.id);
+    }
+    return { manifest: { ...existing, laws: result }, added, removed };
+}

package/dist/modules/foundation/verify.js

@@ -17,8 +17,8 @@ export { underPaths } from "./verify-model.js";
  *
  * When the project has no index, every selected batch law is reported as
  * `skipped` with reason `no-index` (never silently passed). When the gitignored
- * manifest file is missing, the shipped seed is used so a clean clone does not
- * report an empty pass. Each evaluated law lands in exactly one of `passed` /
+ * manifest file is missing, the adapted seed is used so a clean clone does not
+ * report an empty pass or inherit inapplicable dogfood laws. Each evaluated law lands in exactly one of `passed` /
  * `failed` / `unknown`: it fails when the engine produced a finding, is
  * `unknown` when it produced none but rests on unresolved edges (which could
  * hide a violation), and passes otherwise.

package/package.json

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