@caddis/cli 0.4.72 → 0.4.74

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.158",
+  "version": "1.3.160",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

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

@@ -23,12 +23,12 @@ from collections.abc import Callable
 from pathlib import Path
 
 try:
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
+    from caddis_file_lock import _try_lock, _unlock, atomic_write, locked_path, retry_denied
 except ModuleNotFoundError as exc:
     if exc.name != "caddis_file_lock":
         raise
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
+    from caddis_file_lock import _try_lock, _unlock, atomic_write, locked_path, retry_denied
 
 
 _TIMEOUT = 10
@@ -132,6 +132,14 @@ def _lock_path(rid: str) -> Path:
     return _repo_dir(rid) / "coordinator.lock.json"
 
 
+def _watcher_lock_path(rid: str) -> Path:
+    return _repo_dir(rid) / "watcher.lock"
+
+
+def _watcher_stop_path(rid: str) -> Path:
+    return _repo_dir(rid) / "watcher.stop"
+
+
 def read_state(rid: str) -> dict | None:
     """Return the last good parse of `coordinator.json`; None when it is missing or was never good.
 
@@ -367,6 +375,17 @@ def acquire_lock(rid: str, pid: int, session_id: str, name: str) -> tuple[bool,
         return True, None
 
 
+def lock_holder(rid: str) -> dict | None:
+    """Return the lock holder with its `alive` flag, or None when no holder. Never takes or changes the lock.
+
+    Raise OSError when the lock file cannot be read (the caller fails closed)."""
+    holder = _read_holder(_lock_path(rid))
+    if holder is None:
+        return None
+    return {"pid": holder["pid"], "sessionId": holder.get("sessionId"), "name": holder.get("name"),
+            "started_at": holder.get("started_at"), "alive": _holder_alive(holder)}
+
+
 def release_lock(rid: str, pid: int) -> None:
     """Remove the lock if `pid` holds it; do nothing otherwise."""
     with locked_path(_lock_path(rid)) as path:
@@ -943,6 +962,7 @@ def session_lookup(sessions: list[dict], *, session_id: str | None = None, name:
 
 CONFIG_KEYS = ("schema", "default_branch", "merge_method", "required_checks", "not_required", "docs_only",
                "main_workflow", "reviews", "peer_ack", "deploy", "owner_reserved", "stall", "quiet")
+OPTIONAL_CONFIG_KEYS = ("relay",)  # the coordinator's own relay: `.caddis/relay/<relay>.md`
 CONFIG_SCHEMA = 1
 _PLACEHOLDER = "<fill:"
 _FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)")  # a Markdown code fence and its info string
@@ -998,7 +1018,8 @@ def load_config(repo_root: Path) -> dict:
     """Read `<repo_root>/.caddis/coordinator.md` and return its json block.
 
     Raise FileNotFoundError when the file is missing, ValueError when there is no json block, a key is missing,
-    `schema` is not 1, or a value is still a `<fill: ...>` placeholder."""
+    `schema` is not 1, a value is still a `<fill: ...>` placeholder, or the optional `relay` is not a plain
+    workstream name (`caddis_workstreams.is_plain_name`: lower case `a-z0-9_-`, no Windows device name)."""
     path = config_path(repo_root)
     try:
         text = path.read_text(encoding="utf-8")
@@ -1016,9 +1037,24 @@ def load_config(repo_root: Path) -> dict:
     unfilled = _placeholders(config)
     if unfilled:
         raise ValueError(f"the config still has {_PLACEHOLDER} placeholders at: {', '.join(unfilled)}")
+    if "relay" in config and not _plain_workstream_name(config["relay"]):
+        raise ValueError(f"the config relay must be a plain workstream name such as coordinator, "
+                         f"not {config['relay']!r}")
     return config
 
 
+def _plain_workstream_name(value: object) -> bool:
+    """The relay name rule of `caddis_workstreams` (one rule, so a relay that loads here can also be read there)."""
+    try:
+        import caddis_workstreams
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_workstreams":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_workstreams
+    return caddis_workstreams.is_plain_name(value)
+
+
 def init_config(repo_root: Path) -> Path:
     """Copy the template to `<repo_root>/.caddis/coordinator.md` when it is absent. Never overwrite."""
     path = config_path(repo_root)
