create-agent-rig 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,243 @@ 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.
 
+Numbering is ordinary semver — **additive is a minor, a fix is a patch** — so
+that "I only take minors" remains a usable policy; 0.3.2 shipped additive
+content as a patch by the owner's call and stays recorded as one.
+
+## 0.5.0
+
+**Codex is a harness of this rig now, not a thing you adapt it to.** A generated
+project carries one rulebook and two readers: `CLAUDE.md` for Claude Code and
+the same text as `AGENTS.md` for Codex, with repository skills in
+`.agents/skills/`, agent profiles in `.codex/agents/` and portable hook wiring
+in `.codex/hooks.json`. Neither harness gets the weaker policy, and the derived
+half is drift-checked rather than maintained twice.
+
+**This release ships untagged, by the owner's decision, and it has exactly one
+consequence — read it if you ever run `upgrade` on a rig whose
+`.claude/.rig-manifest.json` is missing or unreadable.**
+`templates/hash-history.json`, the table such a rig is measured against, is
+built from `v*` tags. So 0.5.0's bytes never enter it, and the `0.4.0` row it
+gained in this release carries the _previous_ release's bytes: that tag points at
+0.3.2's content, which is why the row adds no hash to any path. Both paths 0.4.0
+actually changed — `.claude/skills/loop/SKILL.md` and `PLAN.md` — are in the
+table with their 0.3.x hashes; what is absent is 0.4.0's bytes from their hash
+lists.
+
+**Who that reaches, and who it does not.** `create`, `init` and `upgrade` each
+write the manifest, and `upgrade` matches it **before** it consults the table, so
+a rig whose manifest is present and parseable is unaffected whatever the table
+says. Without a readable manifest the table decides, and it decides in the
+conservative direction: bytes it recognises are replaced, bytes it does not are
+kept and reported as yours — see `packages/cli/test/upgrade.test.ts` › "replaces
+a file that matches a released version, and reports the rest".
+
+A rig installed **before** 0.4.0 is not the exposed case: its 0.3.x bytes are in
+the table, so those two files are recognised and replaced. The rig that keeps
+them is one installed at **0.4.0** whose manifest is unreadable.
+
+**And the scale of it grows with this release, which matters more than those two
+files.** Because 0.5.0 is untagged, nothing it ships enters the table either — so
+a rig installed at 0.5.0 and later upgraded **without a readable manifest** has
+most of its agent-os files unrecognised, and many of them are paths the table has
+no row for at all. Every one is kept and reported as yours, so no edit is lost
+and no file is silently skipped, but almost nothing would be refreshed either. **Commit `.claude/.rig-manifest.json`** — that single habit makes the
+table irrelevant to you, and it is what `README.md` puts in bold.
+
+### Added
+
+- **Codex is now a native target of the Agent OS.** Generated and `init`ed
+  projects receive `AGENTS.md`, repository skills in `.agents/skills/`, custom
+  agent profiles in `.codex/agents/`, and portable `.codex/hooks.json` wiring.
+  These files are derived from the Claude Code sources and drift-checked.
+- Architecture guards now understand Codex `apply_patch` payloads, inspecting
+  additions and bounded existing content for moves, so removing an old
+  violation does not create a false block.
+
+### Changed
+
+- **`upgrade` now replaces `.claude/settings.json` when the manifest proves you
+  never touched it** — closing the decision 0.4.0's notes left open below. The
+  case it exists for is a release that adds a hook: the hook file arrived and
+  the wiring that calls it did not, so the guard sat on disk doing nothing. When
+  the on-disk bytes hash-match the entry the manifest recorded for the installed
+  release, they are provably the rig's own and the release's version is written.
+
+  **Three limits. The first two are there because not having them was tried,
+  and each produced a regression two reviewers reproduced independently.**
+
+  1. **The released-hash fallback does not apply to this file.** Every other
+     file the rig installed can be recognised by matching a tagged release even
+     with no manifest entry. This one cannot: a rig with no manifest that has
+     run `init` is recorded as `kind: "init"`, and the wiring that flavour
+     writes deliberately omits the hooks `init` does not install.
+  2. **A replacement that would stop calling a hook still present in
+     `.claude/hooks/` is handed over instead**, whatever the manifest says. This
+     is the guard that does not depend on getting `kind` right — a manifest
+     saying `init` on a rig `create` produced reaches the same wrong wiring
+     through the hash arm alone.
+  3. **Anything else is unchanged:** the new entries are printed for you to
+     merge, and nothing is written.
+
+- **`init --force` is deprecated.** It refuses, names `upgrade` as the command
+  that refreshes a rig, and writes nothing. It only ever replaced `CLAUDE.md`,
+  which `upgrade` now does per file and with the manifest behind it. **The flag
+  is removed in 0.6** — this release is the one warning you get.
+
+  The way into a `create` rig that `--force` used to provide is a deleted
+  `CLAUDE.md`; that is what `init`'s refusal is actually about, and it is the
+  case the manifest-preserving fix below was written for.
+
+### Security
+
+- 🔴 **A committed `.claude/.rig-manifest.json` could run code on the machine
+  of whoever upgraded the rig.** `project.name`, `project.scope`,
+  `project.region` and `stacks` were each validated — but only as _path_
+  segments, a predicate that asks whether a value can steer a write. Two of
+  them are also substituted into installed **files**:
+  `.claude/scripts/stop-flag.mjs` embeds the name inside a single-quoted
+  JavaScript string literal that `guard-bash` imports on every Bash call. A
+  value closing that quote steers no path at all and passed — it executed in
+  the hook process, **and** moved the kill switch's path off
+  `~/.claude/<name>-loop-STOP`, so the brake read as installed while doing
+  nothing. The manifest travels in pull requests, so the delivery was an
+  ordinary PR plus an `upgrade`. All four are now held to the shape the rig
+  actually produces (`^[a-z0-9_][a-z0-9._-]*$`), and a manifest carrying
+  anything else is void as a whole rather than corrected.
+
+  **Checking a rig you upgraded from a manifest you did not write — three
+  places, because the name is not the only value that travelled.**
+  `.claude/scripts/stop-flag.mjs` is the executable sink: its kill-switch line
+  must read your own project name. `region` lands in
+  `.claude/skills/ro-debug/SKILL.md` as `export AWS_REGION=…` on rigs carrying
+  the `aws-cdk` overlay — and a manifest also declares `stacks`, so it can
+  request that overlay on a rig that never had it. The name is substituted into
+  the documents the agent obeys as well (`CLAUDE.md`, `PLAN.md`, the `loop`
+  skill), where a hostile value arrives as injected text rather than as code.
+
+  Nothing `create` or `init` writes is rejected by the new rule — including an
+  empty `region` and a name with a leading underscore, which
+  `projectNameFor` really can produce.
+
+### Fixed
+
+- **`init --force` inside a generated project used to make `upgrade` stop
+  refreshing the stack overlays — silently.** ⚠ Read this next to the
+  deprecation above: `--force` is refused in this same release, so
+  the route described here is gone. The fix is not idle — the manifest is
+  preserved on **every** `init` over a `create` rig, and the remaining route in
+  is a deleted `CLAUDE.md`. `init` rewrote the rig manifest
+  as `kind: "init"`, `stacks: []`, empty `region`, and `upgrade` trusts a
+  manifest wholesale rather than re-detecting: the stack files simply left the
+  plan, reported neither as deleted nor as a conflict, and `CLAUDE.md` came
+  back in the `init` flavour. `init` now carries the `kind`, `project` and
+  `stacks` it found in the manifest through unchanged, and adds an entry for
+  each file it wrote without dropping the entries already there. It also says,
+  before writing anything, that this rig came from `create` and `upgrade` is
+  the command that refreshes it.
+
+  ⚠ **Both halves read the manifest, so a rig that has none — anything
+  installed before 0.4.0 — is not covered.** There `init` still writes
+  `kind: "init"`, `stacks: []`, empty `region`, and prints no advisory; worse,
+  such a rig could previously be recovered by `upgrade`, which re-detects the
+  install from the files on disk **only when there is no manifest at all**, and
+  the one `init` writes takes that route away. On a pre-0.4.0 rig, run
+  `upgrade` before `init`.
+
+  **Recovering a rig whose manifest was already flattened:** delete
+  `.claude/.rig-manifest.json` and run `upgrade` — the detection restores
+  `kind`, `stacks` and `region` from the files themselves; hand-writing the
+  manifest is not needed and `parseManifest` rejects the whole file on any
+  malformed field. What that does **not** repair is `CLAUDE.md`: the flattening
+  `init` overwrote it with the `init` flavour, so `upgrade` reports it as
+  `conflict` ("not a version this rig ever released — treated as yours") and
+  the create flavour has to be merged back by hand.
+
+- **The `jira` queue adapter was calling an endpoint Atlassian removed.** Both
+  selection and the triage dedupe went through `GET /rest/api/3/search`, which
+  answers `410 Gone`; the adapter threw on the status line and the loop read
+  that as an unreadable queue. It now uses `POST /rest/api/3/search/jql`. If
+  your rig is on the `jira` adapter, this is the difference between a loop that
+  works and one that reports an empty board. Cursor pagination
+  (`nextPageToken`) is **not** implemented yet, so a board with more open issues
+  than `limit` (default 100) still loses its tail.
+
+### Changed — action needed if your board uses the `jira` adapter
+
+- 🔴 **The elevated-tier marker on Jira is now the `elevated` label, not
+  `human-review`.** A board that marked elevated work with `human-review` will,
+  after this upgrade, hand every item to the loop as `normal` — the
+  elevated-spacing ration silently stops holding anything back. **Relabel those
+  issues to `elevated` before running the loop again.** The change is
+  deliberate: on a Jira board `human-review` reads as "a human is looking at
+  it", which is a different claim from "this change is expensive to reverse".
+  The `github-issues` adapter is unaffected and still reads `human-review`,
+  where it does mean a human reviewed the diff.
+- **Selection now excludes the `operator-queue` label as well as `triage`.** An
+  item in the owner's lane is work a human has taken, so the loop no longer
+  picks one up. If you used `operator-queue` for something else, rename it
+  first.
+
+## 0.4.0
+
+Upgrading is a command now: **`npx create-agent-rig@0.4.0 upgrade`** (`@latest`
+once you know what latest is — this section will not). That sentence replaces
+the six-file manual procedure 0.3.2 had to print, and it is the whole point of
+this release: a rig you cannot bring forward stops being maintained at whatever
+version you installed it at.
+
+Read the [Upgrading](README.md#upgrading-a-rig-you-already-have) section before
+the first run on an existing rig; `--dry-run` prints the plan and writes
+nothing.
+
+### Added
+
+- **`create-agent-rig upgrade [--dry-run] [--yes]`** — brings an installed rig
+  to this version: it replaces the files the rig wrote **and you have not
+  touched**, installs what the release adds, and **reports everything else**.
+  There is no three-way merge and no patching, by decision rather than
+  omission: silently folding your edits into the documents an agent loop obeys
+  is how a rig stops meaning what its owner thinks it means. Every conflict
+  names the file, why it was kept, and the path to the new version, so the diff
+  you may want is one command away.
+- **`.claude/.rig-manifest.json`** — written by `create` and by `init`: the rig
+  version and a hash per installed file. **Commit it.** It is what lets an
+  upgrade tell a file the rig wrote from a file you own, and without it in the
+  repository the command is blind on CI and on a colleague's machine. `init`
+  records only files it actually wrote — never one it kept, which would be
+  claiming somebody else's document.
+- **A released-hash table travels in the package**, generated from the git tags
+  at release time and never by hand. It is what makes a 0.3.x rig upgradable at
+  all, and it answers a second question too: a file that shipped in every
+  release it covers and is gone from disk was **deleted on purpose**, so it
+  stays deleted. The rules tell you to delete the invariants your project does
+  not have; an upgrade that quietly restored them would be undoing your work.
+- **The `loop` skill writes back what a close unblocked**, in a required
+  journal field with three distinct answers — the items that were waiting, by
+  name; "nothing was waiting"; or "this queue has no dependency links" where
+  the adapter cannot answer at all. It is a **report, not an edit** to those
+  items: correcting queue state by hand destroys the evidence that the state is
+  unreliable, which the rules forbid by name.
+
+### Two things `upgrade` deliberately will not do
+
+- **Replace `.claude/settings.json`.** It is where your own hooks live, so the
+  new wiring is printed for you to merge — in the dry run too. The cost is
+  real and stated: a release that adds a hook delivers the file and not its
+  wiring, and whether a manifest-proven-unmodified settings file should be
+  refreshed is an open decision for 0.5.
+- **Touch the skeleton.** After `create`, the code is your project. The manifest
+  covers the agent-os layer and nothing else.
+
+### Deferred, and on what condition
+
+- The clarify-gate (`C-0…C-2`) — unchanged from 0.3.2: it enters once that gate
+  has fired at least once anywhere. Until then there is nothing to copy but an
+  intention.
+- `init --force` now overlaps `upgrade`, and its future is an open question
+  rather than a deprecation: decided in 0.5, unchanged here.
+
 ## 0.3.2
 
 Numbered as a patch by the owner's call; the content below is additive, so
@@ -35,10 +272,14 @@ will not touch them:
 .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.
+Delete those six and re-run `init`, or copy them across by hand. 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.
+
+> **Superseded in 0.4.0.** `create-agent-rig upgrade` delivers exactly these
+> files, and the ones every release after it changes. The procedure above is
+> kept as the record of what 0.3.2 asked of its users; do not follow it if you
+> have 0.4.0 or later.
 
 ### Added
 
@@ -256,7 +497,8 @@ layers, and the `aws-serverless` and `node-service` targets.
 ## Releasing
 
 `npm publish` needs 2FA and cannot be undone, so an agent prepares a release and
-**stops at that command**. Everything before it is mechanical:
+**stops at the first step it is not allowed to take** — normally `npm publish`,
+sometimes earlier (step 6). Everything before that is mechanical:
 
 1. `pnpm test` — the full suite, including the e2e that generates both targets
    cold and runs their own checks through the git path **and** the pack path.
@@ -264,8 +506,50 @@ layers, and the `aws-serverless` and `node-service` targets.
    tree, are in the tarball. This is where scaffolders break, and the git path
    cannot catch it.
 3. Version in `package.json` (and the private inner package, kept in step).
-4. This file, and `PLAN.md` if the plan's claims changed.
-5. `git tag v<version> && git push --tags`.
-6. **Owner:** `npm publish`.
-7. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in
-   an empty directory, then `pnpm install && pnpm check` inside it.
+4. `node scripts/build-hash-history.mjs` — regenerate the released-hash table
+   from the tags **after** the version bump, so the version now shipping is the
+   first one it excludes. Forgetting it would leave `upgrade` unable to
+   recognise the previous release. ⚠ With no tag cut (step 7), what excludes the
+   shipping version is the absent tag rather than that filter — and the same
+   absence keeps it out of every later table too, which is the cost step 7
+   states.
+5. This file, and `PLAN.md` if the plan's claims changed.
+6. **`pnpm test` again — this run, not step 1, is the one that can catch a
+   stale hash table.** The check compares the table against the versions this
+   file lists below the one in `package.json`, so before steps 3–5 it is
+   comparing the _old_ release to the _old_ table and passes either way. A
+   guard that can only fire after the thing it guards has changed has to be run
+   after it.
+7. **Tagging is not part of this project's release process** — standing owner
+   decision, recorded at 0.5.0: the owner publishes by hand and does not tag. So
+   this step is deliberately _not_ performed, and the cost is stated here rather
+   than discovered later.
+
+   Step 4 builds the table from `v*` tags, so an untagged release never enters
+   it. That is free for the release being prepared and **not free for the one
+   after it**: step 6 fails as soon as the CHANGELOG lists an untagged release
+   _below_ the version being prepared, and its message says "stale table", which
+   running the builder cannot satisfy. Measured against this repository at
+   0.5.0 preparation: with `0.5.0` untagged, a `0.5.0` bump passes and an
+   `0.6.0` bump fails. The check is
+   `test/template/hash-history.test.ts` › "covers every released version below
+   the one being prepared". **AR-35 carries the fix**, and which shape it takes
+   is that item's to decide, not this note's.
+
+   **What a releaser may do when step 6 fails, stated so it is not inferred:**
+   stop, and land AR-35 first. Cutting the missing tag after the fact is _not_
+   the sanctioned way out — it would put the table's honesty back on a step this
+   process does not perform, which is the whole reason the decision is recorded
+   here.
+
+   If a tag is ever cut anyway, the older warning still applies: check first
+   that it does not exist (`git ls-remote --tags origin`), because a leftover
+   from an abandoned attempt is a published ref, deleting or moving one is an
+   **owner** action, and a tag on the wrong commit makes the next table **name a
+   version whose bytes it does not carry**. `v0.4.0` is in exactly that state —
+   it points at 0.3.2's content.
+
+8. **Owner:** `npm publish`.
+9. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in
+   an empty directory, then `pnpm install && pnpm check` inside it; and
+   `upgrade --dry-run` in a rig installed from the previous version.

package/README.md

@@ -3,6 +3,12 @@
 Scaffold a project that ships with an **agent operating system** — rules,
 gates, and hooks that hold the architecture mechanically, not by prose.
 
+The same Agent OS is native to both **Claude Code and Codex**. Claude-facing
+files remain the authoring surface; the generator derives Codex's `AGENTS.md`,
+repository skills under `.agents/skills/`, custom agents under `.codex/agents/`,
+and `.codex/hooks.json`. `node scripts/sync-codex-adapter.mjs --check` refuses
+drift between the two projections.
+
 ```sh
 npx create-agent-rig my-app                        # choose a target interactively
 npx create-agent-rig my-app --target node-service  # or name it up front
@@ -22,28 +28,91 @@ 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 — **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.
+hooks — **wired** for both harnesses, in `.claude/settings.json` and
+`.codex/hooks.json`, each naming exactly the hooks it installed — plus matching
+`CLAUDE.md` and `AGENTS.md` maps that describe that rig rather than the generated
+monorepo. It refuses to clobber either existing map; if the repo already has a
+Claude or Codex hook config, 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
+maps: 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.
 
+After generation or upgrade, review the checked-in `.codex/hooks.json` in Codex's
+`/hooks` view and explicitly trust it if Codex presents a trust prompt. The
+[official Codex hooks documentation](https://learn.chatgpt.com/docs/hooks)
+records trust against the current hook hash, so a changed hook definition may
+require that review again; the adapter does not silently replace user-owned hook
+configuration.
+
+## Upgrading a rig you already have
+
+A release changes files, and `init` only ever _adds_ — so bringing an existing
+rig forward is its own command:
+
+```sh
+npx create-agent-rig@latest upgrade --dry-run  # print the plan, write nothing
+npx create-agent-rig@latest upgrade            # print the plan, then ask before writing
+npx create-agent-rig@latest upgrade --yes      # the answer up front (required off a terminal)
+```
+
+It replaces the files the rig installed **and you have not touched**, installs
+what the release added, and **reports everything else** — no three-way merge, no
+patching. Silently merging your edits into the documents an agent loop obeys is
+how a rig quietly stops meaning what you think it means; a conflict report is how
+it does not. Each conflict names the file, why it was kept, and the path to the
+new version so you can diff it yourself.
+
+How it knows: `create` and `init` write `.claude/.rig-manifest.json` — the rig
+version plus a hash per installed file. **Commit it**; without it in the
+repository the command is blind on CI and on a colleague's machine. Rigs
+installed before 0.4.0 have no manifest, so the package also carries the hashes
+of every **tagged** release (0.3.0 onward — 0.1.0 and 0.2.0 shipped untagged,
+and a rig from those reports every file as yours) and recognises a file matching
+one of them. Releases from 0.5.0 on ship untagged as well, so the table does not
+carry them either: on a rig with no manifest most of their files are reported as yours
+rather than refreshed. This is why committing the manifest is the sentence in
+bold above and not an aside.
+
+`.claude/settings.json` is replaced only when the manifest's recorded hash
+proves the rig wrote those exact bytes and you have not touched them — the case
+where a release adds a hook and the wiring that calls it. Anything else, and it
+is where your own hooks live: the new wiring is printed for you to merge, never
+written. Unlike every other file, a match against the released hashes is not
+enough for this one, and a replacement that would stop calling a hook the
+current wiring names — while that hook's file is still in `.claude/hooks/` — is
+handed over instead.
+
+**A file you deleted stays deleted.** The rules invite you to delete the ones
+whose invariant your project does not have, so an upgrade that quietly restored
+them would be undoing your work. With a manifest that is direct — it names the
+file, the disk does not have it, and the manifest is _evidence_, not a command.
+Without one, the shipped table answers instead: a file that was in every release
+it covers was there to be removed. The single case nothing can tell apart is a
+file a **later** release added, which your rig never had — that one is installed,
+and `--dry-run` lists it before anything is written.
+
 ## What you get
 
 **A system of boundaries, each held by tooling.** An agent (or a human using
 one) cannot talk its way past them — each guard is a pre-write scan that stops
 the normal path cold (review and tests back it; the claim is stated exactly,
-never inflated). The hooks live in `.claude/hooks/` and are wired in
-`.claude/settings.json`:
+never inflated). The hook implementations live once in `.claude/hooks/` and are
+wired by both `.claude/settings.json` and `.codex/hooks.json`:
 
 - **`guard-core-purity`** — refuses any edit that puts I/O, clock, randomness,
   environment access, or a non-allowlisted import into the pure domain core;
 - **`guard-web-boundary`** — refuses `db`/service imports from the frontend;
   the web talks to the backend over HTTP only;
+- **`guard-secret-file`** — refuses an edit that writes a credential: either the
+  path names one (`jira.env`, `id_rsa`, anything under `secrets/`) or the text
+  carries a credential VALUE. Both arms read one vocabulary,
+  `.claude/scripts/lib/secrets.mjs`, and a refusal names the pattern and the line
+  and **never the matched value** — printing it would leak the secret in the act
+  of refusing it. Its four blind spots are in its own header, each naming the
+  test that pins it or saying plainly that none does — and those tests live in
+  this generator, not in the rig;
 - **`block-no-verify`** — refuses bypassing pre-commit checks (and knows the
   difference between using the `--no-verify`/`-n` flag and merely mentioning it
   in a message);
@@ -58,7 +127,9 @@ never inflated). The hooks live in `.claude/hooks/` and are wired in
   check is red; it fails open (a missing or corrupt config never makes the
   session unquittable) and never blocks twice in a row;
 - **`inject-rules`** — re-injects the autonomy rules at session start, so they
-  survive compaction and resumes.
+  survive compaction and resumes: the whole file, minus the regions the file
+  itself marks as reference. What is left out is a decision written in
+  `autonomy.md` on the line above it, not one this hook infers.
 
 **A brake that is a real file.** `touch ~/.claude/<project>-loop-STOP` and no
 merge lands until it is removed — enforced at the tool layer, so it holds even if
@@ -87,8 +158,8 @@ never), **stop rules** (three strikes, flaky ≠ retry, session staleness),
 `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
-orients by.
+`ro-debug` on the AWS target), and matching one-page `CLAUDE.md` / `AGENTS.md`
+maps a fresh session orients by.
 
 **The hooks are examples, not laws.** `.claude/rules/invariants.md` states the
 pattern behind each one — a stated invariant, a mechanical check, a test for the
