@caddis/cli 0.4.13 → 0.4.15

package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md

@@ -126,6 +126,24 @@ A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
   `claude-glm -p "/caddis:implement <plan-path> — Phase N only"` (from the repo root, on the
   feature branch). The local-coder gate below exists exactly so these phases survive a weaker
   implementer — a phase may only take this lane if it passes that gate.
+- **codex-sol / codex-astra / agy / glm (via caddis_lanes)** — select one of these five task types
+  and its default chain:
+  - `backend`: `glm`, `codex-sol`, `claude`
+  - `hard`: `claude`, `codex-astra`
+  - `ui`: `claude`, `codex-astra`
+  - `tests`: `codex-sol`, `glm`, `claude`
+  - `docs`: `agy`, `glm`, `claude`
+  Use `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" run --plan <plan-path> --phase N
+  --type <type>` as the launch command. The chains are defaults, not limits on Claude: while Claude
+  has budget, give any phase the `claude` lane. Override chains and model pins per project in
+  `.caddis/config.toml` `[lanes.chains]` and `[lanes.models]`.
+
+**Evidence standard — never plan a load test on a shared host.** Prove timing robustness with
+event-driven fakes, ordering assertions and an A/B check that fails against the racy version. A phase
+must never ask for CPU burners, stress tests, load tests or "every core". `caddis_lanes.py` refuses
+this wording. The host guard kills runaway agent processes. On 2026-09-13, 32 all-core busy loops
+froze CI on the dev box.
+
 - **review lane (every phase that touches code)** — cross-vendor review by a vendor that did NOT
   write the code: `/caddis:cross-review --range main..HEAD`
   (Claude or GLM implemented) or `--provider glm` / a Claude `code-reviewer` pass (DeepSeek-adjacent
@@ -219,6 +237,7 @@ Creating Model: <model-id>
 **Milestone:** M1  *(omit on plans without milestones)*
 **Model:** <tier> (`/model <alias>`) — <one-line rationale tied to this phase's difficulty>
 **Lane:** claude — this session  |  glm-headless — `claude-glm -p "/caddis:implement <this plan's path> — Phase 1 only"`
+**Type:** backend | hard | ui | tests | docs  *(required when the Lane runs through caddis_lanes.py)*
 **Session:** continue | **fresh** (start a new session for this phase — note why: lane change / heavy context)
 **Risk:** high — token-verification seam; a wrong answer here is a silent auth bypass  *(omit this line when normal)*
 **Goal:** <one sentence>
@@ -273,6 +292,11 @@ yourself (relay + Tracker) before stopping — do not hand back "run `/caddis:ha
 - **Ship gate:** NEVER push or merge to main from a phase — phases only commit to the feature branch.
   When all phases are ✅: `/caddis:ship-pr` (stops at green CI), then STOP and wait for the human's
   explicit go before `/caddis:ship-merge`.
+- **Finish:** after the last phase, run `caddis_lanes.py finish --plan <plan>`; the plan is not done
+  until it prints `LEFTOVERS: 0` (merged lane worktrees and branches removed, unmerged or dirty ones
+  reported, feature branch pushed; merging to main stays with `/caddis:ship-merge`).
+- **No load wording** — no phase asks for a CPU burner, stress test, load test or "every core"; prove
+  timing by design.
 
 ## Affected files
 | File | Action |
@@ -303,16 +327,18 @@ done:
 - **No abbreviation** — never "etc.", "similar to Phase 1", "and so on". Write every item in full.
 - **Model tier named** — every phase names a tier (cheap/mid/frontier/ultra) + a one-line rationale; no
   phase silently defaults to the most expensive model. Default mid; frontier/ultra only where justified.
-- **Lane + reviewer named** — every phase names its execution lane (`claude` or `glm-headless`, with
-  the literal launch command for glm phases) and a cross-review provider that is a different vendor
-  than the implementer. A glm-headless phase MUST pass every bullet of this gate — that lane has no
-  slack for reasoning out gaps.
+- **Lane + reviewer named** — every phase names its execution lane (`claude`, `glm-headless`, or a
+  `caddis_lanes.py` lane with its `**Type:**`, with the literal launch command for every non-claude
+  phase) and a cross-review provider that is a different vendor than the implementer. A glm-headless
+  phase MUST pass every bullet of this gate — that lane has no slack for reasoning out gaps.
 - **Launch command is spawnable** — every `glm-headless` phase's command carries **`-p`** (or
   `--print`) and ends with **`— Phase N only`**. Both are load-bearing, not style: the launchers set
   `CADDIS_HEADLESS` *only* on `-p`, and that variable is the guard that stops a spawned session
   spawning another one forever; the `Phase N only` suffix is what stops the child running to the end
   of the plan. The command is executed verbatim by a model with no slack to notice a missing flag,
   and `/caddis:implement` now refuses a command without `-p` rather than running it.
