create-agent-rig 0.4.0 → 0.5.0

package/templates/agent-os/universal/docs/decisions/run-directory.md

@@ -0,0 +1,44 @@
+# Why one run directory per run, and why nothing can enforce it
+
+The rule lives in the `loop` skill, section 1 ("Declare the run directory here").
+This file explains what the enforcement does and does not reach, so nobody
+mistakes the warning for a guarantee. It is not loaded into any session.
+
+## An undeclared run is not a run with a missing journal
+
+`RIG_RUN_DIR` holds two unrelated things: the machine trace, and the run's
+**stop conditions** — the escalation streak, the deploy verdict, the budget flag.
+
+With `RIG_RUN_DIR` unset, the two verdicts a session writes by hand
+(`run-state.mjs deploy …`, `run-state.mjs budget …`) refuse loudly, so it finds
+out. **The escalation count does not.** It is recorded nowhere, silently, and
+selection then hands out work after two walls in a row with nothing on stderr to
+say why.
+
+So an undeclared run is a run whose main brake is off, and which looks exactly
+like a healthy one from the outside.
+
+The trace's first call site is **selection**, which runs before every task.
+Declared later, it misses everything that already happened — which is why the
+declaration belongs in preflight or nowhere.
+
+## What the reuse check catches
+
+- Two writers landing on the same sequence number.
+- A directory that already carries its run-end marker.
+
+Both are refused. Selection still works and says so on stderr, and that run's
+trace ends there — **loudly**, which is the good case.
+
+## What it cannot catch
+
+Two runs whose records happen not to collide.
+
+A run that died before writing its end marker — and dying unexpectedly is
+exactly the case the checkpoint discipline exists for — leaves an intact
+sequence behind it. The next run pointed at that directory **continues it in
+silence**: one seamless trace of two runs, with nothing in the file able to say
+so.
+
+Nothing detects this after the fact. A fresh directory per run is the only thing
+that prevents it, and it is the session's to do.

package/templates/agent-os/universal/docs/decisions/spacing-rations-mechanisms.md