@@ -158,8 +229,8 @@ under test, because that is exactly where scaffolders break. A grep-test keeps
 the universal rules free of any provider mention; the hook-blocking behavior
 itself is under test; and a weekly lockfile-free run resolves each template's
 dependencies fresh to catch upstream breakage early. This repo dogfoods its own
-rulebook — `CLAUDE.md` and `.claude/` are composed from the templates, and
-drift fails the suite.
+rulebook — the Claude and Codex projections are composed from the templates,
+and drift fails the suite.
 
 **And the enforcement layer is adversarially reviewed, not just tested.** The
 Bash guard went through four review rounds with ten reviewers, who executed it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",
@@ -10,6 +10,7 @@
     "template",
     "agent",
     "claude-code",
+    "codex",
     "agent-os",
     "aws-serverless",
     "node-service"

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

@@ -1,13 +1,16 @@
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, stat } from 'node:fs/promises';
+import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { copyTree, listTree } from '../lib/copy-tree.js';
+import { copyTree, listTree, mapConcurrent } from '../lib/copy-tree.js';
 import { ALLOWED_OVERWRITES, detectCollisions } from '../lib/composition.js';
+import { agentOsLayerDirs } from '../lib/install-set.js';
+import { sha256, writeManifest } from '../lib/manifest.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';
+import { skeletonDir } from '../templates.js';
+import { packageVersion } from '../lib/version.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class CreateError extends Error {
 }