+- **caddis_lanes command carries --phase** — a `caddis_lanes.py` launch command must name `--phase N`
+  and `--type`; lane-check refuses one without `--phase`.
 - **Gate-detectable** — if this phase's instruction were WRONG, its exit gate would go red. A phase
   whose gates pass either way (copy, nav entries, badges, ordering, wording, config defaults) must
   not take a lane that cannot escalate, no matter how completely it is specified. Every other bullet

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

@@ -101,6 +101,51 @@ the bug the lane routing exists to fix.
 lane the plan planned. A deviation then shows up as a diff between the phase block and the tracker
 row, visible to any later reader without an Advisory Hub having to catch it live.
 
+**Multi-lane phases — `caddis_lanes.py`.** Use this procedure when the phase launch command is
+`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" run …`.
+
+1. In an interactive session, run the phase's literal command. The script creates a temporary
+   worktree. It runs the lane or its fallback chain inside a resource-capped job. It re-runs the
+   gates with the repo interpreter. It runs the DeepSeek review. It then prints a `NEXT:` line.
+2. Obey `NEXT:`:
+   - `review` → read the packet JSON and inspect `git -C <worktree> diff`. Then decide ACCEPT or REDO.
+   - `redo` → run `abandon`. Then run `run` with `--attempt 2 --findings <file with your findings>`.
+   - `takeover` → run `abandon`. Then implement the phase yourself on the `claude` lane.
+   - `claude-implement` → write the code in the printed worktree. Then run `check`.
+   - `stop` → report the result and halt. `stop (host guard killed the lane…)` means
+     `FAILED-RESOURCE`. The lane saturated the host. Never re-run it with more load. Fix the phase
+     so it proves timing by design.
+3. **ACCEPT** means run `caddis_lanes.py accept --plan <plan> --phase N --attempt K --message
+   "<the phase's commit message>"`. It runs only on the programme branch, never on `main`. It
+   refuses a `BLOCKING` review. If you checked the finding and it is false, add
+   `--override-review "<why the finding is false>"`. The script records that reason in the packet.
+4. Allow at most **2 attempts** per phase on a non-Claude lane. An out-of-budget switch is not an
+   attempt. The owner can request TAKEOVER at any time.
+5. A UI phase needs a `ui-design-reviewer` screenshot review before ACCEPT. This rule applies
+   whichever lane wrote the phase.
+6. A phase that Claude wrote needs a vendor review that is not MISSING. If `review.status` is
+   `MISSING`, run `codex exec -m gpt-5.6-sol -s read-only -C <worktree> --skip-git-repo-check -`.
+   Give the diff to the command on stdin.
+6b. **Orchestrator artefacts live under `.caddis/orchestrator/`.** Store packets and locks in
+    `lane-runs/`. Store evidence notes as markdown directly in `.caddis/orchestrator/`. Follow its
+    `AGENTS.md`. Never write orchestration notes to `.caddis/kb/`.
+7. **Never write a load or stress test into a lane prompt or findings file.** The script refuses
+   this wording without `--allow-load`. Only the owner gives that flag.
+8. Record these Tracker values:
+   - `Model` = the packet's `model`.
+   - `Lane` = the lanes tried, joined with ` -> ` and followed by the reason. For example,
+     `glm -> codex-sol (glm out of budget)`.
+   - `Cross-review` = `CLEAN`, `BLOCKING` or `missing`.
+   - `Notes` = `attempt K, ACCEPT|TAKEOVER|FAILED-RESOURCE`.
+9. The PR body lists every phase accepted with `review.status == MISSING`. It also lists every phase
+   accepted while Codex astra stood in for Claude.
+9b. **Finish.** After the last phase, run `caddis_lanes.py finish --plan <plan>`. It removes merged
+    lane worktrees and branches. It reports unmerged or dirty ones. It pushes the feature branch.
+    The plan is not done until it prints `LEFTOVERS: 0`. Then run `/caddis:ship-pr`. Merging and
+    post-merge cleanup stay with `/caddis:ship-merge` after the owner's go.
+10. **When Claude is out of budget**, the owner opens `caddis-run codex -m gpt-6-astra` and asks it
+    to follow this same subsection.
+
 **Advisory-Hub mode (conditional — OFF by default).** Check whether a companion file
 `<plan-dir>/<plan-stem>-advisory-context.md` exists (e.g. plan `.caddis/plans/foo.md` → look for
 `.caddis/plans/foo-advisory-context.md`). **If it does not exist — the normal case, including every
