@esneiderbravo/speclaw 0.3.13 → 1.0.0

package/dist/modules/foundation/lock.js

@@ -0,0 +1,283 @@
+/**
+ * speclaw.lock — committed digests for rule files (never under `.speclaw/`).
+ * A gitignored lock would be invisible in PR diffs and would not detect
+ * Rules File Backdoor edits. Like package-lock.json / go.sum.
+ */
+// Covers: req~speclaw-lock~1
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pkgName, pkgVersion } from "../../shared/version.js";
+export const LOCKFILE_NAME = "speclaw.lock";
+export const LOCKFILE_VERSION = 1;
+/** Delimited provenance block excluded from digests (self-reference). */
+export const PROVENANCE_START = "<!-- speclaw:begin-provenance";
+export const PROVENANCE_END = "speclaw:end-provenance -->";
+/** Project-relative path of the committed lockfile. */
+export function lockfilePath(projectPath) {
+    return path.join(projectPath, LOCKFILE_NAME);
+}
+/**
+ * Canonical bytes for hashing: LF endings, strip provenance, trim EOL spaces,
+ * ensure a single trailing newline.
+ */
+export function canonicalize(raw) {
+    let text = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    text = stripProvenanceBlock(text);
+    text = text
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/g, ""))
+        .join("\n");
+    if (!text.endsWith("\n"))
+        text += "\n";
+    else if (text.endsWith("\n\n")) {
+        // collapse to exactly one trailing newline
+        text = text.replace(/\n+$/g, "\n");
+    }
+    return text;
+}
+/** Remove speclaw provenance HTML comment blocks. */
+export function stripProvenanceBlock(text) {
+    const re = new RegExp(`${escapeRegExp(PROVENANCE_START)}[\\s\\S]*?${escapeRegExp(PROVENANCE_END)}\\n?`, "g");
+    return text.replace(re, "");
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** sha256 digest with `sha256:` prefix. */
+export function digestOf(canonical) {
+    const hex = crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
+    return `sha256:${hex}`;
+}
+/** Digest raw file text after canonicalization. */
+export function digestText(raw) {
+    return digestOf(canonicalize(raw));
+}
+/** Root hash over sorted path → digest pairs. */
+export function rootDigest(files) {
+    const paths = Object.keys(files).sort();
+    let acc = "";
+    for (const p of paths) {
+        acc += `${p}\0${files[p].digest}\n`;
+    }
+    return digestOf(acc);
+}
+/** Read lockfile or null if missing. Throws on unknown version / parse error. */
+export function readLockfile(projectPath) {
+    const abs = lockfilePath(projectPath);
+    if (!fs.existsSync(abs))
+        return null;
+    const raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    if (typeof raw.lockfileVersion !== "number") {
+        throw new Error("speclaw.lock: missing lockfileVersion");
+    }
+    if (raw.lockfileVersion > LOCKFILE_VERSION) {
+        throw new Error(`speclaw.lock: unsupported lockfileVersion ${raw.lockfileVersion} (max ${LOCKFILE_VERSION})`);
+    }
+    return {
+        lockfileVersion: raw.lockfileVersion,
+        generator: String(raw.generator ?? ""),
+        algorithm: "sha256",
+        root: String(raw.root ?? ""),
+        files: raw.files && typeof raw.files === "object" ? raw.files : {},
+        symlinks: raw.symlinks && typeof raw.symlinks === "object" ? raw.symlinks : {},
+        accepted: Array.isArray(raw.accepted) ? raw.accepted : [],
+    };
+}
+/** Write lockfile with stable JSON formatting. */
+export function writeLockfile(projectPath, lock) {
+    const abs = lockfilePath(projectPath);
+    const body = JSON.stringify(lock, null, 2) + "\n";
+    fs.writeFileSync(abs, body);
+}
+/** Build a fresh lock object from file digests + symlinks. */
+export function buildLock(opts) {
+    const files = { ...opts.files };
+    return {
+        lockfileVersion: LOCKFILE_VERSION,
+        generator: `${pkgName()}@${pkgVersion()}`,
+        algorithm: "sha256",
+        root: rootDigest(files),
+        files,
+        symlinks: { ...(opts.symlinks ?? {}) },
+        accepted: [...(opts.accepted ?? [])],
+    };
+}
+/** Integrity severity policy for a project-relative path. */
+export function integrityPolicy(relPath) {
+    const n = relPath.split("\\").join("/");
+    // `.cursor/rules/` mirrors regenerable `ai-specs/` (gitignored) — lock/CI must
+    // not treat them as strict committed files; scan when present, never pin.
+    if (n === "AGENTS.md" ||
+        n === "CLAUDE.md" ||
+        n.startsWith(".github/instructions/") ||
+        n === ".coderabbit.yaml" ||
+        n === ".claude/rules/speclaw") {
+        return "strict";
+    }
+    if (n === "LAWS.md" || n === "docs/compass.md" || n.startsWith("docs/standards/")) {
+        return "advisory";
+    }
+    return "scan-only";
+}
+/** True when a path is an IDE mirror of regenerable (typically gitignored) content. */
+export function isRegenerableIdeMirror(relPath) {
+    const n = relPath.split("\\").join("/");
+    return (n.startsWith(".cursor/rules/") ||
+        n.startsWith(".cursor/skills/") ||
+        n.startsWith(".cursor/commands/") ||
+        n.startsWith(".claude/skills/") ||
+        n.startsWith(".claude/commands/") ||
+        n.startsWith("ai-specs/"));
+}
+/** Discover candidate paths under the project for locking / scanning. */
+export function discoverIntegrityPaths(projectPath) {
+    const files = [];
+    const symlinks = [];
+    const addFile = (rel) => {
+        const abs = path.join(projectPath, rel);
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile())
+            files.push(rel.split("\\").join("/"));
+    };
+    for (const f of ["AGENTS.md", "CLAUDE.md", "LAWS.md", "docs/compass.md", ".coderabbit.yaml"]) {
+        addFile(f);
+    }
+    walkFiles(path.join(projectPath, "docs", "standards"), projectPath, files, (p) => p.endsWith(".md"));
+    walkFiles(path.join(projectPath, ".cursor", "rules"), projectPath, files, () => true);
+    walkFiles(path.join(projectPath, ".github", "instructions"), projectPath, files, () => true);
+    // Outside-pipeline / skills (scan-only)
+    for (const f of [".clinerules", ".windsurfrules", "BUGBOT.md", ".cursorrules"])
+        addFile(f);
+    walkFiles(path.join(projectPath, "ai-specs", "skills"), projectPath, files, (p) => p.endsWith("SKILL.md") || p.endsWith(".md"));
+    walkFiles(path.join(projectPath, "ai-specs", "agents"), projectPath, files, (p) => p.endsWith(".md"));
+    walkFiles(path.join(projectPath, ".claude", "skills"), projectPath, files, (p) => p.endsWith("SKILL.md") || p.endsWith(".md"));
+    const linkRel = ".claude/rules/speclaw";
+    const linkAbs = path.join(projectPath, linkRel);
+    try {
+        const st = fs.lstatSync(linkAbs);
+        if (st.isSymbolicLink()) {
+            symlinks.push({ path: linkRel, target: fs.readlinkSync(linkAbs) });
+        }
+    }
+    catch {
+        /* missing */
+    }
+    return { files: [...new Set(files)].sort(), symlinks };
+}
+function walkFiles(dir, projectPath, out, pred) {
+    if (!fs.existsSync(dir))
+        return;
+    const stack = [dir];
+    while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(cur, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile()) {
+                const rel = path.relative(projectPath, full).split(path.sep).join("/");
+                if (pred(rel))
+                    out.push(rel);
+            }
+        }
+    }
+}
+/** Markers for the regenerable map block inside `docs/compass.md` (see compass/map.ts). */
+export const COMPASS_MAP_START = "<!-- speclaw:map:start -->";
+export const COMPASS_MAP_END = "<!-- speclaw:map:end -->";
+/**
+ * Strip the regenerable map body between markers so integrity digests stay stable
+ * across `speclaw index` (which rewrites the map in CI before verify).
+ *
+ * @param text - Full docs/compass.md contents.
+ * @returns The same text with an empty map body, or `text` if markers are missing.
+ */
+export function stripCompassMapBlock(text) {
+    const start = text.indexOf(COMPASS_MAP_START);
+    const end = text.indexOf(COMPASS_MAP_END);
+    if (start < 0 || end < 0 || end < start)
+        return text;
+    return text.slice(0, start + COMPASS_MAP_START.length) + "\n" + text.slice(end);
+}
+/**
+ * Path-specific bytes that feed {@link digestText}: speclaw-owned coderabbit
+ * region, regenerable Compass map body stripped, otherwise the file as-is.
+ *
+ * @param relPath - Project-relative path.
+ * @param raw - File contents.
+ * @returns Text to canonicalize and hash for this path.
+ */
+export function prepareIntegrityText(relPath, raw) {
+    const n = relPath.split("\\").join("/");
+    if (n === ".coderabbit.yaml")
+        return extractSpeclawYamlBlock(raw) ?? raw;
+    if (n === "docs/compass.md")
+        return stripCompassMapBlock(raw);
+    return raw;
+}
+/**
+ * Snapshot digests for discovered files with ownership policy.
+ * For `.coderabbit.yaml`, digests only the speclaw delimited block when present.
+ * For `docs/compass.md`, digests with the regenerable map body stripped.
+ */
+export function snapshotLockEntries(projectPath) {
+    const { files: paths, symlinks } = discoverIntegrityPaths(projectPath);
+    const files = {};
+    for (const rel of paths) {
+        const ownership = integrityPolicy(rel);
+        if (ownership === "scan-only")
+            continue; // locked only when previously accepted / explicit
+        const abs = path.join(projectPath, rel);
+        const raw = prepareIntegrityText(rel, fs.readFileSync(abs, "utf8"));
+        files[rel] = { digest: digestText(raw), ownership };
+    }
+    const symlinkMap = {};
+    for (const s of symlinks)
+        symlinkMap[s.path] = { target: s.target };
+    return { files, symlinks: symlinkMap };
+}
+/** Extract a speclaw-marked region from coderabbit yaml if present. */
+export function extractSpeclawYamlBlock(raw) {
+    const m = /# speclaw:begin[\s\S]*?# speclaw:end/.exec(raw);
+    if (m)
+        return m[0];
+    const m2 = /<!-- speclaw:laws:start -->[\s\S]*?<!-- speclaw:laws:end -->/.exec(raw) ??
+        /<!-- speclaw:begin-provenance[\s\S]*?speclaw:end-provenance -->/.exec(raw);
+    return m2 ? m2[0] : null;
+}
+/** Create or refresh speclaw.lock from the current tree. */
+export function refreshLockfile(projectPath) {
+    const prev = (() => {
+        try {
+            return readLockfile(projectPath);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const { files, symlinks } = snapshotLockEntries(projectPath);
+    const lock = buildLock({
+        files,
+        symlinks,
+        accepted: prev?.accepted ?? [],
+    });
+    writeLockfile(projectPath, lock);
+    return lock;
+}
+/** Render a data-only provenance HTML comment (no imperatives). */
+export function provenanceBlock(opts) {
+    const laws = (opts.lawIds ?? []).map((l) => `  law: ${l}`).join("\n");
+    return (`${PROVENANCE_START}\n` +
+        (laws ? laws + "\n" : "") +
+        (opts.source ? `  source: ${opts.source}\n` : "") +
+        `  digest: ${opts.digest}\n` +
+        `  generator: ${pkgName()}@${pkgVersion()}\n` +
+        `speclaw:end-provenance -->\n`);
+}

package/dist/modules/foundation/ownership.js

@@ -1,6 +1,10 @@
 // Which scaffolded files speclaw owns vs the user owns. `speclaw update` uses
 // this split to decide what it may overwrite automatically (managed) and what it
 // must leave to the user's agent via a prompt (personalized).
+//
+// Integrity severity (`strict` / `advisory` / `scan-only` in lock.ts) is a
+// separate axis: CLAUDE.md / AGENTS.md stay PERSONALIZED for update, but are
+// `strict` for `verifyIntegrity` digest mismatches.
 /**
  * Project-relative trees that hold speclaw's workflow machinery. The user is not
  * meant to edit these, so `speclaw update` overwrites them with the current

package/dist/modules/foundation/register-core.js

@@ -1,54 +1,10 @@
 import { z } from "zod";
-import { defineTool, text } from "../../shared/mcp.js";
+import { defineTool, defineAliasTool, text } from "../../shared/mcp.js";
 import { shouldExpose } from "../../shared/exposure.js";
-import { scaffold } from "./scaffold.js";
+import { aliasesEnabled } from "../../shared/tool-catalog.js";
+import { logDeprecatedCall, prefixDeprecated } from "../../shared/deprecation.js";
 import { checkAction } from "./check.js";
-import { verifyLaws } from "./verify.js";
-import { loadPacks } from "../tools/packs.js";
-import { AGENTS, configureAgent } from "../../shared/agents.js";
-import { emptyReport } from "../../shared/install.js";
-/** Human help text for init_project's questionnaire (not embedded in MCP schemas). */
-const profileFieldHelp = {
-    project_name: "Short project name, e.g. the repo name",
-    project_description: "One-line description of what the project does",
-    organization: "Company/team name",
-    stack_summary: "e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'",
-    architecture: "e.g. 'hexagonal architecture with bounded contexts'",
-    test_commands: "Real commands, e.g. 'pytest backend/tests && npm run test'",
-    lint_commands: "Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'",
-    branch_pattern: "e.g. 'feature/<ticket-id>-<slug>'",
-    commit_style: "e.g. 'conventional commits, imperative, English'",
-    custom_laws: "Extra markdown for LAWS.md — project-specific binding rules",
-    compass_hints: "Markdown bullets with real entrypoints for docs/compass.md",
-    base_standards_extra: "Extra cross-cutting rules for base-standards.md",
-    modules_table: "Markdown table of modules/bounded contexts",
-    layering_rules: "Layers and allowed dependencies for architecture.md",
-    backend_layers: "Backend layer table for backend-standards.md",
-    frontend_layers: "Frontend layer table for frontend-standards.md",
-    versioning_rules: "Versioning/release convention for conventions.md",
-    documentation_extra: "Repo-specific docstring notes for documentation.md",
-};
-/** Lean Zod shape for scaffold — no .describe() text (that cost rides in every request). */
-const profileShape = {
-    project_name: z.string(),
-    project_description: z.string().optional(),
-    organization: z.string().optional(),
-    stack_summary: z.string().optional(),
-    architecture: z.string().optional(),
-    test_commands: z.string().optional(),
-    lint_commands: z.string().optional(),
-    branch_pattern: z.string().optional(),
-    commit_style: z.string().optional(),
-    custom_laws: z.string().optional(),
-    compass_hints: z.string().optional(),
-    base_standards_extra: z.string().optional(),
-    modules_table: z.string().optional(),
-    layering_rules: z.string().optional(),
-    backend_layers: z.string().optional(),
-    frontend_layers: z.string().optional(),
-    versioning_rules: z.string().optional(),
-    documentation_extra: z.string().optional(),
-};
+import { handleSpeclawSetup, speclawSetupSchema } from "./setup-tool.js";
 function makeAdd(server, minimal) {
     return (name, description, inputSchema, handler) => {
         if (!shouldExpose(name, minimal))
@@ -57,52 +13,65 @@ function makeAdd(server, minimal) {
     };
 }
 /**
- * Foundation tools except `doctor`. Lives in a separate file so budget/doctor
- * measurement can import it without forming a file-level SCC through
- * `register.ts` → `doctor.ts` → `context-budget.ts`.
+ * Foundation MCP tools (setup + hook check). `doctor` and `law_verify` are CLI-only.
+ * `scaffold` is CLI-only after tool-surface consolidation.
  */
 export function registerFoundationCore(server, opts = {}) {
-    const add = makeAdd(server, Boolean(opts.minimal));
-    add("init_project", "Start here to initialize speclaw: returns the analysis questionnaire and packs.", { projectPath: z.string() }, async () => {
-        const packs = loadPacks();
-        return text({
-            instructions: [
-                "1. Analyze the repository at projectPath and fill in every profile field below with REAL values from the codebase (read package.json / pyproject.toml / CI configs / README — do not invent).",
-                "2. The foundation is a set of GRANULAR standards under docs/standards/ (base, architecture, backend, frontend, testing, conventions, lawbook), bound by LAWS.md and referenced from CLAUDE.md/AGENTS.md. Fill their structured fields from the real repo: modules_table and layering_rules (architecture), backend_layers, frontend_layers, versioning_rules, and any base_standards_extra. Omit a field only when that standard genuinely doesn't apply to this stack.",
-                "3. Suggest packs: add stack packs whose 'detect' hints match dependencies you found; offer the rest. Ask the user which packs to install (the lawbook workflow is always installed).",
-                "4. Infer the working language and the branch/commit/tracker conventions from the repo itself — the language already used in docstrings, commit messages, branch names, and PR/ticket bodies. Do NOT ask the user or assume English; match what the repo does, and set branch_pattern/commit_style accordingly. speclaw does not prescribe a ticket tool — leave tracker linkage to the team's own convention.",
-                "5. Draft any custom_laws (extra binding rules for LAWS.md) from conventions you observed that the standard set doesn't cover.",
-                "6. Call the 'scaffold' tool with { projectPath, profile, packs }.",
-                "7. Follow the nextSteps returned by scaffold: complete the HTML-comment sections still left in docs/standards/*, then run the lawbook_init and compass_index tools (both built into speclaw — no external installs).",
-            ],
-            profileFields: profileFieldHelp,
-            packs,
-        });
-    });
-    add("scaffold", "Write foundation, lawbook workflow, packs, IDE symlinks, and .mcp.json. Never overwrites.", {
-        projectPath: z.string(),
-        profile: z.object(profileShape),
-        packs: z.array(z.string()),
-        agents: z.array(z.string()).optional(),
-    }, async ({ projectPath, profile, packs, agents }) => text(scaffold(projectPath, profile, packs, agents ?? [])));
-    add("configure_agent", "Add one agent's IDE symlinks and MCP config to an already-scaffolded project.", {
-        projectPath: z.string(),
-        agent: z.enum(AGENTS.map((a) => a.id)),
-    }, async ({ projectPath, agent }) => {
-        const report = emptyReport();
-        configureAgent(projectPath, agent, report);
-        return text(report);
-    });
+    const minimal = Boolean(opts.minimal);
+    const add = makeAdd(server, minimal);
+    add("speclaw_setup", "Project setup: init questionnaire, configure agent, list or add packs.", speclawSetupSchema, async (args) => text(handleSpeclawSetup(args)));
     add("speclaw_check", "Invoked by speclaw's hooks to enforce laws — do not call directly.", {
         projectPath: z.string(),
         event: z.enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"]),
         toolName: z.string().optional(),
         payload: z.record(z.unknown()),
     }, async ({ projectPath, event, toolName, payload }) => text(checkAction({ projectPath, event: event, toolName, payload })));
-    add("law_verify", "Verify deterministic deps/graph laws and return violations by file.", {
-        projectPath: z.string(),
-        paths: z.array(z.string()).optional(),
-        engines: z.array(z.enum(["deps", "graph"])).optional(),
-        lawIds: z.array(z.string()).optional(),
-    }, async ({ projectPath, paths, engines, lawIds }) => text(verifyLaws({ projectPath, paths, engines: engines, lawIds })));
+    if (minimal || !aliasesEnabled())
+        return;
+    defineAliasTool(server, {
+        name: "init_project",
+        description: "Deprecated alias for speclaw_setup action init.",
+        inputSchema: { projectPath: z.string() },
+        handler: async ({ projectPath }) => {
+            logDeprecatedCall(projectPath, "init_project");
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath, action: "init" }), null, 2);
+            return text(prefixDeprecated("init_project", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "configure_agent",
+        description: "Deprecated alias for speclaw_setup configure-agent.",
+        inputSchema: {
+            projectPath: z.string(),
+            agent: z.string(),
+        },
+        handler: async ({ projectPath, agent }) => {
+            logDeprecatedCall(projectPath, "configure_agent");
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath, action: "configure-agent", agent }), null, 2);
+            return text(prefixDeprecated("configure_agent", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "list_packs",
+        description: "Deprecated alias for speclaw_setup list-packs.",
+        inputSchema: {},
+        handler: async () => {
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath: ".", action: "list-packs" }), null, 2);
+            return text(prefixDeprecated("list_packs", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "add_pack",
+        description: "Deprecated alias for speclaw_setup add-pack.",
+        inputSchema: {
+            projectPath: z.string(),
+            pack: z.string(),
+            vars: z.record(z.string()).optional(),
+        },
+        handler: async ({ projectPath, pack, vars }) => {
+            logDeprecatedCall(projectPath, "add_pack");
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath, action: "add-pack", pack, vars }), null, 2);
+            return text(prefixDeprecated("add_pack", body));
+        },
+    });
 }

package/dist/modules/foundation/register.js

@@ -1,26 +1,6 @@
-import { z } from "zod";
-import { defineTool, text } from "../../shared/mcp.js";
-import { shouldExpose } from "../../shared/exposure.js";
 import { registerFoundationCore } from "./register-core.js";
 export { registerFoundationCore } from "./register-core.js";
-const DOCTOR_DESCRIPTION = "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).";
-/** Register foundation MCP tools (core + doctor). */
+/** Register foundation MCP tools. Doctor is CLI-only (`speclaw doctor`). */
 export function registerFoundation(server, opts = {}) {
     registerFoundationCore(server, opts);
-    const minimal = Boolean(opts.minimal);
-    if (!shouldExpose("doctor", minimal))
-        return;
-    const inputSchema = { projectPath: z.string() };
-    const handler = async ({ projectPath }) => {
-        // Lazy load: register.ts must stay out of the context-budget → doctor SCC.
-        const { doctor } = await import("./doctor.js");
-        const report = await doctor(projectPath, { redact: true });
-        return text(report);
-    };
-    defineTool(server, {
-        name: "doctor",
-        description: DOCTOR_DESCRIPTION,
-        inputSchema,
-        handler,
-    });
 }

package/dist/modules/foundation/scaffold.js

@@ -10,6 +10,9 @@ import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
 import { mergeSeedLaws, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
+import { compileLaws } from "./compile-laws.js";
+import { refreshLockfile } from "./lock.js";
+import { refreshOwnersIfConfigured } from "../team/owners.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
 // provide default to empty so a bare `scaffold` never leaves a raw {{tag}}.
@@ -150,12 +153,34 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // configured. The seam is the manifest: check-dispatcher enforces `path` laws;
     // executable-laws will extend the same manifest with more backends.
     const lawManifest = ensureLawManifest(projectPath, report);
+    try {
+        compileLaws({ projectPath, agents, writeManifest: false });
+    }
+    catch {
+        // Compilation must not fail scaffold; `speclaw laws compile` surfaces errors.
+    }
+    // Covers: req~lock-refresh-update~1
+    try {
+        refreshLockfile(projectPath);
+    }
+    catch {
+        // Lock refresh must not fail scaffold; `speclaw laws lock` surfaces errors.
+    }
     ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {
         baselines: managedOpts.baselines,
         backup: managedOpts.backup,
         record,
     });
+    // Refresh CODEOWNERS managed block when the project declared team.owners —
+    // never invent owners when the key is absent.
+    try {
+        refreshOwnersIfConfigured(projectPath);
+    }
+    catch (err) {
+        // Surface as a soft note — invalid tokens should not abort scaffold/update.
+        report.skipped.push(`owners refresh skipped: ${err.message}`);
+    }
     // Record what was installed so `speclaw update` can re-apply these packs and
     // gate feature migrations by version, plus the managed-file baselines that let
     // a later update tell user edits from stale files.