@@ -1078,10 +1114,79 @@ def watch_cycle(rid: str, pid: int, now: datetime.datetime, head_of: Callable[[i
     return {"stop": None, "results": results, "error": None}
 
 
-def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None) -> int:
+_TAKEOVER_MAX_S = 150.0  # the longest a `--takeover` waits for the old watcher
+_TAKEOVER_POLL_S = 0.2
+
+
+def _print_line(value: dict) -> None:
+    print(json.dumps(value, separators=(",", ":")), flush=True)
+
+
+def _takeover_wait(interval: float) -> float:
+    """The old watcher checks the stop file right after each sleep, and one cycle can run long (gh calls): wait one
+    interval plus 30 s, at most `_TAKEOVER_MAX_S`."""
+    return min(interval + 30, _TAKEOVER_MAX_S)
+
+
+def _remove_stop_file(rid: str) -> None:
+    retry_denied(lambda: _watcher_stop_path(rid).unlink(missing_ok=True))
+
+
+def _remove_own_stop_file(rid: str) -> None:
+    """Remove the stop file only when this process wrote it: a newer takeover's request stays."""
+    try:
+        owner = json.loads(_watcher_stop_path(rid).read_text(encoding="utf-8")).get("pid")
+    except (OSError, ValueError, AttributeError):
+        return
+    if owner == os.getpid():
+        _remove_stop_file(rid)
+
+
+def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None, takeover: bool = False) -> int:
     """Run `watch_cycle` every `interval` seconds. Print one JSON line (flushed) for each cycle with results or a
     stop, and for an error that differs from the previous cycle's error; print nothing for a quiet cycle or a
-    repeated error. Return 0 on a stop or after `max_cycles` cycles."""
+    repeated error. Return 0 on a stop or after `max_cycles` cycles.
+
+    One watcher per repo: the loop holds the OS lock on `<hub>/repos/<rid>/watcher.lock` for its whole life (the OS
+    frees it when the process dies). When another watcher holds it:
+    - without `takeover`, print `{"stop": "another watcher is running"}` and return 0 at once;
+    - with `takeover`, write `<hub>/repos/<rid>/watcher.stop` and wait (`_takeover_wait`) for the lock. The old
+      watcher sees the stop file right after its next sleep, prints `{"stop": "takeover requested"}` and ends.
+      A `finally` removes this process's own stop file (on success, timeout or an exception; a newer takeover's
+      file stays). When the lock does not come in time, print `{"stop": "old watcher did not stop"}` and
+      return 1. After a `/clear` the old watcher runs on in the same process, but its output belongs to the old
+      conversation: takeover gives the new conversation a watcher whose output it can read.
+    The watcher that gets the lock removes any stop file before its first cycle. When the repo folder does not
+    exist, no lock or stop file is made: the first cycle then stops (it never recreates the folder)."""
+    path = _watcher_lock_path(rid)
+    if not path.parent.is_dir():
+        return _watch_loop(rid, pid, interval, max_cycles)
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    with os.fdopen(os.open(path, flags, 0o666), "r+b") as handle:
+        held = _try_lock(handle)
+        if not held and not takeover:
+            _print_line({"stop": "another watcher is running"})
+            return EXIT_OK
+        if not held:
+            try:
+                atomic_write(_watcher_stop_path(rid), json.dumps({"pid": os.getpid(), "at": _now()}) + "\n")
+                deadline = time.monotonic() + _takeover_wait(interval)
+                while not held and time.monotonic() < deadline:
+                    time.sleep(_TAKEOVER_POLL_S)
+                    held = _try_lock(handle)
+            finally:  # on success, on timeout and on an exception: never leave this process's request behind
+                _remove_own_stop_file(rid)
+            if not held:
+                _print_line({"stop": "old watcher did not stop"})
+                return EXIT_ERROR
+        try:
+            _remove_stop_file(rid)
+            return _watch_loop(rid, pid, interval, max_cycles)
+        finally:
+            _unlock(handle)
+
+
+def _watch_loop(rid: str, pid: int, interval: float, max_cycles: int | None) -> int:
     head_of = _gh_head_of(rid)
     cycles = 0
     last_error: str | None = None
@@ -1098,6 +1203,9 @@ def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None) ->
             if max_cycles is not None and cycles >= max_cycles:
                 return EXIT_OK
             time.sleep(interval)
+            if _watcher_stop_path(rid).exists():  # right after the sleep: a newer watcher asked for the lock
+                _print_line({"stop": "takeover requested"})
+                return EXIT_OK
     except KeyboardInterrupt:
         return EXIT_OK
 
@@ -1405,6 +1513,7 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--name", required=True)
     p = command("release", lock)
     p.add_argument("--pid", type=int, required=True)
+    command("holder", lock)
 
     command("heartbeat")
     command("intake")
@@ -1412,6 +1521,8 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--pid", type=int, required=True, help="the coordinator session pid that holds the lock")
     p.add_argument("--interval", type=float, default=30.0, help="seconds between cycles (default 30)")
     p.add_argument("--max-cycles", type=int, help="stop after this many cycles (for tests)")
+    p.add_argument("--takeover", action="store_true",
+                   help="ask a running watcher of this repo to stop, then take its place (after a /clear)")
     command("state")
 
     queue = sub.add_parser("queue").add_subparsers(dest="queue_command", required=True, parser_class=_Parser)
@@ -1491,6 +1602,12 @@ def _dispatch(args: argparse.Namespace) -> int:
             _claim_state(rid, {"name": args.name, "sessionId": args.session_id, "pid": args.pid})
             _emit(args, {"acquired": True, "holder": None}, "acquired")
             return EXIT_OK
+        if args.lock_command == "holder":
+            holder = lock_holder(rid)
+            _emit(args, holder or {"holder": None}, "no holder" if holder is None else
+                  f"pid {holder['pid']} ({holder['name']}, session {holder['sessionId']}, "
+                  f"{'alive' if holder['alive'] else 'not alive'})")
+            return EXIT_OK
         release_lock(rid, args.pid)
         _emit(args, {"released": True}, "released")
         return EXIT_OK
@@ -1501,7 +1618,7 @@ def _dispatch(args: argparse.Namespace) -> int:
         _emit(args, {"ok": True}, "ok")
         return EXIT_OK
     if args.command == "watch":
-        return watch(rid, args.pid, args.interval, args.max_cycles)
+        return watch(rid, args.pid, args.interval, args.max_cycles, takeover=args.takeover)
     if args.command == "intake":
         results = intake(rid, datetime.datetime.now(datetime.timezone.utc), _gh_head_of(rid))
         lines = [f"{r['id']}: {r['result']} {r['reason']}".rstrip() for r in results]

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

@@ -482,6 +482,17 @@ def render_resume(session: str, session_id: str, workstream: str, prompt: str, r
             f"{_fenced(shown)}\n{start}\n")
 
 
+def render_coordinator_resume(session: str, session_id: str, workstream: str) -> str:
+    """The resume block for the repo's coordinator: three lines to type, no prompt and no start line.
+
+    `/caddis:coordinate start` reads the coordinator's relay and tasks itself, so a pasted prompt would only race it."""
+    return (f"=== RESUME ===\nSession: {session} ({session_id})\nWorkstream: {workstream}\n"
+            "This session is the repo's coordinator. To resume, type these three lines in this window, one at a time:\n"
+            "/clear\n/rename coordinator\n/caddis:coordinate start\n"
+            f"Do not paste a resume prompt; /caddis:coordinate start reads .caddis/relay/{workstream}.md "
+            "and its tasks itself.\n")
+
+
 # ---- CLI --------------------------------------------------------------------------------------
 
 def _load_acks(fleet_dir: Path) -> list[Ack]:
@@ -491,6 +502,28 @@ def _load_acks(fleet_dir: Path) -> list[Ack]:
     return [parse_ack(p.read_text(encoding="utf-8")) for p in sorted(acks_dir.glob("*.md"))]
 
 
+def _coordinator_relay_problem(root: Path, name: str) -> str | None:
+    """None when `<root>/.caddis/coordinator.md` loads and its `relay` is `name`, else one line that says why not.
+
+    The coordinator block says `/caddis:coordinate start` reads `.caddis/relay/<name>.md` itself; start reads the
+    config's `relay`, so the block is true only when the two are the same name."""
+    try:
+        import caddis_coordinate
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_coordinate":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_coordinate
+    try:
+        relay = caddis_coordinate.load_config(root).get("relay")
+    except (OSError, ValueError) as exc:  # FileNotFoundError is an OSError
+        return f"--coordinator needs a valid .caddis/coordinator.md with relay {name!r}: {' '.join(str(exc).split())}"
+    if relay != name:
+        return (f"--coordinator: --name {name!r} is not the coordinator config relay {relay!r}"
+                if relay else f"--coordinator: .caddis/coordinator.md has no relay (needs relay {name!r})")
+    return None
+
+
 def _resume_block_cli(args: argparse.Namespace) -> int:
     try:
         import caddis_workstreams
