@caddis/cli 0.4.70 → 0.4.71

package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""caddis_upstream_check - say when an upstream skill that caddis borrowed ideas from has changed.
+
+Why: /caddis:feature-plan and /caddis:implement adapt ideas from obra/superpowers (writing-plans 7.0.0,
+subagent-driven-development 7.0.0, MIT). `.github/upstream-sources.json` records, per borrowed file, the
+upstream version and the sha256 of the file we read. This script compares that record with the copies
+installed in the Claude Code plugin cache (`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/<path>`),
+so caddis does not fall behind upstream without anyone seeing it. /caddis:usage-review runs it.
+
+One line per source:
+    UP-TO-DATE <id> <version>
+    DRIFT <id> recorded <v> installed <v'> (sha differs): review the upstream diff and port what fits, ...
+    NOT-INSTALLED <id>
+`NO-SOURCES <path>` means there is no record (any repo other than the caddis source repo).
+
+Advisory only: the exit code is always 0. Stdlib only.
+
+Usage:
+    python caddis_upstream_check.py [--sources <json>] [--cache-root <dir>] [--json]
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+SOURCES_REL = Path(".github") / "upstream-sources.json"
+DRIFT_ADVICE = "review the upstream diff and port what fits, then update .github/upstream-sources.json"
+
+
+def default_sources() -> Path:
+    """The record in the current repo; else the one next to this script in a source checkout."""
+    here = Path.cwd() / SOURCES_REL
+    if here.is_file():
+        return here
+    return Path(__file__).resolve().parents[1] / SOURCES_REL
+
+
+def default_cache_root() -> Path:
+    return Path.home() / ".claude" / "plugins" / "cache"
+
+
+def _version_key(version: str) -> tuple:
+    """Numeric parts compare as numbers (7.10.0 > 7.9.0); a non-numeric part sorts before any number."""
+    return tuple((1, int(p)) if p.isdigit() else (0, p) for p in version.split("."))
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def installed_copies(cache_root: Path, plugin: str, rel_path: str) -> list[tuple[str, Path]]:
+    """(version, file) for every installed copy, newest version last."""
+    if not cache_root.is_dir():
+        return []
+    found = [(f.parents[len(Path(rel_path).parts) - 1].name, f)
+             for f in cache_root.glob(f"*/{plugin}/*/{rel_path}") if f.is_file()]
+    return sorted(found, key=lambda vf: _version_key(vf[0]))
+
+
+def check_source(src: dict, cache_root: Path) -> dict:
+    sid, recorded = src["id"], src["version"]
+    plugin = sid.split(":", 1)[0]
+    copies = installed_copies(cache_root, plugin, src["path"])
+    row = {"id": sid, "status": "NOT-INSTALLED", "recorded_version": recorded, "installed_version": None,
+           "line": f"NOT-INSTALLED {sid}"}
+    if not copies:
+        return row
+    version, newest = copies[-1]
+    row["installed_version"] = version
+    if _sha256(newest) == src["sha256"]:
+        row.update(status="UP-TO-DATE", line=f"UP-TO-DATE {sid} {recorded}")
+    else:
+        row.update(status="DRIFT",
+                   line=f"DRIFT {sid} recorded {recorded} installed {version} (sha differs): {DRIFT_ADVICE}")
+    return row
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Compare borrowed upstream skills with the installed copies.")
+    ap.add_argument("--sources", type=Path, default=None, help="path to upstream-sources.json")
+    ap.add_argument("--cache-root", type=Path, default=None, help="the Claude Code plugin cache folder")
+    ap.add_argument("--json", action="store_true", help="print the rows as a JSON list")
+    args = ap.parse_args(argv)
+    sources = args.sources or default_sources()
+    cache_root = args.cache_root or default_cache_root()
+    if not sources.is_file():
+        print(f"NO-SOURCES {sources}")
+        return 0
+    try:
+        data = json.loads(sources.read_text(encoding="utf-8"))
+        rows = [check_source(src, cache_root) for src in data.get("sources", [])]
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        print(f"NO-SOURCES {sources} (unreadable: {exc})")
+        return 0
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for row in rows:
+            print(row["line"])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundles/antigravity-plugin/scripts/schemas/coordinator.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "caddis hub coordinator state (coordinator.json)",
+  "description": "One file per repo id, written only by caddis_coordinate.py. Readers accept schema N and N-1.",
+  "type": "object",
+  "required": ["schema", "repo", "coordinator_session", "heartbeat_at", "queue", "merging_now", "deploy_checks",
+               "ledger", "processed_requests"],
+  "properties": {
+    "schema": {"type": "integer", "enum": [0, 1]},
+    "repo": {"type": "string", "minLength": 1},
+    "coordinator_session": {
+      "type": "object",
+      "required": ["name", "sessionId", "pid"],
+      "properties": {
+        "name": {"type": ["string", "null"]},
+        "sessionId": {"type": ["string", "null"]},
+        "pid": {"type": ["integer", "null"]}
+      }
+    },
+    "heartbeat_at": {"$ref": "#/$defs/utc"},
+    "queue": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pr", "head_sha", "title", "state", "why_waiting", "waits_on", "hotfix", "held",
+                     "entered_ready_at"],
+        "properties": {
+          "pr": {"type": "integer", "minimum": 1},
+          "head_sha": {"type": "string"},
+          "title": {"type": "string"},
+          "state": {"enum": ["waiting", "ci", "ready", "merging", "blocked", "held"]},
+          "why_waiting": {"type": "string"},
+          "waits_on": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["repo", "pr"],
+              "properties": {"repo": {"type": "string"}, "pr": {"type": "integer"}}
+            }
+          },
+          "hotfix": {"type": "boolean"},
+          "held": {"type": "boolean"},
+          "entered_ready_at": {"anyOf": [{"$ref": "#/$defs/utc"}, {"type": "null"}]}
+        }
+      }
+    },
+    "merging_now": {"type": ["integer", "object", "null"]},
+    "deploy_checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pr", "merge_sha", "deploy_run", "health", "at"],
+        "properties": {
+          "pr": {"type": "integer"},
+          "merge_sha": {"type": "string", "pattern": "^[0-9a-f]{40}$", "description": "lower-cased"},
+          "deploy_run": {"type": ["integer", "null"]},
+          "health": {"enum": ["pending", "ok", "failed"]},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    },
+    "ledger": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["what", "decision", "approved_by", "reason", "window", "request_id", "at"],
+        "properties": {
+          "what": {"type": "string", "minLength": 1},
+          "decision": {"enum": ["approve", "decline"]},
+          "approved_by": {"enum": ["owner", "coordinator"]},
+          "reason": {"type": "string", "minLength": 1},
+          "window": {"type": ["string", "null"], "description": "the session window the decision was made in; \"hub\" for an owner click"},
+          "request_id": {"type": ["string", "null"], "description": "the owner request id; null when not from a request"},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    },
+    "processed_requests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "result", "reason", "at"],
+        "properties": {
+          "id": {"type": "string"},
+          "result": {"enum": ["done", "rejected", "expired"]},
+          "reason": {"type": "string"},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    }
+  },
+  "$defs": {
+    "utc": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"}
+  }
+}

