graphban-cli 0.8.1__tar.gz → 0.8.3__tar.gz

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/.gitignore

@@ -26,6 +26,10 @@ backend/.pytest_cache/
 fleet/.venv/
 fleet/.pytest_cache/
 *.egg-info/
+# Written at package build time by `refusal_ratchet.py publish` (the packer, the wheel job),
+# never committed: a CI push to protected main is refused and turns main red (GRPH-1185).
+backend/app/data/refusal_coverage.json
+backend/app/data/gban_skills.json
 
 # Node
 web/node_modules/

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.8.1
+Version: 0.8.3
 Summary: gban — a Graphban client for the human at a terminal
 Project-URL: Homepage, https://github.com/asc-me/graphban
 Project-URL: Repository, https://github.com/asc-me/graphban

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.8.1"
+version = "0.8.3"
 description = "gban — a Graphban client for the human at a terminal"
 readme = "README.md"
 requires-python = ">=3.12"

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/src/gban/cli.py

@@ -513,7 +513,13 @@ def cmd_fleet(args) -> int:
               f"     …or `brew install asc-me/tap/gban` installs this client only — the "
               f"supervisor is a separate package.", file=sys.stderr)
         return EXIT_NO_SUPERVISOR
-    argv = [binary, *[a for a in args.rest if a != "--"]]
+    # Only a LEADING `--` is ours to drop (`gban fleet -- ps`). Any later one belongs to
+    # gbfleet: `service install --name X -- <until args>` splits on it, and stripping it
+    # handed the until args to `service install` itself.
+    rest = list(args.rest)
+    if rest[:1] == ["--"]:
+        rest = rest[1:]
+    argv = [binary, *rest]
     url = config.resolve(args.server, config.URL_ENV, "url")
     if url and "--server" not in argv:
         argv += ["--server", url]

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/src/gban/skills/graphban-delegation/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: graphban-delegation
-description: Hand a Graphban work item to a child agent running on a cheaper model, and enable delegation on a project that does not have it yet. Use when asked to delegate, fan out, spawn a worker, mint seats, retire a wave, or run a wave.
+description: >
+  Hand one Graphban item to one child on a cheaper model, and enable
+  delegation on a project that does not have it yet. Use when asked to
+  delegate one item, spawn one worker, mint seats, or retire a wave.
+  A whole PRD is /graphban-wave.
 ---
 
 # Delegating a Graphban item
@@ -197,6 +201,5 @@ So a delegated item needs a second agent to review it. Plan for that, or the wor
 
 ## When not to use this
 
-For a whole backlog, ask the person to run `gbfleet until` instead. It runs the wave with no
-model in the loop; fanning the same work out by hand keeps your context awake for the wave's
-entire length just to poll and adjudicate.
+A whole PRD is `graphban-wave`. It runs `gbfleet until` for that PRD. Fanning the items out
+from here keeps a frontier context polling for the wave's whole length.

