@caddis/cli 0.4.51 → 0.4.53

package/bundles/antigravity-plugin/skills/roadmap/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: roadmap
+description: "Track milestones across plans in .caddis/roadmaps/<slug>/: next batch, typed blockers, rollup. Every change is a docs PR via caddis_roadmap.py."
+---
+
+# Roadmap
+
+**Core rule:** the roadmap file on `origin/main` is the only truth; every change to it, by a tool or a human, is a
+small docs PR, so it is ordered and recorded in git history. The tool's PRs are merged automatically on green checks
+by `caddis_merge_chain.py --docs-only`; a repo that wants a human to review them protects its default branch.
+
+`scripts/` below is the caddis scripts folder: `${CLAUDE_PLUGIN_ROOT}/scripts` in an installed plugin, `scripts/` in
+the caddis source repo.
+
+## The folder
+
+`.caddis/roadmaps/<slug>/` holds:
+
+| Path | What |
+|---|---|
+| `roadmap.md` | Milestones and Blockers tables (start from `assets/roadmap.template.md`) |
+| `decisions.md` | decision register; a `Depends on` change cites an id from here |
+| `cards/` | one **card** per unit of work handed to a lane or a reviewer: scope, files, pass criteria |
+| `reports/` | what comes back from a card |
+| `.local/` | machine-local: `changes.jsonl` (audit of the tool's PRs), the runner's `runner.jsonl` and `STOP` (its lock and other state are in `<git common dir>/caddis-runner/roadmap-<slug>/`) |
+
+Plans stay in `.caddis/plans/`. Add `.caddis/roadmaps/*/.local/` to the repo's `.gitignore`. The write lock is not in
+the folder: it is `<git common dir>/caddis-roadmaps/<slug>.write.lock`, so every worktree of the repo shares it.
+
+## The format
+
+```markdown
+Runner host: <runner-host>
+
+## Milestones
+| ID | Milestone | Phases | Depends on | Exit check | Status | Owner | Target |
+|---|---|---|---|---|---|---|---|
+| S1 | Lines load | p-alpha#1, p-alpha#2 | - | `python scripts/check_s1.py` | todo | runner | WD3 |
+
+## Blockers
+| Milestone | Type | Reason | Check |
+|---|---|---|---|
+| S2 | data-condition | GPU rows not loaded | `python scripts/rows_ready.py` |
+```
+
+- **Status:** `todo`, `in-progress`, `code-done/data-pending`, `done`, `not-needed`. There is no `blocked` status: a
+  milestone is blocked when it has a Blockers row.
+- **Blocker types:** `owner-gate`, `external`, `shared` (a shared file, the GPU, the merge line, another session),
+  `calendar`, `data-condition`. A new `calendar` blocker needs an ISO date `YYYY-MM-DD` in Check
+  (`block --type calendar --check 2026-11-01`); a date is not a command, so it needs no `--by-owner`.
+- **Owner:** `runner` (or empty) lets the runner take it; a session name means that session does it by hand.
+- **Phase ref** `p-alpha#2` = Phase 2 in the Tracker of `.caddis/plans/p-alpha.md` or `.caddis/plans/done/p-alpha.md`.
+  It is done only when its Tracker Status starts with `done` or a check mark **on origin**. Refs work inside one repo.
+- **Runner host:** the one machine whose runner may run this roadmap. Write a placeholder such as `HOSTNAME` in
+  shared examples.
+- A `Depends on` change cites a decision id in the Milestone cell: `S9 (dep waived: TC94)`. `check` warns otherwise.
+- **Strict sections.** `## Milestones` and `## Blockers` hold only blank lines, one table whose every line starts with
+  `|`, and prose with no unescaped `|` set apart from the table by a blank line. Anything else is a parse error.
+  A roadmap allows only headings, plain paragraphs, lists and pipe tables: no code fences, no HTML, no setext
+  headings, no control or non-ASCII whitespace characters.
+- **A malformed roadmap fails closed.** A row with the wrong cell count, a `|` line outside a table, a near-miss
+  heading such as `## Blockers (open)`, an id that is not `[A-Za-z0-9_-]+`, an unknown Status or blocker type, or a
+  phase ref to a missing plan: every command but `check` exits 4 and prints the errors. Fix the file by a PR.
+
+## Commands
+
+Every command runs `git fetch origin` and reads `origin/<default>`, never the working tree. Exit check and Check
+commands run in a temporary worktree of `origin/<default>` (the merged code), with no stdin, killed with their whole
+process tree on timeout.
+
+```bash
+python scripts/caddis_roadmap.py status  --roadmap <slug> [--json]   # "<done> of <total> done; next <id>; ..."
+python scripts/caddis_roadmap.py next    --roadmap <slug> [--json]   # exit 0 found, 1 nothing ready (reasons)
+python scripts/caddis_roadmap.py check   --roadmap <slug>            # parse errors, unknown refs or types
+python scripts/caddis_roadmap.py set     --roadmap <slug> --id S1 --col Status|Owner|Target --value <v> [--by-owner] [--reason "<r>"]
+python scripts/caddis_roadmap.py block   --roadmap <slug> --id S2 --type <type> --reason "<text>" [--check "<cmd>" --by-owner]
+python scripts/caddis_roadmap.py unblock --roadmap <slug> --id S2 --type <type> --reason "<text>" [--check "<cmd>"] [--by-owner]
+python scripts/caddis_roadmap.py rollup  --roadmap <slug> --id S1
+python scripts/caddis_roadmap.py recheck --roadmap <slug>
+```
+
+`next` picks the first milestone in table order that is `todo` or `in-progress`, whose `Depends on` are all `done` or
+`not-needed`, with no Blockers row, Owner `runner` or empty, and a phase not yet merged. It returns that phase.
+
+## Rules a runner trusts
+
+- **Only `rollup` writes `done`.** `set --value done` exits 4. `rollup` needs every phase merged on origin, every
+  `Depends on` milestone `done` or `not-needed`, and no open blocker other than `data-condition` (exit 1 names it),
+  then runs the Exit check (300 s): pass -> `done`; fail with a `data-condition` blocker -> `code-done/data-pending`;
+  fail otherwise -> an `external` blocker
+  `exit check failing (exit <n>)` (never the command's output). A milestone with no phase refs and no Exit check is
+  refused (exit 4).
+- **Owner-only changes:** `set` Status `not-needed`, any `set` Owner, `unblock` of an `owner-gate`, and `block --check`
+  (recheck runs that command unattended later). They need `--by-owner` and are refused headless: `CADDIS_HEADLESS`
+  or `CLAUDECODE` in the environment (even empty), stdin not a terminal, or on
+  Windows stdin not a console (a NUL stdin is headless).
+- **`unblock` removes one blocker.** When two rows share milestone, type and reason, it exits 4 until `--check`
+  names the row's Check text.
+- **`recheck` clears `data-condition` blockers**, each row whose own Check passed (120 s), **and `calendar`
+  blockers whose Check date has passed** (UTC; no command runs). A `calendar` row whose Check is `-` stays until
+  someone runs `unblock`. Other types stay.
+- **`not-needed` needs a reason.** `set --col Status --value not-needed --by-owner` also needs
+  `--reason "dropped: <why>"` or `--reason .caddis/parking-lot/<file>.md` (the file must be on origin). A reason with
+  `|` or a line break exits 4. The same docs PR adds `- <id> not-needed: <reason> (YYYY-MM-DD)` under `## Notes`
+  (the section is added at the end when missing).
+- **Old blockers are listed.** `status` (and so the runner's toast) ends with
+  `old blockers: <id> <type> (<N> days), ...`, oldest first, for each blocker row older than 14 days. The age is the
+  date of the newest commit on origin that added that exact row (`git log -S`): the roadmap never stores a date, and
+  a row that was cleared and added again counts from the new add.
+- **Commands run the merged code.** Editing a check script or a Check in the working tree changes nothing until it
+  merges.
+
+## How a write lands
+
+`set`, `block`, `unblock`, `rollup` and `recheck` take the write lock (after 30 s, a lock whose holder is dead on
+this host, or an empty or non-JSON lock older than 60 s, is taken over), branch `roadmap/<slug>-<id>-<utc>` from
+`origin/<default>` in a temp worktree, commit `docs(roadmap): <slug> <id> <change>`, push, open a PR, and hand it to
+`caddis_merge_chain.py --docs-only`. `gh` uses the account in `GH_TOKEN` when it is set. Git network calls time out
+after 120 s, `gh` after 60 s and the merge chain after 1800 s (exit 3); none can wait on a credential prompt. `--dry-run` prints the diff
+and `would run: <cmd>` lines, and runs and writes nothing. Exit codes: 0 clean, 1 blocked, 3 could not run, 4 error
+(malformed roadmap, refused change, bad usage).
+
+## The runner
+
+`roadmap-run.ps1 -Roadmap <slug>` (a shim over `scripts/caddis_roadmap_run.py --roadmap <slug>`) runs the roadmap
+unattended; `-Plan <slug>` runs one plain plan instead (the two are exclusive). It starts only on the roadmap's
+`Runner host` (else exit 3). Each iteration:
+
+1. `next`. Nothing ready: stop `BLOCKED nothing ready` (exit 1); the notification carries the `status` line. When
+   the roadmap is finished (every milestone `done` or `not-needed`) the runner also removes its worktree if it is
+   clean (only session relay files left), and keeps it, saying so in the stop line, if not. With the worktree gone it
+   also deletes the local `caddis/roadmap/<slug>/*` branches merged into `origin/<default>` and names the others.
+2. Print `next: <milestone> <plan>#<phase>` (`next` and the batch claim happen under one repo-level claim lock).
+   A phase whose `**Lane:**` line does not start with this engine (`claude`, `agy`, `codex`), names a cloud session
+   or the owner, or that has **no Lane line**, is not run (fail closed): the runner adds
+   `block --type owner-gate --reason "phase <n> lane: <lane>"` (`lane: none` when there is no line) and goes on.
+3. A `todo` milestone is set `in-progress` (a docs PR). Every session of a roadmap runs in ONE dedicated worktree,
+   `%TEMP%/caddis-roadmap-<slug>-<8 hex of the repo's git common dir>`: made with `git worktree add --detach` from `origin/<default>` on the first
+   session, reused on restart, recorded in the runner folder, never the `-Repo` checkout (plan mode keeps working in
+   the given checkout). In that worktree the runner makes a fresh branch `caddis/roadmap/<slug>/<plan>-p<n>` from
+   `origin/<default>` (it refuses a branch of that name already on origin that it did not make) and ONE session runs
+   `assets/plan-resume-prompt.md` on it (if a blocked session left uncommitted work in the worktree, the runner
+   stops `BLOCKED roadmap worktree has uncommitted work from <branch>` instead, and a session branch that already
+   holds commits not on `origin/<default>` is never reset: `BLOCKED <branch> has unpublished commits from an earlier
+   session`; the owner decides), with `{{slug}}` = the plan and
+   `{{phase}}` = the phase. Every session gets its own fresh branch (also after an OWNER-GATE or BLOCKED one), so a
+   blocked phase's commits never reach another PR. Sessions stay on that branch and never push.
+4. Relay `STATUS: CONTINUE` with new commits on that branch: the **runner** checks that the session is still on it
+   and did not touch `.caddis/roadmaps/` (else `FAILED`, nothing published), then, in this order: writes a persistent
+   claim `<git common dir>/caddis-runner/claims/<plan>#<n>.json`, pushes the branch, opens a PR (`gh api`, the account
+   from `GH_TOKEN`) titled `<plan> phase <n>: <phase title>`, writes the PR URL into the claim, records the wait in its
+   runner folder's `waiting.json` (ref, PR, milestone, branch, claim and its hash, the roadmap hash; never in the last
+   stop), and stops `BLOCKED waiting for merge <plan>#<phase> <pr url>` (exit 1). A run killed between the claim and
+   `waiting.json` leaves a claim nothing names: the next start stops on it as an orphaned claim. On restart, GitHub
+   must confirm the PR merged before any branch is deleted; a done Tracker row with the PR still open or closed
+   unmerged stops `BLOCKED <ref> Tracker row is done but PR <url> is not merged` and keeps the branch, the claim and
+   `waiting.json`. The claim keeps the phase held (`next`, other roadmaps and plan mode skip or refuse it) until the PR
+   merges or closes. A run started while the PR still waits stops at once (`BLOCKED still waiting for merge of <ref>:
+   <url>`) and changes nothing. Once it merges, the recheck task restarts the runner. The restart first checks that the merged
+   origin roadmap is the one it published against (a hash, then the frozen tables; any difference is `FAILED roadmap
+   changed`), rolls the milestone up FIRST (when every phase is merged), then removes the claim and the phase's
+   branch (locally and on origin: whoever makes a branch removes it when its PR merges), and goes on with `next`.
+   An own claim that neither the waiting record nor `pending-rollup.json` names (a run killed between the claim and
+   the wait) stops the start `BLOCKED orphaned claim <file> from a killed run`; the owner checks the branch and its PR
+   and deletes the claim.
+   CONTINUE with the phase already merged on origin: `rollup` when every phase is merged, then back to 1. CONTINUE
+   with no new commits and nothing merged stops FAILED. `STATUS: OWNER-GATE <r>` becomes an `owner-gate` blocker,
+   `STATUS: BLOCKED <r>` an `external` one; then back to 1. `STATUS: FAILED` stops.
+5. Every `**Risk:** high` phase done on the branch and not yet reviewed clean (record in the runner's own folder:
+   `<git common dir>/caddis-runner/roadmap-<slug>/reviewed/<plan>.json`; another runner's record does not count) is
+   reviewed BEFORE step 4 writes the claim and publishes
+   (`caddis_review.py --plan --phase --runs 2`): exit 0 publishes;
+   exit 1 starts one fix session, then one more review; exit 1 again stops `BLOCKED review`, exit 3, 4 or any other
+   code `BLOCKED review not run` (neither restartable); the review cost counts against the USD caps.
+
+Stops (each one notifies and releases the lock): a STOP file (`~/.caddis/STOP` or `.local/STOP`), any cap (10 h,
+12 sessions, 120 min and USD 25 per session, USD 150 total; per run, in memory; the global agy spend cap of
+`caddis_spend.py` still counts across runs), a lock or batch claim that cannot be written
+(`BLOCKED claim not written`, before any session), the agy spend cap refusing a reservation, three sessions
+with no newly merged phase, a roadmap write that fails, and the **snapshot guard**: one baseline for the whole run.
+The Milestones and Blockers tables (every cell of every row, rows added, removed or moved) and the `Runner host` line
+are frozen. Every origin read (each `next`, after the runner's own writes, after each session) is compared with the
+previous one; the only differences allowed are the exact edits the runner itself made and recorded for that read: a
+Status it set, a blocker row it added, and what a rollup's audit entry (`changes.jsonl`) says it actually wrote.
+Anything else stops the run `FAILED roadmap changed`.
+Each runner has its own state folder, `<git common dir>/caddis-runner/roadmap-<slug>/` (plan mode: `plan-<slug>/`):
+lock, last stop, options, branches, worktree path, the saved roadmap text. `claims/` and `claim.lock` are shared at
+the top level. The runner hashes its own folder (recursively) and its own claims before and after every session; a
+change there stops the run `FAILED runner state changed` (not restartable). Another runner's writes never stop it. A restart checks that the claim its
+waiting-for-merge stop records is still there with the same content; a missing record, claim or hash is
+`FAILED own claim missing or changed` (not restartable). During the upgrade window a plan-mode lock of the base
+version (`.caddis/plans/.local/<slug>/runner.lock`, read only) still holds its plan while its pid runs and the lock
+file is newer than that process's start (else it is ignored). Roadmap slugs
+match `^[a-z0-9][a-z0-9-]{0,62}$` everywhere (both scripts and `caddis_roadmap.py`). The launch options are kept
+in memory and re-written at every stop, so a changed options file can never raise the caps.
+
+The runner never passes `--by-owner`. Every session and every `caddis_roadmap.py` call it starts gets
+`CADDIS_HEADLESS=1`. The runner lock is `<git common dir>/caddis-runner/roadmap-<slug>/runner.lock` (a plan-mode
+runner: `plan-<slug>/runner.lock`), so every worktree sees it. It holds `{"host", "pid", "started_utc", "batch", "max_hours"}`. On
+this host it is stale when its pid is not running, or the process now holding that pid started after `started_utc`
+(pid reuse after a reboot; when the start time cannot be read, it counts as live). Another host's lock is stale when it
+is older than its own `max_hours` plus 1 h. A stale lock is removed with a notification; a live lock is exit 3. A
+plan-mode lock holds the whole plan (`batch` `<plan>#*`). `next` skips a phase another live lock holds, and plan mode
+refuses a plan that a roadmap lock names, at start and before every session. `-DryRun` prints the chosen batch,
+the session command, the worktree and any pending rollup, skips the host check, writes no files and starts nothing; it
+does run `git fetch`, which updates the remote-tracking refs. `-GhAccount <login>` (recorded in the launch options,
+passed on by the recheck task and in the printed task) makes every gh call of the runner and of `--last-stop` use
+GH_TOKEN from `gh auth token -u <login>`; on a machine with several gh logins, give the repo's account. A gh call that
+cannot answer (gh missing, 401, 404) is an error, never "not merged": the run stops
+`BLOCKED gh cannot see <repo> with account <login>`, notified and recorded.
+
+`roadmap-recheck.ps1 -Roadmap <slug> -Repo <path>` starts `roadmap-run.ps1 -Roadmap <slug>` detached only when:
+the runner's last recorded stop (next to its lock) is `BLOCKED nothing ready` or there is none, and `recheck`
+cleared a blocker; or the last stop is `BLOCKED waiting for merge` and GitHub says that PR merged
+(`--last-stop` asks GitHub only and fetches nothing; the restarted runner checks the Tracker row on origin under its
+lock; in that tick recheck does NOT run `recheck`, because a cleared blocker would change the roadmap the restart
+checks against its hash). If GitHub says merged but the Tracker row is not done, the restart
+removes the claim and stops `BLOCKED <ref> merged but its Tracker row is not done` (the owner decides). A `BLOCKED nothing ready` stop also records the batches that
+another runner's lock or claim held; once every one of those holders is gone, `--last-stop` says `freed:` and recheck
+restarts the runner even with no blocker cleared. A plan in flight anywhere (a live lock or a claim on any of its
+phases) holds the whole plan for every other roadmap and for plan mode. At the top of each run the runner rolls up
+every milestone that waits only for its rollup (Status not finished, every phase merged, and the same rule as
+`next`: no blocker, dependencies finished, Owner the runner); `--last-stop` says `rollup-ready:` for such a milestone,
+so recheck restarts the runner. A sweep rollup that writes nothing stops `BLOCKED rollup of <id> wrote nothing`
+(recorded, not restartable) and is not retried or reported until the roadmap changes. The dry run lists them first. If
+the owner edits the roadmap during a merge wait, the restart stops `FAILED roadmap changed ...` and names the
+recovery: `roadmap-run.ps1 -Roadmap <slug> -AcceptRoadmap` (owner only, refused headless) takes the runner lock (a live
+runner refuses it), prints the diff from the published baseline, asks you to type `accept` (or `--yes`), and accepts
+the origin roadmap as the new baseline of the wait; the next start goes on. With `-DryRun` it prints the diff only. `--last-stop` uses `--gh-account`, else the account the run recorded
+in its launch options. In all cases the lock must be absent or stale; for the agy engine `caddis_spend.py check` must exit 0 too (a
+claude-engine roadmap needs no spend-cap file). A restart after a merge writes `pending-rollup.json` in its runner
+folder, runs the rollup first, then removes the claim and the branch, and only then the file. Every stop records
+itself: a failed rollup, a crash or a STOP file before that is not restartable (the owner decides), and the next start
+finds the file and does the rollup first. A merged
+branch checked out in another checkout is kept locally (HEAD never moves outside the roadmap worktree).
+Any FAILED stop (the snapshot guard, a crash), a cap or a STOP file needs the owner: recheck prints why and starts
+nothing; the owner's next manual run records a new last stop. A runner records the last stop `running` as soon as it
+holds the lock, so a run killed without a stop (a reboot, a kill) also needs the owner; an unexpected exception
+records `FAILED crash: <type>` and notifies once. Recheck restarts with the launch options the last run recorded
+(engine, model, caps), each cap clamped to at most the built-in default (the options file is writable), never higher.
+`roadmap-run.ps1 -Roadmap <slug> -PrintRecheckTask` prints a PowerShell block (`New-ScheduledTaskAction`,
+`New-ScheduledTaskTrigger` every 2 hours, `Register-ScheduledTask`) for the owner to paste; it registers nothing. The
+task runs only while you are logged on unless you add `-User` and `-Password` to `Register-ScheduledTask` (or set that
+option in Task Scheduler).
+
+## Limits
+
+Sessions are cooperative (our own sessions): the runner guards against mistakes and runaway spend, not against a
+deliberately hostile session, which runs as the same OS user and could change anything the runner can. The state
+tripwire catches accidents in a runner's own state only. In particular, a session in another worktree of the repo can
+delete or rewrite ANOTHER runner's claim or lock under `<git common dir>/caddis-runner/`; that is not caught while it
+happens, and the victim runner fails closed only at its next restart (own claim missing or changed, orphaned claim). Caps are per run; the agy spend cap is the only limit across runs. Each roadmap has one
+worktree, removed when the roadmap is finished and the worktree is clean.
+
+Owner-only rules are enforced by this tool; a direct PR that edits `roadmap.md` bypasses them; the runner stops
+when an owner-gate row disappears; repos that need more protect their default branch.
+On Windows, a check's grandchild started in the instant before the job object is attached can escape the tree kill;
+checks are owner-written, so this is accepted. Headless detection cannot see a process started in a fresh console with
+the markers removed: anything that runs this tool unattended (the runner, scheduled tasks) must set `CADDIS_HEADLESS=1`.

package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md

@@ -0,0 +1,77 @@
+---
+type: prompt
+title: Plan resume prompt for {{slug}}
+description: The prompt for one fresh runner session of the plan {{slug}} (runner plan mode). It does one batch and ends with a status line.
+status: current
+timestamp: {{date}}
+---
+
+You are a fresh session for the plan `{{slug}}`. Do ONE batch, then stop.
+
+In the commands below, `<scripts>` is the caddis scripts folder `{{scripts}}` (put it in quotes if it holds a space).
+Use the scripts in that folder; do not look for them in another caddis install.
+
+## 1. Read
+
+1. The plan `.caddis/plans/{{slug}}.md`: its goal, its decisions, its tracker. Every decision binds you.
+2. The relay `.caddis/relay/{{slug}}.md`. Its "Next step" says where to start.
+3. The open-work list `.caddis/open-work.md`, when it exists.
+
+## 2. Step 0: reconcile
+
+The relay can be old. Before you act, compare it with the real state: the plan tracker, worktrees, local branches, open
+pull requests and remote branches. If they disagree, trust the real state. Fix the relay and the tracker. Do not build on a
+guess.
+
+## 3. Pick the batch
+
+A batch is ONE tracker phase (the first row that is not done and not blocked), or ONE named batch that the plan or the relay
+names. If no row can start, end with the status line that says why (an owner gate, a block, or FAILED).
+
+The phase number chosen by the roadmap runner (empty: choose the batch yourself as above): {{phase}}
+When it holds a number, that phase is the batch. Do only that phase.
+
+Roadmap mode (a number above): the runner, not you, publishes the work. The runner made the branch you are on
+(`caddis/roadmap/<roadmap>/<plan>-p<n>`, fresh from the default branch). Stay on it: never switch or create a branch,
+never push, never open a pull request, and never edit anything under `.caddis/roadmaps/` (the runner refuses to
+publish a branch that does). Commit the phase there, with its tracker row set to `done`. When you end with
+`STATUS: CONTINUE` and new commits on that branch, the runner pushes it, opens the pull request and stops with
+`BLOCKED waiting for merge`; the recheck task restarts the runner after the merge.
+
+## 4. Work
+
+- Do ONE batch with `/caddis:implement` discipline: tests first, the phase's exit gate, a commit per phase.
+- agy sessions only: run `python {{scripts}}/caddis_spend.py check` before each agy call. Stop at the cap (exit 1 over
+  the cap, 3 not configured).
+- You may do everything except pass an owner gate. Never pass an owner gate. Never raise a cap. Never delete a STOP file.
+- The runner reviews `risk: high` phases. A phase marked `**Risk:** high`: do not halt for it and do not run the
+  review yourself. When its exit gate is green, set its row `done` and end with `STATUS: CONTINUE`. The runner then
+  reviews it twice and, on findings, starts one fix session.
+- Set the tracker row of the batch to `done` (with its evidence) when its exit gate is green. Set open-work rows with
+  `python <scripts>/caddis_rows.py set` (by row id and column name).
+
+## 5. Write the relay
+
+Write the relay with `python <scripts>/caddis_workstreams.py put --require-status {{slug}} <file>`. Write `<file>` outside
+the repo (for example in the temp folder). Read the current relay first with `python <scripts>/caddis_workstreams.py read {{slug}}`;
+keep its frontmatter shape (`type: relay`, `workstream: {{slug}}`, `branch`, `session_id`, `plan`, `generated.at`). The LAST
+non-empty line must be exactly one of these four:
+
+```
+STATUS: CONTINUE
+STATUS: OWNER-GATE <P>-OG<n>
+STATUS: BLOCKED <owner>
+STATUS: FAILED <reason>
+```
+
+Use `STATUS: CONTINUE` only when the next batch can start with no owner input. A missing or bad line counts as FAILED.
+An owner gate id has the form `<P>-OG<n>`: the plan's 2 to 4 capital-letter prefix (for example `PM-OG1`). Name the gate
+in the plan's decisions with that id. Any other form is a bad line.
+
+## 6. Notify and end
+
+When the status is not CONTINUE, call the `PushNotification` tool as your last action. Put the plan, the status line and the
+next step in the message. After the call succeeds, print the line `PUSH-SENT`. The runner looks for that marker. Without it,
+the runner sends the notification itself.
+
+Then end the session.

package/bundles/antigravity-plugin/skills/roadmap/assets/render-check.template.mjs

@@ -0,0 +1,68 @@
+// Render check template. Copy it into the app (for example frontend/render-check.mjs) so CI and prod checks can run it.
+//
+// Usage:
+//   node render-check.mjs --base http://localhost:5173 --path /dashboard --expect kpi-total --expect chart-main
+//   node render-check.mjs --prod https://app.example.com --path /dashboard --expect kpi-total --channel msedge \
+//        --allow-auth app.example.com
+//   node render-check.mjs --base http://localhost:5173 --path /dashboard --expect kpi-total --prove-it-can-fail
+//
+// Options:
+//   --base <url> | --prod <url>   Origin to test (local or prod). One of them is required.
+//   --path <path>                 Page path. Default "/".
+//   --expect <testid>             A data-testid that must be visible. Repeat it.
+//   --channel <name>              Browser channel, for example msedge. Default: bundled chromium.
+//   --allow-auth <host>           Host that may use the current Windows login (NTLM). Repeat it.
+//   --settle <ms>                 Wait after network idle. Default 3000.
+//   --prove-it-can-fail           Add a test id that does not exist. The run must then exit 1.
+// Exit codes: 0 all checks pass, 1 a check failed, 4 bad arguments.
+import { chromium } from 'playwright'; // or: import { chromium } from '@playwright/test';
+
+const args = process.argv.slice(2);
+const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const all = (name) => args.flatMap((a, i) => (a === name ? [args[i + 1]] : []));
+
+const origin = opt('--prod') ?? opt('--base');
+if (!origin) { console.error('give --base <url> or --prod <url>'); process.exit(4); }
+const path = opt('--path') ?? '/';
+const settle = Number(opt('--settle') ?? 3000);
+const expected = all('--expect');
+const allowAuth = all('--allow-auth');
+if (args.includes('--prove-it-can-fail')) expected.push('testid-that-does-not-exist');
+if (expected.length === 0) { console.error('give at least one --expect <testid>'); process.exit(4); }
+
+const launch = { headless: true };
+if (opt('--channel')) launch.channel = opt('--channel');
+if (allowAuth.length) launch.args = [`--auth-server-allowlist=${allowAuth.join(',')}`];
+
+const failures = [];
+const browser = await chromium.launch(launch);
+for (const width of [1440, 400]) {
+  const context = await browser.newContext({ viewport: { width, height: 900 } });
+  // Dark theme seeded before any page script runs. Change the key and value to match the app.
+  await context.addInitScript(() => { try { localStorage.setItem('theme', 'dark'); } catch { /* ignore */ } });
+  const page = await context.newPage();
+  let consoleErrors = 0;
+  page.on('console', (m) => { if (m.type() === 'error') consoleErrors += 1; });
+  page.on('pageerror', () => { consoleErrors += 1; });
+
+  await page.goto(new URL(path, origin).toString());
+  await page.waitForLoadState('networkidle');
+  await page.waitForTimeout(settle);
+
+  if (consoleErrors > 0) failures.push(`${width}px: ${consoleErrors} console error(s)`);
+  const overflow = await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth);
+  if (overflow) failures.push(`${width}px: horizontal scroll`);
+  for (const id of expected) {
+    const visible = await page.getByTestId(id).first().isVisible().catch(() => false);
+    if (!visible) failures.push(`${width}px: data-testid "${id}" is not visible`);
+  }
+  console.log(`${width}px: console errors ${consoleErrors}, horizontal scroll ${overflow ? 'yes' : 'no'}`);
+  await context.close();
+}
+await browser.close();
+
+if (failures.length) {
+  for (const f of failures) console.error(`FAIL ${f}`);
+  process.exit(1);
+}
+console.log('PASS render check');

package/bundles/antigravity-plugin/skills/roadmap/assets/review-protocol.md

@@ -0,0 +1,78 @@
+---
+type: reference
+title: Review protocol
+description: The review method one model can rely on - invariants, inputs and writers, shared state, execute what the change promises, tests, docs, then severity (only blocking stops the merge; each finding needs a reproduction), one FINDING line per finding and an END REVIEW line. caddis_review.py sends it to every review run.
+status: current
+---
+
+# Review protocol (generic, any diff)
+
+You review a diff. You do NOT edit, create or delete files, and you do not commit. You may read files and run commands
+(tests, dry runs, the commands that plans, cards and docs name). Work through ALL steps in order. Do not stop at the
+first finding. Include a short section per step, in order.
+
+## Step 1 - Purpose and invariants
+Read the card, the plan or design section it cites, and the diff. Write the list of INVARIANTS this change must keep:
+safety limits, gates, money caps, isolation between runs or users, path containment, "X can never cause Y". Include
+invariants that the surrounding system relies on, not only the ones the card names.
+
+## Step 2 - Inputs and who controls them
+List every input the changed code reads: files, file sections, env vars, CLI args, other processes' output, the clock,
+the home folder. For EACH input write: who or what can write it (the owner, an unattended session, another runner,
+a test, a template), and when. Then, for each invariant from step 1, ask: can any writer of any input break it, by
+accident or on purpose? This includes the agent or session the code is meant to limit.
+
+## Step 3 - Shared state and concurrency
+List state that two runs, two kinds of target, or two processes could share (files, locks, relays, logs, caches).
+Can they collide? Can one read the other's output as its own?
+
+## Step 4 - Execute what the change promises
+Run the tests the card names. Then run every command that the plan, its exit gates, the docs or the skill text say
+should work for this change (dry runs, the documented usage lines), exactly as written. Use the repo's OWN fixtures
+and example files, not ones you build, and run unattended scripts (hooks, runners) as they are really run (as a script,
+with a real payload). Compare risky behaviour with the parent commit when the change claims to fix or tighten
+something. Report any that fail or that cannot work as documented.
+
+## Step 5 - Tests
+For each new or changed test: could it pass for the wrong reason (no assertion that can fail, mocked away the thing
+under test)? Does it depend on the real machine (home folder, real STOP files, network, clock, cwd)? Which new
+behaviour has no test, especially the negative cases (placeholders, malformed input, edge values)?
+
+## Step 6 - Docs and contracts
+Compare every doc, skill, prompt asset and usage line touched by or describing this feature with the code. List each
+mismatch (paths, flags, names, steps that do not exist or no longer apply). Check that every tool the new mode is told
+to use supports the new mode.
+
+## Step 7 - Report
+Severity rule. Only **blocking** stops the merge, so use it with care:
+- **blocking** = a defect that breaks a stated invariant from step 1 (safety, security, isolation, a gate passing when
+  it should fail, a crash of something that runs unattended), or loses or corrupts work or data, or breaks a money cap,
+  or makes a documented command fail. Use it even if other limits make the defect unlikely.
+- **should-fix** = a real defect that does not stop the merge: it goes on a follow-up list. Examples: a missing
+  negative test, a doc that is wrong in a way that does not make a command fail, an error message that misleads.
+- **nit** = style and wording.
+
+Every finding needs a concrete reproduction: a command, an input or a test that shows the failure, written in the
+failure scenario. A finding without a reproduction is a **nit**, whatever its severity would otherwise be. Do not
+write "might", "could in theory" or "a future change may": show it or call it a nit.
+
+The gate exits by the findings. A **blocking** finding fails it. **should-fix** and **nit** findings do not: they are
+listed in the report under "Follow-up (not blocking)". The tool allows 3 completed review rounds for a phase; the 4th completed round
+ends with "stop, the owner decides". Report every real defect once, with its true severity, so that one round is
+enough.
+
+End your answer with the findings, one line per finding, in exactly this form (no bullets, no bold, no code block):
+
+```
+FINDING <n> | <severity> | <file>:<line> | <one-sentence failure scenario>
+```
+
+`<n>` counts from 1, `<severity>` is `blocking`, `should-fix` or `nit`. Put the reproduction in the one sentence
+(for example `... ; reproduce: python x.py --flag with an empty file`). If you have no findings, write the line
+`NO FINDINGS` instead. The very last line of your answer is `END REVIEW <count>`, where `<count>` is the number of
+FINDING lines (`END REVIEW 0` after `NO FINDINGS`). A review whose last line is missing or whose count is wrong is
+treated as not run. Do not write a verdict line: the gate reads the findings only.
+No other line may contain the word FINDING followed by a number, anywhere in the line (in any case, also as
+`finding-1`, `finding #1`, `finding (1)`, after a bullet, a `>`, a table `|` or any other text): such a line that is
+not a complete FINDING line also makes the review count as not run. In your step sections, write "issue 1", not
+"finding 1".

package/bundles/antigravity-plugin/skills/roadmap/assets/roadmap.template.md

@@ -0,0 +1,32 @@
+# <slug> roadmap
+
+Runner host: HOSTNAME
+
+The roadmap file on `origin/main` is the only truth. Change it with `scripts/caddis_roadmap.py` (each change is a small
+docs PR), never by a direct push. Only `rollup` sets a milestone `done`.
+
+## Milestones
+| ID | Milestone | Phases | Depends on | Exit check | Status | Owner | Target |
+|---|---|---|---|---|---|---|---|
+| S1 | <what is true when it is done> | <plan>#1, <plan>#2 | - | `<command that exits 0 when S1 holds>` | todo | runner | <date> |
+
+## Blockers
+| Milestone | Type | Reason | Check |
+|---|---|---|---|
+
+## Notes
+
+- Status: todo, in-progress, code-done/data-pending, done or not-needed (blocked = has a Blockers row).
+- Blocker types: owner-gate, external, shared, calendar or data-condition (Check: a command, added by the owner
+  only; recheck runs it in a worktree of origin/main and clears that row on exit 0). A calendar blocker's Check is
+  an ISO date YYYY-MM-DD; recheck clears the row once that date has passed.
+- Status not-needed needs --reason "dropped: why" or --reason .caddis/parking-lot/file.md; the reason is added
+  below as "- id not-needed: reason (date)".
+- status lists each blocker row older than 14 days as "old blockers: id type (N days)"; the age comes from git.
+- A malformed section (wrong cell count, a row without a leading pipe, a line right after the table, a pipe in
+  prose, a second table, a renamed heading) stops every command: fix it by a PR. Escape a pipe in prose as \|.
+- This file allows only headings, plain paragraphs, lists and pipe tables: no code fences, no HTML, no setext
+  headings, no control or non-ASCII whitespace characters. GitHub would hide or move lines the parser reads, so
+  each one is a parse error.
+- Owner: runner (or empty) = the runner may take it; a session name = that session does it by hand.
+- A Depends on change cites a decision id from decisions.md in the Milestone cell: `S9 (dep waived: D4)`.