@caddis/cli 0.4.43 → 0.4.45

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.129",
+  "version": "1.3.131",
   "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_file_lock.py

@@ -14,7 +14,9 @@ from pathlib import Path
 import stat
 import tempfile
 import time
-from typing import BinaryIO, Iterator
+from typing import BinaryIO, Callable, Iterator, TypeVar
+
+_T = TypeVar("_T")
 
 if os.name == "nt":
     import msvcrt
@@ -22,14 +24,53 @@ else:
     import fcntl
 
 
+# Windows refuses os.replace, and even a stat or a read, on a file that another process has open at
+# that instant, with PermissionError (WinError 5). The window is short. Measured 2026-10-03 with one
+# process replacing a file in a loop: 0 of 759 replaces failed alone, and 250 of 908 failed while a second
+# process called resolve() on it. POSIX has no such window, and there a PermissionError is a real,
+# lasting refusal, so it is never retried.
+_RETRY_DENIED = os.name == "nt"
+_DENIED_RETRY_S = 5.0
+
+
+def retry_denied(operation: Callable[[], _T]) -> _T:
+    """Run ``operation``; on Windows retry a transient PermissionError for up to ``_DENIED_RETRY_S`` seconds."""
+    deadline = time.monotonic() + _DENIED_RETRY_S
+    while True:
+        try:
+            return operation()
+        except PermissionError:
+            if not _RETRY_DENIED or time.monotonic() >= deadline:
+                raise
+            time.sleep(0.01)
+
+
+def _plain(path: Path) -> Path:
+    """Drop the Windows extended-length prefix: ``\\\\?\\C:\\x`` and ``C:\\x`` name the same place.
+
+    While another process is creating or replacing a path, ``Path.resolve()`` can return it in the prefixed form
+    while the root resolves to the plain form, and ``is_relative_to`` then says the path escapes the root
+    (measured 2026-10-03: 2 of 60 trials of two writers starting on an empty folder; CI hit it on 2026-10-02).
+    """
+    text = str(path)
+    if text.startswith("\\\\?\\UNC\\"):
+        return Path("\\\\" + text[8:])
+    if text.startswith("\\\\?\\"):
+        return Path(text[4:])
+    return path
+
+
 def _destination(path: Path, root: Path | None) -> Path:
     path = Path(path)
     if ".." in path.parts:
         raise ValueError("destination may not contain parent traversal")
-    resolved = path.resolve()
-    if root is not None and not resolved.is_relative_to(Path(root).resolve()):
+    # Resolve the parent directory, not the file: another writer may be replacing the file right now, and
+    # resolving the file opens it, which can make that writer's os.replace fail. A symlink as the last
+    # component is refused below.
+    resolved = _plain(retry_denied(path.parent.resolve)) / path.name
+    if root is not None and not resolved.is_relative_to(_plain(Path(root).resolve())):
         raise ValueError("destination escapes artifact root")
-    if path.is_symlink():
+    if retry_denied(path.is_symlink):
         raise ValueError("destination may not be a symlink")
     return resolved
 
@@ -37,7 +78,7 @@ def _destination(path: Path, root: Path | None) -> Path:
 def _document_mode(target: Path) -> int:
     """Mode the replaced document should keep: the existing one, else what ``open()`` would give."""
     try:
-        return stat.S_IMODE(target.stat().st_mode)
+        return stat.S_IMODE(retry_denied(target.stat).st_mode)
     except FileNotFoundError:
         # os.umask has no read-only form; the probe is process-wide for one line, so a file
         # another thread creates in that window gets 0o666. caddis writers are single-threaded.