@@ -0,0 +1,125 @@
+# Why the elevated ration counts mechanisms and not documents
+
+The rule lives in the `loop` skill, section 2; the code is
+`.claude/scripts/queue/state.mjs` (which tier a close records) and
+`.claude/scripts/queue/core.mjs` (which tiers clear the ration). This file
+explains why the elevated tier splits in two, why only one half spaces the next
+item, and why an unrecognised tier holds. It is not loaded into any session.
+
+## What the ration was bought for
+
+The rule's own sentence names it: _one **unreviewed** schema or permissions
+change is recoverable; a chain of them compounding overnight is not._ Two words
+in it do the work. **Unreviewed** — the risk is an unattended run stacking
+changes nobody read. **Compounding** — the second change lands on top of what the
+first one did, so the damage is not additive but multiplied.
+
+A rulebook document satisfies neither. It is reviewed on the model lane by two
+cold readers, and it compounds into nothing overnight because no runtime
+executes it. Yet in any repository whose rulebook lives under a declared
+elevated path — every rig, by construction — a `.md` close recorded the same
+`elevated` as a migration and held the next item exactly as hard.
+
+Two measurements on this repository forced the change, and they are different
+facts — the second is the mechanism's own report, the first is not:
+
+- The `loop` run of 2026-08-17 hit `nothing-selectable` with **56 takeable items
+  held, 53 of them by spacing** — the count `queue/index.mjs next` printed, so
+  this one is the ration speaking. It holds on the item's **marker**, which is
+  what those 53 carried. ⚠ Not reproducible from this repository: the queue is
+  tracker-backed and the run's own record is under the gitignored
+  `.claude/runs/`, so this figure is a report, not a check anyone can re-run.
+- Earlier, the AR-63 run recorded (journal, 2026-08) that of 58 selectable items
+  **56 were elevated in fact — by declared path** — 31 of them marked so and 25
+  marked `normal` while their own bodies named an elevated path. That is a
+  measurement of the queue, not of the ration: it says the pressure is not going
+  to ease, because a rig's rulebook lives under a declared path by construction.
+
+Together: the ration was not pacing the project, it was halting it, and the halt
+was indistinguishable from the rule working.
+
+## The split, and where it does NOT apply
+
+`recordCompletedTier` classifies the elevated paths a close actually crossed:
+
+| what the close crossed | tier recorded | effect on the next elevated item |
+| --- | --- | --- |
+| every elevated path is a document | `elevated-prose` | clears the ration |
+| any elevated path is not | `elevated-mechanism` | spaces it |
+| no elevated path at all | `normal` | clears the ration |
+
+⚠ **"Elevated path" is the sweep's answer, not the diff's.** `elevatedPathsIn`
+drops inert paths *before* this classification runs, and a non-rulebook `.md` is
+inert — so `scripts/notes.md` under a declared directory records `normal`, not
+`elevated-prose`. In practice the only markdown that ever reaches the split is
+**rulebook** markdown: `CLAUDE.md` anywhere, everything under `.claude/`, and the
+decision records. That is pre-existing sweep behaviour, restated here because the
+table above reads more broadly than the code behaves.
+
+The predicate is `executesNothing` — **`.md` only** — and it lives in
+`detect-missed-gate.mjs` beside the sweep's own markdown test so the two cannot
+drift apart.
+
+**They are different tests on purpose, and `.mdx` is where they part.** The
+sweep asks *does this need a reviewer* and calls both flavours inert. The ration
+asks *can a merge of this compound overnight*, and MDX carries components and
+imports — it is a program that renders, not a document that is read, which is why
+`decision-router.mjs` already sends it down the code lane
+(`review-lanes.md`). Calling it prose here would clear the spacing hold on a file
+this same rig treats as a program, on the permissive side.
+
+Two questions, two predicates, **one file** — that pairing is why they cannot
+drift. It is not a rule that every markdown test in the rig belongs there:
+`decision-router.mjs` keeps its own sets on purpose, and `review-lanes.md` — now
+with a row for this ration — exists to stop anyone consolidating them.
+
+**The known soft spot: a skill's `SKILL.md` is prose by this test**, and some
+skills carry shell snippets an agent copies and runs. The ruling is that skills
+stay prose for rationing — they are reviewed like the rules they are, and
+rewriting a procedure is not the chain of unreviewed compounding changes the
+ration was bought to stop. It is still the weakest ground the "no runtime
+executes it" justification stands on, and the first place to look if the ration
+turns out too loose.
+
+**A mixed diff is a mechanism close.** The half that runs decides. Reading the
+tier off the first path, or off "most of them are documents", would ship a ration
+any diff can opt out of by also touching a `.md`.
+
+The split is read by **exactly one** consumer: the ration. `elevated-prose` is
+still an elevated change wherever it is *reviewed* — the model lane, the cold
+readers, the `human-review` label, the gate sweep — and `recordCompletedTier`
+still reports every elevated path it found, unchanged. Narrowing the ration must
+not narrow the report: a prose merge that stopped listing its rulebook files
+would look clean to the sweep that exists to catch exactly those merges.
+
+## Unknown holds; absent does not
+
+`core.mjs` releases on `normal`, on `elevated-prose`, and on an **absent** tier —
+`null`/`undefined`, which is the honest statement that nothing has closed yet and
+what a fresh checkout says. Everything else holds: the legacy `'elevated'` an
+older state file carries, a word in the wrong case, a value that is not a string.
+
+The tempting implementation is `tier === 'elevated-mechanism'`. It is wrong in
+the one direction that matters: every unrecognised value would read as "nothing
+elevated closed" and hand out the next elevated item — un-rationing the queue
+silently, on state files this project itself wrote last week. The whole seam
+exists because a filter whose input nobody supplies is indistinguishable from a
+filter that agrees with you.
+
+The legacy word stays *readable* for the same reason it must not be *permissive*:
+a checkout that upgrades mid-run still has one on disk, and refusing it outright
+would exit 1 on the next selection. `loadState` accepts four words and refuses
+the rest — **for the state file only**. Selection falls back to a tier left in
+`queue.json`, and `loadConfig` validates nothing but JSON syntax, so a word like
+`banana` in the config reaches `selectNext` unrefused — measured: the CLI exits 0
+with no refusal, and then **holds** the elevated item with `causes: ["spacing"]`.
+It holds because `core.mjs` is the layer that reads every unrecognised value
+restrictively — the same layer that holds when `selectNext` is called directly.
+
+## What this does not fix
+
+The livelock where *every* remaining item is elevated-by-mechanism still exists —
+narrowed, not closed. Its operator-only remedy is filed and **not built**: no
+such command exists in this repository today, so a run that hits the livelock
+stops and says so rather than clearing its own tier. Spacing is also still per
+checkout, so a second worktree does not get its own allowance.