@@ -500,15 +533,23 @@ def _resume_block_cli(args: argparse.Namespace) -> int:
         sys.path.insert(0, str(Path(__file__).resolve().parent))
         import caddis_workstreams
     root = args.root.resolve()
+    if args.coordinator:
+        problem = _coordinator_relay_problem(root, args.name)
+        if problem:
+            sys.stderr.write(f"resume-block failed: {problem}\n")
+            return caddis_exit.BLOCKED
     try:
         text, digest = caddis_workstreams.read_relay(root, args.name)
         if digest is None:
             raise ResumeError(f"relay {args.name!r} not found")
-        prompt = resume_prompt(text)
+        prompt = "" if args.coordinator else resume_prompt(text)
     except (ValueError, OSError) as exc:  # ResumeError is a ValueError; a bad relay name is one too
         sys.stderr.write(f"resume-block failed: {exc}\n")
         return caddis_exit.BLOCKED
     session, known = session_name(args.session_id, root)
+    if args.coordinator:
+        print(render_coordinator_resume(session, args.session_id, args.name), end="")
+        return caddis_exit.CLEAN
     role = args.role or (role_of(session) if known else args.name)
     if not _SAFE_NAME.match(role):  # the role goes unquoted into the start line
         sys.stderr.write(f"resume-block failed: bad role {role!r}\n")
@@ -553,7 +594,11 @@ def main(argv: list[str] | None = None) -> int:
     p.add_argument("--root", default=".", type=Path)
     p.add_argument("--role", help="role for the new session's name (default: the session name's role, else the relay name)")
     p.add_argument("--fleet", action="store_true", help="fleet close: print no start line (the restart sheet has it)")
+    p.add_argument("--coordinator", action="store_true",
+                   help="this session holds the repo's coordinator lock: print the three restart lines, no prompt")
     args = parser.parse_args(argv)
+    if args.cmd == "resume-block" and args.coordinator and args.role:
+        parser.error("resume-block: --role cannot go with --coordinator (the coordinator keeps its name)")
 
     if args.cmd == "role-of":
         print(role_of(args.name))

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

@@ -46,6 +46,15 @@ def _name(value: str) -> str:
     return value
 
 
+def is_plain_name(value: object) -> bool:
+    """True for a plain workstream name as typed (no lower-casing, no `branch.` namespace), e.g. `coordinator`."""
+    try:
+        _name(value)  # type: ignore[arg-type]
+    except ValueError:
+        return False
+    return bool(_PLAIN_NAME.fullmatch(value))  # type: ignore[arg-type]
+
+
 def _plain_name(value: str) -> str:
     if not isinstance(value, str):
         raise TypeError("plan or suggestion must be text")

package/bundles/antigravity-plugin/scripts/templates/coordinator.md

@@ -7,7 +7,8 @@ How to fill it:
 
 - Replace every `"<fill: ...>"` string with the real value. The coordinator refuses to start while any
   `<fill:` string is left (`caddis_coordinate.py config show` lists them).
-- Keep every key. A missing key also stops the coordinator.
+- Keep every key. A missing key also stops the coordinator. Only `relay` is optional: delete its line if the
+  coordinator has no relay.
 - Put no host names and no secrets here. The production base URL comes from the environment variable that
   `deploy.base_url_env` names.
 
@@ -42,6 +43,7 @@ What the keys mean:
 | `stall.ready_no_ready_msg_min` | Minutes a green PR may wait for its session's ready message. |
 | `quiet.coordination` | Quiet hours for merges (`none`: no quiet hours). |
 | `quiet.timing_checks` | When timing checks may run. |
+| `relay` | The workstream name of the coordinator's relay (optional; the coordinator reads `.caddis/relay/<relay>.md` and its tasks file at start). |
 
 ```json
 {
@@ -86,6 +88,7 @@ What the keys mean:
   "quiet": {
     "coordination": "none",
     "timing_checks": "<fill: when timing checks may run, for example quiet window only>"
-  }
+  },
+  "relay": "<fill: workstream name of the coordinator's relay, e.g. coordinator>"
 }
 ```

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