package/bundles/antigravity-plugin/scripts/schemas/request.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "caddis hub owner request (one line of requests.jsonl)",
+  "description": "Appended by the hub, applied by caddis_coordinate.py intake. Readers accept v N and N-1. pr may be null only for approve/decline, and then args.what is required (ruling R2).",
+  "type": "object",
+  "required": ["v", "id", "created_at", "expires_at", "repo", "pr", "head_sha", "action", "args"],
+  "additionalProperties": false,
+  "properties": {
+    "v": {"type": "integer", "enum": [0, 1]},
+    "id": {"type": "string", "minLength": 1},
+    "created_at": {"$ref": "#/$defs/utc"},
+    "expires_at": {"$ref": "#/$defs/utc"},
+    "repo": {"type": "string", "minLength": 1},
+    "pr": {"type": ["integer", "null"], "minimum": 1},
+    "head_sha": {"type": ["string", "null"], "description": "40 hex characters when pr is set; compared case-insensitively"},
+    "action": {"enum": ["hotfix", "unhotfix", "hold", "release", "approve", "decline"]},
+    "args": {
+      "type": "object",
+      "properties": {"what": {"type": "string", "minLength": 1}}
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"pr": {"type": "null"}}, "required": ["pr"]},
+      "then": {
+        "properties": {
+          "action": {"enum": ["approve", "decline"]},
+          "args": {"required": ["what"]}
+        }
+      },
+      "else": {
+        "properties": {"head_sha": {"type": "string", "pattern": "^[0-9a-fA-F]{40}$"}}
+      }
+    }
+  ],
+  "$defs": {
+    "utc": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"}
+  }
+}

