code-coordinator 0.5.154__tar.gz → 0.5.156__tar.gz

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/CLAUDE.md

@@ -135,30 +135,14 @@ computes the routing without actually building or testing anything.
 ## Working on `tui/` — the `quadraui` pin
 
 **`coord-tui` pins `quadraui` to a git rev in `tui/Cargo.toml`**
-(`quadraui = { git = "https://github.com/JDonaghy/quadraui", rev = "<sha>" }`, #1973). This
-replaced the old relative-path dependency (`../../quadraui/quadraui`), which built against
-whatever branch happened to be checked out in `~/src/quadraui` — a quadraui merge could break
-coord-tui's build/merge with **zero coord-tui commits and no warning** (it already happened
-once). `cargo build`/`cargo test` from `tui/` now fetch quadraui straight from GitHub at the
-pinned rev and never touch `~/src/quadraui`, so the local checkout's branch is irrelevant.
-
-- **Bumping the pin** (deliberate, reviewable, its own coord-tui commit): pick the target
-  quadraui rev — normally the tip of `origin/develop` (quadraui's default/integration branch,
-  per quadraui's CLAUDE.md) — edit the `rev = "..."` in `tui/Cargo.toml`, then run
-  `cargo build && cargo test` from `tui/` and confirm EXIT=0 before committing.
-  `cargo update -p quadraui` alone will **not** move a `rev`-pinned git dependency; the
-  `Cargo.toml` edit is the actual bump.
-- **Co-developing against an unmerged quadraui branch/PR:** if a `tui/` task consumes a
-  not-yet-merged quadraui feature, the briefing **must** name the quadraui PR/branch. The
-  worker builds against a local `~/src/quadraui` checkout **without editing
-  `tui/Cargo.toml`**, via cargo's local-paths override:
-  `cp tui/cargo-config-local-quadraui.toml.example tui/.cargo/config.toml` (git-ignored — see
-  the example file's header) after checking out the target branch in `~/src/quadraui`. Delete
-  `tui/.cargo/config.toml` (or don't create it) to build against the pinned rev again — this
-  is the default and what CI/other workers use. **Verify build EXIT=0 from `tui/` both with
-  the override active (proves the feature works) and, before finishing, confirm the committed
-  `tui/Cargo.toml` still points at the pinned rev** (the override file itself is never
-  committed).
+(`quadraui = { git = "https://github.com/JDonaghy/quadraui", rev = "<sha>" }`, #1973) —
+never edit that `rev` as a shortcut for co-development, and never build `tui/` against
+whatever happens to be checked out in `~/src/quadraui`; a quadraui merge broke coord-tui's
+build with zero coord-tui commits and no warning once already, which is exactly what the pin
+prevents. Bumping the pin deliberately, and building against an unmerged quadraui branch/PR
+without touching the pin, are both procedures — see the `tui-quadraui-workflow` skill
+(`coord/skills/tui-quadraui-workflow/SKILL.md`) for the steps; install it with `coord
+install-skills` if it isn't already on this machine.
 
 ## Key Design Decisions
 

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.154
+Version: 0.5.156
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.154
+Version: 0.5.156
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/code_coordinator.egg-info/SOURCES.txt

@@ -344,7 +344,14 @@ coord/providers/base.py
 coord/providers/claude.py
 coord/providers/claude_pty.py
 coord/providers/opencode.py
+coord/skills/coord-dispatch-verbs/SKILL.md
+coord/skills/drive-queue-preflight/SKILL.md
+coord/skills/fleet-restart-safety/SKILL.md
+coord/skills/merge-stuck-triage/SKILL.md
+coord/skills/pipeline-limbo-triage/SKILL.md
 coord/skills/portal-followup/SKILL.md
+coord/skills/review-verdict-recovery/SKILL.md
+coord/skills/tui-quadraui-workflow/SKILL.md
 coord/skills/update-issue/SKILL.md
 deploy/coord-agent.service
 deploy/coord-db-backup.service
@@ -442,6 +449,7 @@ tests/test_agent_push_failure.py
 tests/test_agent_reap.py
 tests/test_agent_repos_and_pull.py
 tests/test_agent_restart_services_endpoint.py
+tests/test_agent_skills_self_heal.py
 tests/test_agent_startup_diagnostics.py
 tests/test_agent_update.py
 tests/test_agent_update_bluegreen.py

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/code_coordinator.egg-info/scm_file_list.json

@@ -307,7 +307,14 @@
     "coord/review.py",
     "coord/scorecard.py",
     "coord/serve_app.py",
+    "coord/skills/coord-dispatch-verbs/SKILL.md",
+    "coord/skills/drive-queue-preflight/SKILL.md",
+    "coord/skills/fleet-restart-safety/SKILL.md",
+    "coord/skills/merge-stuck-triage/SKILL.md",
+    "coord/skills/pipeline-limbo-triage/SKILL.md",
     "coord/skills/portal-followup/SKILL.md",
+    "coord/skills/review-verdict-recovery/SKILL.md",
+    "coord/skills/tui-quadraui-workflow/SKILL.md",
     "coord/skills/update-issue/SKILL.md",
     "coord/smoke.py",
     "coord/spend_ceiling.py",
@@ -486,6 +493,7 @@
     "tests/test_agent_reap.py",
     "tests/test_agent_repos_and_pull.py",
     "tests/test_agent_restart_services_endpoint.py",
+    "tests/test_agent_skills_self_heal.py",
     "tests/test_agent_startup_diagnostics.py",
     "tests/test_agent_update.py",
     "tests/test_agent_update_bluegreen.py",

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.154",
+  "tag": "0.5.156",
   "distance": 0,
-  "node": "g318d3f718e0a8945e4363a00807cd76278153173",
+  "node": "g3cb93fa341dc733f826d22601d0c538118cd8dc9",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/coord/agent.py

@@ -4504,6 +4504,24 @@ class AgentServer:
         self._graph_heal_last_skip_at: float | None = None
         self._graph_heal_passes: int = 0
 
+        # Skills self-heal (#319 follow-up): `coord install-skills` was a
+        # real fix (coord/skills/*/SKILL.md) for a real problem, but was a
+        # 100%-manual step nothing in provisioning ever ran — so a skill
+        # added or updated in a coordinator release could sit uninstalled on
+        # a worker machine indefinitely, unnoticed, the same "silent gap"
+        # shape already known from the graphify hooks and the browser
+        # capability probe. Rides the same cached health-check tick as the
+        # graph self-heal above rather than adding a new timer — syncing a
+        # handful of small text files is cheap enough to need none of that
+        # pass's guards (no idle-gate, no in-flight dedup, no retry budget).
+        # In-memory only, resets on agent restart, same rationale as
+        # `_graph_heal_passes` above: it exists to answer "is this machine's
+        # skill set current", not to be a durable metric.
+        self._skills_heal_passes: int = 0
+        self._skills_heal_last_run_at: float | None = None
+        self._skills_heal_last_synced: list[dict[str, str]] = []
+        self._skills_heal_last_error: str | None = None
+
         self.state_dir.mkdir(parents=True, exist_ok=True)
         self.log_dir.mkdir(parents=True, exist_ok=True)
         self._load_state()
@@ -4888,6 +4906,21 @@ class AgentServer:
                 "skipped_active": self._graph_heal_skipped_active,
                 "last_skip_at": self._graph_heal_last_skip_at,
             },
+            # Same idea as `graph_self_heal` above, for the bundled
+            # `coord/skills/*/SKILL.md` sync: `coord install-skills` existed
+            # as a real fix but was a 100%-manual step nothing in
+            # provisioning ever ran, so a skill added in a coordinator
+            # release could sit uninstalled on a worker machine
+            # indefinitely, unnoticed. `last_synced` names whichever skills
+            # actually changed on the most recent pass (empty on the common
+            # "already current" tick) so `coord doctor` can show something
+            # more useful than a bare pass count.
+            "skills_self_heal": {
+                "passes": self._skills_heal_passes,
+                "last_run_at": self._skills_heal_last_run_at,
+                "last_synced": self._skills_heal_last_synced,
+                "last_error": self._skills_heal_last_error,
+            },
             # #2299: is this agent actually watching a coordinator.yml, and
             # has it picked anything up? `watching` is None for a
             # config-free/thin-client agent (nothing local to re-read), which
@@ -4953,6 +4986,12 @@ class AgentServer:
                 self._self_heal_stale_graphs(ctx, report)
             except Exception as exc:  # noqa: BLE001 — self-heal is best-effort
                 _log.warning("graph self-heal pass failed: %s", exc)
+            try:
+                # Same isolation as the graph pass above: a skills-sync bug
+                # must never blind this whole health block.
+                self._self_heal_missing_skills()
+            except Exception as exc:  # noqa: BLE001 — self-heal is best-effort
+                _log.warning("skills self-heal pass failed: %s", exc)
             report_dict = report.to_dict()
             payload = {
                 "schema": report_dict["schema"],
@@ -5169,6 +5208,59 @@ class AgentServer:
             if replacement is not None:
                 report.results[i] = replacement
 
+    def _self_heal_missing_skills(self) -> None:
+        """Sync bundled `coord/skills/*/SKILL.md` into ``~/.claude/skills/``
+        on this machine, riding the same cached health-check tick as
+        `_self_heal_stale_graphs` above.
+
+        `coord install-skills` (#319) was a real fix for a real problem, but
+        it was a 100%-manual step — nothing in agent provisioning or this
+        health tick ever ran it, so a skill added or updated in a
+        coordinator release could sit uninstalled on a worker machine
+        indefinitely, unnoticed. That is the same "silent gap" shape as the
+        graphify hooks and the browser-capability probe this codebase
+        already knows about.
+
+        Unlike the graph rebuild, this needs none of that pass's four
+        guards: syncing a handful of small text files is cheap file I/O, not
+        a CPU-heavy subprocess, so there is no idle-gate, no in-flight
+        dedup, and no retry budget — `sync_bundled_skills` is already
+        idempotent (content-identical files are left untouched, so a
+        no-op tick costs a handful of reads, nothing more).
+        """
+        from coord.commands.setup import (  # noqa: PLC0415
+            list_bundled_skill_dirs,
+            sync_bundled_skills,
+        )
+
+        target_root = Path.home() / ".claude" / "skills"
+        try:
+            skill_dirs = list_bundled_skill_dirs()
+        except Exception as exc:  # noqa: BLE001 — recorded, never raised further
+            self._skills_heal_last_error = f"{type(exc).__name__}: {exc}"
+            return
+
+        self._skills_heal_passes += 1
+        self._skills_heal_last_run_at = time.time()
+        self._skills_heal_last_error = None
+        if not skill_dirs:
+            self._skills_heal_last_synced = []
+            return
+
+        target_root.mkdir(parents=True, exist_ok=True)
+        results = sync_bundled_skills(target_root, skill_dirs)
+        changed = [
+            {"skill": name, "action": action}
+            for name, action in results
+            if action != "unchanged"
+        ]
+        self._skills_heal_last_synced = changed
+        if changed:
+            _log.info(
+                "skills self-heal: %s",
+                ", ".join(f"{c['skill']} {c['action']}" for c in changed),
+            )
+
     @staticmethod
     def _graph_failure_result(result: Any, values: dict, detail: str) -> Any:
         """Guard 4's WARN replacement, shared by the attempt and the

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/coord/commands/issues.py

@@ -683,6 +683,9 @@ def backlog(repo: str, issue: int, config_path: Path) -> None:
         "Stage a Pipeline issue as \"next up\" by tagging it with "
         "`status:queued` — moves a Pipeline:New card into "
         "In-progress:`ready` with no dispatch (display + intent only).\n\n"
+        "NOT the driver queue: this command never dispatches anything. To "
+        "actually get an issue worked end-to-end, use `coord drive-queue "
+        "add <repo> <issue>` instead — see the coord-dispatch-verbs skill.\n\n"
         "Deliberately a separate label from `status:ready`: that one is "
         "already applied automatically by `coord track` / the refinement "
         "finalize step for every issue sent to the Pipeline, so it carries "

{code_coordinator-0.5.154 → code_coordinator-0.5.156}/coord/commands/setup.py

@@ -482,6 +482,60 @@ def _build_init_yaml(
     return "\n".join(lines) + "\n"
 
 
+def list_bundled_skill_dirs() -> list[tuple[str, object]]:
+    """Enumerate bundled `coord/skills/*/SKILL.md` directories (#319).
+
+    Returns ``(skill_name, entry)`` pairs, sorted by name, for every
+    sub-directory of the installed `coord.skills` package that contains a
+    readable ``SKILL.md``. Raises ``ModuleNotFoundError``/``TypeError`` if
+    the package itself can't be located, or ``FileNotFoundError``/
+    ``NotADirectoryError`` if its directory listing can't be read — callers
+    decide how to surface that (``install_skills`` below exits 1; the
+    agent-side self-heal in `agent.py` logs and moves on, since a skills
+    hiccup must never block `/health`).
+    """
+    import importlib.resources as _ilr  # noqa: PLC0415
+
+    skills_ref = _ilr.files("coord").joinpath("skills")
+    skill_dirs: list[tuple[str, object]] = []
+    for entry in skills_ref.iterdir():
+        skill_name = entry.name  # type: ignore[attr-defined]
+        skill_file = entry.joinpath("SKILL.md")
+        try:
+            skill_file.read_text(encoding="utf-8")
+            skill_dirs.append((skill_name, entry))
+        except (FileNotFoundError, IsADirectoryError, TypeError):
+            pass
+    return sorted(skill_dirs)
+
+
+def sync_bundled_skills(
+    target_root: Path, skill_dirs: list[tuple[str, object]]
+) -> list[tuple[str, str]]:
+    """Write each ``(skill_name, entry)`` from *skill_dirs* into
+    *target_root* (normally ``~/.claude/skills/``) if missing or changed
+    (#319 / agent self-heal).
+
+    Returns ``(skill_name, action)`` pairs, ``action`` one of ``"installed"``,
+    ``"updated"``, or ``"unchanged"`` — content-identical skills are left
+    untouched (no rewrite, no mtime bump) so a periodic caller can run this
+    every tick without churn. Does not create *target_root* itself; callers
+    create it first once they know there is something to write.
+    """
+    results: list[tuple[str, str]] = []
+    for skill_name, skill_dir_ref in skill_dirs:
+        skill_file_dest = target_root / skill_name / "SKILL.md"
+        src_text = skill_dir_ref.joinpath("SKILL.md").read_text(encoding="utf-8")  # type: ignore[attr-defined]
+        if skill_file_dest.exists() and skill_file_dest.read_text(encoding="utf-8") == src_text:
+            results.append((skill_name, "unchanged"))
+            continue
+        action = "updated" if skill_file_dest.exists() else "installed"
+        skill_file_dest.parent.mkdir(parents=True, exist_ok=True)
+        skill_file_dest.write_text(src_text, encoding="utf-8")
+        results.append((skill_name, action))
+    return results
+
+
 @click.command(
     "install-skills",
     help=(
@@ -490,8 +544,6 @@ def _build_init_yaml(
         "No repo clone required — reads from the installed PyPI package."
     ),
 )
-
-
 @click.option(
     "--list",
     "do_list",
@@ -499,43 +551,24 @@ def _build_init_yaml(
     default=False,
     help="Show bundled skills and their installed status without copying.",
 )
-
-
 @click.option(
     "--dry-run",
     is_flag=True,
     default=False,
     help="Print what would be installed without writing any files.",
 )
-
-
 def install_skills(do_list: bool, dry_run: bool) -> None:  # noqa: FBT001
     """Install bundled coordinator skills to ~/.claude/skills/ (#319)."""
-    import importlib.resources as _ilr  # noqa: PLC0415
-
     if do_list and dry_run:
         click.echo("warning: --dry-run has no effect when --list is used", err=True)
 
     target_root = Path.home() / ".claude" / "skills"
 
-    # Locate the skills directory inside the installed package.
     try:
-        skills_ref = _ilr.files("coord").joinpath("skills")
+        skill_dirs = list_bundled_skill_dirs()
     except (TypeError, ModuleNotFoundError) as e:
         click.echo(f"error: cannot locate bundled skills: {e}", err=True)
         sys.exit(1)
-
-    # Enumerate skill directories (each sub-directory that contains SKILL.md).
-    skill_dirs: list[tuple[str, object]] = []
-    try:
-        for entry in skills_ref.iterdir():
-            skill_name = entry.name  # type: ignore[attr-defined]
-            skill_file = entry.joinpath("SKILL.md")
-            try:
-                skill_file.read_text(encoding="utf-8")
-                skill_dirs.append((skill_name, entry))
-            except (FileNotFoundError, IsADirectoryError, TypeError):
-                pass
     except (FileNotFoundError, NotADirectoryError) as e:
         click.echo(f"error: bundled skills directory not readable: {e}", err=True)
         sys.exit(1)
@@ -546,31 +579,26 @@ def install_skills(do_list: bool, dry_run: bool) -> None:  # noqa: FBT001
 
     if do_list:
         click.echo("Bundled skills:")
-        for skill_name, _ in sorted(skill_dirs):
+        for skill_name, _ in skill_dirs:
             installed_path = target_root / skill_name / "SKILL.md"
             status = "installed" if installed_path.exists() else "not installed"
             click.echo(f"  {skill_name:30s}  {status}")
         return
 
-    # Install / update each skill.
-    if not dry_run:
-        target_root.mkdir(parents=True, exist_ok=True)
-    for skill_name, skill_dir_ref in sorted(skill_dirs):
-        skill_dest = target_root / skill_name
-        skill_file_dest = skill_dest / "SKILL.md"
-        if dry_run:
+    if dry_run:
+        for skill_name, _ in skill_dirs:
+            skill_file_dest = target_root / skill_name / "SKILL.md"
             action = "update" if skill_file_dest.exists() else "install"
             click.echo(f"  would {action}: {skill_file_dest}")
-            continue
+        return
 
-        skill_dest.mkdir(parents=True, exist_ok=True)
-        src_text = skill_dir_ref.joinpath("SKILL.md").read_text(encoding="utf-8")
-        action = "updated" if skill_file_dest.exists() else "installed"
-        skill_file_dest.write_text(src_text, encoding="utf-8")
-        click.echo(f"  {action}: {skill_file_dest}")
+    target_root.mkdir(parents=True, exist_ok=True)
+    for skill_name, action in sync_bundled_skills(target_root, skill_dirs):
+        if action == "unchanged":
+            continue
+        click.echo(f"  {action}: {target_root / skill_name / 'SKILL.md'}")
 
-    if not dry_run:
-        installed_names = sorted(name for name, _ in skill_dirs)
-        cmd_list = "  ".join(f"/{n}" for n in installed_names)
-        click.echo(f"\nDone. Available skills: {cmd_list}")
-        click.echo("Type a skill name inside a Claude Code session to use it.")
+    installed_names = sorted(name for name, _ in skill_dirs)
+    cmd_list = "  ".join(f"/{n}" for n in installed_names)
+    click.echo(f"\nDone. Available skills: {cmd_list}")
+    click.echo("Type a skill name inside a Claude Code session to use it.")

code_coordinator-0.5.156/coord/skills/coord-dispatch-verbs/SKILL.md

@@ -0,0 +1,76 @@
+# coord-dispatch-verbs skill
+
+**Trigger:** About to run a `coord` command to enqueue, dispatch, stage, or
+otherwise move a GitHub issue forward through the coordinator — from any repo,
+including agents working *inside* a coordinator-managed repo, not just the
+operator's own coordinator session — especially when unsure of the exact
+subcommand name, or when a command exited 0 / printed a success message but
+the expected effect (an entry in the queue, an assignment, a dispatch) didn't
+show up.
+
+**Purpose:** `coord`'s CLI has roughly 70 top-level commands, and several have
+names that sound interchangeable but do very different things — picking the
+wrong one usually does **not** error, it silently does something else. This is
+the disambiguation table for the pairs that have actually cost real time,
+plus the one rule that would catch a wrong guess before it's mistaken for
+success.
+
+---
+
+## The incident this skill exists for
+
+An agent working in coord-portal wanted to queue issue #119 for the
+coordinator to pick up. It ran:
+
+```
+coord queue coord-portal 119
+```
+
+This command **exists**, exited 0, and printed a success-looking message — so
+nothing signaled a mistake. But `coord queue` is **not** the driver queue. It
+only tags the issue with a `status:queued` **label** — "next up" staging,
+display + intent only, no dispatch (#1500; it's what the TUI's right-click
+"Mark ready" fires). The issue never entered `coord drive-queue`'s actual
+`waiting` list, so nothing ever picked it up.
+
+**The command that was needed:** `coord drive-queue add coord-portal 119` —
+the durable, board-backed driver queue (#1750) that a periodic tick actually
+walks and dispatches from. See `docs/DRIVE_QUEUE.md` and the
+`drive-queue-preflight` skill.
+
+## Disambiguation table — commands whose names collide but whose effects don't
+
+| If you want to... | Use | NOT | Why the wrong one is dangerous |
+|---|---|---|---|
+| Actually get an issue worked, end-to-end, unattended | `coord drive-queue add <repo> <issue>` | `coord queue <repo> <issue>` | `queue` only applies a label — no dispatch, ever. A silent no-op relative to what you wanted. |
+| Dispatch one issue's Work stage right now, interactively | `coord assign <machine> <repo> <issue>` | `coord drive <repo> <issue> --tmux` outside the queue, while the queue timer is active | `--tmux` drives correctly but is invisible to the queue panel and can race a live `coord-drive-queue.timer` tick — see `docs/OPERATING_GOTCHAS.md` #9. |
+| Un-stage an issue you `coord queue`'d by mistake | `coord unqueue <repo> <issue>` | `coord drive-queue remove <repo> <issue>` | These touch two different systems (a label vs. a queue row) — running the wrong one leaves the other system's state untouched and the symptom persists. |
+| Retry a failed **queue entry** | remove + re-add (`coord drive-queue remove` then `add`) | `coord retry <assignment_id>` | `retry` operates on a board *assignment*, not a drive-queue row — there is deliberately no `coord drive-queue reset` (see `drive-queue-preflight` / `docs/DRIVE_QUEUE.md` §4). |
+| Check whether an issue is actually queued | `coord drive-queue list` / `coord drive-queue status` | trusting the exit code of whatever command you just ran | `coord queue`, `coord assign`, and `coord drive-queue add` all print a success line on their own happy path — only `coord drive-queue list` proves the entry exists as `waiting`. |
+
+## The one rule
+
+**A `coord` command exiting 0 is proof it did what *that command* does — not
+proof it did what you intended.** Before reporting a dispatch/queue/staging
+action as done, confirm the effect directly:
+
+```bash
+coord drive-queue list          # is my issue actually a waiting/running row?
+coord status                    # does an assignment exist for it?
+coord gates <repo> <issue>      # what stage does the board think it's in?
+```
+
+If unsure which of two similarly-named commands does what you want, run
+`coord <command> --help` first — every command's help text states its exact
+effect (`coord queue --help` says so explicitly: "no dispatch, display +
+intent only"). Guessing from the name alone is how this incident happened.
+
+## Rules
+
+- Never assume `coord queue` enqueues work for dispatch — it only labels. The
+  only real dispatch queue is `coord drive-queue`.
+- After any dispatch/queue command, verify with `coord drive-queue list` or
+  `coord status` before reporting the action as done — don't trust a clean
+  exit code alone.
+- When unsure between two `coord` subcommands with similar names, run
+  `--help` on the one you're about to use before running it.

code_coordinator-0.5.156/coord/skills/drive-queue-preflight/SKILL.md

@@ -0,0 +1,90 @@
+# drive-queue-preflight skill
+
+**Trigger:** About to `coord drive-queue add` more than ~2 issues on one repo,
+setting up an overnight/unattended drive-queue run, or looking at a `QUEUE:
+STALLED` / `QUEUE: BLOCKED` status-bar alert.
+
+**Purpose:** Give the real cost model before queuing deep (a queue longer than
+~2 issues per repo is *not* an unattended feature), and the read-the-alert
+table for when a queue stalls. Sourced from `docs/DRIVE_QUEUE.md`'s "Read this
+before queuing more than ~2 issues" (#1715) and its §4 alert table — read that
+doc in full for the mechanics; this is the preflight checklist and the alert
+decoder.
+
+---
+
+## Before queuing — the cascade to know about
+
+Every merge on a repo invalidates every *other* queued branch's Test verdict
+on that same repo (the base moved). Queue N independent issues against one
+repo and merging the first stales the other N−1. This is **intra-repo only**
+— cross-repo entries in the same queue never stale each other and run in
+parallel (the per-repo concurrency ceiling defaults to 1 for exactly this
+reason).
+
+**What has NOT changed:** none of the self-repair below is automatic. The
+unattended auto-drain always passes `revalidate=False` (deliberately, since
+the 2026-06-07 token-burn incident) — an overnight timer with no operator
+still parks stale entries.
+
+**What has changed:** clearing a stale queue the next morning is now one
+command per shared base, not N−1 by hand:
+
+```bash
+coord merge --revalidate --dry-run   # names each batch and its members
+coord merge --revalidate             # one composed suite run per base, then merge
+```
+
+A composed run validates the batch **together**, not each branch alone — a
+re-confirmation of verdicts each member already earned individually, not a
+first proof. If the composite fails, nothing merges; each branch is then
+re-tested alone so the culprit is named and the innocent branches still land.
+
+**Practical guidance:**
+- Genuinely unattended overnight run, nobody coming back to it: keep to 1–2
+  entries per repo (or spread across different repos — they don't stale each
+  other).
+- A run you WILL come back to and drain: queue as deep as you like — the
+  morning drain is one command.
+
+## Reading a `QUEUE:` alert
+
+| Segment | Meaning | What to do |
+|---|---|---|
+| `QUEUE: empty` | nothing queued | nothing |
+| `QUEUE: N running · M waiting` | normal operation | nothing |
+| `QUEUE: STALLED — N waiting, none eligible` (warn) | capacity is free, but every waiting entry is deferred — usually an unresolved `--after` pre-req | usually self-resolves once the pre-req lands; `coord drive-queue status` names exactly which entries and why |
+| `QUEUE: BLOCKED N · M waiting` (warn/crit, outranks a simultaneous stall) | one or more entries are `blocked`: a dependency cycle, a broken `--after`, or a drive that died `attempts` times in a row | usually needs an operator action (below) — but since #2230 some blocked entries self-heal, see next |
+
+**Since #2230, not every `blocked` entry needs a human.** Every tick re-checks
+a blocked entry's own merge gate (unless it's one of two permanent causes — a
+pre-dispatch refusal, or a genuine dead end) and moves it back to `waiting`
+the moment the gate reads clear. If a row is *still* `blocked`, either it
+never had a re-evaluable cause, the gate is genuinely still shut, or it
+already oscillated past the resume ceiling (3 — `resumes=N/3` in `coord
+drive-queue list`).
+
+**Fix for a row that needs a human** — there's deliberately no `reset`;
+remove-and-re-add gives a clean `waiting`/`attempts=0` row:
+
+```bash
+coord drive-queue remove REPO ISSUE && coord drive-queue add REPO ISSUE
+# re-add WITHOUT the bad --after if that was the cause
+```
+
+or, from the TUI overlay, select the blocked entry and press `u`.
+
+Treat `last_reason` as history, not a live diagnosis — it's a snapshot taken
+the instant it was written and never re-validated; `coord drive-queue list`
+shows its age for exactly this reason. Once it's more than a few minutes old,
+go check the board/CI/review state directly instead of trusting the text.
+
+## Rules
+
+- Never assume a deep queue is "fine because auto-drain will handle it" —
+  auto-drain never revalidates, by design.
+- Don't `coord drive-queue add` more than ~2 issues on one repo and walk away
+  unless you're planning to run `coord merge --revalidate` yourself later.
+- Confirm an issue actually landed in the queue with `coord drive-queue list`
+  — see the `coord-dispatch-verbs` skill for why the add command's own exit
+  code isn't sufficient proof.