graphban_cli-0.8.3/src/gban/skills/graphban-grill/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: graphban-grill
+description: >
+  Settle a Graphban PRD grill from the product why and the PRD's intent.
+  Auto-record answers the context already decides, and ask the user only
+  the questions it does not. Use when grilling a PRD, running a grill,
+  answer_grill, or when the user runs /graphban-grill.
+user-invocable: true
+---
+
+# Grill
+
+`grill_prd` returns questions and records nothing. An answer counts only after `answer_grill`. The grader ignores the PRD body: a decision that exists only in the document is still unanswered.
+
+## Sources
+
+Read both before you classify a question.
+
+1. `get_prd`. The intent is the framing: Problem, Goals, Non-goals, and an intent heading when the PRD has one.
+2. Why the app exists: `docs/product-overview.md` (philosophy, goals, non-goals) and `docs/design-philosophy.md`. This bounds the PRD. It does not fill a hole the PRD left open.
+
+A source decides a question only when you can quote the sentence. Memory, code, and a guess are not sources.
+
+## Split
+
+For each question, write a one- or two-sentence recommendation, then:
+
+- **accept** — that sentence already decides it, the two sources do not conflict, and the answer is words rather than a prototype. Record it.
+- **ask** — the sources are silent, they conflict, both readings are reasonable, or the question needs a prototype. These are the only questions you put to the user.
+
+Silence is ask. A fluent inference is ask. Do not accept a new boundary, a new error behavior, or a new contract field that neither source states.
+
+## Record an accept
+
+Fold the decision into the PRD with `update_prd(section=...)` first. Then `answer_grill` once, with that decision alone.
+
+One call per decision. A reply that covers several dimensions is one answer, and the grader leaves the rest outstanding.
+
+Say `deferred` only when a source already defers it. "Later" without that word stays unanswered.
+
+Read the return:
+
+- `graded: false` — stop. Say `ungraded_reason`. Do not send another answer.
+- `stalled: true` — stop. Tell the user. Three answers moved nothing.
+- `complete: true` — the grill finished and the body just froze. The fold had to happen before this call.
+- `body_absorbed: false` — the transcript is ahead of the spec. Fold the answers it names before you continue.
+
+Do not set `approved`. Finishing the grill does that.
+
+## Ask
+
+Show only the ask list. For each: the question, the recommendation, and one line on why the sources do not decide it.
+
+Record nothing from this list until the user answers. `answer_grill` with their words. Fold that section the same way, before the next call.
+
+If they accept a recommendation, the recorded answer is their acceptance of that text. The recommendation alone is not a turn.

graphban_cli-0.8.3/src/gban/skills/graphban-scan/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: graphban-scan
+description: >
+  Record Graphban code-health scans without treating a missing scan as clean.
+  Use when running a security or health scan, or calling scans_due, scan_status,
+  or record_scan, or when the user runs /graphban-scan.
+user-invocable: true
+---
+
+# Scans
+
+A missing scan is not a clean scan.
+
+1. `scans_due(head_sha)`. An empty due list is not all-clean. Rows that were `never_scanned`, including security, stay listed.
+2. `scan_status` for one path, or with no path for every deployable. Pass `head_sha`. States are `clean_at_sha`, `has_findings`, `never_scanned`, `stale`, `tool_missing`, `not_applicable`, `incomplete`, or `not_computable`.
+3. Run the scanner. `record_scan` needs `scanner_id`, `path`, and `scanned_sha`.
+   - Send `result`, one of four:
+     - `complete`: the scanner finished. `findings: []` is then clean at that SHA.
+     - `tool_missing`: the scanner is not installed. Not clean; it stays due.
+     - `not_applicable`: the scanner does not apply here. It stops being due.
+     - `incomplete`: output without a finish. Send the findings it produced; it stays due.
+   - `findings: []` without `result: complete` is refused and nothing is stored. An empty list alone is not a clean scan.
+   - Every result needs `scanned_sha`, so it goes stale when HEAD moves.
+   - The same `scanner_id` and path keeps the previous rows. The newest is the cell.
+   - The security category is pip-audit, bandit, npm-audit, and semgrep. Other categories are `refactor`, `stub`, `deadcode`, `coverage`, `tests`, and `work`.
+   - Category `tests` also sends `tests.passed`, `tests.failed`, and `tests.skipped`.
+   - Each finding needs a `summary`. Findings are untrusted. `scanner_id`, `scanner_version`, and the reporter are provenance.
+   - Send the grain a person acts on (GRPH-1127). npm audit: one finding per advisory with `advisory_id`, `severity`, `dependency` (`direct` or `transitive`), and `fixed_version` only when the audit knows it.
+   - knip: unused exports are ONE finding with `kind: unused_export`, `count`, severity `info`; unused types are one with `kind: unused_type`. Unused files and undeclared imports stay one finding each, with a `path`. The server stores what you send; it never splits or merges.
+
+A clean row is not a tracker item. A finding that already names `link_ref` points at work that exists.