package/bundles/antigravity-plugin/skills/_registry.md

@@ -58,7 +58,7 @@
 | Office Documents Official | `office-documents-official/` | Hint for Office and PDF file work. Use when the user asks to create, edit, read or convert a Word .docx, PDF, PowerPoint .pptx or Excel .xlsx file. caddis does not ship these skills; points to Anthropic's official document-skills plugin. |
 | Tech Explainer | `tech-explainer/` | >- |
 | Technical Writing | `technical-writing/` | Documentation best practices for READMEs, API docs, architecture docs, runbooks and developer guides. Use when writing or reviewing docs or setting documentation standards. |
-| Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |
+| Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code. In caddis, plans are written with /caddis:feature-plan, the only plan writer; this skill sends you there. |
 
 ### Frontend
 

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

@@ -45,7 +45,7 @@ Start by understanding the current project context, then ask questions one at a
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
 - Use the `using-git-worktrees` skill (caddis, devops/) to create an isolated workspace
-- Use `/caddis:feature-plan` for a phased plan, or the `writing-plans` skill (caddis, docs/)
+- Use `/caddis:feature-plan` to write the plan (it is the only plan writer in caddis)
 
 ## Key Principles
 

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

@@ -12,6 +12,9 @@ If `$ARGUMENTS` is empty, ask what to plan and stop.
 The plan file is the **durable spine of the harness** — it must let any future session (or another
 agent, on any tool) resume with zero re-discovery. Optimize for that.
 
+This command is the only plan writer in caddis. The task-level shape, Global Constraints, Review Focus and
+the self-review checklist are adapted from obra/superpowers `writing-plans` 7.0.0 (MIT); see NOTICE.md.
+
 ## Headless mode
 When the invocation contains the marker **`HEADLESS RUN RULES`**, **or `CADDIS_HEADLESS` is set in
 the environment** (the caddis OSS launchers export it on claude's `-p`/`--print`) — a non-interactive
@@ -186,6 +189,29 @@ internal repo path into stakeholder-facing copy, and set a `live` status flag th
 framework's own "Soon" badge). `tsc` clean, 632/632 tests green, cross-review CLEAN, exit gate
 satisfied. A headless run following it literally would have committed both, entirely green.
 
+### Choose how each phase's tasks run (`Execution:`)
+Write one `Execution:` line per phase, next to its `Lane:` and model lines. A fixed rule picks it:
+- **`Execution: per-task`** when the phase has 3 or more tasks that consume each other's interfaces,
+  OR when a mistake would be costly: security, data loss, money, merges or deploys, concurrency.
+- Otherwise `Execution: inline`.
+
+`inline` means today's behaviour: one implementer does the whole phase. `per-task` means the executor
+gives each task a fresh implementer (on the phase's model tier and lane) and a short task review (spec
+compliance, then quality) before the next task starts. The task review does not replace the phase's review by another vendor:
+`review-tier` and `/caddis:cross-review` still run once per phase.
+
+A `per-task` phase is split into tasks. Each task must have:
+- **`Files:`** — every file to create, modify and test, with exact paths.
+- **`Interfaces:`** — `Consumes:` (what it uses from earlier tasks) and `Produces:` (what later tasks
+  use): exact names, parameters and return types. An implementer sees only its own task; this block is
+  how it learns the names that its neighbours use.
+- **Steps** — write the failing test (its name, its assertions and the exact values from the spec); run
+  it, expected FAIL; implement the named signature; run it, expected PASS; commit with named files.
+
+A task is the smallest unit that has its own test cycle and is worth its own review. Put setup, config
+and docs steps in the task whose deliverable needs them. An `inline` phase may keep the lighter shape of
+the phase template.
+
 ### Group phases into MILESTONES — only when the plan is big enough
 **Add milestones when the plan has ~8+ phases OR spans multiple sessions.** Below that, phases and a
 Tracker are enough; a three-phase feature gains nothing from ceremony.
@@ -240,6 +266,16 @@ Creating Model: <model-id>
 ## Constraints & decisions
 - <key tech decision + rationale>
 
+## Global Constraints
+<The project-wide requirements: version floors, dependency limits, naming and copy rules, platform needs.
+One line each, with the exact values copied from the spec or PRD. Every phase's requirements include
+this section.>
+
+## Review Focus
+<Up to five inputs or failure modes that the spec implies but no task test exercises, most likely first.
+One line each: the input or condition, and the behaviour a user expects. Each line gets a test, added
+to the phase or task that owns the code. Write "none found" only after you checked.>
+
 ## Phases
 
 ### Phase 1 — <name>  ⏳
@@ -249,6 +285,7 @@ Creating Model: <model-id>
 **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)*