@@ -117,6 +117,7 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Draw Io | `draw-io/` | draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage. |
+| Flow Chart From Counts | `flow-chart-from-counts/` | Turn a from-to-count edge list into a zoomable Mermaid flow chart page with counts, a legend and a render check. |
 | Mermaid Diagrams | `mermaid-diagrams/` | Software diagrams in Mermaid: class, sequence, flowchart, ERD, C4, state, git graph, gantt. Use for domain models, API flows, processes and database schemas. |
 | Particle Art | `particle-art/` | >- |
 

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

@@ -19,6 +19,13 @@ Argument: **$ARGUMENTS**
   `queue next` result. Change nothing.
 - `stop`: do **6. Stop**.
 
+## Restart and resume
+
+- Planned restart: run `/caddis:handoff`, `/clear`, `/rename coordinator`, `/caddis:coordinate start`, in
+  that order, in this window.
+- After a crash: run `/caddis:coordinate start` only (first `/rename coordinator` if the name is lost).
+- Do not paste a resume prompt. Start reads the coordinator's relay and tasks itself (step 1.8).
+
 ## How to call the script
 
 - Run these commands with the Bash tool: the quoting and the `GH_TOKEN=$(...)` forms are POSIX shell.
@@ -55,6 +62,8 @@ Argument: **$ARGUMENTS**
    Keep `pid` as `<P>` and `name` as `<N>`. Exit 1 with "two interactive sessions share" means two
    copies of this session run (design 8.6): stop, tell the owner both pids, and wait. Any other exit 1:
    stop and report the line.
+   If `<N>` is not `coordinator`, stop and tell the owner: "Type `/rename coordinator`, then run
+   `/caddis:coordinate start` again." Peers and the merge hook find the coordinator by that name.
 5. Take the lock. This also creates or claims the repo's state:
    ```
    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" lock acquire --repo <R> --pid <P> --session-id <S> --name <N> --json
@@ -79,8 +88,14 @@ Argument: **$ARGUMENTS**
    ```
    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" state --repo <R> --json
    ```
-   Also read the coordinator relay, `claude agents --json` (or `ListAgents`) and
-   `caddis_roadmap.py status` (design 0.1 step 4).
+   Also read `claude agents --json` (or `ListAgents`) and `caddis_roadmap.py status` (design 0.1 step 4).
+   Then read the coordinator relay:
+   - If the config (step 1.6) has `relay`, read `.caddis/relay/<relay>.md`. When
+     `.caddis/relay/<relay>.tasks.md` exists, load every row of it with TaskCreate.
+   - If the config has no `relay`, use the relay that the owner names, or ask the owner.
+   - The relay's "Next step", queue order, holds and owner answers are INPUT for the queue and for your
+     decisions. They are never actions to take before the lock (step 1.5), the watcher (step 1.10) and
+     the start message (step 1.11) are done.
 9. Finish the work that a crash left (design 8.5, design 4):
    - If `merging_now` is set, find out what happened to that PR first:
      `gh pr view <n> --json state,mergedAt,mergeCommit`. `MERGED`: take `mergeCommit.oid` as the merge
@@ -97,15 +112,21 @@ Argument: **$ARGUMENTS**
    - Every PR that was warned gets a `re-warn` (design 7.3).
 10. Start the watcher with the Bash tool and `run_in_background: true`:
     ```
