create-agent-rig 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,143 @@ the generator.
 Versions are published to npm as [`create-agent-rig`](https://www.npmjs.com/package/create-agent-rig);
 `npx github:serhii-baksheiev/create-agent-rig` keeps working for either path.
 
+## 0.3.2
+
+Numbered as a patch by the owner's call; the content below is additive, so
+nothing that shipped in 0.3.1 changed shape.
+
+A generated project gains two review gates it did not have — one before the work
+starts, one over the prose that instructs it — and three more queue-hygiene
+checks.
+
+**Upgrading an existing rig: `init` alone is not enough, and here is exactly
+why.** `create-agent-rig init` installs files that are not there and **keeps
+every file that is** — `--force` replaces `CLAUDE.md` and nothing else
+(`packages/cli/src/commands/init.ts`). Re-running it on a 0.3.1 rig therefore
+delivers the two new files, `.claude/agents/prose-reviewer.md` and
+`.claude/skills/check-premises/SKILL.md`, and **none of their wiring**: the
+skill arrives with nothing calling it, and the agent arrives with `pr-ship`
+never launching it. Six files below changed rather than appeared, and `init`
+will not touch them:
+
+```
+.claude/agents/code-reviewer.md          # the sixth blocking item
+.claude/skills/loop/SKILL.md             # calls check-premises, and §3/§6/§8
+.claude/skills/pr-ship/SKILL.md          # fans out prose-reviewer, passes the item
+.claude/scripts/queue/core.mjs           # the three hygiene checks + Ticket.body
+.claude/scripts/detect-missed-gate.mjs   # sees a rulebook outside the repo root
+.claude/hooks/gate-stop-dod.mjs          # judges the tree it is in
+```
+
+Delete those six and re-run `init`, or copy them across by hand. A proper
+upgrade command is queued, not shipped — and until it exists this note tells you
+the manual steps rather than an easy sentence that leaves half the release
+inert. That failure mode is the whole subject of 0.3.1, immediately below.
+
+### Added
+
+- **`check-premises` skill** — a queue item is a _claim about the code_, written
+  by someone who was not reading the code at the time, and nothing downstream
+  re-checks it: the failing test is written against the item, the implementation
+  against the test, and the reviewer compares the diff to the item. A false
+  premise therefore produces work that is correct, tested, reviewed and useless.
+  The skill runs between taking the item and the Red step, is read-only by
+  frontmatter so it cannot start implementing, and returns `PREMISES HOLD` /
+  `PREMISE FALSE` / `UNVERIFIABLE`. Its two boundaries are the point: a false
+  load-bearing premise is **stop and report**, never a silent re-aim of the task,
+  and only load-bearing claims are checked — an audit is what makes the step
+  expensive enough to skip. The `loop` skill calls it, and treats `PREMISE FALSE`
+  as a per-task escalation rather than a licence to rewrite the item.
+- **`prose-reviewer` agent** — a fourth gate, read-only. In this layer the prose
+  _is_ the implementation: a rule that overstates its own enforcement fails
+  exactly like broken code, silently and in the direction of false confidence. It
+  blocks on five things — enforcement claimed beyond the mechanism, a dead
+  reference, two rules that contradict each other, stated limits gone stale in
+  either direction, and domain that must not travel (a vendor name, a host path,
+  a tracker key or a credential in a layer meant to be neutral) — and its
+  boundary comes before its checklist: it is **not
+  a literary editor**, and prose that is merely clumsy is not a finding. Wired
+  into the `pr-ship` fan-out and named in both maps.
+- **A sixth blocking item for `code-reviewer`** — a change that contradicts the
+  queue item it claims to implement. The instruction is to report the mismatch,
+  never to decide which side "must have been meant": a reviewer who reconciles
+  the two silently turns a visible mismatch into an invisible one. Where no item
+  was supplied, it says so rather than reconstructing one from the PR body —
+  which is evidence `autonomy.md` refuses by name. `pr-ship` now passes the item.
+- **Three queue-hygiene checks** — a parent that says it was split up and is
+  still open; a dependency line naming a blocker no link carries (worse than a
+  stale label: selection reads the item as unblocked); and a document link that
+  is broken on its face. The neutral `Ticket` shape gains a **nullable `body`**
+  so these live in one pure function instead of once per adapter — and `null`
+  means "this adapter cannot answer", never "checked, found nothing".
+
+### Fixed
+
+- **The baseline commit of a generated project could land in the caller's
+  repository.** Git hands its hooks an absolute `GIT_DIR`, and the CLI spawned
+  git with the environment intact — so `git init` re-initialised the caller's
+  repo, `add -A` staged its tree, and the commit landed on whatever branch it had
+  checked out, while the generated project got no `.git` at all. A redirected
+  `git init` can also flip the caller's repository to `core.bare=true`. The path
+  that triggers it is a pre-commit hook running a suite that generates projects —
+  which is what made the `worktree-task` skill unusable. Every git call site now
+  strips the variables that locate a repository, including the shipped
+  `gate-stop-dod` hook (which asked git whether _which_ tree was clean) and
+  `preflight`.
+- **The Tier-2 gate sweep could not see a rulebook outside the repository root.**
+  `detect-missed-gate` exempts the rulebook from its inert-file rule so a merge
+  rewriting the autonomy tiers cannot pass as "just prose" — but the exemption
+  was anchored at `CLAUDE.md` / `.claude/`. Any project that vendors, templates
+  or nests a rig keeps its rulebook elsewhere, and every `.md` there was dropped
+  before the elevated-path test ran. It is now recognised wherever it sits, and
+  the sweep's verdict vocabulary knows the words `pr-ship` actually emits.
+
+### Deferred, and on what condition
+
+Two pieces of the source brief did **not** travel, because shipping an unproven
+gate into other people's projects is worse than not having one:
+
+- the queue-closing discipline for blocked dependents — enters when it has been
+  merged and used in the project it came from;
+- the clarify-gate (`C-0…C-2`) — enters once that gate has fired at least once
+  anywhere. Until then there is nothing to copy but an intention.
+
+## 0.3.1
+
+`create-agent-rig init` shipped a rig that looked installed and enforced
+nothing. Everything below is that one failure, in its four parts — a repo
+`init`ed with 0.3.0 should be re-run with this version (`--force` to replace the
+CLAUDE.md it wrote).
+
+### Fixed
+
+- **The hooks are wired.** `init` laid the hook files down and stopped there: no
+  `.claude/settings.json` meant `guard-bash`, `block-no-verify`, `gate-stop-dod`
+  and `inject-rules` were never called, while the installed `CLAUDE.md` claimed
+  they were enforced at the tool layer. The wiring is now _derived_ from the
+  shipped settings, so it names exactly the hooks that travelled — never one that
+  did not. Where the repo already has a `settings.json`, `init` keeps it and
+  prints the entries to merge rather than failing silently.
+- **The kill switch works.** `init` copied templates byte-for-byte, leaving
+  `__PROJECT_NAME__` in six places — including `stop-flag.mjs`, so the brake
+  looked for `~/.claude/__PROJECT_NAME__-loop-STOP` while the operator, following
+  the instructions in the same install, created `~/.claude/<repo>-loop-STOP`. It
+  never fired, and never said so.
+- **The installed `CLAUDE.md` describes the repo it landed in.** It used to be
+  the generated monorepo's map — `packages/core/`, `apps/web/`, links to an
+  `architecture.md` and two guards that `init` deliberately does not install. It
+  is now its own document: what was installed, what was not, and that the
+  architecture rules are yours to write.
+- **The elevated-path block names paths that exist.** It seeded
+  `packages/db/src/` into repos that have no such directory, so the Tier-2 gate
+  sweep reported "clean" while looking at nothing.
+
+### Added
+
+- A template test that fails if anything `init` installs references a `.claude`
+  file `init` does not install — the drift that produced three of the four
+  findings above, now mechanical.
+
 ## 0.3.0
 
 The factory extraction: a scaffolded project now arrives with a working

package/README.md

@@ -22,7 +22,15 @@ npx create-agent-rig init --dry-run  # print the plan, write nothing
 ```
 
 `init` drops in the autonomy tiers, stop rules, workflow, and the enforcement
-hooks, and refuses to clobber an existing `CLAUDE.md`.
+hooks — **wired**, in a `.claude/settings.json` that names exactly the hooks it
+installed — plus a `CLAUDE.md` that describes that rig rather than the generated
+monorepo. It refuses to clobber an existing `CLAUDE.md`; if the repo already has
+a `.claude/settings.json`, it keeps it and prints the entries to merge, because a
+hook nothing calls is not enforcement.
+
+Two things it deliberately leaves to you, and says so in the installed
+`CLAUDE.md`: the Definition-of-Done gate has no `dod-checks.json` (it cannot know
+your commands), and the elevated-path list names only what every repo has.
 
 ## What you get
 
@@ -75,8 +83,8 @@ never labels**, and **the agent never files its own work items**.
 
 Around all of it: **autonomy tiers** (what an agent does alone / after review /
 never), **stop rules** (three strikes, flaky ≠ retry, session staleness),
-**subagent gates** (`test-writer`, `code-reviewer`, `security-scanner`, and
-`cdk-diff-reviewer` on the AWS target), **skills** (`pr-ship` pre-merge gate;
+**subagent gates** (`test-writer`, `code-reviewer`, `security-scanner`,
+`prose-reviewer`, and `cdk-diff-reviewer` on the AWS target), **skills** (`pr-ship` pre-merge gate;
 `loop` queue driver; `worktree-task` for concurrent sessions; `new-invariant`, a
 generator for the invariant→hook→test pattern; `post-deploy-verify` and
 `ro-debug` on the AWS target), and a one-page `CLAUDE.md` map a fresh session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",

package/packages/cli/dist/commands/create.js

@@ -5,6 +5,7 @@ import { promisify } from 'node:util';
 import { copyTree, listTree } from '../lib/copy-tree.js';
 import { ALLOWED_OVERWRITES, detectCollisions } from '../lib/composition.js';
 import { substituteContent, substituteFileName } from '../lib/substitute.js';
+import { gitEnv } from '../lib/git-env.js';
 import { DEFAULT_TARGET, TARGETS, TARGET_NAMES } from '../lib/targets.js';
 import { agentOsStackDir, agentOsUniversalDir, skeletonDir } from '../templates.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
@@ -72,9 +73,10 @@ async function initGitBaseline(projectDir) {
     // .git/objects/pack after we return — a non-deterministic tail that races any
     // caller cleaning up the directory, and pointless work on a one-commit repo.
     const quiet = ['-c', 'gc.auto=0', '-c', 'maintenance.auto=false'];
+    const where = { cwd: projectDir, env: gitEnv() };
     try {
-        await run('git', [...quiet, 'init', '--quiet'], { cwd: projectDir });
-        await run('git', [...quiet, 'add', '-A'], { cwd: projectDir });
+        await run('git', [...quiet, 'init', '--quiet'], where);
+        await run('git', [...quiet, 'add', '-A'], where);
         // Explicit identity: the baseline must commit even where git has no
         // global user configured (fresh machines, CI). --no-verify here shields
         // the baseline from the USER'S global hooks only — the generated
@@ -90,7 +92,7 @@ async function initGitBaseline(projectDir) {
             '--no-verify',
             '-m',
             'Pristine template (create-agent-rig)',
-        ], { cwd: projectDir });
+        ], where);
     }
     catch {
         // git missing or unusable — generation never fails on this.

package/packages/cli/dist/commands/init.js

@@ -1,37 +1,93 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { agentOsUniversalDir } from '../templates.js';
+import { settingsForInstalledHooks } from '../lib/init-settings.js';
+import { substituteContent } from '../lib/substitute.js';
+import { agentOsInitDir, agentOsUniversalDir } from '../templates.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class InitError extends Error {
 }
+const SETTINGS = '.claude/settings.json';
 async function loadManifest() {
     const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
     return JSON.parse(raw);
 }
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The name this repo is known by inside the rig. It ends up in a *filename* —
+ * `~/.claude/<name>-loop-STOP`, the kill switch — so it is reduced to
+ * characters an operator can type into a shell without quoting.
+ */
+export function projectNameFor(repoDir) {
+    const base = path.basename(path.resolve(repoDir));
+    const slug = base
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+    return slug === '' ? 'project' : slug;
+}
 /**
  * `init` installs only the PROCESS layer (hooks-and-reach brief §3/§4): rules
  * that assume nothing about the codebase shape. Architecture rules reference
  * `packages/core` and friends — installing them into an arbitrary repo would
  * describe a structure that does not exist, which is worse than no rule.
  *
- * CLAUDE.md is the meta file we bring, but never over an existing one.
+ * It also installs two things the process manifest does not name, because both
+ * are meaningless in the generated shape and load-bearing here:
+ *
+ * - `CLAUDE.md` — the map, taken from the init override layer, which describes
+ *   the rig this command installs rather than the generated monorepo;
+ * - `.claude/settings.json` — the wiring, derived from the shipped settings so
+ *   it names exactly the hooks that travelled.
  */
-async function processFiles(manifest) {
-    // the process layer, plus CLAUDE.md as the map (guarded separately)
-    return [...manifest.process, 'CLAUDE.md'];
-}
-async function exists(p) {
-    try {
-        await access(p);
-        return true;
+export async function initManifest() {
+    const manifest = await loadManifest();
+    const universal = agentOsUniversalDir();
+    const override = agentOsInitDir();
+    const files = [];
+    for (const rel of [...manifest.process, 'CLAUDE.md']) {
+        const overridden = path.join(override, rel);
+        files.push({
+            rel,
+            source: (await exists(overridden)) ? overridden : path.join(universal, rel),
+        });
     }
-    catch {
-        return false;
+    files.push({ rel: SETTINGS, source: null });
+    return files;
+}
+/**
+ * Exactly the bytes `init` would write, keyed by destination path — the single
+ * source the plan, the install and the template tests all read.
+ *
+ * Every file the process layer carries is text (asserted by a template test),
+ * so substitution can be applied unconditionally: an unsubstituted
+ * `__PROJECT_NAME__` in `stop-flag.mjs` is a kill switch that silently never
+ * fires.
+ */
+export async function initFileContents(repoDir) {
+    const projectName = projectNameFor(repoDir);
+    const ctx = { projectName, projectScope: projectName, region: '' };
+    const files = await initManifest();
+    const contents = new Map();
+    for (const { rel, source } of files) {
+        if (source === null)
+            continue;
+        contents.set(rel, substituteContent(await readFile(source, 'utf8'), ctx));
     }
+    const installedHooks = new Set(files.map((f) => f.rel).filter((rel) => rel.startsWith('.claude/hooks/')));
+    const shipped = JSON.parse(await readFile(path.join(agentOsUniversalDir(), SETTINGS), 'utf8'));
+    contents.set(SETTINGS, `${JSON.stringify(settingsForInstalledHooks(shipped, installedHooks), null, 2)}\n`);
+    return contents;
 }
 export async function planInit(repoDir) {
-    const manifest = await loadManifest();
-    const files = await processFiles(manifest);
+    const files = (await initManifest()).map((f) => f.rel);
     const conflicts = [];
     for (const rel of files) {
         if (await exists(path.join(repoDir, rel)))
@@ -40,9 +96,7 @@ export async function planInit(repoDir) {
     return { files: files.map((p) => ({ path: p })), conflicts };
 }
 export async function initProject(repoDir, options) {
-    const manifest = await loadManifest();
-    const files = await processFiles(manifest);
-    const universal = agentOsUniversalDir();
+    const files = (await initManifest()).map((f) => f.rel);
     // Refuse to clobber an existing CLAUDE.md unless forced — init edits
     // someone's working repository (brief §4, non-negotiable).
     if (!options.force && files.includes('CLAUDE.md')) {
@@ -51,6 +105,7 @@ export async function initProject(repoDir, options) {
                 'Merge the agent-os map in by hand, or re-run with --force to replace it.');
         }
     }
+    const contents = await initFileContents(repoDir);
     const written = [];
     const skipped = [];
     const plannedCount = files.length;
@@ -65,7 +120,7 @@ export async function initProject(repoDir, options) {
         if (options.dryRun)
             continue;
         await mkdir(path.dirname(dest), { recursive: true });
-        await writeFile(dest, await readFile(path.join(universal, rel)));
+        await writeFile(dest, contents.get(rel) ?? '');
         written.push(rel);
     }
     return { written, skipped, plannedCount };

package/packages/cli/dist/index.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
-import { InitError, initProject, planInit } from './commands/init.js';
+import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
 import { makePalette } from './lib/colors.js';
 import { promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
@@ -65,6 +65,16 @@ async function runInit(rawArgs) {
     process.stdout.write(`\nInstalled ${result.written.length} files` +
         (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
         '.\n');
+    // The one kept file that silently disables everything else: without this
+    // wiring the hooks sit on disk and are never called, while the rules claim
+    // they are enforced. Say so loudly, and hand over the exact entries.
+    if (result.skipped.includes('.claude/settings.json')) {
+        const wiring = (await initFileContents(cwd)).get('.claude/settings.json') ?? '';
+        process.stdout.write(`\n!  .claude/settings.json already exists — it was kept, so the rig's hooks are NOT wired.\n` +
+            `   Until you merge these entries into it, nothing enforces the rules:\n\n` +
+            wiring.replace(/^/gm, '   ') +
+            '\n');
+    }
     return 0;
 }
 async function main() {

package/packages/cli/dist/lib/git-env.js

@@ -0,0 +1,48 @@
+/**
+ * Variables that point git at a repository other than the one at `cwd`.
+ *
+ * Inherited, they silently redirect a git command into the CALLER's repository:
+ * `git init` re-initialises it, `add -A` stages the caller's tree, and a commit
+ * lands on whatever branch the caller has checked out — while the directory the
+ * command was aimed at ends up with no `.git` at all.
+ *
+ * This is not hypothetical. Git sets `GIT_DIR` and `GIT_INDEX_FILE` — absolute —
+ * for the hooks it runs, so a `git commit` from a linked worktree whose
+ * pre-commit runs a suite that shells out to git writes one junk commit per
+ * invocation onto the branch being committed. Observed twice in this repo, from
+ * two different call sites, which is why this lives in one module: a second copy
+ * of this list is a second chance to fix one and forget the other.
+ *
+ * The list is explicit rather than a `GIT_*` sweep on purpose — `GIT_SSH_COMMAND`
+ * or `GIT_TERMINAL_PROMPT` are the caller's environment and none of our business.
+ * Only repository *location* is stripped.
+ *
+ * 🔴 Limit, stated: this strips repository *location*, not every way git can be
+ * redirected. The config-injection family (`GIT_CONFIG_COUNT`/`_KEY_n`/`_VALUE_n`,
+ * `GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_GLOBAL`/`_SYSTEM`) can carry `core.worktree`
+ * or `core.bare` and is deliberately out of scope: git never sets those for the
+ * hooks that cause this problem, and stripping a caller's deliberate config
+ * overrides would be its own surprise.
+ *
+ * 🔴 And it protects exactly the call sites that use it. It does not make git
+ * safe to call from a hook-invoked process in general, and a spawn that forgets
+ * `gitEnv()` is unprotected — nothing in this module can detect that. The sweep
+ * in `test/template/git-env.test.ts` is what watches for it.
+ */
+export const GIT_LOCATION_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+];
+/** The caller's environment minus anything that re-points git at another repo. */
+export function gitEnv(env = process.env) {
+    const sanitised = { ...env };
+    for (const key of GIT_LOCATION_VARS)
+        delete sanitised[key];
+    return sanitised;
+}