+**Execution:** inline | per-task  *(the rule in Step 2; per-task phases list their tasks below)*
 **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>
@@ -264,6 +301,18 @@ Creating Model: <model-id>
 **Then:** update the Tracker row (status + hash). If this phase ends the session, WRITE the handoff
 yourself (relay + Tracker) before stopping — do not hand back "run `/caddis:handoff`" as the next action.
 
+#### Task 1.1 — <name>  *(per-task phases only)*
+**Files:** create `<path>` · modify `<path>` · test `<test path>`
+**Interfaces:**
+  - Consumes: `<name>(<params>) -> <return type>` from Task <N.M>, or "none"
+  - Produces: `<name>(<params>) -> <return type>`
+**Steps:**
+  1. Write the failing test `<test path>::<case>`: assert `<call>` == `<exact value from the spec>`.
+  2. Run `<literal test command>`: expected FAIL (<the reason, not an import error>).
+  3. Implement `<name>(<params>) -> <return type>` in `<path>`.
+  4. Run `<literal test command>`: expected PASS.
+  5. Commit: `git add <named files>` then `git commit -m "<message>" -- <named files>`.
+
 ### Phase 2 — <name>  🔲
 <same structure>
 
@@ -278,6 +327,8 @@ Three rules: one attempt, one review.
 
 - One phase at a time: read this plan → run the phase on its **Lane** → RED→GREEN→VERIFY→CROSS-REVIEW→
   COMMIT → update the **Tracker** row. The Tracker is the resume signal for every future session.
+  An `Execution: per-task` phase runs task by task: a fresh implementer per task, and a task review
+  before the next task. The cross-review still runs once for the phase.
 - **Session boundaries:** the executor WRITES the handoff (durable `relay.md` + Tracker) after any
   phase that ends a sitting — it performs the work, it does not suggest the command. Start a FRESH
   session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or whenever
@@ -360,6 +411,8 @@ done:
   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.
+- **Execution named** — every phase has an `Execution:` line set by the rule in Step 2, and every task
+  of a `per-task` phase has `Files:`, `Interfaces:` and its five steps.
 - **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
@@ -369,6 +422,16 @@ done:
 
 If any phase relies on the implementer *reasoning out* a gap, close the gap in the plan now.
 