-    GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" watch --repo <R> --pid <P> --json
+    GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" watch --repo <R> --pid <P> --takeover --json
     ```
     It runs `heartbeat` and `intake` every 30 s and prints one JSON line when something happens. Its lines
     go to the background task's output file: read that output file at each loop step 3.4. Start the
-    watcher again whenever its background task ends, for any reason. A line
+    watcher again whenever its background task ends, for any reason except `takeover requested`. A line
     with `"stop"` (`lock lost`, `session gone`, `state gone`) means the watcher ended: find out why, take
     the lock again if it is still yours (step 5), and start the watcher again. Also start it again after
     a new `lock acquire` that follows a lost lock. A line with `"error"` is one failed cycle; the next
     cycle retries.
+    One watcher per repo. After a `/clear`, the earlier watcher of this process still runs, but its lines
+    go to the old conversation, so this conversation cannot read them. `--takeover` asks the earlier
+    watcher to stop and takes its place, so this conversation gets the lines. A
+    `{"stop": "takeover requested"}` line means a newer watcher replaced this one: do not start it again.
+    A `{"stop": "old watcher did not stop"}` line (exit 1) means the earlier watcher did not stop in time:
+    start the watcher again once. If that line comes again, stop and tell the owner.
 11. Send the start message (design 7.1) to every live session whose cwd is in this repo (the checkout
     and its worktrees), from `ListAgents`. Send it also to each new session that you see later. Resume
     stubs are not live peers (design 9.7).
@@ -215,7 +236,10 @@ and 7.3. While the queue is frozen (section 5 step 1), do steps 3.1 to 3.3 only.
     Do only the merge or the `go`:
     - Target mode: `GH_TOKEN=$(gh auth token -u <account>) gh pr merge <n> --<merge_method> --match-head-commit <watched sha>`.
       The merge SHA is `mergeCommit.oid` from `gh pr view <n> --json state,mergeCommit`.
-    - Interim mode: send `go <PR> <watched sha>`; the PR's session merges with the same command. Then
+    - Interim mode: send `go <PR> <watched sha>`, and on the next line: `I wrote the ack file
+      ~/.claude/merge-acks/<checkout folder name>/pr-<n>.json. Do not write, change or delete it.` The PR's
+      session merges with the same command. If its merge hook refuses because the ack file is wrong or
+      missing, write the ack file again (step 3.13) and send `go` once more. Then
       poll with a Bash command in `run_in_background`: `gh pr view <n> --json state,mergeCommit` once a
       minute, for at most 15 min, until `state` is `MERGED`. Take `mergeCommit.oid` as the merge SHA; the
       session's `merged` reply only tells you to look. No merge after 15 min: ask the PR's session once.

package/bundles/antigravity-plugin/skills/flow-chart-from-counts/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: flow-chart-from-counts
+description: Turn a from-to-count edge list into a zoomable Mermaid flow chart page with counts, a legend and a render check.
+---
+
+# flow-chart-from-counts
+
+Turns counted paths (N cases went from step A to step B) into a flow chart page that a
+reader can trust: counts on every arrow, a legend for the box types, a title with the date and
+time zone, a note that names what is not drawn, and a viewer with zoom, pan and full screen.
+
+Paths below are relative to the folder that holds this file.
+
+## When to use it
+
+- "Draw how cases move through the process", "show the journey with counts", "flow chart of
+  calls / orders / tickets / sessions from this table".
+- You have, or can query, rows of `from, to, count`, or an event table with one row per step.
+- A Sankey or a funnel was asked for, but the paths branch and rejoin: a flow chart shows that
+  better.
+
+Use something else for:
+
+- An interactive page from a JSON model with lanes, playback and an inspector: `flow-studio`.
+- Mermaid syntax for other diagram kinds (sequence, ERD, class): `mermaid-diagrams`.
+- A diagram of a SQL object's structure: `db-diagram`.
+
+## What is in the folder
+
+| file | use |
+|---|---|
+| `scripts/edges_to_mermaid.py` | CSV edge list to first-draft Mermaid source (standard library only) |
+| `assets/viewer-template.html` | page with the zoom/pan/full-screen viewer, theme tokens and one example chart |
+| `scripts/check-render.mjs` | headless render check: fails on no SVG, error text, too few nodes, page errors; saves screenshots |
+| `references/edge-list-sql.md` | SQL pattern: event table to edge list and box counts, and the checks to run on it |
+
+## Process
+
+1. **Get the edge list.** From an event table, use `references/edge-list-sql.md`. Run its checks
+   (START rows add up to the cases; path occurrences in equal path occurrences out per step).
+   Count arrows as distinct cases per pair. Get the box counts (distinct cases per step) at the
+   same time.
+2. **Name the node types** with the reader, or from the process owner's own glossary: for
+   example automatic step, in-scope step, optional step, hand-off, end. Write a `nodes.csv`
+   (`name,type,count`).
+3. **Make the first draft:**
+   ```
+   python scripts/edges_to_mermaid.py edges.csv --nodes nodes.csv --min 25 \
+          --in-scope scope --optional choice --out chart.mmd --strict
+   ```
+   `--out` writes UTF-8 (do not use `>` in Windows PowerShell 5.1: it can write UTF-16). The note
+   on hidden paths goes to stderr. Keep it: it goes under the chart. `--strict` exits 1 on a
+   `warning:` line, which means an arrow is larger than its box: fix the query before you draw.
+   Duplicate `from,to` rows are added together. Node types become classes named `t_<type>`.
+4. **Put it in the page.** Copy `assets/viewer-template.html`. Paste the source into the
+   `<script type="text/plain">` block. Set `data-title` (what, which day) and `data-sub` (the UTC
+   window, the unit of the counts, the minimum path size). Replace the legend and the note.
+   For more charts, add one `.fv` block and one source script per chart.
+5. **Render and check:**
+   ```
+   node <skill folder>/scripts/check-render.mjs page.html --out shots [--channel msedge]
+   ```
+   Run it from a folder whose `node_modules` has `playwright`. It exits 1 when a check fails.
+6. **Look at the screenshots** (`chart-N.png` is the chart at Fit, `chart-1-full.png` is full
+   screen) and run the tidy checklist below. If a rule fails, change the layout with the layout
+   fixes, and go back to step 5.
+7. **Show** the page and the screenshots only when every checklist rule passes. Say which labels
+   are your reading (see Wording). If a rule cannot be met, say which rule and why.
+
+## Tidy checklist (the chart must pass it before you show it)
+
+A clean, tidy chart is an acceptance rule, not a nice-to-have. A reader who has to trace a
+line across the page stops trusting the numbers on it.
+
+1. **No crossing lines.** No line passes through a box or a label. Use the tree rule with
+   dashed stubs, and split shared targets (layout fixes 1 and 2).
+2. **No overlaps.** No label or box sits on another. Edge labels are short: `(1,234)` and at
+   most a few words. Long text goes in the note under the chart, not on the chart.
+3. **Rows and side flows.** Boxes of the same kind line up in one row where the flow allows
+   (layout fix 5). A side flow sits in its own dashed box at the bottom, pushed down with an
+   invisible link (layout fix 4).
+4. **One look per type.** One box shape per type, a small fixed palette (5 to 7 classes), a
+   legend that matches the chart exactly (stubs included), and the title with the date and the
+   time zone on the chart.
+5. **Readable at Fit and at full screen** on a 1280 x 900 screen. Nothing is clipped.
+6. **Checked by eye.** You opened both screenshots and checked rules 1 to 5 on them. The render
+   check's warnings (box overlaps, labels on boxes) help, but they cannot see a crossing line.
+
+## Count rules
+
+- **Arrows and boxes both count distinct cases.** An arrow says how many distinct cases took
+  that path (`COUNT(DISTINCT case_id)` per from-to pair). A box says how many distinct cases
+  reached it. Do not draw path occurrences (`COUNT(*)`): a case that loops counts twice, and a
+  reader who sees a box of 8,538 followed by an arrow of 8,541 stops trusting the chart. Label
+  every number as cases.
+- **Self-check: no arrow into or out of a box exceeds that box's count.** If one does, the
+  query counts occurrences. The converter warns on stderr when this happens.
+- **Say in the note that arrows into a box can sum to a little more than the box**, because a
+  case can reach it by two paths.
+- **Put counts in brackets, with thousands separators:** `(1,234)`. In Mermaid an edge label that
+  holds brackets must be quoted: `A -->|"(1,234)"| B`. Unquoted, `(` starts a node shape and the
+  chart fails to parse.
+- **Hide small paths with a stated minimum.** Choose a minimum (for example 25), drop the paths
+  under it, and write a note that names them and their total: "Not drawn because fewer than 25
+  cases took them: X to Y (12), ... (41 in total)." A chart that drops paths without a note looks
+  complete and is not.
+- **Merge small boxes into one named box, and say so.** When you merge, the count is a sum of
+  rounded or filtered parts: write `(about 600)`, and say in the note what the box holds.
+- **Put the date and the time zone on the chart.** Write the title as HTML inside the zoomable
+  stage (the template does this from `data-title` and `data-sub`), so it stays with the chart in
+  full screen and in screenshots. Do not use a frontmatter `title:` as well: it would show a second title. Give the
+  local day and the UTC window: `Mon 5 Oct 2026 (4 Oct 23:00 to 5 Oct 23:00 UTC)`.
+- **Name the unit.** "Counts in brackets are calls / orders / cases." A count with no unit gets
+  read as the wrong one.
+
+## Node types and the legend
+
+- One `classDef` per node type, and one `class id1,id2 type;` line per type. The converter writes
+  these from `nodes.csv`.
+- **In-scope boxes get a thick border** (`stroke-width:3px`), so the reader finds the subject of
+  the chart first.
+- **Optional or owner-choice boxes get a dashed border** (`stroke-dasharray:6 4`): a step that is
+  a decision still open, or one that runs only for some cases.
+- End boxes share one quiet grey class. Stubs share one class: white fill, thin dashed grey
+  border (`stroke-dasharray:3 3`), so they read as pointers, not steps.
+- Put a legend above the chart with one swatch per type, with the same fill, border width and
+  dash as the chart. Use light fills with dark text. Keep the chart canvas light in dark mode
+  too (the template's `--canvas` token does this), or the dark text loses contrast.
+
+## Layout fixes that work
+
+Mermaid's layout (dagre) puts each node on a rank and orders each rank to cut crossings. It does
+not know what the reader looks for. These fixes move it.
+
+1. **Draw the chart as a tree.** Give every box exactly one parent edge: the biggest path into
+   it. For every other path into that box, add a small dashed stub under its own source,
+   labelled with the target and the count: `B --> toB_C(["to C (412)"])`. Shared targets and
+   back-edges are what make the layout cross lines; a tree with stubs has none. Add a legend
+   entry for stubs ("dashed: the path continues at the box named"). The converter does this by
+   default (`--no-tree` turns it off).
+2. **Give each source its own end box.** One shared "Ends" box pulls a long line from every step
+   across the chart. Write `A --> endA(["Ends"])` and `B --> endB(["Ends"])` instead. The
+   converter does this. Apply the same fix to any shared target that sits far from its sources:
+   a copy of the box next to each source is easier to read than one box with crossing lines.
+3. **Do not draw a loop-back as an edge.** A line back up the chart crosses everything. End the
+   path in a stub: `A --> backA(["back to Triage (190)"])`. The converter does this for every
+   edge that points back to a step on the path.
+4. **Put a side flow in its own subgraph and push it down.** For example the steps after a
+   hand-off. Draw them in `subgraph AFTER[...] direction LR ... end` and add an invisible link
+   from a low node of the main flow: `X2 ~~~ AFTER`. The subgraph then sits under the main
+   flow, not beside it.
+5. **Put same-kind boxes in one row.** Group them in a subgraph, and lengthen the edges into it
+   (`---->`, one dash per extra rank) so they land on the same rank.
+6. **Replace a long jump with a short stub or a dotted link.** When an edge must reach a box
+   far away, end it in a small stub node near the source, or draw it dotted (`-.->`) with a
+   label such as `"few"`, so the eye can tell it is secondary.
+7. **Order the edges from a node in the order you want the boxes, left to right**, and declare
+   the nodes in the same order. Dagre takes this as its first guess. It can still swap them to
+   cut crossings: check the screenshot.
+8. **Quote every label that holds brackets, quotes or `<br/>`:** `["Text<br/>(12)"]`,
+   `|"(12)"|`. Write a quote inside a label as `#quot;`.
+
+Change one thing at a time and re-render. Two fixes at once hide which one helped.
+
+## Wording
+
+- **Use the process owner's words for box labels** when a glossary or a list of step names
+  exists. A reader checks the chart against those names.
+- **Write neutral endings.** "Case ends" or "Call ends" means the data shows no further step.
+  Do not write a guess such as "hangs up" or "gives up": the data does not say who ended it.
+  Say what "ends" means in the note.
+- **Mark your own reading.** When a label or a grouping is your interpretation, not a name from
+  the source, say so in the note ("'Team queues' is our grouping of four queues").
+
+## Verify
+
+`scripts/check-render.mjs` fails (exit 1) when a chart has no SVG, shows an error message, has
+fewer nodes than `--min-nodes`, or the page throws. Make it fail once on purpose (break one
+line of the source) to see that it can. It also counts box overlaps and arrow labels on boxes
+as warnings. Those are hints: open the screenshots and run the tidy checklist by eye, because
+the check cannot see a crossing line.
+
+Also check the numbers, not only the drawing: the START count equals the cases in the window,
+and no arrow into or out of a box is larger than the box (the converter warns when one is).
+
+## Publishing
+
+- As an Artifact: follow the artifact-design rules. Mermaid loads from
+  `https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js` (an exact version on the
+  allowed CDN). The template already has theme tokens for light and dark, an explicit body
+  background, and a 16px side gutter for phone width.
+- In an app: render with the app's own Mermaid package and keep the same source, title and note.
+  Keep the count rules; they are what makes the chart trustworthy.