grok-bot-os 1.0.0__tar.gz

grok_bot_os-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+site/.astro/
+site/dist/
+site/node_modules/
+.polyglot-cache.json
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.venv/
+
+.swarm/

grok_bot_os-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grok_bot_os-1.0.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: grok-bot-os
+Version: 1.0.0
+Summary: Operating system for Grok Bot teams: slow-burn Health A queue. Not the testing-os dogfood-swarm CLI.
+Project-URL: Homepage, https://mcp-tool-shop-org.github.io/grok-bot-os/
+Project-URL: Repository, https://github.com/mcp-tool-shop-org/grok-bot-os
+Author: mcp-tool-shop
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/grok-bot-os/readme.png" width="280" alt="grok-bot-os">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+# grok-bot-os
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/grok-bot-os/actions"><img src="https://github.com/mcp-tool-shop-org/grok-bot-os/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/grok-bot-os"><img src="https://img.shields.io/npm/v/@mcptoolshop/grok-bot-os.svg" alt="npm"></a>
+  <a href="https://pypi.org/project/grok-bot-os/"><img src="https://img.shields.io/pypi/v/grok-bot-os.svg" alt="PyPI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
+  <a href="https://mcp-tool-shop-org.github.io/grok-bot-os/"><img src="https://img.shields.io/badge/landing-page-0ea5e9.svg" alt="Landing page"></a>
+</p>
+
+Versioned operating system for **Grok Bot** teams. Orchestrator, Builder,
+Reviewer, and Researcher sit in a Grok Bot group chat. **Coordinator** is
+Grok Build on the operator's machine — not a Grok Bot. Work moves through a
+live `QUEUE.md` on the Bot VM. Default cadence: one coding job at a time,
+many in review, Coordinator merges when the human is back. Health A is the
+**default lane**, not the ceiling — Coordinator can open Health B–D and
+named features on this same queue.
+
+**Status:** v1.0.0 on PyPI (`grok-bot-os`), npm (`@mcptoolshop/grok-bot-os`), and GitHub Releases.
+
+## What this is not
+
+- Not the `testing-os` dogfood-swarm CLI (`swarm init` / 10-phase).
+- Not `swarm-control-plane` (SQLite waves, domain freeze, receipts).
+- Not Role OS. Role OS orchestrates Codex. This OS orchestrates Grok Bots
+  on the cloud VM via QUEUE.
+
+Stay on **this queue** for one-locus work (Health A default; later classes
+when Coordinator names them). Escalate to swarm-control-plane only when
+the job is **cross-cutting** (frozen domains, wave receipts — Kim 2025 is
+about seats, not a Health A ceiling). Grounding:
+[`docs/RESEARCH.md`](docs/RESEARCH.md).
+
+## Install / use
+
+Registries (optional — the live OS is still a git clone on the Bot VM):
+
+```
+pip install grok-bot-os
+npm install @mcptoolshop/grok-bot-os
+```
+
+`pip` installs `route-scratch` and `check-queue-fields`. The Bot VM still
+clones this repo per `CLONE-POLICY.md` and runs `python3 scripts/route-scratch.py`.
+
+1. Clone the OS and the consumer per `CLONE-POLICY.md`. Coordinator
+   workstation: a local clone of this repo. Bot VM:
+   `/workspace/studio/<repo>` only after a ticket names `owner/repo`.
+   Never copy the Coordinator tree onto the VM. Never copy `.swarm`.
+   Bots never copy the scratch transport clone.
+2. The generic OS contract is `SLOW-BURN.md` in this git. Consumer holds
+   (PR numbers, hours) live in `consumers/<name>.md`. Do **not** overwrite
+   a VM `SLOW-BURN.md` that still carries consumer PR numbers until
+   Orchestrator is reading **both** git files.
+3. Paste **all four** Bot profiles (Name / Title / Description) from
+   `bots/orchestrator.md`, `bots/builder.md`, `bots/reviewer.md`, and
+   `bots/researcher.md` **before** adding anyone to the group. Then add
+   those four to one Grok Bot **group chat** — still four seats, no fifth
+   (Kim 2025). Coordinator is not a Bot (`bots/coordinator.md`).
+4. Seed live `QUEUE.md` on the VM from `QUEUE.template.md` plus the
+   consumer file (stop / prerequisite / owner / fallback in full). Live
+   QUEUE and `TO-COORDINATOR.md` stay on the VM.
+5. Run Orchestrator once (clock or `@Orchestrator`) so it pulls consumer
+   `main` and assigns the first `ready` row. **The first coding job is an
+   Orchestrator @**, never a human paste and never “add Orchestrator after
+   idle.”
+6. Only then may Builder code. Scratch routing: `ROUTE.md` +
+   `scripts/route-scratch.py` on the VM. Poll with `gh api` only (no
+   `git fetch`). Fail-closed: seed last-sha first; do not advance it on
+   exit != 0. Empty stdout after exit 0 = silent. Researcher
+   `SendToAgent`s Bot `DELIVER`s only.
+
+Coordinator session-open (Grok Build TUI on the operator's machine):
+`git pull` the local scratch-transport clone, then read new
+`to: grok-build` envelopes. Do not paste Bot-group logs.
+`TO-COORDINATOR.md` is the VM append-only log, not the transport. The
+TUI has no inbound ping and no API to Grok Bot. Do not reconstruct
+state from the group transcript (KC 2026).
+
+## QUEUE contract (do not compress)
+
+Every QUEUE row, Orchestrator `@`, and scratch ticket carries **stop /
+prerequisite / owner / fallback** in full. **`see SLOW-BURN` is
+forbidden** (Sun 2026). Ready Dependabot / patch rows skip Reviewer.
+Hold / major / behavior still require Reviewer 🛑. Coordinator still
+merges every `coordinator-merge`.
+
+Builder does not review itself. Reviewer pass on a mergeable PR is 🛑.
+Merge stays on Grok Build (Panickssery 2024; Kambhampati 2024).
+
+Finalize emojis, last line only: ✅ Bot done, no Coordinator · 🔧 rework ·
+🛑 Coordinator must act.
+
+## Trust model
+
+**Touches:** public git playbooks; `gh api` against
+`mcp-tool-shop/rig-bridge-scratch` from an already-authenticated `gh`
+on the VM; markdown QUEUE on the VM.
+
+**Does not touch:** npm registry, consumer `main`, Coordinator swarm
+sqlite (`.swarm`, `~\.grok\*.sqlite`), PATs, `auth.json`,
+`mcp_credentials.json`, telemetry, GitHub MCP token fields.
+
+**Permissions:** read this repo; `gh api` as `mcp-tool-shop` for scratch
+routing. Bots never merge. Coordinator merges every `coordinator-merge`
+(`--admin` if Actions dark). Reviewer 🛑 is required for hold / major /
+behavior. Ready patch / Dependabot PRs skip Reviewer. Auto-merge is an
+optional later consumer-side alternative, not this repo's CI. No
+Dependabot merge of hold PRs.
+
+No telemetry. No secrets in source or in tool-call examples.
+
+## Layout
+
+| Path | What |
+|------|------|
+| `SLOW-BURN.md` | Generic OS: seats, QUEUE class, pipeline, emojis |
+| `ROUTE.md` | Scratch `to:` ids + poll + Orchestrator outbox |
+| `CLONE-POLICY.md` | What the VM may clone; Coordinator `git pull` of `the local scratch-transport clone` |
+| `QUEUE.template.md` | Columns including class + four constraint fields |
+| `TO-COORDINATOR.template.md` | VM append-only log format (not the transport) |
+| `bots/*.md` | Paste-ready profiles. `coordinator.md` is not a Bot |
+| `scripts/route-scratch.py` | `gh api` compare → DELIVER lines |
+| `consumers/` | Per-repo catalog, holds, hours |
+| `docs/RESEARCH.md` | Study-swarm citations + implications |
+| `site/` | Landing + Starlight handbook |
+
+## License
+
+MIT.
+
+---
+
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

grok_bot_os-1.0.0/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/grok-bot-os/readme.png" width="280" alt="grok-bot-os">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+# grok-bot-os
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/grok-bot-os/actions"><img src="https://github.com/mcp-tool-shop-org/grok-bot-os/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/grok-bot-os"><img src="https://img.shields.io/npm/v/@mcptoolshop/grok-bot-os.svg" alt="npm"></a>
+  <a href="https://pypi.org/project/grok-bot-os/"><img src="https://img.shields.io/pypi/v/grok-bot-os.svg" alt="PyPI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
+  <a href="https://mcp-tool-shop-org.github.io/grok-bot-os/"><img src="https://img.shields.io/badge/landing-page-0ea5e9.svg" alt="Landing page"></a>
+</p>
+
+Versioned operating system for **Grok Bot** teams. Orchestrator, Builder,
+Reviewer, and Researcher sit in a Grok Bot group chat. **Coordinator** is
+Grok Build on the operator's machine — not a Grok Bot. Work moves through a
+live `QUEUE.md` on the Bot VM. Default cadence: one coding job at a time,
+many in review, Coordinator merges when the human is back. Health A is the
+**default lane**, not the ceiling — Coordinator can open Health B–D and
+named features on this same queue.
+
+**Status:** v1.0.0 on PyPI (`grok-bot-os`), npm (`@mcptoolshop/grok-bot-os`), and GitHub Releases.
+
+## What this is not
+
+- Not the `testing-os` dogfood-swarm CLI (`swarm init` / 10-phase).
+- Not `swarm-control-plane` (SQLite waves, domain freeze, receipts).
+- Not Role OS. Role OS orchestrates Codex. This OS orchestrates Grok Bots
+  on the cloud VM via QUEUE.
+
+Stay on **this queue** for one-locus work (Health A default; later classes
+when Coordinator names them). Escalate to swarm-control-plane only when
+the job is **cross-cutting** (frozen domains, wave receipts — Kim 2025 is
+about seats, not a Health A ceiling). Grounding:
+[`docs/RESEARCH.md`](docs/RESEARCH.md).
+
+## Install / use
+
+Registries (optional — the live OS is still a git clone on the Bot VM):
+
+```
+pip install grok-bot-os
+npm install @mcptoolshop/grok-bot-os
+```
+
+`pip` installs `route-scratch` and `check-queue-fields`. The Bot VM still
+clones this repo per `CLONE-POLICY.md` and runs `python3 scripts/route-scratch.py`.
+
+1. Clone the OS and the consumer per `CLONE-POLICY.md`. Coordinator
+   workstation: a local clone of this repo. Bot VM:
+   `/workspace/studio/<repo>` only after a ticket names `owner/repo`.
+   Never copy the Coordinator tree onto the VM. Never copy `.swarm`.
+   Bots never copy the scratch transport clone.
+2. The generic OS contract is `SLOW-BURN.md` in this git. Consumer holds
+   (PR numbers, hours) live in `consumers/<name>.md`. Do **not** overwrite
+   a VM `SLOW-BURN.md` that still carries consumer PR numbers until
+   Orchestrator is reading **both** git files.
+3. Paste **all four** Bot profiles (Name / Title / Description) from
+   `bots/orchestrator.md`, `bots/builder.md`, `bots/reviewer.md`, and
+   `bots/researcher.md` **before** adding anyone to the group. Then add
+   those four to one Grok Bot **group chat** — still four seats, no fifth
+   (Kim 2025). Coordinator is not a Bot (`bots/coordinator.md`).
+4. Seed live `QUEUE.md` on the VM from `QUEUE.template.md` plus the
+   consumer file (stop / prerequisite / owner / fallback in full). Live
+   QUEUE and `TO-COORDINATOR.md` stay on the VM.
+5. Run Orchestrator once (clock or `@Orchestrator`) so it pulls consumer
+   `main` and assigns the first `ready` row. **The first coding job is an
+   Orchestrator @**, never a human paste and never “add Orchestrator after
+   idle.”
+6. Only then may Builder code. Scratch routing: `ROUTE.md` +
+   `scripts/route-scratch.py` on the VM. Poll with `gh api` only (no
+   `git fetch`). Fail-closed: seed last-sha first; do not advance it on
+   exit != 0. Empty stdout after exit 0 = silent. Researcher
+   `SendToAgent`s Bot `DELIVER`s only.
+
+Coordinator session-open (Grok Build TUI on the operator's machine):
+`git pull` the local scratch-transport clone, then read new
+`to: grok-build` envelopes. Do not paste Bot-group logs.
+`TO-COORDINATOR.md` is the VM append-only log, not the transport. The
+TUI has no inbound ping and no API to Grok Bot. Do not reconstruct
+state from the group transcript (KC 2026).
+
+## QUEUE contract (do not compress)
+
+Every QUEUE row, Orchestrator `@`, and scratch ticket carries **stop /
+prerequisite / owner / fallback** in full. **`see SLOW-BURN` is
+forbidden** (Sun 2026). Ready Dependabot / patch rows skip Reviewer.
+Hold / major / behavior still require Reviewer 🛑. Coordinator still
+merges every `coordinator-merge`.
+
+Builder does not review itself. Reviewer pass on a mergeable PR is 🛑.
+Merge stays on Grok Build (Panickssery 2024; Kambhampati 2024).
+
+Finalize emojis, last line only: ✅ Bot done, no Coordinator · 🔧 rework ·
+🛑 Coordinator must act.
+
+## Trust model
+
+**Touches:** public git playbooks; `gh api` against
+`mcp-tool-shop/rig-bridge-scratch` from an already-authenticated `gh`
+on the VM; markdown QUEUE on the VM.
+
+**Does not touch:** npm registry, consumer `main`, Coordinator swarm
+sqlite (`.swarm`, `~\.grok\*.sqlite`), PATs, `auth.json`,
+`mcp_credentials.json`, telemetry, GitHub MCP token fields.
+
+**Permissions:** read this repo; `gh api` as `mcp-tool-shop` for scratch
+routing. Bots never merge. Coordinator merges every `coordinator-merge`
+(`--admin` if Actions dark). Reviewer 🛑 is required for hold / major /
+behavior. Ready patch / Dependabot PRs skip Reviewer. Auto-merge is an
+optional later consumer-side alternative, not this repo's CI. No
+Dependabot merge of hold PRs.
+
+No telemetry. No secrets in source or in tool-call examples.
+
+## Layout
+
+| Path | What |
+|------|------|
+| `SLOW-BURN.md` | Generic OS: seats, QUEUE class, pipeline, emojis |
+| `ROUTE.md` | Scratch `to:` ids + poll + Orchestrator outbox |
+| `CLONE-POLICY.md` | What the VM may clone; Coordinator `git pull` of `the local scratch-transport clone` |
+| `QUEUE.template.md` | Columns including class + four constraint fields |
+| `TO-COORDINATOR.template.md` | VM append-only log format (not the transport) |
+| `bots/*.md` | Paste-ready profiles. `coordinator.md` is not a Bot |
+| `scripts/route-scratch.py` | `gh api` compare → DELIVER lines |
+| `consumers/` | Per-repo catalog, holds, hours |
+| `docs/RESEARCH.md` | Study-swarm citations + implications |
+| `site/` | Landing + Starlight handbook |
+
+## License
+
+MIT.
+
+---
+
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

grok_bot_os-1.0.0/grok_bot_os/__init__.py

@@ -0,0 +1,32 @@
+"""Installed entry points for grok-bot-os (PyPI). Source of truth is scripts/."""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+__version__ = "1.0.0"
+
+
+def _load(filename: str):
+    here = Path(__file__).resolve().parent
+    candidates = (
+        here / filename,
+        here.parent / "scripts" / filename,
+    )
+    for path in candidates:
+        if path.is_file():
+            spec = importlib.util.spec_from_file_location(path.stem.replace("-", "_"), path)
+            if spec is None or spec.loader is None:
+                continue
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)
+            return mod
+    raise FileNotFoundError(filename)
+
+
+def route_scratch_main() -> int:
+    return int(_load("route-scratch.py").main())
+
+
+def check_queue_fields_main() -> int:
+    return int(_load("check_queue_fields.py").main())

grok_bot_os-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "grok-bot-os"
+version = "1.0.0"
+description = "Operating system for Grok Bot teams: slow-burn Health A queue. Not the testing-os dogfood-swarm CLI."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "mcp-tool-shop" }]
+urls = { Homepage = "https://mcp-tool-shop-org.github.io/grok-bot-os/", Repository = "https://github.com/mcp-tool-shop-org/grok-bot-os" }
+
+[project.scripts]
+route-scratch = "grok_bot_os:route_scratch_main"
+check-queue-fields = "grok_bot_os:check_queue_fields_main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["grok_bot_os"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"scripts/route-scratch.py" = "grok_bot_os/route-scratch.py"
+"scripts/check_queue_fields.py" = "grok_bot_os/check_queue_fields.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/grok_bot_os",
+  "/scripts",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]