package/packages/cli/dist/lib/init-settings.js

@@ -0,0 +1,52 @@
+/**
+ * `init` installs the PROCESS layer only — a subset of the hooks the generated
+ * shape gets. The wiring it writes has to match that subset exactly:
+ *
+ * - wiring a hook file that was not installed makes every matching tool call
+ *   fail on a missing module;
+ * - wiring nothing at all is worse and quieter — the hooks sit on disk, the
+ *   rules claim they are enforced, and nothing ever calls them.
+ *
+ * So the wiring is *derived* from the shipped settings.json rather than
+ * maintained as a second copy: add a process hook and wire it once, upstream,
+ * and init picks it up.
+ */
+/** Matches the hook file a wired command runs, e.g. `.claude/hooks/guard-bash.mjs`. */
+const HOOK_REFERENCE = /\.claude\/hooks\/[A-Za-z0-9._-]+\.mjs/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** An entry survives unless it names a hook file that is not installed. */
+function keepEntry(entry, installed) {
+    if (!isRecord(entry) || typeof entry.command !== 'string')
+        return true;
+    const referenced = HOOK_REFERENCE.exec(entry.command);
+    return referenced === null || installed.has(referenced[0]);
+}
+/** A group survives only with at least one entry left — never as an empty shell. */
+function keepGroup(group, installed) {
+    if (!isRecord(group) || !Array.isArray(group.hooks))
+        return group;
+    const hooks = group.hooks.filter((entry) => keepEntry(entry, installed));
+    return hooks.length === 0 ? null : { ...group, hooks };
+}
+/**
+ * The shipped settings, narrowed to the hooks actually installed. Shapes this
+ * function does not understand are passed through untouched — it filters, it
+ * never rewrites.
+ */
+export function settingsForInstalledHooks(settings, installed) {
+    if (!isRecord(settings) || !isRecord(settings.hooks))
+        return settings;
+    const events = {};
+    for (const [event, groups] of Object.entries(settings.hooks)) {
+        if (!Array.isArray(groups)) {
+            events[event] = groups;
+            continue;
+        }
+        const kept = groups.map((group) => keepGroup(group, installed)).filter((g) => g !== null);
+        if (kept.length > 0)
+            events[event] = kept;
+    }
+    return { ...settings, hooks: events };
+}

