feat(workbench): requirement 003 with the gates and register contracts

Requirement 003 Operator Workbench (operator-confirmed 2026-11-11) and the contracts its work packages build on: gates.py keeps gate rules, branch parents and gate receipts in ~/.local/state/agents-council/gates.db (resolve takes the branch's own level, else the strictest of all parents; derive records the nearest ancestor tips; tree hashes everything a worktree holds through a temporary index). rasci.py gains --unpin, stamps every changed row with updated, and ranks a task after its after-dependencies.

🎯 Fix: 95 %
💥 Break: 3 %
💸 Cost: 100 %
⏱️ Time: 100 %
🛡️ Security: 100 %
🏆 Score: 92
🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/requirements/003-operator-workbench.md

@@ -0,0 +1,316 @@
+# 003 - Operator Workbench
+
+## User Story
+
+As the operator of many parallel agents, I want to handle every open task,
+review, plan, branch gate and resource figure from one simple, interactive
+Agent Orchestrator, and agents that commit through fast deterministic hooks
+instead of skipping them, so that I steer the work by drag and drop, see what
+changed and what it costs, and a gate means something again.
+
+## Decisions (operator-confirmed 2026-11-11; do not re-litigate)
+
+1. **One document**: the whole package lives here as work packages W1 to W5.
+   Rejected: one document per feature.
+2. **Operator tasks next to Tasks**: the Inbox entry leaves the top navigation
+   and the Stream; the Tasks entry carries the count of open operator tasks;
+   the Tasks filter "Waits on Operator" shows them as Stream cards with
+   checkboxes and the bulk bar. The Stream keeps its operator cards with their
+   actions. Rejected: a separate Operator tab, a Stream without operator rows.
+3. **Diff preview**: every review card shows its diff expanded; the requesting
+   agent's script ships it with the review (the hub reads no git, 001); one
+   block per file, a file over 400 changed lines collapsed, 2 MiB cap with the
+   rest listed by stat; lines MEDUSA's secret rules match are masked.
+   Rejected: the hub reads git.
+   Every Ask for a `git commit` shows the staged diff the same way (with
+   `-a` or `--all` the diff against HEAD); the permission hook on the host
+   attaches it (operator order 2026-11-11).
+4. **Inline feedback**: selected lines of a diff or a command go back to the
+   agent as one radio `post` with path, line range, quote and text, through
+   the right-click menu, the key `f` or a button at the selection.
+5. **Kanban**: columns Waiting, Running and Done; Blocked and Stopped become
+   labels; `operator/*` rows stay off the board; swimlanes P1, P2, P3, P4+ and
+   Unpinned (by WSJF), collapsible; Done older than 24 h hidden by default.
+6. **Lines**: solid arrows are `after` dependencies, several into one card; one
+   dashed line runs through the cards holding a live queue entry, in queue
+   order. Rejected: rank lines per lane, dependencies only.
+7. **Drag and drop**: card to column = status, to lane = priority pin, handle
+   onto a card = `after`; a click on an arrow removes it; a click on a card
+   opens its popup. Moves are staged, shown at once and applied with one
+   passkey; each affected agent gets a post. Rejected: a passkey per move, no
+   passkey.
+8. **Dependencies are enforced**: the queue holds a task until its `after`
+   tasks are done, and the rank follows them. Rejected: display only, warning
+   only.
+9. **Forecast**: two lines in distinct colours, the finish at fixed scope and
+   the finish at growing scope (done trend meets scope trend); ∞ when never
+   reached. Scope excludes `operator/*`; a task unchanged for 3 days is
+   labelled stale and counted apart. Rejected: count everything, only drop
+   operator rows.
+10. **Clean all merged**: dry run, one passkey, signed job. Local branches
+    merged by ancestry and without a remote branch need no token; remote
+    branches and squash-merge candidates need the GitHub token, stored through
+    an operator row. Rejected: wait for the token, ancestry for remotes.
+11. **Ancestry**: Artifacts and Agents get a family tree (generations top down)
+    in the slot of today's Tree view. A branch may have several parents;
+    parents are recorded at creation (post-checkout hook), older branches are
+    derived and marked derived, and the operator corrects them by drag and
+    drop. Rejected: derivation only, manual only.
+12. **Gates**: a level (none < quick < test < quality-high < e2e) per branch
+    and action (commit, merge, push, pr), inherited from all ancestors, the
+    strictest wins, an own rule wins over all; kept in the local database
+    `~/.local/state/agents-council/gates.db` (the council root lives in the
+    tmpfs `/tmp` and loses it at reboot) that agents read through `gates.py`;
+    set in every Artifacts view. Rejected: a committed `.gates.yml`, repo plus
+    local.
+13. **Hooks with receipts**: pre-commit runs only quick checks of the staged
+    files (< 30 s); heavy gates run through the queue and on green write a
+    receipt (tree sha of the tested content, level, log); commit-msg,
+    pre-merge-commit and pre-push only compare the receipt with the resolved
+    level (< 1 s). `--no-verify` only on the operator's word for that commit.
+    Core's hooks change only in a core PR agreed with Experiment and Main.
+    Rejected: heavy gates at pre-push, skills-side checks with `--no-verify`.
+14. **Resources**: a host unit samples every 60 s without any LLM call: disks
+    per mount, CPU, RAM, swap, load, GPU and VRAM (`nvidia-smi` only while the
+    dGPU is awake, else asleep), the queue; tokens per agent and model from
+    the transcripts' usage fields. 7 days at 1 min, 90 days at 15 min.
+    Replaces 001 S7.
+15. **Simplicity**: icons, counts and names instead of text; every action is
+    reachable in the GUI.
+16. **Delivery**: one subtree `feature/operator-workbench` with split
+    worktrees, at most 4 subagents at a time on W1 to W4, W5 serially in the
+    requesting agent with Experiment; one gate (make test, e2e Chromium and
+    Firefox at 1920, 1366 and 390 px, MEDUSA, 90/5); master only on the
+    operator's word. Rejected: 8 in parallel, serial without subagents.
+
+## Approach
+
+```mermaid
+flowchart TD
+    subgraph P["🧭 0 · Preparation"]
+        P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
+        P2 -- "✏️ corrections" --> P1
+    end
+    P2 -- "🤖 yes" --> C1
+    subgraph C["📐 1 · Contracts"]
+        C1["🗄️ gates.db schema, staged-change job, diff payload, sampler files"] --> C2["🔴 Red tests per work package"]
+    end
+    C2 --> W1A & W2A & W3A & W4A & W5A
+    subgraph W1["📥 W1 · Operator tasks"]
+        W1A["🛠️ Nav badge, Waits on Operator cards, diff, feedback"] --> W1B{"🧪 Green?"}
+        W1B -- "🔴 fix" --> W1A
+    end
+    subgraph W2["🗂️ W2 · Kanban and forecast"]
+        W2A["🛠️ Lanes, labels, drag and drop, arrows, popup, two forecasts, stale"] --> W2B{"🧪 Green?"}
+        W2B -- "🔴 fix" --> W2A
+    end
+    subgraph W3["🌳 W3 · Artifacts"]
+        W3A["🛠️ Clean all merged, ancestry views, gate icons"] --> W3B{"🧪 Green?"}
+        W3B -- "🔴 fix" --> W3A
+    end
+    subgraph W4["📈 W4 · Resources"]
+        W4A["🛠️ Sampler unit, token parser, view"] --> W4B{"🧪 Green?"}
+        W4B -- "🔴 fix" --> W4A
+    end
+    subgraph W5["🪝 W5 · Gates, receipts, hooks"]
+        W5A["🛠️ gates.py, receipts, hooks, queue after-wait"] --> W5B{"🤝 Experiment agrees?"}
+        W5B -- "✏️ changes" --> W5A
+    end
+    W1B & W2B & W3B & W4B -- "🟢" --> U1
+    W5B -- "👍" --> U1
+    subgraph U["🔀 2 · Unify"]
+        U1["🔀 Merge splits into the subtree"] --> U2{"🧪 Gate: make test, e2e x3, MEDUSA, 90/5"}
+        U2 -- "🔴 fix" --> U1
+        U2 -- "🟢" --> U3["📸 Screenshots 1920 / 1366 / 390"]
+        U3 --> UF{"💬 Operator feedback?"}
+        UF -- "✏️ changes" --> U1
+    end
+    UF -- "👍 commit word" --> D1["🏁 Merge to master, install row, core PR proposal"]
+```
+
+## Acceptance Criteria
+
+### W1 Operator tasks
+
+- [ ] The top navigation has no Inbox entry; the Tasks entry shows the count of
+      waiting, unsnoozed operator tasks, hidden at 0.
+- [ ] The Stream has no inbox button; `#stream/inbox` opens `#tasks/operator`.
+- [ ] `#tasks/operator` shows each operator task as a Stream card (command,
+      directory, reason, run, deny, copy, snooze, pin) with a checkbox; the
+      bulk bar acts on the checked cards.
+- [ ] The Stream keeps its operator cards with their actions.
+- [ ] The bulk approve counts and approves every checked card, asks, reviews
+      and operator commands alike, with one passkey.
+- [ ] Approving or denying an Ask in the hub also settles the agent's native
+      permission dialog where the runtime allows it (the permission hook
+      waits for the hub's decision); where it does not, the limit is recorded
+      here.
+- [ ] A review card shows its diff expanded: one unified block per file,
+      additions and deletions coloured, a file over 400 changed lines
+      collapsed, a binary file named only.
+- [ ] The review request of `approval.py` (kvb-git-diff) carries
+      `git diff --cached` of the exact staged tree; past 2 MiB the rest is
+      listed per file with its stat.
+- [ ] An Ask for a `git commit` carries the staged diff of its working
+      directory (with `-a` or `--all` the diff against HEAD), attached by
+      `permission_hook.py`, and shows it like a review, feedback included.
+- [ ] A diff line MEDUSA's secret rules match is shown masked.
+- [ ] Selecting lines in a diff or a command and choosing Feedback (right-click
+      menu, key `f`, or the button at the selection) posts one radio `post` to
+      the requesting agent with path, line range, quote and text; the feedback
+      shows under the card.
+
+### W2 Kanban
+
+- [ ] Columns Waiting, Running and Done; no Blocked or Stopped column.
+- [ ] A blocked task carries a red Blocked label, a stopped one a grey Stopped
+      label in Done; `operator/*` rows are not on the board.
+- [ ] Swimlanes P1, P2, P3, P4+ and Unpinned, collapsible, Unpinned sorted by
+      WSJF rank; Done cards older than 24 h hidden until shown.
+- [ ] Each `after` dependency is a solid arrow into the dependent card, several
+      per card allowed; the cards holding a live queue entry are joined by one
+      dashed line in queue order.
+- [ ] Dragging a card to a column stages a status, to a lane a pin (P4+ the
+      lowest free pin from 4, Unpinned none), its handle onto a card an
+      `after`; a click on an arrow stages its removal; every move is also in
+      the card's keyboard menu.
+- [ ] Staged moves show at once as pending; "Apply n changes" signs them with
+      one passkey; the host executor applies them through `rasci.py`, refuses
+      a cycle or a `done` with an open key result, and the card shows why.
+- [ ] Each affected agent receives one post listing the operator's changes to
+      its rows.
+- [ ] A click on a card opens its detail popup.
+
+### W2 Forecast
+
+- [ ] The burn chart draws, in distinct colours with a legend, the finish at
+      fixed scope and the finish at growing scope, each ending at its date; a
+      line never reached shows ∞.
+- [ ] Scope excludes `operator/*`; a task without a register change for 3 days
+      carries a Stale label, is counted apart and can be stopped from the
+      board.
+
+### W3 Artifacts
+
+- [ ] "Clean all merged" shows the gc dry run of every `merged-clean` item; one
+      passkey runs the signed job.
+- [ ] Without a GitHub token, local branches merged by ancestry into the
+      default branch and without a remote branch can be deleted; the others
+      show "token needed", and an operator row stores the token.
+- [ ] Artifacts and Agents show Ancestry in the Tree slot: generations top
+      down, several parents per node; a derived parent edge is dashed.
+- [ ] Dragging a branch onto another stages a parent edge, applied with the
+      board's passkey batch.
+- [ ] Agents' Ancestry shows operator, chair, sessions and subagents.
+- [ ] Every Artifacts view shows each branch's effective gate level per action
+      as an icon (inherited ones faint, source in the tooltip) and lets the
+      operator set a rule, signed.
+
+### W5 Gates, receipts and hooks
+
+- [ ] `gates.py` keeps rules, parents and receipts in
+      `~/.local/state/agents-council/gates.db`.
+- [ ] `gates.py resolve --repo R --branch B --action A` prints the level and its
+      source: the branch's own rule, else the strictest resolved level of all
+      ancestors, else none.
+- [ ] The post-checkout hook records as parents every local branch whose tip
+      equals the new branch's start commit; `gates.py parents derive` adds
+      derived parents for the others.
+- [ ] A green queue gate writes a receipt: repo, tree sha of the tested content
+      (tracked, staged, unstaged, untracked, via a temporary index), level,
+      log, time.
+- [ ] `gates.py hooks install --repo R` installs pre-commit (quick checks of the
+      staged files, under 30 s on this repository), commit-msg,
+      pre-merge-commit, pre-push and post-checkout.
+- [ ] commit-msg, pre-merge-commit and pre-push pass when a receipt for the
+      resulting tree meets the resolved level, else refuse with the
+      `queue.py hold` command that produces it; each check stays under 1 s.
+- [ ] `queue.py hold` for a task whose `after` tasks are not all done waits with
+      `waits for <task>`; the register rank places a task after its `after`
+      tasks.
+- [ ] The commit skills commit through the hooks; `--no-verify` only on the
+      operator's word for that commit.
+- [ ] Experiment's and Main's answer on core's hooks is recorded here; core's
+      `.pre-commit-config.yaml` changes only in a core PR.
+
+### W4 Resources
+
+- [ ] `resources.py sample`, run every 60 s by a user timer that
+      `make orchestrator-install` enables, appends one row: used and total per
+      mount, CPU, RAM and swap percent, load, GPU utilization and VRAM per
+      GPU, waiting and active queue jobs.
+- [ ] An NVIDIA GPU whose PCI `runtime_status` is not `active` is recorded as
+      asleep without running `nvidia-smi`.
+- [ ] `resources.py tokens` adds input, output, cache-read and cache-write
+      tokens per agent and model from transcript usage fields since the last
+      byte offset; no sampler or parser calls an LLM.
+- [ ] Rows older than 7 days fold into 15-minute means; means older than 90
+      days are dropped.
+- [ ] The Resources entry shows on one time axis disks, CPU, RAM, swap, GPU,
+      VRAM and stacked tokens per agent; bands mark idle (< 30 %) and
+      saturated (> 90 %); a marker flags spans where jobs waited while CPU and
+      RAM stayed under 50 %; the view reads only the sampler files.
+- [ ] 001 S7 points to this section.
+
+### Contracts
+
+The work packages meet only through these interfaces:
+
+- **Gates**: `skills/kvb-check-gate/scripts/gates.py` (its docstring is the
+  reference). The hub reads `gates.py show --json`; a GUI change is a signed
+  job whose argv is `rule set|drop` or `parents add|drop`
+  (`signing.gate_argv`), run by the host runner with `--gates`.
+- **Register**: the board's signed task changes (`signing.task_argv`) accept
+  `set <task>` with exactly one of `--status <s>`, `--after <t>`,
+  `--drop-after <t>`, `--prio <n>` or `--unpin`; every changed row carries
+  `updated` (ISO time), which Stale reads.
+- **Review diff**: the review request of `approval.py` gains `diff`, a list of
+  `{path, status, additions, deletions, patch, masked}`: status one of A, M,
+  D, R or B (binary), patch the unified text (empty for binary files and
+  past the 2 MiB cap), masked the line numbers shown masked. An Ask for a
+  `git commit` carries the same `diff` from `permission_hook.py`.
+- **Feedback**: a feedback is a message to the requesting agent through the
+  existing signed message flow, text `Feedback on <ref> <path>:<from>-<to>:
+  "<quote>" <text>`.
+- **Resources**: the host unit writes `samples.jsonl` (`{t, disks: [{mount,
+  used, total}], cpu, ram, swap, load, gpus: [{name, util, vram_used,
+  vram_total} | {name, asleep: true}], queue: {waiting, active}}`),
+  `tokens.jsonl` (`{t, agent, model, input, output, cache_read,
+  cache_write}`, t the hour) and `offsets.json` under
+  `~/.local/state/agents-council/resources/`.
+- **Mounts**: the hub mounts `~/.local/state/agents-council` read-only and
+  opens `gates.db` read-only.
+
+### Simplicity
+
+- [ ] Every new control is a Bootstrap Icon with `title` and `aria-label`; no new
+      visible text beyond counts and names.
+
+### Tests
+
+- Unit:
+  - [ ] Board staging, lanes and refusals (cycle, open key result); forecast
+        fixed, growing and never; stale; scope without `operator/*`.
+  - [ ] Gates resolve (own rule, strictest of several ancestors, none);
+        parents derive; receipt tree sha with unstaged and untracked files;
+        hook pass and refuse; queue wait on `after`.
+  - [ ] Resources sample parsing on fixtures (df, meminfo, nvidia-smi, asleep
+        GPU); token offsets; retention fold; diff cap and masking; feedback
+        payload.
+- Integration:
+  - [ ] A scratch repository with installed hooks refuses a commit without a
+        receipt and passes it after a queue gate; refuses a merge below the
+        parent's level; post-checkout records parents.
+  - [ ] The host executor applies a signed board batch to a scratch register
+        and refuses a forged one; deletes a local merged branch without a
+        token and refuses a remote one.
+  - [ ] The sampler writes rows in a scratch HOME.
+- E2E, headless Chromium and Firefox at 1920, 1366 and 390 px:
+  - [ ] Tasks badge, no Inbox entry, operator cards with bulk actions, review
+        diff expanded, feedback by right-click and `f` reaching the radio
+        store.
+  - [ ] Kanban lanes, no Blocked or Stopped column, drags to column, lane and
+        dependency, Apply with a test passkey, arrows and the dashed queue
+        line, card popup; forecast two lines and ∞.
+  - [ ] Artifacts clean-all dry run, Ancestry in both tabs, a gate set;
+        Resources charts; no page scrollbar.

docs/requirements/README.md

@@ -6,3 +6,4 @@ skill defines the format.
 
 - [001 - Agent Orchestrator](001-agent-orchestrator.md)
 - [002 - Cosmos](002-cosmos.md)
+- [003 - Operator Workbench](003-operator-workbench.md)

skills/kvb-check-gate/scripts/gates.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""Gate rules, branch parents and gate receipts of every repository on this host.
+
+Args:
+    --db: the SQLite database, default ~/.local/state/agents-council/gates.db
+        (GATES_DB overrides it); it survives reboots, the council root under
+        /tmp does not.
+
+    rule set --repo R --branch B --action A --level L: the branch's own level
+        for one action. rule drop --repo R --branch B --action A removes it.
+    parents add|drop --repo R --branch B --parent P [--source S]: one parent
+        edge; S is recorded, derived or operator (default operator).
+    parents derive --repo R: gives every local branch without a parent, except
+        the default branch, the nearest local branches whose tip is its
+        ancestor, as derived parents.
+    resolve --repo R --branch B --action A: prints `<level>\t<source>`, the
+        branch's own level, else the strictest resolved level of all its
+        parents, else `none\t-`.
+    tree --worktree W: prints the tree sha of everything W holds, tracked,
+        staged, unstaged and untracked, ignored files left out.
+    receipt add --repo R --tree T --level L --log P: records a green gate.
+    receipt check --repo R --tree T --level L: exit 0 when a receipt for T
+        meets L, else 1.
+    show --json [--repo R]: {repo: {branch: {parents: [{parent, source}],
+        rules: {action: level}, resolved: {action: {level, source}}}}} for the
+        local branches of R, or of every repository the database knows.
+
+    R is any path inside the repository; it is stored as the absolute path of
+    the main checkout, so linked worktrees share it.
+
+Exit codes:
+    0 done, 1 a receipt check that fails, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+LEVELS = ("none", "quick", "test", "quality-high", "e2e")
+ACTIONS = ("commit", "merge", "push", "pr")
+SOURCES = ("recorded", "derived", "operator")
+DEFAULT_DB = Path.home() / ".local" / "state" / "agents-council" / "gates.db"
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS rules (repo TEXT, branch TEXT, action TEXT, level TEXT, set_at REAL,
+    PRIMARY KEY (repo, branch, action));
+CREATE TABLE IF NOT EXISTS parents (repo TEXT, branch TEXT, parent TEXT, source TEXT,
+    PRIMARY KEY (repo, branch, parent));
+CREATE TABLE IF NOT EXISTS receipts (repo TEXT, tree TEXT, level TEXT, log TEXT, at REAL,
+    PRIMARY KEY (repo, tree, level));
+"""
+
+
+def fail(message: str) -> None:
+    print(f"gates: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+def git(cwd: str | Path, *args: str, env: dict | None = None) -> str:
+    result = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, check=False, env=env)
+    if result.returncode != 0:
+        fail(result.stderr.strip() or f"git {args[0]} failed in {cwd}")
+    return result.stdout.strip()
+
+
+def ancestor(repo: str, older: str, newer: str) -> bool:
+    return subprocess.run(
+        ["git", "merge-base", "--is-ancestor", older, newer], cwd=repo, capture_output=True, check=False
+    ).returncode == 0
+
+
+def root(path: str) -> str:
+    common = Path(git(path, "rev-parse", "--path-format=absolute", "--git-common-dir"))
+    return str(common.parent if common.name == ".git" else common)
+
+
+def connect(path: Path) -> sqlite3.Connection:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    db = sqlite3.connect(path)
+    db.executescript(SCHEMA)
+    return db
+
+
+def branches(repo: str) -> dict[str, str]:
+    listed = git(repo, "for-each-ref", "refs/heads", "--format=%(refname:short) %(objectname)")
+    return dict(line.split(" ", 1) for line in listed.splitlines() if line)
+
+
+def default_branch(repo: str, local: dict[str, str]) -> str | None:
+    remote = subprocess.run(
+        ["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"], cwd=repo, capture_output=True, text=True,
+        check=False,
+    ).stdout.strip()
+    named = remote.removeprefix("origin/") if remote else None
+    return next((name for name in (named, "main", "master") if name in local), None)
+
+
+def parents_of(db: sqlite3.Connection, repo: str, branch: str) -> list[tuple[str, str]]:
+    return db.execute(
+        "SELECT parent, source FROM parents WHERE repo = ? AND branch = ? ORDER BY parent", (repo, branch)
+    ).fetchall()
+
+
+def resolve(db: sqlite3.Connection, repo: str, branch: str, action: str, seen: frozenset = frozenset()) -> tuple[str, str | None]:
+    own = db.execute(
+        "SELECT level FROM rules WHERE repo = ? AND branch = ? AND action = ?", (repo, branch, action)
+    ).fetchone()
+    if own:
+        return own[0], branch
+    best: tuple[str, str | None] = ("none", None)
+    for parent, _ in parents_of(db, repo, branch):
+        if parent in seen or parent == branch:
+            continue
+        level, source = resolve(db, repo, parent, action, seen | {branch})
+        if LEVELS.index(level) > LEVELS.index(best[0]):
+            best = (level, source)
+    return best
+
+
+def derive(db: sqlite3.Connection, repo: str) -> list[tuple[str, str]]:
+    local = branches(repo)
+    default = default_branch(repo, local)
+    added = []
+    for branch, tip in sorted(local.items()):
+        if branch == default or parents_of(db, repo, branch):
+            continue
+        candidates = [
+            other for other, other_tip in local.items()
+            if other != branch and (other_tip != tip or other == default) and ancestor(repo, other_tip, tip)
+        ]
+        nearest = [
+            other for other in candidates
+            if not any(more != other and local[more] != local[other] and ancestor(repo, local[other], local[more]) for more in candidates)
+        ]
+        for parent in sorted(nearest):
+            db.execute("INSERT OR IGNORE INTO parents VALUES (?, ?, ?, 'derived')", (repo, branch, parent))
+            added.append((branch, parent))
+    db.commit()
+    return added
+
+
+def worktree_tree(worktree: str) -> str:
+    with tempfile.TemporaryDirectory(prefix="kvb-gates-") as scratch:
+        env = {**os.environ, "GIT_INDEX_FILE": str(Path(scratch) / "index")}
+        git(worktree, "read-tree", "HEAD", env=env)
+        git(worktree, "add", "-A", ".", env=env)
+        return git(worktree, "write-tree", env=env)
+
+
+def show(db: sqlite3.Connection, repos: list[str]) -> dict:
+    shown = {}
+    for repo in repos:
+        named = set(branches(repo)) | {row[0] for row in db.execute("SELECT branch FROM rules WHERE repo = ?", (repo,))}
+        shown[repo] = {
+            branch: {
+                "parents": [{"parent": parent, "source": source} for parent, source in parents_of(db, repo, branch)],
+                "rules": dict(db.execute("SELECT action, level FROM rules WHERE repo = ? AND branch = ?", (repo, branch))),
+                "resolved": {
+                    action: dict(zip(("level", "source"), resolve(db, repo, branch, action))) for action in ACTIONS
+                },
+            }
+            for branch in sorted(named)
+        }
+    return shown
+
+
+def parser() -> argparse.ArgumentParser:
+    top = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    top.add_argument("--db", type=Path, default=Path(os.environ.get("GATES_DB", DEFAULT_DB)))
+    sub = top.add_subparsers(dest="command", required=True)
+    rule = sub.add_parser("rule").add_subparsers(dest="verb", required=True)
+    for verb in ("set", "drop"):
+        p = rule.add_parser(verb)
+        p.add_argument("--repo", required=True)
+        p.add_argument("--branch", required=True)
+        p.add_argument("--action", required=True, choices=ACTIONS)
+        if verb == "set":
+            p.add_argument("--level", required=True, choices=LEVELS)
+    parents = sub.add_parser("parents").add_subparsers(dest="verb", required=True)
+    for verb in ("add", "drop"):
+        p = parents.add_parser(verb)
+        p.add_argument("--repo", required=True)
+        p.add_argument("--branch", required=True)
+        p.add_argument("--parent", required=True)
+        if verb == "add":
+            p.add_argument("--source", choices=SOURCES, default="operator")
+    parents.add_parser("derive").add_argument("--repo", required=True)
+    p = sub.add_parser("resolve")
+    p.add_argument("--repo", required=True)
+    p.add_argument("--branch", required=True)
+    p.add_argument("--action", required=True, choices=ACTIONS)
+    sub.add_parser("tree").add_argument("--worktree", required=True)
+    receipt = sub.add_parser("receipt").add_subparsers(dest="verb", required=True)
+    for verb in ("add", "check"):
+        p = receipt.add_parser(verb)
+        p.add_argument("--repo", required=True)
+        p.add_argument("--tree", required=True)
+        p.add_argument("--level", required=True, choices=LEVELS)
+        if verb == "add":
+            p.add_argument("--log", required=True)
+    p = sub.add_parser("show")
+    p.add_argument("--json", action="store_true", required=True)
+    p.add_argument("--repo")
+    return top
+
+
+def main() -> int:
+    args = parser().parse_args()
+    if args.command == "tree":
+        print(worktree_tree(args.worktree))
+        return 0
+    db = connect(args.db)
+    repo = root(args.repo) if getattr(args, "repo", None) else None
+    if args.command == "rule" and args.verb == "set":
+        db.execute("INSERT OR REPLACE INTO rules VALUES (?, ?, ?, ?, ?)", (repo, args.branch, args.action, args.level, time.time()))
+    elif args.command == "rule":
+        db.execute("DELETE FROM rules WHERE repo = ? AND branch = ? AND action = ?", (repo, args.branch, args.action))
+    elif args.command == "parents" and args.verb == "add":
+        if args.parent == args.branch:
+            fail(f"{args.branch} cannot be its own parent")
+        db.execute("INSERT OR REPLACE INTO parents VALUES (?, ?, ?, ?)", (repo, args.branch, args.parent, args.source))
+    elif args.command == "parents" and args.verb == "drop":
+        db.execute("DELETE FROM parents WHERE repo = ? AND branch = ? AND parent = ?", (repo, args.branch, args.parent))
+    elif args.command == "parents":
+        for branch, parent in derive(db, repo):
+            print(f"{branch}\t{parent}\tderived")
+    elif args.command == "resolve":
+        level, source = resolve(db, repo, args.branch, args.action)
+        print(f"{level}\t{source or '-'}")
+    elif args.command == "receipt" and args.verb == "add":
+        db.execute("INSERT OR REPLACE INTO receipts VALUES (?, ?, ?, ?, ?)", (repo, args.tree, args.level, args.log, time.time()))
+    elif args.command == "receipt":
+        levels = [row[0] for row in db.execute("SELECT level FROM receipts WHERE repo = ? AND tree = ?", (repo, args.tree))]
+        return 0 if any(LEVELS.index(level) >= LEVELS.index(args.level) for level in levels) else 1
+    else:
+        known = {row[0] for row in db.execute("SELECT repo FROM rules")} | {row[0] for row in db.execute("SELECT repo FROM parents")}
+        repos = [repo] if repo else sorted(known)
+        print(json.dumps(show(db, repos)))
+    db.commit()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skills/kvb-org-rasci/scripts/rasci.py

@@ -113,7 +113,12 @@ def database() -> Iterator[dict[str, dict]]:
         except OSError as error:
             fail(f"cannot lock {LOCK}: {error.strerror}")
         tasks = load()
+        before = {task: json.dumps(row, sort_keys=True) for task, row in tasks.items()}
         yield tasks
+        now = stamp()
+        for task, row in tasks.items():
+            if before.get(task) != json.dumps(row, sort_keys=True):
+                row["updated"] = now
         nofollow.replace(ROOT, DB, json.dumps(tasks, indent=1, sort_keys=True), FILE_MODE)
 
 
@@ -284,7 +289,19 @@ def ranked(rows: dict[str, dict]) -> list[str]:
         agent = order.get(row.get("worker"), len(order))
         return (pinned is None, pinned or 0, score is None, -(score[2] if score else 0), agent, task)
 
-    return sorted(rows, key=key)
+    placed: list[str] = []
+
+    def place(task: str, trail: frozenset) -> None:
+        if task in placed or task in trail:
+            return
+        for before in rows[task].get("after", []):
+            if before in rows:
+                place(before, trail | {task})
+        placed.append(task)
+
+    for task in sorted(rows, key=key):
+        place(task, frozenset())
+    return placed
 
 
 def by_agent(rows: dict[str, dict]) -> dict[str, list[str]]:
@@ -362,6 +379,8 @@ def cmd_set(args: argparse.Namespace) -> int:
     check_task(args.task)
     if args.prio is not None and args.prio < 1:
         fail("--prio must be 1 or higher")
+    if args.unpin and args.prio is not None:
+        fail("--unpin removes the pin; it cannot go with --prio")
     times = {f: stamp(getattr(args, f)) for f in ("start", "end") if getattr(args, f)}
     for ref in args.artifact:
         if not ARTIFACT.match(ref):
@@ -375,6 +394,8 @@ def cmd_set(args: argparse.Namespace) -> int:
             value = getattr(args, field)
             if value is not None:
                 entry[field] = value
+        if args.unpin:
+            entry.pop("prio", None)
         if args.status:
             apply_status(entry, args.status)
         entry.update(times)
@@ -591,6 +612,7 @@ def main() -> int:
     for field in (*TEXT_FIELDS, "start", "end"):
         p.add_argument(f"--{field}")
     p.add_argument("--prio", type=int)
+    p.add_argument("--unpin", action="store_true")
     for flag in (*LIST_FIELDS.values(), "artifact"):
         p.add_argument(f"--{flag}", action="append", default=[])
         p.add_argument(f"--drop-{flag}", action="append", default=[])

tests/test_gates.py

@@ -0,0 +1,94 @@
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+GATES = Path(__file__).resolve().parents[1] / "skills" / "kvb-check-gate" / "scripts" / "gates.py"
+
+
+def git(repo: Path, *args: str) -> str:
+    return subprocess.run(["git", *args], cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+
+
+class TestGates(unittest.TestCase):
+    def setUp(self):
+        scratch = tempfile.TemporaryDirectory()
+        self.addCleanup(scratch.cleanup)
+        self.base = Path(scratch.name)
+        self.repo = self.base / "repo"
+        self.repo.mkdir()
+        git(self.repo, "init", "-q", "-b", "main")
+        git(self.repo, "config", "user.email", "t@example.org")
+        git(self.repo, "config", "user.name", "t")
+        self.commit("a")
+        self.env = {**os.environ, "GATES_DB": str(self.base / "gates.db")}
+
+    def commit(self, name: str) -> None:
+        (self.repo / name).write_text(name, encoding="utf-8")
+        git(self.repo, "add", name)
+        git(self.repo, "commit", "-q", "-m", name)
+
+    def gates(self, *args: str) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            [sys.executable, str(GATES), *args], cwd=self.repo, env=self.env, capture_output=True, text=True, check=False
+        )
+
+    def resolve(self, branch: str, action: str = "merge") -> str:
+        return self.gates("resolve", "--repo", str(self.repo), "--branch", branch, "--action", action).stdout.strip()
+
+    def test_a_branch_takes_its_own_rule_else_the_strictest_of_all_parents_else_none(self):
+        repo = str(self.repo)
+        self.assertEqual(self.resolve("fix"), "none\t-")
+        for parent, level in (("iam", "test"), ("production", "quality-high")):
+            self.gates("rule", "set", "--repo", repo, "--branch", parent, "--action", "merge", "--level", level)
+            self.gates("parents", "add", "--repo", repo, "--branch", "fix", "--parent", parent)
+        self.assertEqual(self.resolve("fix"), "quality-high\tproduction")
+        self.gates("rule", "set", "--repo", repo, "--branch", "fix", "--action", "merge", "--level", "quick")
+        self.assertEqual(self.resolve("fix"), "quick\tfix")
+        self.assertEqual(self.resolve("fix", "push"), "none\t-")
+
+    def test_derive_gives_each_branch_its_nearest_ancestor_tips_and_the_default_branch_none(self):
+        git(self.repo, "checkout", "-q", "-b", "feature")
+        self.commit("b")
+        git(self.repo, "checkout", "-q", "-b", "fix")
+        self.commit("c")
+        derived = self.gates("parents", "derive", "--repo", str(self.repo)).stdout.splitlines()
+        self.assertEqual(sorted(derived), ["feature\tmain\tderived", "fix\tfeature\tderived"])
+        shown = json.loads(self.gates("show", "--json", "--repo", str(self.repo)).stdout)
+        branches = next(iter(shown.values()))
+        self.assertEqual(branches["main"]["parents"], [])
+        self.assertEqual(branches["fix"]["parents"], [{"parent": "feature", "source": "derived"}])
+
+    def test_the_tree_covers_unstaged_and_untracked_files_but_not_ignored_ones(self):
+        tree = lambda: self.gates("tree", "--worktree", str(self.repo)).stdout.strip()
+        head = git(self.repo, "rev-parse", "HEAD^{tree}")
+        self.assertEqual(tree(), head)
+        (self.repo / ".gitignore").write_text("ignored\n", encoding="utf-8")
+        git(self.repo, "add", ".gitignore")
+        git(self.repo, "commit", "-q", "-m", "ignore")
+        (self.repo / "ignored").write_text("x", encoding="utf-8")
+        self.assertEqual(tree(), git(self.repo, "rev-parse", "HEAD^{tree}"))
+        (self.repo / "a").write_text("changed", encoding="utf-8")
+        (self.repo / "new").write_text("new", encoding="utf-8")
+        dirty = tree()
+        self.assertEqual(git(self.repo, "status", "--porcelain"), "M a\n?? new")
+        git(self.repo, "add", "-A")
+        self.assertEqual(dirty, git(self.repo, "write-tree"))
+
+    def test_a_receipt_meets_its_own_level_and_every_lower_one(self):
+        repo, tree = str(self.repo), git(self.repo, "rev-parse", "HEAD^{tree}")
+        check = lambda level: self.gates("receipt", "check", "--repo", repo, "--tree", tree, "--level", level).returncode
+        self.assertEqual(check("quick"), 1)
+        self.gates("receipt", "add", "--repo", repo, "--tree", tree, "--level", "test", "--log", "/tmp/x.log")
+        self.assertEqual((check("quick"), check("test"), check("quality-high")), (0, 0, 1))
+
+    def test_a_branch_cannot_be_its_own_parent(self):
+        result = self.gates("parents", "add", "--repo", str(self.repo), "--branch", "fix", "--parent", "fix")
+        self.assertEqual(result.returncode, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_rasci.py

@@ -166,6 +166,22 @@ class TestRasci(unittest.TestCase):
         rows = json.loads((self.root / "rasci.json").read_text(encoding="utf-8"))
         return {task: row["after"] for task, row in rows.items() if "after" in row}
 
+    def test_unpin_drops_the_pin_a_change_stamps_only_its_row_and_the_rank_follows_after(self):
+        rows = lambda: json.loads((self.root / "rasci.json").read_text(encoding="utf-8"))
+        self._out("set", "work/a", "--prio", "1", "--worker", "One")
+        self._out("set", "work/b", "--prio", "2", "--worker", "One")
+        self.assertEqual(self._out("agents")[0].split("\t")[3], "work/a, work/b")
+        self._out("set", "work/a", "--after", "work/b")
+        self.assertEqual(self._out("agents")[0].split("\t")[3], "work/b, work/a")
+        stamped = rows()["work/a"]["updated"]
+        self._out("set", "work/b", "--unpin")
+        self.assertNotIn("prio", rows()["work/b"])
+        self.assertEqual(rows()["work/a"]["updated"], stamped)
+        self.assertIn("updated", rows()["work/b"])
+        refused = self._run("set", "work/b", "--unpin", "--prio", "3")
+        self.assertEqual(refused.returncode, 2)
+        self.assertIn("--unpin", refused.stderr)
+
     def test_after_stores_and_drops_a_dependency_and_refuses_unknown_tasks_and_cycles(self):
         for task in ("work/a", "work/b", "work/c"):
             self._out("set", task)