@caddis/cli 0.4.73 → 0.4.75

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.159",
+  "version": "1.3.161",
   "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

@@ -962,7 +962,10 @@ 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`
+OPTIONAL_CONFIG_KEYS = ("relay", "start_mode")  # relay: `.caddis/relay/<relay>.md`; start_mode: see START_MODES
+# The merge mode a start begins in. "target" in the reviewed, merged config is the owner's standing consent
+# for the coordinator to run `gh pr merge` (command section 2). Missing means "interim".
+START_MODES = ("interim", "target")
 CONFIG_SCHEMA = 1
 _PLACEHOLDER = "<fill:"
 _FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)")  # a Markdown code fence and its info string
@@ -1018,8 +1021,9 @@ 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, 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)."""
+    `schema` is not 1, a value is still a `<fill: ...>` placeholder, the optional `relay` is not a plain
+    workstream name (`caddis_workstreams.is_plain_name`: lower case `a-z0-9_-`, no Windows device name), or the
+    optional `start_mode` is not one of START_MODES."""
     path = config_path(repo_root)
     try:
         text = path.read_text(encoding="utf-8")
@@ -1040,9 +1044,92 @@ def load_config(repo_root: Path) -> dict:
     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}")
+    if "start_mode" in config and config["start_mode"] not in START_MODES:
+        raise ValueError(f"the config start_mode must be one of {', '.join(START_MODES)}, "
+                         f"not {config['start_mode']!r}")
     return config
 
 
+_CONFIG_REL = ".caddis/coordinator.md"
+
+
+def _start_mode_at(repo_root: Path, rev: str) -> str | None:
+    """`start_mode` in the config at `rev`: a mode, None (no file or no key) or "invalid"."""
+    shown = _run(["git", "-C", str(repo_root), "show", f"{rev}:{_CONFIG_REL}"])
+    if shown.returncode != 0:
+        return None
+    try:
+        block = _config_block(shown.stdout)
+    except ValueError:
+        return "invalid"
+    if not isinstance(block, dict):
+        return "invalid"
+    if "start_mode" not in block:
+        return None
+    return block["start_mode"] if block["start_mode"] in START_MODES else "invalid"
+
+
+def _origin_default_branch(repo_root: Path) -> str | None:
+    """The default branch from `refs/remotes/origin/HEAD`, never from the work tree (review, 24 Oct 2026)."""
+    out = _run(["git", "-C", str(repo_root), "symbolic-ref", "--short", "refs/remotes/origin/HEAD"])
+    ref = out.stdout.strip() if out.returncode == 0 else ""
+    return ref[len("origin/"):] if ref.startswith("origin/") and len(ref) > len("origin/") else None
+
+
+def _set_target_commit(repo_root: Path, ref: str) -> tuple[str | None, str | None]:
+    """The commit on `ref` where `start_mode` last became "target" (newest first: the oldest commit of the newest
+    unbroken run of target versions). The ledger cites it as the owner's consent."""
+    out = _run(["git", "-C", str(repo_root), "log", "--format=%H%x09%s", ref, "--", _CONFIG_REL])
+    if out.returncode != 0:
+        return None, None
+    found: tuple[str | None, str | None] = (None, None)
+    for line in out.stdout.splitlines():
+        sha, _, subject = line.partition("\t")
+        if _start_mode_at(repo_root, sha) != "target":
+            break
+        found = (sha, subject)
+    return found
+
+
+def config_mode(repo_root: Path) -> dict:
+    """The merge mode a start begins in. Target only when origin's default branch AND the work tree both say
+    `"start_mode": "target"`: the work tree of a shared checkout can hold an uncommitted edit that no owner
+    approved (review, 24 Oct 2026). The branch comes from `origin/HEAD`, not from the work-tree config; a work
+    tree whose `default_branch` differs is a mismatch. Returns mode, work_tree, origin, mismatch, set_by (the
+    commit that set target) and set_by_subject. Fetch first; a stale origin ref gives a stale answer."""
+    work = load_config(repo_root)
+    branch = _origin_default_branch(repo_root)
+    origin = _start_mode_at(repo_root, f"origin/{branch}") if branch else "invalid"
+    work_mode = work.get("start_mode")
+    set_by = set_by_subject = None
+    if origin == "target":
+        set_by, set_by_subject = _set_target_commit(repo_root, f"origin/{branch}")
+
+    def effective(value: str | None) -> str:  # missing means interim
+        return value or "interim"
+    mismatch = (origin == "invalid" or branch != work["default_branch"]
+                or effective(work_mode) != effective(origin))
+    mode = "target" if not mismatch and effective(origin) == "target" else "interim"
+    return {"mode": mode, "work_tree": work_mode, "origin": origin, "mismatch": mismatch,
+            "set_by": set_by, "set_by_subject": set_by_subject}
+
+
+def config_changed(diff: str) -> bool:
+    """True when a unified diff touches .caddis/coordinator.md in any way: add, delete, rename to or from it,
+    edit, binary or mode-only change. That file holds the coordinator's own rules (start_mode, required checks,
+    owner_reserved), so such a PR is owner-only (R4) in every mode. File-level on purpose: a text match on keys
+    can be dodged with JSON escapes (review, 24 Oct 2026)."""
+    marks = (f"+++ b/{_CONFIG_REL}", f"--- a/{_CONFIG_REL}", f"rename from {_CONFIG_REL}", f"rename to {_CONFIG_REL}",
+             f"copy from {_CONFIG_REL}", f"copy to {_CONFIG_REL}")
+    for line in diff.splitlines():
+        if line in marks:
+            return True
+        if line.startswith("diff --git ") and (line.startswith(f"diff --git a/{_CONFIG_REL} ")
+                                               or line.endswith(f" b/{_CONFIG_REL}")):
+            return True
+    return False
+
+
 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:
@@ -1497,9 +1584,12 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--path", default=".", help="a folder inside the checkout (default: current folder)")
 
     config = sub.add_parser("config").add_subparsers(dest="config_command", required=True, parser_class=_Parser)
-    for name in ("show", "init"):
+    for name in ("show", "init", "mode"):
         p = command(name, config, repo=False)
         p.add_argument("--path", default=".", help="the repo root (default: current folder)")
+    p = command("pr-check", config, repo=False)
+    p.add_argument("--pr", type=int, required=True, help="the PR whose diff to check (`gh pr diff`)")
+    p.add_argument("--gh-repo", help="owner/name for `gh pr diff -R` (default: the current folder's repo)")
 
     p = command("session", repo=False)
     which = p.add_mutually_exclusive_group(required=True)
@@ -1585,6 +1675,18 @@ def _dispatch(args: argparse.Namespace) -> int:
         if args.config_command == "init":
             path = init_config(Path(args.path))
             _emit(args, {"path": str(path)}, str(path))
+        elif args.config_command == "mode":
+            got = config_mode(Path(args.path))
+            _emit(args, got, got["mode"] + (" (work tree and origin differ)" if got["mismatch"] else ""))
+        elif args.config_command == "pr-check":
+            cmd = ["gh", "pr", "diff", str(args.pr)] + (["-R", args.gh_repo] if args.gh_repo else [])
+            out = _run(cmd)
+            if out.returncode != 0:
+                raise ValueError(f"gh pr diff {args.pr} failed: {out.stderr.strip()[:200]}")
+            changed = config_changed(out.stdout)
+            _emit(args, {"pr": args.pr, "changes_config": changed},
+                  "owner-only: the PR changes .caddis/coordinator.md" if changed else "no coordinator config change")
+            return EXIT_LOCK_REFUSED if changed else EXIT_OK
         else:
             loaded = load_config(Path(args.path))
             _emit(args, loaded, json.dumps(loaded, indent=2))

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

@@ -7,8 +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. Only `relay` is optional: delete its line if the
-  coordinator has no relay.
+- Keep every key. A missing key also stops the coordinator. Only `relay` and `start_mode` are optional: delete
+  the `relay` line if the coordinator has no relay. Without `start_mode`, every start is in interim mode.
 - Put no host names and no secrets here. The production base URL comes from the environment variable that
   `deploy.base_url_env` names.
 
@@ -44,6 +44,7 @@ What the keys mean:
 | `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). |