@@ -36,13 +39,10 @@ export async function createProject(dirArg, options) {
         transformName: (name) => substituteFileName(name, ctx),
     };
     // Layer 2 (the skeleton) + layer 1 (agent-os: universal + stack overlays).
+    const agentOsLayers = agentOsLayerDirs(target.stacks);
     const layers = [
         { name: `skeleton/${target.skeletonDir}`, dir: skeletonDir(target.skeletonDir) },
-        { name: 'agent-os/universal', dir: agentOsUniversalDir() },
-        ...target.stacks.map((stack) => ({
-            name: `agent-os/stack/${stack}`,
-            dir: agentOsStackDir(stack),
-        })),
+        ...agentOsLayers,
     ];
     // Composition safety: layers must claim disjoint paths. Checked before any
     // copy — a collision is a template bug and must never be resolved by order.
@@ -61,11 +61,44 @@ export async function createProject(dirArg, options) {
     for (const layer of layers) {
         await copyTree(layer.dir, projectDir, transforms);
     }
+    await recordInstall(projectDir, agentOsLayers, transforms, ctx, targetName);
     if (options.git !== false) {
         await initGitBaseline(projectDir);
     }
     return { projectDir, projectName };
 }
+/**
+ * Record the agent-os layer in `.claude/.rig-manifest.json`, so a later
+ * `upgrade` can tell a file the rig wrote from a file the project's own people
+ * changed.
+ *
+ * The skeleton is **not** recorded, and that is the boundary of the whole
+ * upgrade story: once generated, the code belongs to the project. The hashes
+ * are read back off the disk rather than recomputed, so the manifest states
+ * what is actually there and cannot drift from what was copied. The manifest
+ * lands before the baseline commit — it is part of the pristine template, and
+ * it belongs in the project's git history.
+ */
+async function recordInstall(projectDir, agentOsLayers, transforms, ctx, target) {
+    const files = {};
+    for (const layer of agentOsLayers) {
+        const paths = await listTree(layer.dir, transforms);
+        const hashes = await mapConcurrent(paths, 16, async (rel) => ({
+            rel,
+            hash: sha256(await readFile(path.join(projectDir, ...rel.split('/')), 'utf8')),
+        }));
+        for (const { rel, hash } of hashes) {
+            files[rel] = hash;
+        }
+    }
+    await writeManifest(projectDir, {
+        version: await packageVersion(),
+        kind: 'create',
+        project: { name: ctx.projectName, scope: ctx.projectScope, region: ctx.region },
+        stacks: [...(TARGETS[target]?.stacks ?? [])],
+        files,
+    });
+}
 const run = promisify(execFile);
 async function initGitBaseline(projectDir) {
     // Disable git's background maintenance for these one-shot commands: a commit