package/packages/cli/dist/lib/targets.js

@@ -10,5 +10,19 @@ export const TARGETS = {
     },
 };
 export const TARGET_NAMES = Object.keys(TARGETS);
-/** Zero options at the personal stage: one implicit target (PLAN.md §6). */
+/**
+ * The pre-selected entry in the interactive menu, and the API-level default.
+ *
+ * 🔴 **Not the fallback for a non-interactive run.** A run with no TTY and no
+ * `--target` is *refused* (`index.ts`) — never prompt into a pipe, and never
+ * guess a whole project shape for a script that did not say. This constant is
+ * what `Enter`, an out-of-range number or an unrecognised name resolve to at the
+ * prompt (`prompts.ts`), plus what `createProject` uses when called as a library
+ * with no target.
+ *
+ * The comment this replaces said "one implicit target", which was stale from
+ * when there was one. Its first correction claimed the CLI defaults silently in
+ * CI — the opposite of what it does, in the file a maintainer would open to
+ * check exactly that.
+ */
 export const DEFAULT_TARGET = 'aws-serverless';

package/packages/cli/dist/templates.js

@@ -19,3 +19,11 @@ export function agentOsUniversalDir() {
 export function agentOsStackDir(stack) {
     return path.join(templatesRoot(), 'agent-os', 'stack', stack);
 }
+/**
+ * Overrides `init` applies on top of the universal layer. A file here replaces
+ * its universal namesake when the rig is installed into an existing repo whose
+ * shape the generator knows nothing about. `create` never reads this directory.
+ */
+export function agentOsInitDir() {
+    return path.join(templatesRoot(), 'agent-os', 'init');
+}

package/scripts/prepare.mjs

@@ -5,25 +5,62 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const root = path.dirname(fileURLToPath(import.meta.url)) + '/..';
 
-// 1. Wire up the pre-commit hook when working inside the git checkout.
-if (existsSync(path.join(root, '.git'))) {
-  spawnSync('git', ['config', 'core.hooksPath', '.husky'], { cwd: root, stdio: 'inherit' });
+/**
+ * The environment `git config` runs under, minus anything that could point it
+ * at another repository's config file.
+ *
+ * This script runs from `pnpm install`, and a pre-commit hook can reach an
+ * install — a hook-started process inherits an absolute `GIT_DIR`, and
+ * `core.hooksPath` would then be written into somebody ELSE's repository.
+ *
+ * ⚠ The canonical list lives in `packages/cli/src/lib/git-env.ts` and this is a
+ * deliberate second copy, because `prepare` step 1 runs *before* step 2 builds
+ * the TypeScript that would make it importable. The subset is not a smaller
+ * opinion about that list: `git config --local` resolves its target file only
+ * through `GIT_DIR`/`GIT_COMMON_DIR`, and `GIT_CONFIG` names a config file
+ * outright. `GIT_WORK_TREE` and `GIT_INDEX_FILE` cannot move it, so stripping
+ * them here would be noise.
+ *
+ * Exported so the behaviour is testable — importing this module must not build
+ * anything, hence the entry-point guard at the bottom.
+ */
+export const gitConfigEnv = (env = process.env) => {
+  const sanitised = { ...env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_CONFIG']) delete sanitised[key];
+  return sanitised;
+};
+
+function main() {
+  // 1. Wire up the pre-commit hook when working inside the git checkout.
+  if (existsSync(path.join(root, '.git'))) {
+    spawnSync('git', ['config', 'core.hooksPath', '.husky'], {
+      cwd: root,
+      env: gitConfigEnv(),
+      stdio: 'inherit',
+    });
+  }
+
+  // 2. Build the CLI so the `bin` entry exists (required for git/tarball installs).
+  const require = createRequire(import.meta.url);
+  const tscPath = path.join(
+    path.dirname(require.resolve('typescript/package.json')),
+    'lib',
+    'tsc.js',
+  );
+  const result = spawnSync(
+    process.execPath,
+    [tscPath, '-p', path.join(root, 'packages/cli/tsconfig.build.json')],
+    { cwd: root, stdio: 'inherit' },
+  );
+  process.exit(result.status ?? 1);
 }
 
-// 2. Build the CLI so the `bin` entry exists (required for git/tarball installs).
-const require = createRequire(import.meta.url);
-const tscPath = path.join(
-  path.dirname(require.resolve('typescript/package.json')),
-  'lib',
-  'tsc.js',
-);
-const result = spawnSync(
-  process.execPath,
-  [tscPath, '-p', path.join(root, 'packages/cli/tsconfig.build.json')],
-  { cwd: root, stdio: 'inherit' },
-);
-process.exit(result.status ?? 1);
+// Run only when executed, never when imported: a test that imports this module
+// to check one exported function must not trigger a build or touch git config.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}