grok_bot_os-1.0.0/scripts/check_queue_fields.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Fail-closed four-field gate for QUEUE tables and TO-COORDINATOR list items.
+
+Usage: check_queue_fields.py [path ...]
+       check_queue_fields.py --list-items [path]
+
+Default path is QUEUE.template.md (cwd = repo root). Optional extra paths
+let the VM lint live QUEUE.md / TO-COORDINATOR.md without committing them.
+
+Scans only markdown table cells (or `- field:` list items with --list-items
+/ auto-detect). Prose such as the template's "see SLOW-BURN" prohibition
+does not self-fail.
+
+Does not send, fetch, or write git. No token on argv.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REQUIRED_FIELDS = ("owner", "stop", "prerequisite", "fallback")
+SEE_SLOW_BURN_RE = re.compile(r"(?i)\bsee\s+slow-burn\b")
+JOB_ID_RE = re.compile(r"^JOB-\S+$", re.I)
+SEP_CELL_RE = re.compile(r"^:?-{3,}:?$")
+LIST_ITEM_RE = re.compile(
+    r"^-\s+(stop|prerequisite|owner|fallback)\s*:\s*(.*)$",
+    re.I,
+)
+USAGE = "usage: check_queue_fields.py [--list-items] [path ...]"
+
+
+def fail(code: str, message: str, hint: str, exit_code: int) -> int:
+    sys.stderr.write(
+        f"code={code} message={message} hint={hint} retryable=false\n"
+    )
+    return exit_code
+
+
+def split_row(line: str) -> list[str]:
+    line = line.strip()
+    if line.startswith("|"):
+        line = line[1:]
+    if line.endswith("|"):
+        line = line[:-1]
+    return [cell.strip() for cell in line.split("|")]
+
+
+def is_separator(line: str) -> bool:
+    if "|" not in line:
+        return False
+    cells = split_row(line)
+    if len(cells) < 2:
+        return False
+    return all(SEP_CELL_RE.fullmatch(cell.replace(" ", "")) for cell in cells)
+
+
+def parse_tables(text: str) -> list[tuple[list[str], list[list[str]]]]:
+    """Return (headers, data_rows) for each markdown table. Ignore prose."""
+    lines = text.splitlines()
+    tables: list[tuple[list[str], list[list[str]]]] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if "|" not in line or is_separator(line):
+            i += 1
+            continue
+        if i + 1 >= len(lines) or not is_separator(lines[i + 1]):
+            i += 1
+            continue
+        headers = split_row(line)
+        rows: list[list[str]] = []
+        i += 2
+        while i < len(lines):
+            row_line = lines[i]
+            if "|" not in row_line or is_separator(row_line):
+                break
+            rows.append(split_row(row_line))
+            i += 1
+        tables.append((headers, rows))
+    return tables
+
+
+def _header_names(headers: list[str]) -> list[str]:
+    names: list[str] = []
+    for raw in headers:
+        name = raw.strip().strip("*`").lower()
+        names.append(name)
+    return names
+
+
+def check_queue_text(text: str, path: str = "") -> list[str]:
+    """Errors for QUEUE markdown tables. Empty list = pass.
+
+    Does not scan prose outside table cells.
+    """
+    label = path or "<queue>"
+    errors: list[str] = []
+    tables = parse_tables(text)
+    queue_tables = []
+    for headers, rows in tables:
+        names = _header_names(headers)
+        if "id" in names or any(field in names for field in REQUIRED_FIELDS):
+            queue_tables.append((names, rows))
+    if not queue_tables:
+        errors.append(f"{label}: no QUEUE markdown table")
+        return errors
+
+    for names, rows in queue_tables:
+        missing = [field for field in REQUIRED_FIELDS if field not in names]
+        if missing:
+            for field in missing:
+                errors.append(f"{label}: header missing {field}")
+            continue
+        index = {name: i for i, name in enumerate(names)}
+        id_i = index.get("id", 0)
+        for row in rows:
+            if not row:
+                continue
+            job_id = row[id_i].strip() if id_i < len(row) else ""
+            if not JOB_ID_RE.match(job_id):
+                continue
+            for field in REQUIRED_FIELDS:
+                fi = index[field]
+                cell = row[fi].strip() if fi < len(row) else ""
+                if not cell:
+                    errors.append(f"{label}: {job_id} empty {field}")
+                elif SEE_SLOW_BURN_RE.search(cell):
+                    errors.append(
+                        f"{label}: {job_id} compressed {field}"
+                    )
+    return errors
+
+
+def check_list_items(
+    text: str,
+    path: str = "",
+    require_all: bool = False,
+) -> list[str]:
+    """Errors for `- stop:` / `- prerequisite:` / `- owner:` / `- fallback:` items.
+
+    Missing fields are ignored unless require_all is True, so a TO-COORDINATOR
+    template that has not yet grown an owner line does not self-fail. Present
+    items must be non-empty and uncompressed.
+    """
+    label = path or "<list>"
+    errors: list[str] = []
+    found = {field: 0 for field in REQUIRED_FIELDS}
+    for raw in text.splitlines():
+        match = LIST_ITEM_RE.match(raw.strip())
+        if not match:
+            continue
+        field = match.group(1).lower()
+        value = match.group(2).strip()
+        found[field] += 1
+        if not value:
+            errors.append(f"{label}: empty list item {field}")
+        elif SEE_SLOW_BURN_RE.search(value):
+            errors.append(f"{label}: compressed list item {field}")
+    if require_all:
+        for field in REQUIRED_FIELDS:
+            if found[field] == 0:
+                errors.append(f"{label}: missing list item {field}")
+    return errors
+
+
+def looks_like_table(text: str) -> bool:
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if "|" in line and i + 1 < len(lines) and is_separator(lines[i + 1]):
+            return True
+    return False
+
+
+def check_path(path: str | Path, list_items: bool | None = None) -> list[str]:
+    p = Path(path)
+    if not p.is_file():
+        return [f"{p}: not a file"]
+    text = p.read_text(encoding="utf-8")
+    if list_items is True:
+        return check_list_items(text, str(p))
+    if list_items is False:
+        return check_queue_text(text, str(p))
+    if looks_like_table(text):
+        return check_queue_text(text, str(p))
+    return check_list_items(text, str(p))
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+    list_items: bool | None = None
+    paths: list[str] = []
+    for tok in argv:
+        if tok in ("--list-items", "--coordinator"):
+            list_items = True
+        elif tok in ("--table", "--queue"):
+            list_items = False
+        elif tok in ("-h", "--help"):
+            return fail("INPUT_USAGE", USAGE, "optional path; default QUEUE.template.md", 2)
+        elif tok.startswith("-"):
+            return fail("INPUT_USAGE", f"unknown flag {tok}", USAGE, 2)
+        else:
+            paths.append(tok)
+    if not paths:
+        paths = ["QUEUE.template.md"]
+
+    errors: list[str] = []
+    missing_files = []
+    for path in paths:
+        p = Path(path)
+        if not p.is_file():
+            missing_files.append(path)
+            continue
+        errors.extend(check_path(p, list_items=list_items))
+    if missing_files:
+        return fail(
+            "INPUT_USAGE",
+            "missing: " + ", ".join(missing_files),
+            "pass a QUEUE.md path; live queue is not in git",
+            2,
+        )
+    if errors:
+        for message in errors:
+            sys.stderr.write(
+                "code=QUEUE_FIELDS "
+                f"message={message} "
+                "hint=JOB-* rows need uncompressed owner/stop/prerequisite/fallback "
+                "retryable=false\n"
+            )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())