package/templates/agent-os/universal/docs/decisions/stop-conditions-in-a-file.md

@@ -0,0 +1,46 @@
+# Why the run's stop conditions are a file, not a memory
+
+The rule lives in the `loop` skill, section 3 ("What keeps the loop running,
+and what stops it"). This file records why the state was moved out of the
+session, and why only one of the two written verdicts can be taken back. It is
+not loaded into any session.
+
+## The defect the file fixed
+
+`escalations` and `lastDeployVerdict` now live in `<RIG_RUN_DIR>/state.json`,
+written by `run-state.mjs`.
+
+Before that existed, the CLI called `stopConditionOf` with the queue counts
+alone. Every state-dependent branch therefore held its **default** on every real
+selection — the runtime-regression stop, the two-escalations stop, the budget
+stop. None of them could fire. The rules were enforced only by whichever session
+happened to remember them.
+
+Compaction is exactly the moment a long unattended run stops remembering, and a
+long unattended run is the only situation these stops exist for. So the stops
+were reliably absent precisely where they were needed.
+
+## Why the escalation count has two writers, and both must be the documented one
+
+- It **rises** through the adapter's `escalate()`. Hand-labelling an item
+  escalated marks the item and counts nothing, so the run grinds past the wall.
+- It **resets** through the close step's `recordCompletedTier`, and only when
+  that call is passed `runDir` — see `docs/decisions/closing-a-task.md`.
+
+Both halves fail quietly when done the undocumented way, and they fail in
+opposite directions: one never stops a broken run, the other stops a healthy one.
+
+## Why only the deploy verdict can be taken back
+
+The asymmetry is deliberate.
+
+`HEALTHY` names a **real later event** — the revert landed and the runtime was
+re-verified. Without a way to record it, one bad deploy would end every later
+selection in the run, however thoroughly it was fixed.
+
+Spend only accumulates. Un-exhausting a budget would name no event at all — only
+a decision to keep going, taken by the very run that declared the stop. That is
+the shape of a stop condition a run can talk itself out of, which is not a stop
+condition.
+
+A new run starts from a clean state. That is the way back from both.

package/templates/agent-os/universal/docs/decisions/two-empty-endings.md

@@ -0,0 +1,62 @@
+# Why "queue empty" and "nothing selectable" are different endings
+
+The rule lives in the `loop` skill, section 3. This file explains why the two
+stops are reported separately, how the parked pile grows under each adapter, and
+why a parked cause outranks a holding one. It is not loaded into any session.
+
+## The two endings ask the owner for opposite things
+
+- **Queue empty after the filters** — there is no work. Refilling it is the
+  owner's job. Expect this to be the most common ending: the queue is finite and
+  the loop drains it.
+- **Nothing selectable** — the work is there and every piece of it is held back
+  by a condition that clears when _something else happens_: the elevated spacing
+  (a normal item lands — or an elevated one whose paths were all documents, see
+  `spacing-rations-mechanisms.md`), a blocker (its item closes), `in-progress`
+  (the other session finishes), a trigger (a human declares it).
+
+An empty queue wants refilling. A held one wants interleaving, or simply time.
+Reporting the second as the first sends the owner to write tickets that already
+exist; reporting the first as the second tells them to wait for nothing.
+
+## The parked pile is reported next to the verdict, never inside it
+
+Parked items are out of play and waiting on a human. They are not work this run
+can take, and they are not why the queue is empty — so they are named separately,
+by cause and count.
+
+How that pile grows is the adapter's business, and the stop line does not guess:
+
+| adapter                                  | what lands in the parked pile                         |
+| ---------------------------------------- | ----------------------------------------------------- |
+| tracker-backed (`github-issues`, `jira`) | an escalated item and a filed proposal both stay open |
+| `plan-md`                                | only a `[triage]` line sitting in the Agent queue     |
+
+Under `plan-md` a filed proposal goes to the Operator queue, where selection
+never looks, and an escalation leaves **no mark on the queue at all** — a flat
+list has no per-item state.
+
+## That absence is not a safety
+
+`plan-md`'s `escalate` writes nothing to the queue and returns `ok: false`,
+handing back the instruction with it: move the item to the Operator queue in the
+same edit. That move is the session's, and skipping it means the next run takes
+the stuck item straight back.
+
+It does still record the escalation into the run state, like every other
+adapter. The two are different facts, which is why escalating must go through
+the adapter rather than by hand-labelling: the count is what ends a run that has
+hit the same wall twice.
+
+## Why a parked cause outranks a holding one
+
+An escalated item is left **claimed** on purpose, so it arrives carrying
+`in-progress` as well as `escalated`.
+
+Reading that as _held_ would report "another session will finish it" about an
+item no session is on — and, worse, would make the empty verdict unreachable
+from the first escalation onward. Reporting a working queue as empty is the
+defect this distinction exists to prevent; reporting a parked one as working is
+the same defect reversed.
+
+Neither ending is an invitation to refill the queue or invent work.

package/templates/agent-os/universal/journal/README.md

@@ -0,0 +1,101 @@
+# The journal
+
+The human record of what sessions did here. **One file per month**, named
+`journal/YYYY-MM.md` — the month is the filename's job, so entries themselves
+stay date-free and their order carries the sequence.
+
+**Newest-on-top inside each file.** A new entry goes directly under the month's
+heading, so the file reads as a stack. Prune freely: this is operational memory,
+not an archive.
+
+**The shape of a month file**, stated because the first session of a new month
+creates it and a shape nobody wrote down is one that has to be guessed:
+
+- it **opens with a single `#` heading** naming the month;
+- **every entry is a `###`** under that heading, and there is nothing at `##`
+  or any other level in between;
+- a new entry is inserted directly beneath the `#` heading, above the previous
+  newest.
+
+**What is mechanically checked, precisely — because this file ships into a
+project and its checks do not.** The generator that produced this rig has tests
+for the first two bullets and for the `YYYY-MM.md` filename; **this project has
+none of them** unless you write them. That is the same arrangement
+`.claude/rules/invariants.md` describes for the hooks, and the same caveat
+applies: what is not tested here is convention, however firmly it is written.
+
+The third bullet — *where* a new entry is inserted — is convention even in the
+generator. Nothing checks entry order anywhere yet; making "newest" decidable
+for date-free entries is its own piece of work. Do not read the presence of a
+shape rule as a guarantee that a misordered file would be caught.
+
+`README.md` is this document, not a month file. Other names: a file that does
+not match `YYYY-MM.md` is never **read** as a month file — but do not read that
+as permission, because in the generator any other `*.md` in this directory
+**fails** the filename check. Keep archives and side notes out of this
+directory, or somewhere with a non-`.md` extension.
+
+An unattended run writes an entry at every stop **and** at checkpoints along the
+way, because a run that dies unexpectedly must not take its history with it.
+
+🔴 **This is not the run trace.** `.claude/runs/<run>/events.jsonl` and
+`decisions.jsonl` are machine-readable, append-only and **oldest-first**, written
+by `run-journal.mjs`. This file is the human record and is newest-on-top. They
+answer different questions — the trace says what the run decided and on what
+basis, this says what a reader needs to know afterwards — and reading one as the
+other is how a reader concludes a run did nothing.
+
+## The entry
+
+The fields exist so an entry can be visibly **incomplete**. A journal with no
+stated shape decays into a diary that reads fine and proves nothing.
+
+Copy the block and drop the fields that do not apply — `unblocked` is the
+exception, and it is stated even when the answer is "nothing".
+
+```markdown
+### <one-line summary of the session>
+
+- **done** — what landed, one line each, with the PR reference
+- **escalated** — what stopped, and the diagnosis: what failed, what was tried,
+  the current hypothesis, and the one question whose answer unblocks it
+- **reviewed** — changes that went through a reviewer gate, and what it returned
+- **stopped at** — which stop condition ended the session (or "checkpoint,
+  still running")
+- **unblocked** — what the session's closes released
+- **queue hygiene** — queue state the session found unreliable and reported
+- **cost** — the counts the session actually observed
+```
+
+## The two fields that are most often got wrong
+
+**`unblocked` is never dropped**, and it has **three** answers that do not
+substitute for each other:
+
+1. the items that were waiting, by name;
+2. "nothing was waiting" — the queue carries dependency links and none pointed
+   here;
+3. "this queue has no dependency links" — it cannot answer at all.
+
+A flat-list queue is **absent, not satisfied**, and writing "nothing was waiting"
+there claims a look that no query could perform. A missing line and an unpaid
+debt read identically from outside, which is why the empty case has to be
+written to mean anything.
+
+**`cost` carries only what the session observed** — reviewer subagents run, CI
+runs consumed (re-runs included, the cheapest signal that a task fought its
+tests), deploys triggered.
+
+## Never estimated — and this governs every field, not just `cost`
+
+**Any** field the session cannot observe stays **visibly empty, never
+estimated**. A plausible number will be believed, by the next reader and by the
+next run reasoning about its own budget — and the same is true of a plausible
+sentence: a guessed `reviewed` or an inferred `unblocked` is the identical
+failure without the digits. Leave the gap; it is information.
+
+## Queue hygiene is reported, never corrected in passing
+
+A stale marker, a dependency already satisfied, an item describing work already
+done — record it here. Quietly fixing the metadata destroys the evidence that the
+metadata is unreliable.

package/templates/agent-os/universal/layers.json

@@ -14,21 +14,53 @@
     ".claude/hooks/guard-bash.mjs",
     ".claude/hooks/gate-stop-dod.mjs",
     ".claude/hooks/inject-rules.mjs",
+    ".claude/hooks/guard-secret-file.mjs",
+    ".claude/hooks/lib/edit-input.mjs",
     ".claude/skills/pr-ship/SKILL.md",
     ".claude/skills/loop/SKILL.md",
     ".claude/skills/check-premises/SKILL.md",
     ".claude/skills/worktree-task/SKILL.md",
+    ".agents/skills/new-invariant/SKILL.md",
+    ".agents/skills/new-invariant/guard-invariant.example.mjs",
+    ".agents/skills/new-invariant/guard-invariant.example.test.mjs",
+    ".agents/skills/pr-ship/SKILL.md",
+    ".agents/skills/loop/SKILL.md",
+    ".agents/skills/check-premises/SKILL.md",
+    ".agents/skills/worktree-task/SKILL.md",
+    ".codex/agents/test-writer.toml",
+    ".codex/agents/code-reviewer.toml",
+    ".codex/agents/security-scanner.toml",
+    ".codex/agents/prose-reviewer.toml",
     ".claude/scripts/detect-missed-gate.mjs",
+    ".claude/scripts/decision-router.mjs",
     ".claude/scripts/reconcile-external-prs.mjs",
     ".claude/scripts/stop-flag.mjs",
+    ".claude/scripts/git-env.mjs",
     ".claude/scripts/preflight.mjs",
+    ".claude/scripts/run-journal.mjs",
+    ".claude/scripts/run-state.mjs",
+    ".claude/scripts/verdict.mjs",
+    ".claude/scripts/lib/verdict.mjs",
+    ".claude/scripts/lib/secrets.mjs",
     ".claude/scripts/queue/core.mjs",
     ".claude/scripts/queue/plan-md.mjs",
     ".claude/scripts/queue/github-issues.mjs",
     ".claude/scripts/queue/jira.mjs",
     ".claude/scripts/queue/index.mjs",
+    ".claude/scripts/queue/checkout.mjs",
+    ".claude/scripts/queue/state.mjs",
+    ".claude/scripts/queue/gate-rounds.mjs",
     ".claude/queue.json",
-    "PLAN.md"
+    "PLAN.md",
+    "journal/README.md",
+    "docs/decisions/fail-open-guards.md",
+    "docs/decisions/codex-adapter.md",
+    "docs/decisions/closing-a-task.md",
+    "docs/decisions/review-lanes.md",
+    "docs/decisions/run-directory.md",
+    "docs/decisions/spacing-rations-mechanisms.md",
+    "docs/decisions/stop-conditions-in-a-file.md",
+    "docs/decisions/two-empty-endings.md"
   ],
   "architecture": [
     ".claude/rules/architecture.md",
@@ -37,6 +69,8 @@
   ],
   "meta": [
     ".claude/settings.json",
-    "CLAUDE.md"
+    ".codex/hooks.json",
+    "CLAUDE.md",
+    "AGENTS.md"
   ]
 }