+**Self-review (run it yourself after you write the plan, then fix what it finds in place):**
+- **Spec coverage** — each requirement in the spec or PRD maps to a phase or task. Add a task for a gap.
+- **Step scan** — no step that decides nothing ("TBD", "handle edge cases", "add validation", a name
+  that no task defines). No full function body that the signature and the tests already determine.
+- **Name consistency** — a name, signature or field in a later task matches the one an earlier task's
+  `Produces:` defines.
+- **Review Focus coverage** — each Review Focus line has its test in the task that owns the code.
+- **Proportion** — a plan several times longer than its spec is a transcript of the code. Replace the
+  bodies with signatures, test names and assertions.
+
 A `risk: high` phase gets two independent review runs: run by the roadmap/plan runner automatically (from caddis-next Phase 11), and by hand in an interactive `/caddis:implement` run (`caddis_review.py --plan <plan> --phase <n> --runs 2`, from Phase 10). Only a `blocking` finding fails that review (exit 1); `should-fix` and `nit` findings go on a follow-up list and do not stop the merge. A phase gets 3 completed review rounds (a run that did not complete uses none); the 4th ends with exit 5, "stop, the owner decides". The advisory hub is retired; do not plan a separate validation session.
 
 ## Programme triggers
@@ -381,7 +444,7 @@ Small work that does not meet a trigger skips its block.
 
 ## Step 4 — Report
 Output the plan path (`.caddis/plans/<feature-slug>.md`), the phase list (one line each, with each
-phase's model tier + lane), confirm the local-coder gate passed (or list the phases that need
+phase's model tier + lane + execution), confirm the local-coder gate passed (or list the phases that need
 tightening), and: *"To start: `read the plan and implement Phase 1`. To resume later: `/handoff` at
 session end, then `read relay.md` next time. The plan's Execution protocol carries every command —
 nothing to memorize."*

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

@@ -236,6 +236,17 @@ report — do not redo completed work.
      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.
+   - **EXECUTION** — read the phase's `Execution:` line. A missing line means `inline` (older plans
+     have none). `inline`: run the steps below for the whole phase, as before. `Execution: per-task`:
+     run the phase's tasks in order. Give each task a fresh implementer: a subagent on the phase's
+     lane and model, with a brief that holds the task's `Files:`, `Interfaces:` and steps, the plan's
+     Global Constraints and the test-economy lines (Multi-lane item 7b). If you cannot dispatch a
+     subagent, implement the task yourself and note that in the review file. After each task, run a
+     short task review before the next task: first spec compliance (the task's files, names and tests
+     match the plan), then quality (the author self-check). Fix blocking findings, then go on. Record
+     each task (name, commit, review result) under `## Task progress` in the review file. Then run the
+     phase's normal gates: VERIFY, the `review-tier` review by another vendor, COMMIT and the Tracker.
+     The task reviews never replace that review.
    - **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.
@@ -348,6 +359,9 @@ branch: <current branch>
 ## Assumptions made
 - <any gap the plan left that you decided — or "none">
 
+## Task progress  *(only for `Execution: per-task` phases)*
+- <phase N task N.M — commit <hash> — task review: clean | fixed <finding>>
+
 ## Not done / follow-ups
 - <phases skipped/blocked and why — or "none; all phases complete">
 

package/bundles/antigravity-plugin/skills/usage-review/SKILL.md

@@ -33,6 +33,15 @@ impactful finding** — the one most likely to reduce rate-limit consumption or
 
 Do NOT paraphrase every finding in prose — the report is already the output.
 
+## Step 2b — check the borrowed upstream skills
+
+Run `python "<scripts folder>/caddis_upstream_check.py"` from the project root (same folder as
+`usage_review.py`). It compares the upstream skills that caddis borrowed ideas from with the copies
+installed on this machine. Show every `DRIFT` line in the report under **Upstream drift**. A `DRIFT`
+line means: review the upstream diff, port what fits, then update `.github/upstream-sources.json`.
+Say nothing for `UP-TO-DATE`, `NOT-INSTALLED` or `NO-SOURCES` (no record: not the caddis source repo).
+The check never fails the review.
+
 ## Step 3 — offer to apply
 
 For each finding marked **[apply]** in the report, ask the user whether to apply it.