create-ailk 0.19.0 → 0.20.0

package/dist/update.js

@@ -0,0 +1,504 @@
+/**
+ * `create-ailk update [<target-dir>]` — bring template fixes into a site's
+ * already-copied `apps/web`, `apps/api` and `apps/mcp` code (#8522).
+ *
+ * Reads `.ailk-template-files.json` (`template-record.ts`) to tell an
+ * untouched copy from an owner's edit. An untouched file whose template
+ * copy changed is overwritten. An edited file whose template copy changed
+ * is three-way merged (`lib/merge-three-way.ts`) against its recorded
+ * version's copy — read from this package's own `templates/` when that is
+ * the running version, else re-materialised from the published npm tarball
+ * (`lib/fetch-template-snapshot.ts`) — and the running version's copy. A
+ * conflict leaves the file untouched and is listed under "Needs review". A
+ * site with no record gets one backfilled from `.ailk-site-manifest.json`'s
+ * `patternVersion` on its first run, then updates normally. Every refusal
+ * throws before the first write.
+ *
+ * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
+ * `adopt.ts` / `add-route.ts` split.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
+import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.js";
+import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
+import { mergeThreeWay } from "./lib/merge-three-way.js";
+import { ParseError } from "./parse-args.js";
+import { SITE_ROSTER_PATH } from "./site-roster.js";
+import { excludedRoutePaths } from "./surfaces.js";
+import { TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
+import { TopologyError, isSpokeExcluded, readSpokeShape, spokeExclusions, } from "./topology.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export class UpdateRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "UpdateRefusedError";
+    }
+}
+/** `buildScaffoldMarkers`, with `CREATE_AILK_VERSION` set to the version being rendered (D3). */
+function markersForVersion(projectName, version) {
+    return { ...buildScaffoldMarkers(projectName), CREATE_AILK_VERSION: version };
+}
+const VERSION_TUPLE = /^(\d+)\.(\d+)\.(\d+)/;
+/** `true` iff semver `a` is strictly older than semver `b` (major, minor, patch, numerically). */
+function versionOlder(a, b) {
+    const ma = VERSION_TUPLE.exec(a);
+    const mb = VERSION_TUPLE.exec(b);
+    if (ma === null || mb === null)
+        return false;
+    for (let i = 1; i <= 3; i++) {
+        const na = Number(ma[i]);
+        const nb = Number(mb[i]);
+        if (na !== nb)
+            return na < nb;
+    }
+    return false;
+}
+/** Every file under `templatesDir`'s three app trees, raw bytes keyed by destination path (D3). */
+function walkLocalTemplates(templatesDir) {
+    const out = new Map();
+    for (const app of ["web", "api", "mcp"]) {
+        const root = join(templatesDir, "apps", app);
+        if (!existsSync(root))
+            continue;
+        const stack = [root];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                break;
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const abs = join(dir, entry.name);
+                if (entry.isSymbolicLink())
+                    continue;
+                if (entry.isDirectory()) {
+                    stack.push(abs);
+                    continue;
+                }
+                const rel = `apps/${app}/${relativeToRoot(root, abs)}`;
+                const dest = templateDestination(rel);
+                if (dest === undefined)
+                    continue;
+                out.set(dest, readFileSync(abs));
+            }
+        }
+    }
+    return out;
+}
+/** `abs`'s path relative to `root` (both under the same app directory), `/`-separated. */
+function relativeToRoot(root, abs) {
+    return abs.slice(root.length + 1).split(sep).join("/");
+}
+/** The running or an old template version's recordable files, rendered (D3). */
+function renderSnapshot(raw, projectName, version) {
+    const markers = markersForVersion(projectName, version);
+    const out = new Map();
+    for (const [dest, bytes] of raw) {
+        if (!isRecordable(dest))
+            continue;
+        out.set(dest, renderTemplateFile(bytes, dest, {}, markers));
+    }
+    return out;
+}
+/** The root `package.json` `name`, falling back to the target's basename (D8). */
+function backfillProjectName(targetDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name.length > 0)
+            return pkg.name;
+    }
+    catch {
+        // no readable root package.json — fall back below.
+    }
+    return targetDir.split(sep).filter(Boolean).pop() ?? targetDir;
+}
+/** The highest directory or file missing on disk on `destRel`'s chain below `apps/<app>/` (D4 rule iii). */
+function highestMissingAncestor(destRel, targetDir) {
+    const segments = destRel.split("/");
+    let current = segments.slice(0, 2).join("/");
+    for (let i = 2; i < segments.length; i++) {
+        current = `${current}/${segments[i]}`;
+        if (!existsSync(join(targetDir, ...current.split("/"))))
+            return current;
+    }
+    return undefined;
+}
+/** Whether `prefix` (or something under it) is one of `knownPaths` (D4 rule iii). */
+function containsKnownPath(prefix, knownPaths) {
+    for (const path of knownPaths) {
+        if (path === prefix || path.startsWith(`${prefix}/`))
+            return true;
+    }
+    return false;
+}
+export async function updateSite(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const version = opts.version;
+    // ── Load the record, or determine the backfill (D8) ──────────────────
+    const recordPath = join(targetDir, TEMPLATE_RECORD_PATH);
+    let record;
+    let backfillPatternVersion;
+    if (existsSync(recordPath)) {
+        try {
+            record = parseTemplateRecord(readFileSync(recordPath, "utf8"));
+        }
+        catch (err) {
+            throw new UpdateRefusedError(err.message);
+        }
+    }
+    else {
+        const manifestPath = join(targetDir, SITE_ROSTER_PATH);
+        let patternVersion;
+        if (existsSync(manifestPath)) {
+            try {
+                const doc = JSON.parse(readFileSync(manifestPath, "utf8"));
+                const value = doc["patternVersion"];
+                if (typeof value === "string" && value.length > 0)
+                    patternVersion = value;
+            }
+            catch {
+                // an unreadable manifest is the same refusal as a missing one, below.
+            }
+        }
+        if (patternVersion === undefined) {
+            throw new UpdateRefusedError(`no ${TEMPLATE_RECORD_PATH} and no "patternVersion" in ${SITE_ROSTER_PATH} to rebuild it from; run \`create-ailk adopt\` first`);
+        }
+        backfillPatternVersion = patternVersion;
+        record = { schema: 1, projectName: backfillProjectName(targetDir), files: {} };
+    }
+    // ── Refuse a downgrade before any fetch (D8) ──────────────────────────
+    const recordedVersions = backfillPatternVersion !== undefined
+        ? [backfillPatternVersion]
+        : [...new Set(Object.values(record.files).map((row) => row.version))];
+    for (const recorded of recordedVersions) {
+        if (versionOlder(version, recorded)) {
+            throw new UpdateRefusedError(`create-ailk ${version} is older than ${recorded}, already recorded in ${TEMPLATE_RECORD_PATH} — use a newer create-ailk to run update`);
+        }
+    }
+    // ── The site's scope: gated-off surfaces and spoke exclusions (D4 i/ii) ─
+    const archPath = join(targetDir, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new UpdateRefusedError(`${targetDir} has no architecture.yaml; run \`create-ailk adopt\` or \`--sync-architecture\` first`);
+    }
+    let header;
+    try {
+        header = readArchitectureHeader(readFileSync(archPath, "utf8"));
+    }
+    catch (err) {
+        if (err instanceof AddModuleRefusedError) {
+            throw new UpdateRefusedError(err.message);
+        }
+        throw err;
+    }
+    let spoke;
+    try {
+        spoke = readSpokeShape(targetDir);
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new UpdateRefusedError(err.message);
+        throw err;
+    }
+    const excludedRoutes = excludedRoutePaths(header.surfaces);
+    const spokeExclusionList = spoke !== undefined ? spokeExclusions(opts.templatesDir, spoke) : undefined;
+    const outOfScope = (destRel) => {
+        if (isExcluded(destRel, excludedRoutes))
+            return true;
+        if (spoke !== undefined && spokeExclusionList !== undefined) {
+            return isSpokeExcluded(destRel, { ...spoke, exclusions: spokeExclusionList });
+        }
+        return false;
+    };
+    // ── The running version's rendered copies ─────────────────────────────
+    const runningRaw = walkLocalTemplates(opts.templatesDir);
+    const newMap = renderSnapshot(runningRaw, record.projectName, version);
+    // ── A cache of rendered copies by version, fetched at most once each ──
+    const versionCache = new Map();
+    async function loadVersionMap(v) {
+        const cached = versionCache.get(v);
+        if (cached !== undefined)
+            return cached;
+        let result;
+        if (v === version) {
+            result = newMap;
+        }
+        else {
+            try {
+                const raw = await fetchTemplateSnapshot({
+                    version: v,
+                    ...(opts.registryUrl !== undefined ? { registryUrl: opts.registryUrl } : {}),
+                    ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+                });
+                result = renderSnapshot(raw, record.projectName, v);
+            }
+            catch (err) {
+                result = { error: err.message };
+            }
+        }
+        versionCache.set(v, result);
+        return result;
+    }
+    // ── The backfill: fetch the old base and build the synthetic record ──
+    let knownSnapshotPaths;
+    if (backfillPatternVersion !== undefined) {
+        const base = await loadVersionMap(backfillPatternVersion);
+        if ("error" in base) {
+            throw new UpdateRefusedError(`backfill: the ${backfillPatternVersion} template could not be read: ${base.error}`);
+        }
+        knownSnapshotPaths = new Set(base.keys());
+        const files = {};
+        for (const [path, bytes] of [...base.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            if (outOfScope(path))
+                continue;
+            if (!existsSync(join(targetDir, ...path.split("/"))))
+                continue;
+            files[path] = { sha256: sha256Hex(bytes), version: backfillPatternVersion };
+        }
+        record = { schema: 1, projectName: record.projectName, files };
+    }
+    // ── Every recorded row (D4) ────────────────────────────────────────────
+    const updated = [];
+    const merged = [];
+    const added = [];
+    const removed = [];
+    const current = [];
+    const review = [];
+    const skipped = [];
+    const nextFiles = { ...record.files };
+    const writes = [];
+    const deletes = [];
+    for (const path of Object.keys(record.files).sort()) {
+        const rec = record.files[path];
+        if (outOfScope(path)) {
+            skipped.push({ path, reason: "outside this site's scope" });
+            continue;
+        }
+        const abs = join(targetDir, ...path.split("/"));
+        if (!existsSync(abs)) {
+            skipped.push({ path, reason: "deleted locally" });
+            continue;
+        }
+        const diskBytes = readFileSync(abs);
+        const diskHash = sha256Hex(diskBytes);
+        const edited = diskHash !== rec.sha256;
+        const newBytes = newMap.get(path);
+        if (!edited) {
+            if (newBytes === undefined) {
+                deletes.push(path);
+                delete nextFiles[path];
+                removed.push(path);
+                continue;
+            }
+            const newHash = sha256Hex(newBytes);
+            if (newHash === rec.sha256)
+                continue; // no template change
+            writes.push({ path, bytes: Buffer.from(newBytes) });
+            nextFiles[path] = { sha256: newHash, version };
+            updated.push(path);
+            continue;
+        }
+        // Edited.
+        if (newBytes === undefined) {
+            review.push({ path, reason: `edited here, removed from the template in ${version}` });
+            continue;
+        }
+        const newHash = sha256Hex(newBytes);
+        if (newHash === rec.sha256)
+            continue; // template unchanged for this file
+        if (diskHash === newHash) {
+            nextFiles[path] = { sha256: newHash, version };
+            current.push(path);
+            continue;
+        }
+        // Template changed, and the edit does not already match it: three-way merge.
+        const base = await loadVersionMap(rec.version);
+        if ("error" in base) {
+            review.push({
+                path,
+                reason: `edited here, and the ${rec.version} template could not be read: ${base.error}`,
+            });
+            continue;
+        }
+        const baseBytes = base.get(path);
+        if (baseBytes === undefined) {
+            review.push({
+                path,
+                reason: `edited here, and the ${rec.version} template could not be read: not present in that version's snapshot`,
+            });
+            continue;
+        }
+        if (sha256Hex(baseBytes) !== rec.sha256) {
+            review.push({
+                path,
+                reason: `edited here, and the ${rec.version} template copy does not match the record`,
+            });
+            continue;
+        }
+        if (!isTextFile(path)) {
+            review.push({ path, reason: "edited here; binary files are not merged" });
+            continue;
+        }
+        const mergeResult = mergeThreeWay({
+            ours: diskBytes.toString("utf8"),
+            base: Buffer.from(baseBytes).toString("utf8"),
+            theirs: Buffer.from(newBytes).toString("utf8"),
+            oursLabel: "yours",
+            baseLabel: `template ${rec.version}`,
+            theirsLabel: `template ${version}`,
+        });
+        if (mergeResult.status === "merged") {
+            const mergedBytes = Buffer.from(mergeResult.text, "utf8");
+            writes.push({ path, bytes: mergedBytes });
+            // D1/D5 — the row keeps the TEMPLATE's hash, never the merged disk
+            // bytes': that is what lets the next update still see the owner's
+            // edit (the disk bytes keep differing from the recorded hash) and
+            // merge against the right base, instead of reading a now-current
+            // file as "edited" against its own past self forever.
+            nextFiles[path] = { sha256: newHash, version };
+            merged.push(path);
+        }
+        else if (mergeResult.status === "conflict") {
+            review.push({
+                path,
+                reason: `conflicts with the template change ${rec.version} → ${version}`,
+            });
+        }
+        else {
+            review.push({ path, reason: `the three-way merge could not run: ${mergeResult.reason}` });
+        }
+    }
+    // ── Every recordable path the running template has that this record does not (D4) ──
+    const knownPaths = new Set([...Object.keys(record.files), ...(knownSnapshotPaths ?? [])]);
+    for (const path of [...newMap.keys()].sort()) {
+        if (Object.prototype.hasOwnProperty.call(record.files, path))
+            continue;
+        const abs = join(targetDir, ...path.split("/"));
+        const newBytes = newMap.get(path);
+        if (existsSync(abs)) {
+            const diskBytes = readFileSync(abs);
+            if (sha256Hex(diskBytes) !== sha256Hex(newBytes)) {
+                skipped.push({ path, reason: "exists, not in the record" });
+            }
+            continue;
+        }
+        if (outOfScope(path))
+            continue; // rule i/ii
+        const highest = highestMissingAncestor(path, targetDir);
+        if (highest !== undefined && containsKnownPath(highest, knownPaths))
+            continue; // rule iii
+        writes.push({ path, bytes: Buffer.from(newBytes) });
+        nextFiles[path] = { sha256: sha256Hex(newBytes), version };
+        added.push(path);
+    }
+    // ── Apply: writes and removals, then the record (D4 Order) ───────────
+    for (const write of writes) {
+        const abs = join(targetDir, ...write.path.split("/"));
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, write.bytes);
+    }
+    for (const path of deletes) {
+        rmSync(join(targetDir, ...path.split("/")));
+    }
+    const backfilled = backfillPatternVersion !== undefined
+        ? { version: backfillPatternVersion, files: Object.keys(record.files).length }
+        : undefined;
+    const recordChanged = backfilled !== undefined ||
+        updated.length > 0 ||
+        merged.length > 0 ||
+        added.length > 0 ||
+        removed.length > 0 ||
+        current.length > 0;
+    if (recordChanged) {
+        writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
+    }
+    return {
+        targetDir,
+        version,
+        updated,
+        merged,
+        added,
+        removed,
+        current,
+        review,
+        skipped,
+        ...(backfilled !== undefined ? { backfilled } : {}),
+    };
+}
+/** The printed report (D9): one section per non-empty list, in order. */
+export function formatUpdateReport(result) {
+    const lines = [`[create-ailk] update → ${result.targetDir}`];
+    if (result.backfilled !== undefined) {
+        lines.push(`Record written from ${result.backfilled.version}: ${result.backfilled.files} files`);
+    }
+    const sections = [
+        ["Updated", result.updated],
+        ["Merged", result.merged],
+        ["Added", result.added],
+        ["Removed", result.removed],
+        ["Already current", result.current],
+    ];
+    for (const [label, paths] of sections) {
+        if (paths.length === 0)
+            continue;
+        lines.push(`${label} (${paths.length}):`);
+        lines.push(...paths.map((path) => `  ${path}`));
+    }
+    if (result.review.length > 0) {
+        lines.push(`Needs review (${result.review.length}):`);
+        lines.push(...result.review.map((row) => `  ${row.path} — ${row.reason}`));
+    }
+    if (result.skipped.length > 0) {
+        lines.push(`Skipped (${result.skipped.length}):`);
+        lines.push(...result.skipped.map((row) => `  ${row.path} — ${row.reason}`));
+    }
+    const nothingHappened = result.backfilled === undefined &&
+        result.updated.length === 0 &&
+        result.merged.length === 0 &&
+        result.added.length === 0 &&
+        result.removed.length === 0 &&
+        result.current.length === 0 &&
+        result.review.length === 0 &&
+        result.skipped.length === 0;
+    if (nothingHappened) {
+        return `[create-ailk] Already up to date (create-ailk ${result.version}).\n`;
+    }
+    return lines.join("\n") + "\n";
+}
+export const UPDATE_HELP = `create-ailk update — bring template fixes into a site's copied app code.
+
+Usage:
+  create-ailk update [<target-dir>]
+
+Arguments:
+  <target-dir>             The existing site. Defaults to the current dir.
+
+Options:
+  --help, -h               Print this message.
+
+Reads .ailk-template-files.json (written beside .ailk-site-manifest.json by
+every template scaffold) to tell an untouched copy from an edit. An
+untouched apps/web, apps/api or apps/mcp file whose template copy changed is
+overwritten. An edited file whose template copy also changed is three-way
+merged with \`git\` (git must be on PATH); a conflict leaves the file alone
+and is listed under "Needs review" — nothing else in the run is held back.
+A site with no record gets one on its first run, from the version its
+.ailk-site-manifest.json already records. Commit before running, and review
+the diff after.
+`;
+/** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
+export function parseUpdateArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`update takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return { target, help: parsed.values.help === true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.39.0",
-    "@working-theory/templates": "0.39.0"
+    "@working-theory/schema": "0.41.0",
+    "@working-theory/templates": "0.41.0"
   },
   "repository": {
     "type": "git",

package/templates/.claude/cloudparity-repo-hooks.json

@@ -0,0 +1,9 @@
+{
+  "hooks": [
+    {
+      "event": "PostToolUse",
+      "matcher": "Edit|Write",
+      "command": "bash .claude/hooks/architecture-check.sh"
+    }
+  ]
+}

package/templates/.claude/hooks/architecture-check.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# PostToolUse (Edit|Write): run the architecture boundary lint after an edit.
+# Exits 0 until dependencies are installed, and 2 on a violation so Claude
+# reads the finding. Registered in .claude/settings.json and declared in
+# .claude/cloudparity-repo-hooks.json; keep the two in step.
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+[ -x node_modules/.bin/tsx ] || exit 0
+pnpm --silent architecture >&2 || exit 2

package/templates/.claude/rules/loop-contract.md

@@ -0,0 +1,129 @@
+# Per-Issue Workflow
+
+The contract every change goes through. One issue in, one PR out, no
+scope creep.
+
+This is the single-developer flow. If you're working solo on this
+project, this is what every meaningful change looks like.
+
+## Pick
+
+Open an issue or claim one from your backlog. The issue must have:
+
+- A `## Acceptance Criteria` section listing observable, verifiable
+  outcomes.
+- A `## Scope` section listing the files or path globs you intend
+  to touch.
+
+If either is missing, write them before you start — not as a
+formality but because the rest of the workflow depends on them.
+
+## Read
+
+Before any edits:
+
+1. The issue body in full — every acceptance bullet, scope path,
+   and dependency note.
+2. `CLAUDE.md` — the operating manual you're already reading.
+3. The files inside `## Scope` — confirm they exist and your mental
+   model matches what's actually there.
+
+If anything is missing or the issue is infeasible as written, stop
+and refine the issue before coding.
+
+## Branch
+
+```bash
+git checkout main
+git pull --ff-only origin main
+git checkout -b issue-<N>-<kebab-slug>
+```
+
+Use a 3–6 word slug from the issue title. Branch names show up in
+your PR list — make them scannable.
+
+## TDD: RED → GREEN
+
+For functional acceptance criteria:
+
+1. Write tests from the criteria first. They should fail (RED) —
+   your implementation doesn't exist yet.
+2. Implement the smallest change that makes the tests pass (GREEN).
+3. Refactor if the implementation is messy. Tests stay green
+   throughout.
+
+Skip TDD only for: pure documentation, prompt-only changes, or
+single-line fixes already covered by an existing test.
+
+## Verify
+
+Before commit AND before push:
+
+```bash
+pnpm preflight
+```
+
+This runs `architecture` + `claude-md:check` + `type-check` + `lint` +
+`build`. It runs no tests, so it is not a stand-in for CI: run
+`pnpm test` as well whenever your change has tests, and read CI's own
+result on the PR.
+
+For PRs touching specific surfaces:
+
+- `database/` schema changes — also run `pnpm db:migrate` locally if
+  you added a migration.
+
+## Commit + PR
+
+- Commit message format: `feat(area): description (#N)`. Include
+  the issue number when one exists.
+- Multiple commits on the branch are fine; squash-merge collapses
+  them.
+- PR title: same as the commit message format.
+- PR body must include:
+  - **Summary** — what the PR does, in plain language.
+  - **Scope** — paths actually touched (a subset of the issue's
+    scope).
+  - **Verification** — checklist of what you ran, with
+    `[x] pnpm preflight` ticked.
+  - `Closes #N` line — required for issue PRs; triggers GitHub's
+    auto-close on merge.
+
+## After PR open
+
+1. Wait for CI. If it goes red, diagnose and fix; do not merge red.
+2. Wait for any automated reviewers (Bugbot, code review bots) to
+   return. Address every finding — either fix it or write a short
+   reply explaining why it's not actionable.
+3. Merge once CI is green and reviews are reconciled.
+
+## After merge
+
+1. Close the issue if the PR didn't auto-close it.
+2. Delete the local and remote branch.
+3. Pick the next issue.
+
+## Mid-task scope expansion
+
+If you realize mid-task that the issue's `## Scope` was insufficient:
+
+1. Stop before writing outside scope.
+2. Update the PR description to add the new path with a one-line
+   reason.
+3. Continue.
+
+That short pause is the entire point — it forces you to acknowledge
+that the work has grown, instead of letting it grow silently.
+
+## When to escalate
+
+Stop and surface the question rather than make the call alone if:
+
+- An architecture invariant in `.claude/rules/architecture.md` would
+  have to bend.
+- A change to a published `@working-theory/*` package is needed (file the
+  issue upstream; don't fork locally).
+- The acceptance criteria contradict each other or the existing code.
+- You'd be deleting or moving more than five files at once.
+
+A short clarifying question beats a long detour down the wrong path.

package/templates/.claude/settings.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cd \"$CLAUDE_PROJECT_DIR\" && [ -x node_modules/.bin/tsx ] || exit 0; pnpm --silent architecture >&2 || exit 2"
+            "command": "bash .claude/hooks/architecture-check.sh"
           }
         ]
       }
@@ -23,5 +23,6 @@
   },
   "enabledPlugins": {
     "ailk@working-theory": true
-  }
+  },
+  "x-cloudparity-managed-keys": ["hooks"]
 }