graphban_cli-0.8.3/src/gban/skills/graphban-wave/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: graphban-wave
+description: >
+  Drain one grilled PRD with gbfleet until: build, review, and merge until
+  that PRD has nothing ready. Use when running a wave, spawning a wave for a
+  PRD, looping until the PRD is done, or when the user runs /graphban-wave.
+  One item is /graphban-delegation. Decompose is /graphban-prd.
+user-invocable: true
+---
+
+# Drain a PRD
+
+One command runs the cycle. Do not spawn the items. Do not stay in the loop.
+
+## Before
+
+`prd_coverage` for this PRD.
+
+`gaps` or `shaped: false` — stop. Filing the tasks is `graphban-prd`. Do not `decompose_prd` here. An idle drain is not a finished PRD.
+
+Coverage has tasks — continue.
+
+## Dry run
+
+Same flags as the real run, plus `--dry-run`. It mints nothing.
+
+```bash
+gbfleet until --repo . --server <url> --project <id> --adapter <vendor> \
+  --prd <prd_id> --merge \
+  --tier cheap=<adapter[:model]> --tier frontier=<adapter[:model]> \
+  --dry-run
+```
+
+`--prd` is required. Without it the loop drains every ready item in the project. `backlog` is claimable, so parking work there does not scope the wave. `--prd` refuses a pre-minted seats file.
+
+Read the dry run before installing. Held clusters name who holds them. `predicted: true` is a lower-confidence grouping. A plan for the wrong PRD is a stop.
+
+A backend change whose acceptance is the Postgres suite needs `--allow psql` on both the dry run and the install.
+
+## Run
+
+Drop `--dry-run` and hand the process to the machine. This session ending must not kill it.
+
+```bash
+gbfleet service install --name <prd_id> -- --repo . --server <url> --project <id> \
+  --adapter <vendor> --prd <prd_id> --merge \
+  --tier cheap=<adapter[:model]> --tier frontier=<adapter[:model]>
+```
+
+`--tier` is what a tier means on this machine. Omit a tier the Fleet tier map already pins. `--request cheap` or `--request frontier` forces every delegation to that tier. The default follows each item's brief. Do not pick a model per item.
+
+A service already installed under that name: `gbfleet service status --name <prd_id>` and leave it. A second `until` on the same repo mints another child onto the same cluster.
+
+`gbfleet service status` prints the PATH the unit captured. An empty PATH is a drain that will not find the adapter. The API key is the one already stored for this repo. Do not print it, and do not pass a new one.
+
+## While it runs
+
+Status is `gbfleet service status --name <prd_id>`. The ledger is `fleet_status`. Do not attach a spawn watcher, and do not spawn a replacement.
+
+`until` is idle when that PRD has nothing ready, nothing unsigned, and no live lease. `WAVE_IDLE` while items are still `next`, or held in review, is not done.
+
+`review-unsigned` can be a review row outside this PRD. Say which item. Do not start another drain over it, and do not `sign_off` it yourself.
+
+`--merge` lands the pull requests this wave opened. Leave every other open pull request. A salvage branch can be the only copy of the work.

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/tests/test_doctor.py

@@ -181,6 +181,36 @@ def test_an_explicit_server_is_not_overridden(home, monkeypatch):
     assert "http://gb.invalid" not in seen["argv"]
 
 