package/templates/hash-history.json

@@ -2,7 +2,8 @@
   "versions": [
     "0.3.0",
     "0.3.1",
-    "0.3.2"
+    "0.3.2",
+    "0.4.0"
   ],
   "files": {
     ".claude/agents/cdk-diff-reviewer.md": {

package/templates/skeleton/aws-serverless/.github/workflows/deploy.yml

@@ -53,5 +53,38 @@ jobs:
           role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
           aws-region: ${{ vars.AWS_REGION || '__REGION__' }}
 
+      # `--require-approval never` is deliberate and dev-only: this workflow has
+      # no production path at all (see the header), so the approval prompt would
+      # only ever block an unattended dev deploy on a change nobody is watching.
       - if: steps.guard.outputs.skip != 'true'
-        run: pnpm --filter @app/infra exec cdk deploy AppStack WebStack --require-approval never
+        run: >
+          pnpm --filter @app/infra exec cdk deploy AppStack WebStack
+          --require-approval never --outputs-file cdk-outputs.json
+
+      # The bundle is built above and the bucket is created by the deploy — but
+      # nothing puts one into the other, so without this step CloudFront keeps
+      # serving whatever was uploaded by hand, last time somebody remembered.
+      # `web-stack.ts` deliberately does not use BucketDeployment (synth must
+      # never depend on `next build` having run), which is why the upload lives
+      # here rather than in the stack.
+      - if: steps.guard.outputs.skip != 'true'
+        name: Upload the web bundle and invalidate the edge cache
+        run: |
+          # `jq -r` prints the string "null" and exits 0 for a missing key, and
+          # GitHub's shell is `bash -e` with no `-u` and no pipefail — so a
+          # renamed stack or a half-finished deploy would sync the bundle into
+          # `s3://null`, a real bucket in a global namespace someone else owns,
+          # and issue --delete against it. `-e` makes jq exit non-zero instead.
+          set -euo pipefail
+          BUCKET=$(jq -er '.WebStack.WebBucketName' infra/cdk-outputs.json)
+          DISTRIBUTION=$(jq -er '.WebStack.WebDistributionId' infra/cdk-outputs.json)
+          # An existing-but-empty bundle syncs zero objects, and --delete then
+          # empties the live site with a green checkmark.
+          [ -n "$(ls -A apps/web/out 2>/dev/null)" ] || {
+            echo "apps/web/out is empty — refusing to sync"; exit 1;
+          }
+          # --delete makes the bucket the bundle's territory alone: anything not
+          # in this build is removed from it.
+          aws s3 sync apps/web/out "s3://$BUCKET" --delete
+          aws cloudfront create-invalidation \
+            --distribution-id "$DISTRIBUTION" --paths '/*'

package/templates/skeleton/aws-serverless/README.md

@@ -45,13 +45,27 @@ do not edit the workflow:
 
 1. In AWS, create an IAM role your repo can assume via GitHub's OIDC provider
    (`token.actions.githubusercontent.com`) — a short-lived federated role, no
-   long-lived access keys anywhere.
-2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`** (and,
-   optionally, repo variables `AWS_REGION` and `API_URL`).
-
-The workflow then assumes the role, builds the web bundle, and runs
-`cdk deploy AppStack WebStack`. The web bundle is served from S3 + CloudFront
-(the `WebUrl` output).
+   long-lived access keys anywhere. Beyond what `cdk deploy` needs, the
+   workflow uploads the bundle itself, so the role also needs
+   **`s3:ListBucket`, `s3:PutObject`, `s3:DeleteObject`** on the web bucket and
+   **`cloudfront:CreateInvalidation`** on the distribution. A role scoped only
+   to CDK's bootstrap roles gets through the deploy and fails on the upload —
+   after both stacks are already up.
+2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`**, and set the
+   repo variable **`API_URL`** to the deployed API's URL (the `ApiUrl` output
+   of a first deploy). It becomes `NEXT_PUBLIC_API_URL`, which Next **inlines
+   into the bundle at build time** — unset, the site calls `/notes` on its own
+   CloudFront domain, where nothing answers. `AWS_REGION` is genuinely
+   optional. The first deploy is therefore two passes: deploy, read `ApiUrl`
+   from the job's `cdk deploy` Outputs, set the variable, then re-run the
+   workflow (push, or **Run workflow** — it is `workflow_dispatch`-enabled).
+
+The workflow then assumes the role, builds the web bundle, runs
+`cdk deploy AppStack WebStack --outputs-file`, then **uploads `apps/web/out` to
+the web bucket (`aws s3 sync --delete`) and invalidates the CloudFront cache**,
+reading both destinations from the stack outputs. You do not sync anything by
+hand on this path. The site is served from S3 + CloudFront (the `WebUrl`
+output).
 
 ### Local / manual
 
@@ -59,8 +73,26 @@ The workflow then assumes the role, builds the web bundle, and runs
 # needs AWS credentials; region comes from your profile (generator default: __REGION__)
 cd infra
 npx cdk bootstrap   # first time per account/region
-npx cdk deploy AppStack WebStack
-aws s3 sync ../apps/web/out "s3://<WebBucketName output>"
+npx cdk deploy AppStack WebStack --outputs-file cdk-outputs.json
+# --delete makes the bucket the bundle's territory alone, so a stale or missing
+# `out/` would empty the live site — or restore last month's. The workflow
+# builds two steps before its sync; by hand, build here.
+# Read the outputs into variables FIRST. `jq -er` exits non-zero on a missing
+# key, but a command substitution inside an assignment or an argument throws
+# that status away — which is how a stale outputs file becomes a bundle built
+# against `null` and an `aws s3 sync … s3://null --delete`.
+API=$(jq -er '.AppStack.ApiUrl' cdk-outputs.json) || { echo "no ApiUrl"; exit 1; }
+BUCKET=$(jq -er '.WebStack.WebBucketName' cdk-outputs.json) || { echo "no WebBucketName"; exit 1; }
+DIST=$(jq -er '.WebStack.WebDistributionId' cdk-outputs.json) || { echo "no WebDistributionId"; exit 1; }
+
+# NEXT_PUBLIC_API_URL is inlined at build time: without it the bundle calls its
+# own CloudFront domain instead of the API, and the sync below makes that live.
+(cd .. && NEXT_PUBLIC_API_URL="$API" pnpm build:web)
+[ -f ../apps/web/out/index.html ] || { echo "no web bundle — build failed"; exit 1; }
+aws s3 sync ../apps/web/out "s3://$BUCKET" --delete
+# a synced bucket whose distribution still serves the old objects has not
+# deployed — invalidate, or you are looking at the previous build
+aws cloudfront create-invalidation --paths '/*' --distribution-id "$DIST"
 ```
 
 ### Production — a human step, on purpose
@@ -76,12 +108,41 @@ your own approval — reusing the dev workflow's OIDC pattern.
 After every deploy:
 
 ```sh
+# From the deploy's outputs file — run this from `infra/`, where the manual
+# section leaves you. Deployed through CI instead? That file is written on the
+# runner and never lands here: take both values from the job's `cdk deploy`
+# Outputs, or re-run `cdk deploy … --outputs-file cdk-outputs.json` locally.
+API_URL=$(jq -er '.AppStack.ApiUrl' cdk-outputs.json)
+WEB_URL=$(jq -er '.WebStack.WebUrl' cdk-outputs.json)
+
 curl -s -X POST "$API_URL/notes" \
   -H 'content-type: application/json' \
   -d '{"title":"smoke test","tags":["deploy"]}'
 # expect: HTTP 201 with { "note": { … } }
 ```
 
+**That checks the API, not the site.** The two fail independently: a bundle
+built without `NEXT_PUBLIC_API_URL` calls its own CloudFront domain, and a
+misnamed origin is refused by the browser — neither is visible to a `curl` that
+sends no `Origin` header. So also open the `WebUrl` output, create a note in
+the form, and reload:
+
+```sh
+curl -s -I "$WEB_URL" | head -1                      # the bundle is served
+
+# API Gateway answers a preflight 204 whether or not the origin matched, so the
+# status code proves nothing here. The browser gates on the echoed header —
+# that is what to look for. `content-type` is sent because the real call uses
+# it, and a non-safelisted header is what makes `allowHeaders` matter.
+curl -s -X OPTIONS "$API_URL/notes" -D - -o /dev/null \
+  -H "Origin: $WEB_URL" \
+  -H 'access-control-request-method: POST' \
+  -H 'access-control-request-headers: content-type' \
+  | grep -i '^access-control-allow-origin:'
+# expect: a line echoing $WEB_URL. No line = the browser will refuse the call,
+# whatever the status code said.
+```
+
 Then confirm the pipeline: the worker logs `note.created processed`, and the
 **DLQ alarm stays quiet**. If the smoke test regresses: `npx cdk deploy` the
 previous revision (or `git revert` and redeploy) **first**, diagnose second.
@@ -95,5 +156,26 @@ previous revision (or `git revert` and redeploy) **first**, diagnose second.
 - `packages/db` is the only module that touches the storage SDK.
 - A failing queue message is poison: it throws, SQS retries ×3, the DLQ alarm
   fires. Never wrap the worker in a broad catch.
+- **Creating a note is a dual write, and it is not atomic.** `create-note`
+  puts to DynamoDB and then publishes to SQS. If the publish fails, the note
+  is stored and its event never happened — the worker never runs, and nothing
+  compensates; the caller gets a 500 for a note that exists. That is a
+  deliberate simplification for a starter. When it starts to matter, the two
+  ways out are an **outbox** (write the event alongside the note, relay it
+  afterwards) or DynamoDB Streams feeding the worker, which deletes the second
+  write instead of coordinating it.
+- **CORS names who may call the API, and that half is wired for you.**
+  `bin/app.ts` builds `WebStack` first and passes its CloudFront origin to
+  `AppStack`, so the API allows the deployed site without you configuring it.
+  The other half is not automatic: the bundle has to know where the API *is*,
+  and that is `NEXT_PUBLIC_API_URL` above. For a custom domain or a second
+  origin, deploy with `-c allowedOrigins=https://app.example.com` (comma-
+  separated for several) — the entrypoint prefers the flag over the wired
+  default, and the cross-stack export disappears with it. An `allowedOrigins`
+  that parses to nothing, or an entry no browser could send, is refused at
+  synth rather than deployed as an API nobody can call. `*` is not the default
+  and never will be, but the flag does take it: you get a warning naming the
+  consequence, not a refusal, because the alternative is people editing the
+  stack.
 
 See `.claude/rules/architecture.md` for the full rules.

package/templates/skeleton/aws-serverless/apps/web/src/lib/api.ts

@@ -2,8 +2,15 @@
 // (the guard-web-boundary hook refuses such imports at the tool layer).
 import type { Note } from '@app/core';
 
-// Same-origin by default (the API server serves this bundle); set
-// NEXT_PUBLIC_API_URL at build time when the API lives elsewhere.
+// In THIS target the API is never same-origin: the bundle is served from
+// CloudFront and the API is API Gateway, so `NEXT_PUBLIC_API_URL` has to be set
+// at build time — Next inlines it, and an unset one leaves the empty string
+// here, which sends every call to whatever is serving this page.
+//
+// The `?? ''` is a fallback to nothing, not to a working default: there is no
+// dev proxy in this project, so `pnpm --filter @app/web dev` needs the variable
+// too. It exists only so a missing value is a relative URL rather than the
+// string "undefined" in a request path.
 const base = process.env.NEXT_PUBLIC_API_URL ?? '';
 
 export async function createNote(input: { title: string; tags: string[] }): Promise<Note> {