@@ -78,7 +119,7 @@ def locked_path(
     target = _destination(path, root)
     target.parent.mkdir(parents=True, exist_ok=True)
     lock_path = target.with_name(target.name + ".lock")
-    if lock_path.is_symlink():
+    if retry_denied(lock_path.is_symlink):
         raise ValueError("lock file may not be a symlink")
     # O_NOFOLLOW closes the gap between the check above and the open on POSIX.
     flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
@@ -114,7 +155,7 @@ def atomic_write(path: Path, text: str, *, root: Path | None = None) -> None:
             os.fsync(handle.fileno())
         # NamedTemporaryFile creates 0o600; without this every write would narrow the document.
         os.chmod(temporary, _document_mode(target))
-        os.replace(temporary, target)
+        retry_denied(lambda: os.replace(temporary, target))
         temporary = None  # replaced: that name may now belong to another writer
     finally:
         if temporary is not None:

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

@@ -182,6 +182,7 @@ class GateResult:
     returncode: int
     passed: bool
     tail: str
+    duration_s: float = 0.0
 
 
 @dataclass
@@ -738,6 +739,7 @@ def run_gates(
         with heavy_slot("gates"):
             results = []
             for command in cmds:
+                gate_started = time.monotonic()
                 try:
                     completed = subprocess.run(
                         governed_argv(command),
@@ -756,6 +758,7 @@ def run_gates(
                             returncode=-1,
                             passed=False,
                             tail=f"timed out after {timeout_s}s",
+                            duration_s=time.monotonic() - gate_started,
                         )
                     )
                     continue
@@ -770,6 +773,7 @@ def run_gates(
                         returncode=completed.returncode,
                         passed=passed,
                         tail=output[-2000:],
+                        duration_s=time.monotonic() - gate_started,
                     )
                 )
             return results
@@ -1417,6 +1421,9 @@ def build_prompt(
         "run anything against production.\n"
         "- Do not implement any other phase.\n"
         "- Run every command in the foreground and wait for it to finish. Start no background tasks, watchers or dev servers.\n"
+        "- Test economy: after each step run only the tests for the file or module you changed. Run the full suite "
+        "only for the baseline and once at the end. Do not run a review loop in this lane; the orchestrator reviews. "
+        "Print a progress line every 20 minutes. Never start a second heavy test run while one is still running.\n"
         "Resource budget (enforced by the machine, not by this text):\n"
         f"- You run inside a Windows Job Object: {limits_line}. Exceeding it slows "
         "you down; it does not stop the limit.\n"
@@ -1558,6 +1565,23 @@ def _gate_dict(result: GateResult) -> dict:
         "returncode": result.returncode,
         "passed": result.passed,
         "tail": result.tail,
+        "duration_s": round(result.duration_s, 1),
+    }
+
+
+def _time_split(packet: dict, gates: list[GateResult], review_s: float) -> dict:
+    """Measured seconds the orchestrator can read: the lane run, the gate commands, the review.
+
+    What happens INSIDE the lane (edits versus the lane's own test runs) is not measured: the idle
+    sampler sees process image names every IDLE_SAMPLE_S seconds, not command lines, so it cannot tell a
+    pytest run from any other python process.
+    """
+    return {
+        "lane_s": round(sum(float(lane.get("duration_s") or 0) for lane in packet.get("lanes_tried", [])), 1),
+        "gates_s": round(sum(gate.duration_s for gate in gates), 1),
+        "gate_runs": len(gates),
+        "review_s": round(review_s, 1),
+        "in_lane": "not measured: only process names are visible inside a lane",
     }
 
 
@@ -1597,7 +1621,9 @@ def _run_post_checks(
         packet.pop("_freeze_before", None)
         return "stop", EXIT_NOT_RUN
 
+    review_started = time.monotonic()
     review = run_review(worktree, dict(os.environ))
+    review_s = time.monotonic() - review_started
     pythons = list(before)
     if pythons:
         after = {python: freeze_snapshot(python) for python in pythons}
@@ -1626,6 +1652,7 @@ def _run_post_checks(
             "gates": [_gate_dict(gate) for gate in gates],
             "gates_passed": gates_passed,
             "review": _review_dict(review),
+            "time_split": _time_split(packet, gates, review_s),
             "freeze_unchanged": freeze_unchanged,
             "next": next_step,
         }

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

@@ -12,7 +12,7 @@ from pathlib import Path
 
 try:
     import caddis_exit
-    from caddis_file_lock import atomic_write, locked_path
+    from caddis_file_lock import atomic_write, locked_path, retry_denied
     from caddis_frontmatter import parse, split_document
     from caddis_workstreams import _artifact, _name
 except ModuleNotFoundError as exc:
@@ -21,7 +21,7 @@ except ModuleNotFoundError as exc:
     sys.path.insert(0, str(Path(__file__).resolve().parent))
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
     import caddis_exit
-    from caddis_file_lock import atomic_write, locked_path
+    from caddis_file_lock import atomic_write, locked_path, retry_denied
     from caddis_frontmatter import parse, split_document
     from caddis_workstreams import _artifact, _name
 
@@ -41,15 +41,17 @@ def _path(root: Path, workstream: str | None) -> tuple[Path, Path]:
     if folder.is_symlink() or not folder.resolve().is_relative_to(artifact.resolve()):
         raise ValueError("todo-list path escapes artifact root")
     path = folder / f"{name}.md"
-    if path.is_symlink():  # reads are unlocked, so refuse here as well as in locked_path
+    # Reads are unlocked, so refuse here as well as in locked_path. On Windows a writer replacing the file
+    # makes this probe (and the read below) fail with PermissionError for an instant, so both retry.
+    if retry_denied(path.is_symlink):
         raise ValueError("to-do file may not be a symlink")
     return artifact, path
 
 
 def _read(path: Path, workstream: str | None) -> list[dict]:
-    if not path.exists():
+    if not retry_denied(path.exists):
         return []
-    text = path.read_text(encoding="utf-8")
+    text = retry_denied(lambda: path.read_text(encoding="utf-8"))
     header, body = split_document(text)
     name = workstream or "inbox"
     if header.get("type") != "todo" or header.get("workstream") != name or header.get("status") not in {"current", "done"}:

package/bundles/antigravity-plugin/scripts/claude-oss.ps1

@@ -32,7 +32,7 @@ if (-not $provider) {
 
 # Save the current ANTHROPIC_* so we can restore them — this launcher shares the session.
 $restore = @{}
-foreach ($name in "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL", "ANTHROPIC_AUTH_TOKEN", "CADDIS_HEADLESS") {
+foreach ($name in "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL", "ANTHROPIC_AUTH_TOKEN", "CADDIS_HEADLESS", "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS") {
   $restore[$name] = [Environment]::GetEnvironmentVariable($name)
 }
 
@@ -42,7 +42,15 @@ foreach ($name in "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL", "ANTHROPIC_AUTH_TOKEN
 # EXECUTING the relay's leftover next step before its own prompt.
 $headless = $false
 foreach ($a in $rest) { if ($a -eq "-p" -or $a -eq "--print") { $headless = $true } }
-if ($headless) { $env:CADDIS_HEADLESS = "1" }
+if ($headless) {
+  $env:CADDIS_HEADLESS = "1"
+  if ($provider -eq "glm") {
+    # Print mode exits on the first end_turn without waiting for background tasks.
+    # GLM can background steps and exit with 'standing by', returning no review.
+    # Disable background tasks so GLM executes verification steps synchronously.
+    $env:CLAUDE_CODE_DISABLE_BACKGROUND_TASKS = "1"
+  }
+}
 
 try {
   # Resolve endpoint/model/key. The three stdout lines are captured into a variable and
@@ -54,7 +62,11 @@ try {
   $env:ANTHROPIC_MODEL      = $cfg[1]
   $env:ANTHROPIC_AUTH_TOKEN = $cfg[2]
 
-  & claude @rest
+  if ($MyInvocation.ExpectingInput) {
+    $input | & claude @rest
+  } else {
+    & claude @rest
+  }
   exit $LASTEXITCODE
 } finally {
   foreach ($name in $restore.Keys) {

package/bundles/antigravity-plugin/scripts/claude-oss.sh

@@ -33,12 +33,23 @@ fi
 # act on it — the SessionStart relay injection is skipped for headless runs, because a run
 # handed its task on the command line does not need a resume pointer and was observed
 # EXECUTING the relay's leftover next step before its own prompt.
+headless=0
 for _arg in "$@"; do
   case "$_arg" in
-    -p|--print) export CADDIS_HEADLESS=1 ;;
+    -p|--print)
+      export CADDIS_HEADLESS=1
+      headless=1
+      ;;
   esac
 done
 
+if [ "$headless" -eq 1 ] && [ "$provider" = "glm" ]; then
+  # Print mode exits on the first end_turn without waiting for background tasks.
+  # GLM can background steps and exit with 'standing by', returning no review.
+  # Disable background tasks so GLM executes verification steps synchronously.
+  export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
+fi
+
 # Prefer python3, fall back to python.
 PY="python3"; command -v "$PY" >/dev/null 2>&1 || PY="python"
 

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

@@ -36,11 +36,11 @@
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Adopt App | `adopt-app/` | Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard — inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production". |
+| Adopt App | `adopt-app/` | >- |
 | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipelines for GitHub Actions and Azure DevOps: build and deploy workflows, quality gates, environment promotion and release automation. |
 | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
 | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
-| Port To Github | `port-to-github/` | Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over WinRM) — all branches and tags, SHA-verified, CI translated, history kept source-only, deploy cut over with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub". |
+| Port To Github | `port-to-github/` | >- |
 | Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting a directory tree, scratchpad or git worktree, or "tidying up" generated folders, especially on Windows, where deleting through a junction or symlink destroys its target; and to verify a venv or node_modules survived. |
 | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from the current workspace, or before executing an implementation plan: creates an isolated git worktree safely. |
 | Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, IIS or nginx reverse proxy and git-pull. Use for Windows prod deploys, NSSM, reverse proxy setup, dev/prod config, or prod troubleshooting. |
@@ -64,6 +64,7 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Css Architecture | `css-architecture/` | CSS architecture: design tokens, custom properties, Tailwind config, CSS Modules, container queries, dark mode, fluid typography, animation. Covers how to implement styling; frontend-design covers what to achieve. |
+| Flow Studio | `flow-studio/` | Design an interactive flow, lifecycle or journey page (nodes, lanes, links, motion, inspector, notes) from a JSON model as a self-contained demo, then build it in an app. Use for lineage, pipelines, ticket or agent journeys. |
 | Frontend Design | `frontend-design/` | Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters or applications. |
 | Mockup | `mockup/` | Create framework-aware UI mockups with feasibility checks. Prevents wasted effort by validating that proposed designs work within the target framework's constraints. |
 | React Best Practices | `react-best-practices/` | Modern React development guidelines covering hooks, component patterns, state management, performance optimization, and TypeScript integration. |
@@ -118,7 +119,7 @@
 |-------|------|-------------|
 | Draw Io | `draw-io/` | draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage. |
 | 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/` | Zero-dependency animated particle art as a React/Next.js component (spring physics, CSS-variable theming, mouse interaction). Use for animated hero art or a living logo, or on "particles that form a shape", "particle animation", "node network", "animated letter/logo/initials", "living letter", "morphing particles", "constellation", "neural net art", "dot field", "stipple portrait", "halftone animation", "ASCII art animation", "background art for my site", or "art that reacts to mouse". |
+| Particle Art | `particle-art/` | >- |
 
 ### Testing
 
@@ -133,7 +134,7 @@
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Advisory Hub | `advisory-hub/` | A long-lived "Hub" session re-derives each phase of a multi-session plan instead of trusting its self-report. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or a long plan with expensive-to-reverse work (a migration, a security change, production data correctness) needs independent checks; not for short features. Hub artefacts, including `hub-NN.spawn.md`, go in `.caddis/advisory-hub-reports/`. |
+| Advisory Hub | `advisory-hub/` | >- |
 | Best Practices | `best-practices/` | >- |
 | Brainstorming | `brainstorming/` | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. |
 | Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |

package/bundles/antigravity-plugin/skills/adopt-app/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: adopt-app
-description: Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard — inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production".
+description: >-
+  Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard:
+  inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this
+  app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on
+  the server", "what would it take to get this into CI", "nobody knows how this is deployed", or "it
+  started as a prototype and now it is production".
 ---
 
 # adopt-app

package/bundles/antigravity-plugin/skills/advisory-hub/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: advisory-hub
-description: A long-lived "Hub" session re-derives each phase of a multi-session plan instead of trusting its self-report. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or a long plan with expensive-to-reverse work (a migration, a security change, production data correctness) needs independent checks; not for short features. Hub artefacts, including `hub-NN.spawn.md`, go in `.caddis/advisory-hub-reports/`.
+description: >-
+  A long-lived "Hub" session re-derives each phase of a multi-session plan instead of trusting its
+  self-report. Use when the user says "advisory hub", "validate this phase", "phase report", "hub
+  verdict", "who checks the implementing session", "re-derive don't trust", "hand off the hub", or a
+  long plan with expensive-to-reverse work (migration, security change, production data correctness)
+  needs independent checks; not for short features. Hub artefacts go in
+  `.caddis/advisory-hub-reports/`.
 ---
 
 # Advisory Hub — cross-session phase validation

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

@@ -28,7 +28,7 @@ comes out differently.
 ```markdown
 ---
 type: adr
-status: accepted
+status: current
 found: <YYYY-MM-DD>
 ---
 

package/bundles/antigravity-plugin/skills/flow-studio/README.md

@@ -0,0 +1,53 @@
+# flow-studio (engine source)
+
+Stage S1a of the `flow-studio` skill: a model file (JSON) describes a flow, lifecycle or journey, and one
+engine draws it as a self-contained HTML page with pan and zoom, lanes, linked nodes, a slide-in
+inspector, motion that carries state, and numbered implementation notes. The design is in
+`.caddis/plans/flow-studio-skill-design.md`; the plan for this stage is `.caddis/plans/flow-studio-s1a-plan.md`.
+There is no `SKILL.md` yet: the playbook arrives in stage S2.
+
+## Use it
+
+```bash
+# from this folder (Node 22.6 or newer)
+node --experimental-strip-types scripts/validate.mjs examples/lineage.json
+node --experimental-strip-types scripts/build.mjs examples/lineage.json out/lineage.html
+```
+
+Open `out/lineage.html`. It has no network access and no libraries.
+
+`build.mjs` embeds the model's own `notes` plus any extra notes from `--notes notes.json` (the model's
+notes come first, then the file's). Note anchors are CSS selectors for parts of the page, for example
+`#viewport`.
+
+## Check a page
+
+The harness drives a real browser. Run it from a folder whose `node_modules` has `playwright`
+(it is looked up from the current folder, not from this one):
+
+```bash
+node /path/to/flow-studio/scripts/check.mjs out/lineage.html --out shots --hostile out/hostile.html --channel msedge
+```
+
+It checks structure (no overlap, links touch their nodes, text stays inside cards, readable first view),
+interaction (zoom, pan, select, what-if, view switch), accessibility (names, focus, contrast in both themes,
+reduced motion), safety (no network, hostile text stays inert) and performance (200 nodes). Exit code 0 means
+every check passed.
+
+`scripts/lib/check-selftest.test.mjs` feeds the harness pages with one deliberate defect each and fails
+if a defect is not caught. It is skipped when Playwright cannot be resolved, so run it from a folder that has
+it: `FLOW_STUDIO_CHANNEL=msedge node --test /path/to/flow-studio/scripts/lib/check-selftest.test.mjs`.
+
+## Develop it
+
+- The source of truth is `src/*.ts`. The pure modules (`model`, `viewport`, `routing`, `trace`, `layout`,
+  `rules`, `stateCss`) have unit tests. The DOM modules (`render`, `controls`, `interact`, `inspector`,
+  `chrome`, `notes`, `engine`) are tested through the check harness.
+- `npm test` runs the unit tests (`node --experimental-strip-types --test`).
+- `templates/engine.html` is generated and committed. After you change `src/` or `templates/engine.shell.html`,
+  run `node --experimental-strip-types scripts/build-engine.mjs`. A test fails when the committed file is stale.
+- `build-engine.mjs` needs `esbuild`. It looks in this folder, then in the caddis `cli/` folder, then in the
+  current folder. In a caddis checkout, `cli/node_modules` already has it. Elsewhere, run `npm i -D esbuild`. The stale-engine check compares bytes, so use the same esbuild version as the checkout that committed the file (the caddis `cli/` one).
+- Type check with `tsc -p tsconfig.json` (TypeScript from `cli/node_modules` or your own install).
+- Examples use fictional data only: this repository is public.
+- Delete the `out/` folder before exporting bundles. It is ignored by git but not by a file copy.

package/bundles/antigravity-plugin/skills/flow-studio/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: flow-studio
+description: Design an interactive flow, lifecycle or journey page (nodes, lanes, links, motion, inspector, notes) from a JSON model as a self-contained demo, then build it in an app. Use for lineage, pipelines, ticket or agent journeys.
+---
+
+# flow-studio
+
+Turns a one-paragraph brief into an explorable page: stages across, lanes down, linked nodes, pan and zoom,
+a slide-in inspector, motion that carries meaning, and numbered implementation notes. One JSON **model**
+describes the scenario. One engine draws it. A check script proves it is sound.
+
+Use it for: data lineage and dependency impact, a ticket or case lifecycle, an agent or customer journey, a CI/CD
+or release pipeline, an approval flow, an incident timeline, a service map. See `references/patterns.md`.
+Not for: a static screen or UI variants (use `mockup` or `sketch`), a chart, a graph with more than 300 nodes.
+
+## What works today (version 0.1)
+
+Left-to-right flows in **columns** (stages) and **lanes** (apps, systems or actors): states with their own look
+and motion, portal chips for shared nodes, wide placeholders for what is not recorded, two or more views
+(for example Today and Complete), search, a what-if action (a red ripple downstream), a table view, and notes.
+
+**Not yet** (planned, do not promise them): links that go back to an earlier stage (loops), gateway diamonds,
+automatic placement, token playback along a path, live data updates, free x and y placement. If the scenario
+needs a loop, show the return as its own node in a later column (for example "Reopened") and say so.
+
+## Process: demo mode
+
+1. **Ask at most three questions**: what is the page for, who reads it, and what are the nouns (the stages, the
+   lanes, the states). If the brief already says, ask none.
+2. **Map the scenario** to the model (`references/patterns.md` has a recipe per scenario):
+   columns = stages left to right, lanes = who or what owns the row, states = the vocabulary (for example
+   new, open, waiting, breached, resolved), nodes = the things, links = the flow.
+3. **Write `model.json`.** Fields are in `model.schema.json`; `examples/lineage.json` is a complete model.
+4. **Validate:** `node --experimental-strip-types scripts/validate.mjs model.json`. Fix every error. Read every
+   warning.
+5. **Build:** `node --experimental-strip-types scripts/build.mjs model.json out/page.html`. It is one file with
+   no network use.
+6. **Check:** from a folder that has `playwright`:
+   `node <skill folder>/scripts/check.mjs out/page.html --out shots [--channel msedge]`.
+   Every check must pass. Open the screenshots and look at them: the checks do not judge taste.
+7. **Show** the page and the screenshots. Do not call it done until the checks pass and you have looked.
+
+Paths above are relative to the folder that holds this file. Node 22.6 or newer is needed.
+
+## Design rules (the engine and the checks enforce most of them)
+
+1. **No orphan.** Every node sits in a lane and has a link. A missing neighbour is a dotted placeholder that says
+   what is missing. Never guess a link.
+2. **The first view is readable**: fit to width at zoom 0.6 or more (up to 60 groups). Key `0` shows everything.
+3. **Read left to right**, with pinned column headers and a phase ribbon.
+4. **Motion carries state**: links flow by state, gaps breathe, the selected path draws in, a what-if ripples.
+   No decorative loops, no sweeping scan line, no bounce.
+5. **No permanent side panel.** The inspector slides in on a click and closes with Esc.
+6. **Standard controls**: select, hand, zoom in and out, fit, 100 percent, zoom to selection, fullscreen, keys.
+7. **Every state has a word as well as a colour.** Contrast at least 4.5 in light and dark.
+8. **Titles stay short** (one line at the column width). Long text goes in `subtitle` or `members`.
+9. **Fixed node sizes per kind.** The engine never measures text, so layout does not depend on fonts.
+10. **Reduced motion** removes all motion and keeps the glow.
+
+## Model in one screen
+
+```
+version 1, meta {title, help, asOf, source, labels?}, layout "columns-lanes"
+columns [{id, title, short?, width, phase?}]              stages, left to right
+lanes   [{id, title, badge?, badgeTone?, note?, gap?}]    rows; gap true = dashed amber "no document" lane
+states  {id: {word, tone, border, edge, motion, bucket}} the vocabulary; bucket good|neutral|gap
+nodes   [{id, kind, lane, col, colSpan?, row, state, title, subtitle?, members?, weight?, ref?, upgrade?,
+          stateIn?, visibleIn?}]                          kind: card group chip placeholder (others draw as cards)
+links   [{id, from, to, state, label?, stateIn?, visibleIn?}]   from must be in an earlier column than to
+views   [{id, label, default?}]                           the first view is the baseline
+inspector {relations [3 of {id,label,dir,filter?}], actions [{id,label,dir,staleText}]}
+notes   [{anchor, title, text}]                           anchor is a CSS selector for a part of the page
+```
+
+Rows are numbers (1 row = 62 px). Keep nodes in one column at least 1 row apart. A lane needs about 1.75 rows of
+space between single-row lanes. `validate.mjs` checks all of this and names the node or link at fault.
+
+## Build mode: implement it in a real app
+
+Use the demo page as the visual contract and `model.schema.json` as the data contract.
+
+1. Copy the pure modules from `src/` into the app: `model.ts`, `layout.ts`, `viewport.ts`, `routing.ts`,
+   `trace.ts`, `rules.ts`, `stateCss.ts`, and their `*.test.ts` files. They have no DOM and no dependencies.
+2. Work test first: run the copied tests, then write a failing test for each change.
+3. Write the components in the app's own framework and design system (the demo's DOM and CSS are in
+   `src/render.ts`, `src/controls.ts`, `src/inspector.ts`, `src/chrome.ts`, `src/styles.css`). Feed them from the
+   app's real data through the app's hook and service layer. Make node and link ids stable (use business keys, not
+   array positions).
+4. Keep typed loading, empty and error states. A failed refresh keeps the last good graph. Never draw a missing
+   value as zero.
+5. Run `scripts/check.mjs` against the running app page for the structural, interaction and accessibility checks
+   (the page must expose the same element ids, or copy the harness and adapt it).
+
+A packaged React kit and live-update API are planned; until then, build mode is "copy the pure modules, port the
+DOM modules".
+
+## Gotchas
+
+- Examples and any committed data must be invented: a public repo must not carry real host, job or repo names.
+- A model string is data, never markup. The engine renders text safely; keep it that way in any port.
+- The caddis pool budgets all skill descriptions together. Keep this one short.
+- `templates/engine.html` is generated. After changing `src/`, run `node --experimental-strip-types
+  scripts/build-engine.mjs` (it needs `esbuild`; see `README.md`).

package/bundles/antigravity-plugin/skills/flow-studio/examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Model files only. Build one with `node --experimental-strip-types scripts/build.mjs examples/<name>.json out/<name>.html`.
+
+| File | What it shows |
+|---|---|
+| `lineage.json` | A fictional data estate ("Northwind Analytics"): nine columns from source system to page, eight lanes (documented, infrastructure, gaps), four evidence states, two views (Today and Complete), portal chips, wide placeholders, the failure what-if. The proof that the generic engine reproduces a hand-built lineage page. |
+| `hostile.json` | The same model with markup and script text in every free-text field (`</script>`, an image with an `onerror`, quotes, U+2028 and U+2029). The check harness loads it to prove nothing executes. Do not use it as a template. |
+
+All data is fictional. The names are invented, and no real host, job, table or repository appears in them.
+`lineage.json` and `hostile.json` are generated by a script that is not part of the skill; edit the JSON directly.