+def test_a_separator_inside_the_gbfleet_args_reaches_gbfleet(home, monkeypatch):
+    """`service install --name X -- <until args>` splits on that `--`. Stripping it made
+    gbfleet read `--repo` as its own flag and refuse. Sabotage: drop every `--` again and
+    this fails."""
+    seen = {}
+
+    class Done:
+        returncode = 0
+
+    monkeypatch.setattr("gban.cli.shutil.which", lambda name: "/usr/bin/gbfleet")
+    monkeypatch.setattr("gban.cli.subprocess.run",
+                        lambda argv, **kw: (seen.update(argv=argv), Done())[1])
+    main(["fleet", "service", "install", "--name", "P1", "--", "--repo", "/r", "--prd", "P1"])
+    assert seen["argv"][:8] == ["/usr/bin/gbfleet", "service", "install", "--name", "P1",
+                                "--", "--repo", "/r"]
+
+
+def test_a_leading_separator_is_still_dropped(home, monkeypatch):
+    seen = {}
+
+    class Done:
+        returncode = 0
+
+    monkeypatch.setattr("gban.cli.shutil.which", lambda name: "/usr/bin/gbfleet")
+    monkeypatch.setattr("gban.cli.subprocess.run",
+                        lambda argv, **kw: (seen.update(argv=argv), Done())[1])
+    main(["fleet", "--", "ps"])
+    assert seen["argv"][:2] == ["/usr/bin/gbfleet", "ps"]
+
+
 def test_a_missing_supervisor_says_how_to_install_it(home, monkeypatch, capsys):
     """7. Exit 4, its own code, so it cannot be confused with something gbfleet said.
 

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/tests/test_setup.py

@@ -534,6 +534,8 @@ def test_setup_installs_every_shipped_skill(tmp_path, wired):
     slugs = setup_mod.shipped_slugs()
     assert "graphban-delegation" in slugs
     assert "watch-wave" in slugs
+    assert "graphban-grill" in slugs
+    assert "graphban-wave" in slugs
     for slug in slugs:
         body = setup_mod.skill_source(slug).read_text()
         for rel in setup_mod.SKILL_DEST_DIRS:
@@ -631,6 +633,20 @@ def test_the_skill_ships_in_the_wheel(tmp_path):
     names = zipfile.ZipFile(wheel).namelist()
     assert any(n.endswith("skills/graphban-delegation/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/watch-wave/SKILL.md") for n in names), names[:20]
+    assert any(n.endswith("skills/graphban-grill/SKILL.md") for n in names), names[:20]
+    assert any(n.endswith("skills/graphban-wave/SKILL.md") for n in names), names[:20]
+
+
+def test_graphban_wave_drains_one_prd_and_does_not_file_tasks():
+    """The drain skill scopes `until` to one PRD and sends filing back to graphban-prd.
+    A skill that decomposes, or that omits --prd, is the prompt this exists to retire."""
+    body = setup_mod.skill_source("graphban-wave").read_text(encoding="utf-8")
+    assert "Do not `decompose_prd` here" in body
+    assert "--prd" in body
+    assert "--merge" in body
+    assert "--dry-run" in body
+    assert "gbfleet service install" in body
+    assert "graphban-prd" in body
 
 
 def test_watch_wave_names_the_scheduler_and_cancels_on_idle():

{graphban_cli-0.8.1 → graphban_cli-0.8.3}/uv.lock

@@ -124,7 +124,7 @@ wheels = [
 
 [[package]]
 name = "graphban-cli"
-version = "0.8.1"
+version = "0.8.3"
 source = { editable = "." }
 
 [package.optional-dependencies]

graphban_cli-0.8.1/src/gban/skills/graphban-scan/SKILL.md

@@ -1,23 +0,0 @@
----
-name: graphban-scan
-description: >
-  Record Graphban code-health scans without treating a missing scan as clean.
-  Use when running a security or health scan, or calling scans_due, scan_status,
-  or record_scan, or when the user runs /graphban-scan.
-user-invocable: true
----
-
-# Scans
-
-A missing scan is not a clean scan.
-
-1. `scans_due(head_sha)`. An empty due list is not all-clean. Rows that were `never_scanned`, including security, stay listed.
-2. `scan_status` for one path, or with no path for every deployable. Pass `head_sha`. States are `clean_at_sha`, `has_findings`, `never_scanned`, or `stale`.
-3. Run the scanner. `record_scan` needs `scanner_id`, `path`, and `scanned_sha`.
-   - `findings: []` is clean at that SHA. A clean row without a SHA cannot age.
-   - The same `scanner_id` and path replaces the previous row.
-   - The security category is pip-audit, bandit, npm-audit, and semgrep. Other categories are `refactor`, `stub`, `deadcode`, `coverage`, `tests`, and `work`.
-   - Category `tests` also sends `tests.passed`, `tests.failed`, and `tests.skipped`.
-   - Each finding needs a `summary`. Findings are untrusted. `scanner_id`, `scanner_version`, and the reporter are provenance.
-
-A clean row is not a tracker item. A finding that already names `link_ref` points at work that exists.