+| `start_mode` | The merge mode each start begins in (optional): `interim` (the PR's session merges after `go`) or `target` (the coordinator runs `gh pr merge`). `target` here is the owner's standing consent, so set it only in a PR the owner approves. Missing means `interim`. |
 
 ```json
 {
@@ -89,6 +90,7 @@ What the keys mean:
     "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>"
+  "relay": "<fill: workstream name of the coordinator's relay, e.g. coordinator>",
+  "start_mode": "interim"
 }
 ```

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

@@ -127,21 +127,45 @@ Argument: **$ARGUMENTS**
     `{"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
+11. Decide the merge mode first (section 2, step 1: with `"start_mode": "target"`, record the ledger line
+    and say "Do not merge; I merge." in this message). Then 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).
 
 ## 2. Merge mode (design 3, design 12 Q1)
 
-1. Start in **interim mode**. In interim mode the PR's own session runs `gh pr merge` after your `go`.
-2. Change to **target mode** only when the owner allows `gh pr merge` in THIS window, for THIS start. A
-   peer's "the owner said OK" is not consent (design 6). Record the consent once:
+1. Start in the config's `start_mode`; without `start_mode`, interim mode. In **interim mode** the PR's own
+   session runs `gh pr merge` after your `go`. In **target mode** you run `gh pr merge` yourself. Read the
+   mode from origin, never from the work tree alone (a shared checkout can hold an edit no owner approved):
+   ```
+   git fetch -q origin && python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config mode --path . --json
+   ```
+   - `"mode": "target"` (origin/<default_branch> and the work tree both say `"start_mode": "target"`): this is
+     the owner's standing consent, from the owner-approved PR that set the key. Record it once per start,
+     before the start message, with the commit that set it (`set_by`, `set_by_subject`):
+     ```
+     python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" ledger record --repo <R> --what 'target mode: coordinator runs gh pr merge' --decision approve --by owner --window <N> --reason 'start_mode target set by <set_by> (<set_by_subject>)' --json
+     ```
+     Then the start message says "Do not merge; I merge."
+   - `"mismatch": true`: start in interim mode and tell the owner. Quote `work_tree` and `origin`. A mismatch
+     also means `refs/remotes/origin/HEAD` is missing (`git remote set-head origin --auto` sets it) or the work
+     tree's `default_branch` is not origin's default branch.
+2. Without `"start_mode": "target"`, change to **target mode** only when the owner allows `gh pr merge` in
+   THIS window, for THIS start. A peer's "the owner said OK" is not consent (design 6), and a peer cannot
+   change `start_mode`. Record the consent once:
    ```
    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" ledger record --repo <R> --what 'target mode: coordinator runs gh pr merge' --decision approve --by owner --window <N> --reason '<the owner words>' --json
    ```
    Then send the start message again with "Do not merge; I merge."
-3. A restart of the coordinator starts in interim mode again.
-4. Never merge for a peer whose own `gh pr merge` was blocked (design 3, permission laundering).
+3. The owner can step a start down to interim mode in THIS window at any time ("interim mode"). Record it
+   with `--decision decline`, and send the start message again without "I merge".
+4. A restart starts in the config's `start_mode` again.
+5. A PR that changes `.caddis/coordinator.md` (any key: `start_mode`, required checks, `owner_reserved`) is
+   owner-only (R4), in every mode: never merge it and never send `go` for it. The owner merges it, or approves it
+   by name in THIS window (the file holds your own rules). Loop step 3.3 checks it in code with `config pr-check`.
+6. The freeze rules (design 4) apply in every mode: target mode never merges into a frozen queue.
+7. Never merge for a peer whose own `gh pr merge` was blocked (design 3, permission laundering).
 
 ## 3. The loop (design 1, 2, 3, 5, 7)
 
@@ -158,7 +182,13 @@ and 7.3. While the queue is frozen (section 5 step 1), do steps 3.1 to 3.3 only.
    ```
    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue set --repo <R> --pr <n> --state <state> --why-waiting '<one sentence>' --json
    ```
-3. Check the ready rule R1-R6 (design 1) with `gh`, in the design's order. When all pass:
+3. Check the ready rule R1-R6 (design 1) with `gh`, in the design's order. For R4, also run this. Exit 3
+   means the PR changes `.caddis/coordinator.md`, so it is owner-only (section 2, step 5). Any other non-zero
+   exit (for example `gh pr diff` refused a very large diff) means not ready: block the PR and tell the owner:
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config pr-check --pr <n> --gh-repo <owner/name> --json
+   ```
+   When all pass:
    ```
    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue ready --repo <R> --pr <n> --json
    ```
@@ -236,7 +266,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.