@@ -187,7 +232,9 @@ report — do not redo completed work.
      first, every phase, not just the one you resumed at. Step 1's check only ever saw the *resume*
      phase: on a plan whose phase 1 is `claude` and phase 2 is `glm-headless`, it finds no mismatch and
      this loop then carries you straight through phase 2 — so the lane silently executes nothing for
-     every phase after the first, which is the original bug wearing a different hat.
+     every phase after the first, which is the original bug wearing a different hat. For a
+     `caddis_lanes.py` launch command, follow "Multi-lane phases" above instead of spawning the command
+     blind.
    - **RED** — write the failing test(s) the phase names (`<test file>::<case>`). Run them; confirm they
      fail for the right reason (the missing behavior, not an import error). If a phase genuinely has no
      testable surface, say so in the review file and implement the minimal change directly.

package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: pr-merge
+description: End-to-end pull request and merge lane — push feature branch, open or update PR, monitor CI to green, merge to default branch, and clean up the feature branch.
+---
+
+# /pr-merge — the unified reviewed lane: branch → PR → green → merged → cleaned up
+
+End-to-end delivery of feature-branch work through the reviewed lane in one shot: run preflight checks,
+push safely, create or update the Pull Request, monitor CI checks to green, merge into the default
+branch, validate the deployment, and clean up the feature branch.
+
+For a hotfix straight to the default branch with no PR ceremony, use `/ship` (the express lane) instead.
+To open a PR and stop at green for human review without merging, use `/ship-pr`.
+To merge an already-opened PR, use `/ship-merge`.
+
+Optional argument: **$ARGUMENTS** (PR title override; default = derived from the branch's
+conventional-commit summary). An optional strategy override (`squash` | `merge` | `rebase`)
+can be provided.
+
+## Step 0 — Detect the lane (before anything else)
+
+- **Gitea lane** — `.gitea/workflows/` exists. PR creation, CI monitoring, and merge via the Gitea API
+  (token loading and job-polling procedure: the `deploy-local` skill).
+- **GitHub lane** — `.github/workflows/` exists (and no `.gitea/`). PR creation, checks monitoring,
+  and merge via the `gh` CLI (`gh pr create`, `gh pr checks --watch`, `gh pr merge` — see the `gh-cli` skill).
+- **Local-only lane** — neither exists, or there is no push remote. There is no forge and no PR concept:
+  **refuse early**, tell the user to use `/ship`, and stop. Do not fabricate a PR flow.
+
+Read `AGENTS.md` + the detected workflow file(s) first for the repo's real gate names, default
+branch, and merge conventions — never assume `main`, never assume job names.
+
+## Step 1 — Refuse on the default branch
+
+A PR is *branch → default*. If HEAD **is** the default branch, stop and point at `/ship` — there is
+nothing to open a PR from. (Offer to create a feature branch from the current work if the changes
+are uncommitted.)
+
+## Step 2 — Preflight (local gates mirroring CI)
+
+- Backend: `ruff check .` clean (or repository linter).
+- Frontend: `npm run typecheck && npm run build` if `frontend/` exists.
+- Fix failures first. **Never open a PR over red preflight** — a PR that arrives red wastes CI resources
+  and reviewer time.
+
+## Step 3 — Scope-guard pre-check (before the PR exists)
+
+- If the repo has a **named scope-guard workflow** (e.g. a Gitea `pr-scope-guard` that blocks PRs
+  mixing infra `.gitea/`/`.github/` changes with product `src/`/`frontend/`/`tests/` changes): read
+  the workflow's own rule and check the branch diff against exactly that rule **before** creating
+  the PR. On a violation, **refuse with the specific offending files** — do not let the guard fail
+  the PR after the fact.
+- Without a named guard, apply the generic infra-vs-product mixed-diff heuristic as a **warning
+  only** — surface it and proceed (repos without a guard allow mixed PRs by construction).
+
+## Step 3b — Cross-review trigger (before anything is pushed)
+
+<!-- shared:cross-review-trigger — keep byte-identical across commands; a test pins it -->
+**Run the trigger, do not eyeball the diff:**
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-trigger --range <base>...HEAD
+```
+
+Exit **0** — say nothing, carry on. Exit **2** — it prints which rule fired and on which files.
+Run `/caddis:cross-review`, show the findings, and let the user decide. It **never blocks**: this
+picks when to ask for a second opinion, it is not a verdict, and a review gate that blocks a ship
+gets switched off inside a week.
+
+It fires on SQL and repositories, `services/`, caches and refresh jobs, auth and RBAC, or a diff
+over 400 changed lines. No judgement in any of those — deliberately, because judgement is exactly
+what failed.
+<!-- /shared:cross-review-trigger -->
+
+## Step 4 — Rebase-safe currency
+
+- If the branch is **behind** the default branch, offer to rebase onto it (stale branches are how
+  merges rot). Only when behind — never rebase gratuitously.
+- If the branch was already pushed, a rebase rewrites history. **Snapshot first, then push safely:**
+  ```
+  git branch backup/<branch>-preship          # recovery ref BEFORE any rewrite
+  git rebase <default-branch>
+  git push --force-with-lease origin <branch> # never bare --force
+  ```
+
+## Step 5 — Push + create or update the PR
+
+- Push the branch to remote (plain push if no rewrite happened).
+- Create the PR: title from the branch's conventional-commit summary (or `$ARGUMENTS`); body = the
+  commit list + a "generated by /pr-merge" note.
+- **Idempotent:** if a PR for this branch **already exists**, reuse it, update its title/body, and
+  report it — never error, never open a duplicate.
+
+## Step 6 — Monitor PR CI checks
+
+Watch the PR's checks job-by-job until completion:
+- Gitea lane: poll the run for the PR's head SHA via the API (`deploy-local` skill procedure).
+- GitHub lane: `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
+- If any check fails (red check): report the failure, classify the cause, and **stop before merging**.
+  Do not merge a failing PR. Apply the minimum source fix and re-push.
+
+## Step 7 — Merge to default branch
+
+Once all required checks are **green**, there are no merge conflicts, and review requirements are satisfied:
+- Use the repo's configured **merge strategy** — read it from repo settings (Gitea repo settings API /
+  `gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed`) and `AGENTS.md`;
+  an explicit argument wins. Options: **squash**, **merge-commit**, rebase-merge. **Don't assume** —
+  if detection is inconclusive, use merge-commit (never silently squash someone's history without evidence).
+- Execute merge:
+  - GitHub: `gh pr merge <pr> --<strategy>` (e.g. `gh pr merge <pr> --squash`).
+  - Gitea: call the Gitea PR merge API with the chosen strategy.
+- Record the merge SHA.
+
+## Step 8 — Monitor deployment & validate (if applicable)
+
+If the default branch triggers an automated deployment pipeline:
+- Gitea: `lint_and_test` → `deploy_prod` → `release_metadata` (`deploy-local` skill).
+- GitHub: `gh run watch <run-id> --exit-status` on the default branch. If CI-only, note that no deploy occurs.
+- Validate health and deployed SHA if a live service is deployed. If deploy validation fails, report
+  immediately and **skip cleanup** (Step 9).
+
+## Step 9 — Close feature-branch lifecycle (Clean up)
+
+**Only after** the merge is complete and deployment (if any) is validated green:
+- Switch to the default branch: `git switch <default-branch>`.
+- Fast-forward to the merge commit: `git pull --ff-only origin <default-branch>`.
+- Delete the **local** feature branch: `git branch -d <branch>` (use `-D` only if squashed after verifying tree contents match).
+- Delete the **remote** feature branch: `git push origin --delete <branch>` (if not deleted by forge).
+- Drop the temporary `backup/<branch>-preship` ref if one was created in Step 4.
+
+If deploy validation failed: **skip cleanup** entirely and report why — never delete a branch whose
+work may need re-work.
+
+## Step 10 — Report
+
+```
+PR:            #<n> <title> — merged (<strategy>) as <merge-sha>
+Checks:        <check ✓ per check>
+Deploy:        <job ✓ / ✗ per job | n/a>
+Prod SHA:      matches merge ✓ | n/a
+Cleanup:       remote branch deleted / local branch deleted / backup ref dropped | SKIPPED (<why>)
+```
+
+## Rules
+
+- Never merge a PR whose required checks are red or absent.
+- Never delete a feature branch before its merge is confirmed and any deploy validated.
+- Never `git add -A` without reviewing `git status` first (stage named files only).
+- Never force-push without a `backup/*-preship` recovery ref; force pushes are `--force-with-lease` only.
+- Never edit a workflow file (`.gitea/workflows/`, `.github/workflows/`) to make a gate pass — fix the source.
+- Local-only lane: refuse + point at `/ship`. On the default branch: stop + point at `/ship`.
+
+## Skill reference
+
+Gitea API monitoring, deploy tracking, failure triage: the `deploy-local` skill (ships in optional `caddis-extras`).
+GitHub `gh pr create`, `gh pr checks`, `gh pr merge`: the `gh-cli` skill.

package/bundles/antigravity-plugin/warm_start_agy.py

@@ -50,6 +50,29 @@ RELAY_FRAME_FOOTER = "=== end session-context ==="
 
 _TRUTHY = {"1", "true", "yes", "on"}
 
+# The freshness report (fetch, then say how far this checkout is from the remote default
+# branch) is the ONE piece here that is imported rather than duplicated: the agy bundle ships
+# hooks/repo_freshness.py beside this file, listed in runtime-targets.json. In the source repo
+# it sits one directory over, so both layouts resolve. Fail open — an older bundle without it
+# simply reports no freshness.
+try:
+    _HOOKS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "hooks")
+    if os.path.isdir(_HOOKS_DIR) and _HOOKS_DIR not in sys.path:
+        sys.path.append(_HOOKS_DIR)
+    import repo_freshness  # noqa: E402
+except Exception:
+    repo_freshness = None  # type: ignore[assignment]
+
+
+def freshness_lines(root: str) -> list[str]:
+    """Where `root` stands against the remote default branch; [] on any problem."""
+    if repo_freshness is None:
+        return []
+    try:
+        return repo_freshness.report(root)
+    except Exception:
+        return []
+
 
 def is_headless() -> bool:
     """True when no human is watching — a run given its task explicitly needs no resume pointer."""
@@ -268,11 +291,22 @@ def main() -> None:
             if conversation:
                 _mark_injected(root, conversation)
 
-        if not blocks:
+        # agy has no SessionStart event, so this first invocation is also where the freshness
+        # report belongs. It is emitted even when there is no relay to inject, and it stays
+        # silent in a repo that is clean, level and on the default branch.
+        fresh: list[str] = []
+        for root in roots:
+            fresh.extend(freshness_lines(root))
+
+        if not blocks and not fresh:
             return
-        message = (RELAY_FRAME_HEADER + "\n" + "\n\n".join(blocks)
-                   + "\n\n" + RELAY_FRAME_FOOTER)
-        payload = json.dumps({"injectSteps": [{"ephemeralMessage": message}]})
+        parts = []
+        if blocks:
+            parts.append(RELAY_FRAME_HEADER + "\n" + "\n\n".join(blocks)
+                         + "\n\n" + RELAY_FRAME_FOOTER)
+        if fresh:
+            parts.append("\n".join(fresh))
+        payload = json.dumps({"injectSteps": [{"ephemeralMessage": "\n\n".join(parts)}]})
         sys.stdout.write(payload)
     except Exception:
         return  # fail open: no injection is always better than a broken invocation