From 0fce29357b1bb92e8bbe52ff35ef15a955866cad Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 06:56:38 +0000 Subject: [PATCH 01/34] =?UTF-8?q?spec(protocol):=20issue-native=20tracking?= =?UTF-8?q?=20=E2=80=94=20control=20plane=20to=20GitHub=20issues,=20eviden?= =?UTF-8?q?ce=20stays=20in=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Accepted design, not yet enforced. Moves the volatile control plane (row State/Owner, coordination claims, NOW) onto GitHub issues, and keeps doctrine and evidence in the repo. Rationale: every recorded record-corruption event is the same bug — one fact stored in two writable places, reconciled by a three-way merge (the 2026-08-04 binding-number variant, the interleaved state tail, union-duplicated keyed rows, the unclaimed concurrent pushes). Issue assignment is a server-side atomic write, so the claim race disappears. Scope: ~160 live rows (SPIKE/READY/ACTIVE/GATING/PARTIAL/BLOCKED) become issues; the 155 INVENTORIED/DONE/OUT-OF-SCOPE rows, the 52 ANCHOR-BACKFILL evidence-debt rows, and the ~48k lines of append-only evidence (state, benchmark-record, parity-ledger, specs, public keyed tables) stay in git. A number that exists only in an issue comment is not binding. PARTIAL rows are included (user-directed): on a public roadmap a capability with explicit missing modes is exactly the content outsiders need. P0 is the live-state audit and lands first, standalone (user-directed): 49 rows claim ACTIVE simultaneously, which cannot be true. A truthful matrix is worth having even if every later phase stalls, and auditing first means the backfill mints issues from a corrected record rather than publishing the rot. Preserves the T0 spike gate (state:ready+ implies a committed spec card) and the DONE anchor contract via a CI-only check-issue-record.py, with a skip-when-offline / required-in-CI degradation rule so local work is never blocked and nothing merges unreconciled. Membership is enforced in both directions so the tracker is exhaustive, not merely consistent. Records that closing keywords must live in the squash COMMIT message, not the PR body: this project lands squashes via commit-tree + direct push, so PR-body keywords would never fire and issues would silently never close. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .agents/specs/issue-native-tracking.md | 285 +++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 .agents/specs/issue-native-tracking.md diff --git a/.agents/specs/issue-native-tracking.md b/.agents/specs/issue-native-tracking.md new file mode 100644 index 00000000..7279cb94 --- /dev/null +++ b/.agents/specs/issue-native-tracking.md @@ -0,0 +1,285 @@ +# Issue-native tracking protocol + +User-directed 2026-08-06. Status: **accepted design, not yet enforced.** This +document is the contract; the migration phases and CI guards named below are the +work it implies. `AGENTS.md`, `.agents/workflow.md` and the checkers are +deliberately untouched until this is reviewed. + +## Scope + +Move the project's **control plane** — which work exists, what state it is in, +and who owns it — from hand-merged Markdown into GitHub issues, so that tracking +is deterministic and concurrent sessions cannot corrupt it. + +Out of scope, and explicitly staying in files: the **doctrine** (`AGENTS.md`, +`.agents/directives.md`, `.agents/discipline.md`, `.agents/gates.md`, the +benchmark and parity-lever protocols) and the **evidence** (`.agents/state.md`, +`.agents/benchmark-record.md`, `.agents/parity-ledger.md`, every +`.agents/specs/` card, `docs/STATUS.md`, `docs/BENCHMARKS.md`, +`docs/FEATURES.md`, goldens). Also out of scope: what work to do (the roadmap's +ordering) and how to do it. + +## Our baseline — why this exists + +The record is 30 files and ~52k lines under `.agents/`, plus 393 ID'd rows across +seven area matrices, of which 367 carry a recognised lifecycle state. Two +properties of it are in tension: + +- **Evidence** is append-only, git-provenanced, greppable and shipped with the + code. This works. `benchmark-record.md` exists precisely so a lever is not + re-run after being closed, and that only works because it is local and + greppable. +- **Control state** — `State`, `Owner`, and the `coordination.md` claim table — + is *mutable state concurrently written by parallel worktrees*. This does not + work, and the failures are recorded: + + - 2026-08-04: a three-way merge silently produced a **variant** of another + session's binding numbers. No conflict, no marker. + - union-merging appends from parallel worktrees interleaved the `state.md` + tail, so "newest last" was false and cold resume returned a jumble + (`check-state-order.py` and `sort-state-tail.py` exist to repair this). + - union-resolving the keyed tables **duplicates rows** rather than merging + them. + - `coordination.md` is a mutex implemented as a text file merged across + worktrees. On 2026-08-04 two sessions pushed to `main` within minutes and + neither claimed anything in it. + +Every one of those is the same bug: **one fact stored in two writable places, +reconciled by a three-way merge.** + +A second, quieter symptom: **49 rows are simultaneously marked `ACTIVE`.** That +cannot be true. A stale `ACTIVE` cell inside a several-hundred-row table is +invisible rot; an issue with no assignee and no linked PR is visibly stale. + +Meanwhile GitHub already carries half the workflow — 44 PRs, branches already +named `row/` — while the issue tracker holds exactly one issue. The +mapping already exists by accident. + +### Row census (2026-08-06) + +| Bucket | Count | Gets an issue? | +|---|---|---| +| `ACTIVE` 49, `SPIKE` 24, `GATING` 11, `BLOCKED` 6, `READY` 6 | **96** | yes — live work | +| `PARTIAL` | **64** | yes — a known open gap is roadmap content | +| `ANCHOR-BACKFILL` | 52 | not at backfill; on transition | +| `INVENTORIED` 125, `DONE` 22, `OUT-OF-SCOPE` 8 | 155 | no — inventory and history | + +**~160 issues at backfill** (user-directed 2026-08-06: include `PARTIAL`). A +`PARTIAL` row is a capability with working modes and explicitly missing ones — +on a public roadmap that is exactly the content outsiders need, and leaving the +64 of them invisible would undersell what is genuinely open. `ANCHOR-BACKFILL` +is evidence debt rather than a capability gap, so it stays file-side until +someone picks it up. + +A wholesale conversion would create 393 issues of mostly dead inventory. The +tracker is the **live window**; the matrices remain the **permanent inventory**. + +## Design + +### The principle + +**Every field has exactly one writable home.** This is the whole design; the +rest is consequence. + +| Field | Home | Why | +|---|---|---| +| `ID`, `Item`, `Upstream`, `Our code`, `Tests/evidence`, `Spike/spec` | matrix row (file) | durable evidence anchors; CI already verifies path class and line range | +| `State` | issue label | volatile, concurrently mutated | +| `Owner` / claim | issue assignee | a real server-side lock, not a text-file mutex | +| Dependencies | issue links | | +| Per-attempt narrative | issue comments, summarising the files | | + +Consequence: **the `State` and `Owner` columns are removed from the matrices** +and replaced by one `Issue` column holding `#N`. The `coordination.md` +active-claim table is retired. + +### Lifecycle + +An issue is the live window of a row. The membership rule is exact and +bidirectional, because that is what makes the tracker deterministic: + +**An open issue exists for a row if and only if its state is `SPIKE`, `READY`, +`ACTIVE`, `GATING`, `PARTIAL` or `BLOCKED`.** + +- **opened** when a row enters that set; +- **closed** by the landing commit at `DONE`, at which point the durable anchors + are written back into the matrix row. + +`INVENTORIED`, `DONE` and `OUT-OF-SCOPE` never carry an open issue. +`ANCHOR-BACKFILL` does not either — it is evidence debt on already-landed code, +and it gains an issue only when someone claims the backfill, at which point the +row moves into the live set. + +### Keys, labels, milestones + +**Row ID stays the primary handle.** Branches remain `row/`, matrices +key on Row ID, issue titles are prefixed `[ENG-SCHED-CORE] …`, and `#N` is a +pointer. Nothing existing is renamed, no historical reference in `state.md` or +the ledger breaks, and the ID survives if the tracker is ever swapped out. CI +asserts the ID↔issue mapping is bijective. + +Labels mirror the existing tabular lifecycle rather than inventing one: + +- `state:spike|ready|active|gating|partial|blocked` — a closed issue is `DONE`; +- `area:engine|model|quant|kernel|backend|feature|sglang` — names the owning + matrix; +- `tier:T0|T1|T2|T3`; +- `blocked:hardware|external|upstream`; +- `roadmap` — the public headline tracks. + +**Milestones are the roadmap's ordered blocks** (order-0 perf closure, +`ROAD-V1-MM`, backend expansion, …). Milestone order *is* the portfolio order, +which produces the public ordered roadmap for free. + +Issues are written to be read by outsiders, not only by agents: a prose summary +of what the row is and why it matters, above the machine fields. + +### The claim becomes an assignment + +`scripts/agent-role.py claim helper --row ENG-FOO` today writes a +`coordination.md` row. It will instead, in one server-side write: + +1. refuse if the issue is already assigned; +2. assign the issue and set `state:active`; +3. create the `row/ENG-FOO` worktree and branch; +4. open the draft PR. + +Assignment is atomic and unmergeable, so the claim race disappears. The +operator/helper roles, the exclusive operator lock, and the "helper works in a +worktree and opens a draft PR at the start" rule are unchanged — only the +*medium* of the claim changes. + +### Read cache for offline work + +`.agents/rows.generated.md` is an **untracked, machine-written** projection of +the open issues (`ID | state | assignee | issue | milestone`), refreshed from the +API by `scripts/sync-rows.py`, which `agent-preflight.sh` runs at session start. +It is never hand-edited and never committed, so it can never conflict and never +churns `main`. A fresh clone with no network simply has no cache until its first +online run. + +`.agents/NOW.md` becomes generated by the same script: the open +`state:active`/`state:gating` issues plus the gate being chased. "Generated, +therefore always current" replaces `check-now-current.py`'s hand-maintained +freshness coupling. + +### What `coordination.md` keeps + +The active-claim table and the completed-claim archive go (the archive to +`.agents/completed/`). The **row contract**, the **spike gate**, the canonical +hierarchy, and the dependency and GPU-lock rules stay — those are doctrine and +belong in files. The file shrinks to a few hundred lines of contract. + +## Enforcement + +The split follows what is provable from the tree. + +**Offline, local, in `agent-preflight.sh`** — unchanged in spirit. Everything +provable from the tree stays provable from the tree: `check-doc-checkpoint.py`, +`check-state-order.py`, `check-protocol-consistency.py`, and every anchor +path-class and line-range check in `check-agent-record.py`. + +**CI-only, new `scripts/check-issue-record.py`** (Actions already provides a +token): + +1. every matrix `Issue #N` resolves, and that issue's Row ID matches the row; +2. no orphan open issues — every one has a matrix row; +3. **every row in a live state has an open issue, and every open issue's row is + in a live state** — the membership rule above, enforced in both directions. + This is what makes the tracker exhaustive rather than merely consistent; +4. no two open issues share a Row ID; +5. a **closed** issue implies its matrix row carries `DONE`-grade anchors — code + + tests/evidence + spec + exact parity-ledger line + closing commit present + in Git history. This is today's contract, preserved verbatim; +6. `state:ready` or later implies a resolving `.agents/specs/.md` exists + in the tree. **This preserves the T0 spike gate**, which is the one gate most + at risk from the migration. + +**Degradation rule.** When `gh` is unavailable or unauthenticated, the +issue-dependent checks *skip loudly* and never block local work; they are +**required in CI**, so nothing merges unreconciled. Local stays offline-capable, +the merge gate stays strict. Never weaken a checker to make a transition pass — +repair the record. + +`check-agent-record.py` loses its `State`/`Owner` validation and gains `Issue` +column validation; its mutation suite moves in the same change. +`claim-view.py` and `ready-for-helper.py` read the cache instead of +`coordination.md`. + +### The closing keyword must live in the commit message + +Because `gh pr merge` squashes as `localai-bot`, this project lands squashes +locally via `commit-tree` and a direct push to `main`. GitHub auto-closes an +issue from a **PR body** keyword only when the PR is merged through GitHub — +which we do not do. A `Closes #N` in the PR body would therefore never fire, and +every issue would stay open forever while the tracker looked authoritative. + +**The closing keyword goes in the squash commit message**, next to +`FOLLOWING_AGENTS_PROTOCOL` (GitHub does close issues from commit messages +pushed to the default branch). Preflight checks that a commit on a `row/` +branch carries it. + +## Migration + +Six independently landable phases. The tracker keeps working throughout; a wrong +phase is reverted alone. **P3 is the irreversible one and lands only after the +P2 backfill is verified.** + +| Phase | Work | +|---|---| +| P0 | **The live-state audit** — reconcile the 49 `ACTIVE` rows against branches, PRs and commits → in-flight / landed / abandoned; confirm each of the 64 `PARTIAL` rows names its missing modes; correct the matrices. Pure file-side, no issue machinery | +| P1 | Label and milestone schema, `.github/ISSUE_TEMPLATE/row.yml`, `scripts/sync-rows.py`, `scripts/check-issue-record.py` (skip-when-offline, required-in-CI) | +| P2 | Idempotent backfill of the ~160 live rows into issues; dry-run first | +| P3 | Strip `State`/`Owner` from the seven matrices, add `Issue`; update `check-agent-record.py` **and its mutation suite** | +| P4 | `agent-role.py claim` assigns instead of writing a row; `coordination.md` claim table retired to `completed/`; `NOW.md` generated; rewire `claim-view.py`, `ready-for-helper.py`, `check-now-current.py` | +| P5 | Prose: `AGENTS.md` T0, `.agents/workflow.md`, `.agents/directives.md` | + +**P0 lands first and stands alone** (user-directed 2026-08-06). It is an audit, +not bookkeeping: it is the first time the 49 `ACTIVE` claims are tested against +reality. Its value does not depend on the migration — a truthful matrix is worth +having even if every later phase stalls — and running it first means the backfill +mints ~160 issues from a corrected record rather than publishing the rot. Because +`PARTIAL` rows now become public issues, P0 also checks that each states its +missing modes, which the row contract already requires; a vague `PARTIAL` row +would otherwise become a vague public issue. + +**P5 constraint.** `check-protocol-consistency.py` asserts that the obligation +blocks appear *verbatim* in `.agents/workflow.md` and equal the checker's +constants. Prose and gate must move in the same change — that checker exists +because an obligation was once migrated in `AGENTS.md` and the checker but not +in the manual, which went on instructing agents to do the thing the migration +had removed. Prose is what agents actually read. + +## Risks and decisions + +**Accepted cost: a lifecycle transition is no longer verifiable from the tree +alone.** CI must query the API, which is flakier than a local file read and +cannot be verified offline. This is paid only for the surfaces where concurrency +is the actual problem — claims and row status — and not for the ~48k lines of +evidence. The degradation rule bounds the blast radius: offline work is never +blocked, and the merge gate is never relaxed. + +**Rejected: full conversion.** Moving `state.md` (36,277 lines) and +`benchmark-record.md` (12,145) into issues would trade append-only git +provenance, local grep, offline cold-start and most CI gating for nothing the +control-plane migration does not already deliver. Issue comments are mutable, +deletable, and live on someone else's server; T0 says evidence is moved, never +deleted, and issues cannot promise that. + +**Rejected: spike cards as issue bodies.** It would make issues +self-describing, but "no row enters `READY`/`ACTIVE` without a *committed* +`.agents/specs/.md`" would stop being checkable from a commit, and spikes +would stop being greppable and diffable. Issues link to the spec; the spec stays +a file. + +**Rejected: `State` in both places with a CI reconciler.** It preserves today's +offline workflow but re-creates the two-writers problem the migration exists to +kill; the reconciler becomes the thing that breaks. + +**Binding-number rule.** A number that exists only in an issue comment is **not +binding**. Binding numbers live in `docs/BENCHMARKS.md`, the parity ledger and +the benchmark record, in git. + +**Open risk: issue-tracker lock-in.** Row IDs staying primary is the mitigation +— the matrices remain a complete inventory keyed independently of GitHub, so the +control plane can be rehomed without touching the evidence. From d41e7bcbd019b3914443ecfd1616fdb1bff8360b Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:04:13 +0000 Subject: [PATCH 02/34] =?UTF-8?q?plan(protocol):=20P0=20live-state=20audit?= =?UTF-8?q?=20=E2=80=94=20reconcile=20160=20live=20rows=20against=20Git=20?= =?UTF-8?q?reality?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implementation plan for phase P0 of .agents/specs/issue-native-tracking.md. Builds scripts/audit-live-rows.py, which imports the row parser from check-agent-record.py rather than reimplementing it (P1's sync-rows.py reuses the same helpers), cross-references each live row against row/ branches and main commits, and classifies ACTIVE rows IN-FLIGHT / LANDED / ABANDONED. The classifier is a pure function over gathered evidence, so it unit-tests without Git and cannot be flaky. The tool proposes and reports; it never rewrites a matrix. Corrections are applied per-matrix in reviewable commits, because a state transition carries contract obligations only a reader of the row can satisfy: an abandoned ACTIVE row goes to READY if it has a real spec, otherwise INVENTORIED. The gate is wired LAST, after the record is repaired, so it never has to be relaxed to pass. Git evidence only, no gh: an open PR always has a row/ branch with unmerged commits, so P0 stays offline-capable and free of the issue machinery P1 introduces. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 967 ++++++++++++++++++ 1 file changed, 967 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-06-p0-live-state-audit.md diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md new file mode 100644 index 00000000..40986636 --- /dev/null +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -0,0 +1,967 @@ +# P0 Live-State Audit Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Reconcile the 160 live-state matrix rows against Git reality — above all the 49 rows simultaneously claiming `ACTIVE`, which cannot all be true — so the record is truthful before any issue backfill mints ~160 public issues from it. + +**Architecture:** A new reporting tool, `scripts/audit-live-rows.py`, reuses the row parser already inside `scripts/check-agent-record.py` (never reimplements it) and cross-references each live row against local/remote `row/` branches and `main` commits mentioning the ID. Classification is a **pure function** over already-gathered evidence, so it is unit-testable without Git. The tool **proposes and reports; it never rewrites a matrix.** A human/agent applies corrections per matrix in reviewable commits. Only after the record is corrected does the tool become a CI gate, so the rot cannot return. + +**Tech Stack:** Python 3 standard library only (no new dependencies), `argparse`, `importlib.util` for loading the hyphenated checker module, `subprocess` for Git, `unittest` for the mutation suite. Matches the existing `scripts/check-*.py` house style. + +**Deliberate divergence from the spec.** The spec's P0 says "reconcile against branches, PRs and commits". This plan uses **Git evidence only — no `gh`**. An open PR always has a `row/` head branch with unmerged commits, so the branch check already covers it, while staying fully offline-capable and keeping P0 free of the issue machinery that P1 introduces. If a row is ever worked without a `row/` branch, the audit reports it `ABANDONED` and the human review in Task 5 Step 3 catches it. + +## Global Constraints + +Copied from `AGENTS.md`, `.agents/coordination.md` and `.agents/specs/issue-native-tracking.md`. Every task's requirements implicitly include this section. + +- **Every commit carries the trailer `FOLLOWING_AGENTS_PROTOCOL`** plus `Assisted-by: : [TOOL]`. **Never** `Signed-off-by` or `Co-Authored-By` from an AI. CI rejects commits lacking the protocol trailer. +- **Run `scripts/agent-preflight.sh` before every commit.** It must exit 0. Never pipe it (`cmd | tail` masks the exit status); redirect to a file and check `$?`. +- **Never weaken a checker to make a transition pass. Repair the record.** +- **Never three-way merge a keyed record.** The matrices, `docs/STATUS.md`, `docs/BENCHMARKS.md`, `docs/FEATURES.md` and `.agents/NOW.md` are merged by taking `main`'s version wholesale, re-applying your edit, and verifying the other side is byte-identical. +- **Evidence is moved, never deleted.** +- **Python: standard library only.** No new dependencies. Use `from __future__ import annotations`, dataclasses and type hints, matching `scripts/check-agent-record.py`. +- **DRY across P0/P1:** row parsing lives in `scripts/check-agent-record.py` and is imported, never copied. `scripts/sync-rows.py` (P1) will import the same helpers. +- **Heuristics report; they never gate.** The `PARTIAL` missing-modes detector is a flag for human review and must never become a hard failure. +- **State-transition legality** (enforced by `check-agent-record.py`, so violating it breaks the build): + - `READY`, `ACTIVE`, `GATING`, `DONE`, `BLOCKED` require a real `.agents/specs/.md` link. + - `PARTIAL`, `ANCHOR-BACKFILL`, `GATING`, `DONE` require resolving code/test evidence anchors. + - Therefore an abandoned `ACTIVE` row moves to **`READY` if it has a real spec, otherwise `INVENTORIED`** — it may not simply be blanked. +- The live set is exactly: `SPIKE`, `READY`, `ACTIVE`, `GATING`, `PARTIAL`, `BLOCKED`. + +**Baseline census on `origin/main` @ `027af9b0` (verified 2026-08-06):** 367 rows carry a state — `INVENTORIED` 125, `PARTIAL` 64, `ANCHOR-BACKFILL` 52, `ACTIVE` 49, `SPIKE` 24, `DONE` 22, `GATING` 11, `OUT-OF-SCOPE` 8, `BLOCKED` 6, `READY` 6. **Live total = 160.** + +--- + +## File Structure + +| File | Responsibility | +|---|---| +| `scripts/audit-live-rows.py` (create) | Load live rows, gather Git evidence, classify, render report/JSON, and (from Task 7) gate | +| `tests/scripts/test_audit_live_rows.py` (create) | Unit + mutation suite for the classifier and the shipped-matrix integration | +| `.agents/specs/live-state-audit-2026-08-06.md` (create) | The audit findings artifact — the evidence justifying every correction | +| `.agents/*-matrix.md` (modify, Task 6) | The corrections themselves, one commit per matrix | +| `.agents/state.md` (modify, Task 6) | Append-only checkpoint entry | +| `scripts/agent-preflight.sh:50-63` (modify, Task 7) | Register the new mutation suite and the gate | +| `.github/workflows/ci.yml:42-46` (modify, Task 7) | Run the gate and its mutation suite in CI | + +--- + +### Task 1: Row loading and Git evidence collection + +**Files:** +- Create: `scripts/audit-live-rows.py` +- Test: `tests/scripts/test_audit_live_rows.py` + +**Interfaces:** +- Consumes: `scripts/check-agent-record.py` — `ClaimRow` (frozen dataclass with fields `path: Path`, `line_no: int`, `item_id: str`, `state: str`, `header: tuple[str, ...]`, `cells: tuple[str, ...]`, `raw: str`, and method `field(name: str) -> str`); `parse_claim_rows(path: Path, errors: list[str]) -> list[ClaimRow]`; `MATRIX_PATHS: list[Path]`. +- Produces: `LIVE_STATES: frozenset[str]`; `live_rows() -> list[ClaimRow]`; `row_branches() -> dict[str, list[str]]`; `main_commits(item_id: str) -> list[str]`; `unmerged(branch: str) -> list[str]`. + +- [ ] **Step 1: Write the failing test** + +Create `tests/scripts/test_audit_live_rows.py`: + +```python +#!/usr/bin/env python3 +"""Unit and mutation checks for scripts/audit-live-rows.py. + +The audit only helps if it is honest in both directions: it must not call a +live row abandoned when work is really in flight, and it must not call an +abandoned row live because a branch name happens to exist. +""" + +from __future__ import annotations + +import importlib.util +import sys +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] + + +def _load(name: str, relative: str): + path = ROOT / relative + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +audit = _load("audit_live_rows", "scripts/audit-live-rows.py") + + +class LiveRowLoadingTests(unittest.TestCase): + def test_live_states_are_exactly_the_six(self): + self.assertEqual( + audit.LIVE_STATES, + frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}), + ) + + def test_shipped_matrices_yield_only_live_rows(self): + rows = audit.live_rows() + self.assertTrue(rows, "the shipped matrices must contain live rows") + for row in rows: + self.assertIn(row.state, audit.LIVE_STATES) + + def test_every_live_state_is_represented_in_the_shipped_matrices(self): + # Guards the loader against silently dropping a whole state: if a + # header rename made one state unparseable, its count would go to + # zero while the other five still looked healthy. + rows = audit.live_rows() + present = {row.state for row in rows} + self.assertEqual(present, set(audit.LIVE_STATES)) + self.assertGreater(len(rows), 100, "the live set is ~160 rows") + + +if __name__ == "__main__": + unittest.main() +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: FAIL — `FileNotFoundError` / `AssertionError` from `_load`, because `scripts/audit-live-rows.py` does not exist yet. + +- [ ] **Step 3: Write minimal implementation** + +Create `scripts/audit-live-rows.py`: + +```python +#!/usr/bin/env python3 +"""Audit the live-state matrix rows against Git reality. (P0) + +49 rows claim ACTIVE at once, which cannot be true: a stale ACTIVE cell inside +a several-hundred-row table is invisible rot. This tool makes it visible. + +It PROPOSES and REPORTS. It never rewrites a matrix -- corrections are applied +by a human/agent in reviewable per-matrix commits, because a state transition +carries contract obligations (a spec link, evidence anchors) that only a reader +of the row can satisfy. + +Row parsing is imported from scripts/check-agent-record.py rather than +reimplemented, so the audit and the gate can never disagree about what a row is. + + scripts/audit-live-rows.py # markdown report + scripts/audit-live-rows.py --json # machine-readable + scripts/audit-live-rows.py --check # exit 1 if an ACTIVE row is abandoned +""" + +from __future__ import annotations + +import argparse +import importlib.util +import json +import re +import subprocess +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] + + +def _load(name: str, relative: str): + path = ROOT / relative + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +record = _load("agent_record", "scripts/check-agent-record.py") + +LIVE_STATES = frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}) + + +def live_rows() -> list: + """Every row in the shipped matrices whose state is in LIVE_STATES.""" + rows = [] + for path in record.MATRIX_PATHS: + errors: list[str] = [] + for row in record.parse_claim_rows(path, errors): + if row.state in LIVE_STATES: + rows.append(row) + return rows + + +def git(*args: str) -> str: + result = subprocess.run( + ["git", *args], cwd=ROOT, capture_output=True, text=True, check=False + ) + return result.stdout if result.returncode == 0 else "" + + +def row_branches() -> dict[str, list[str]]: + """Map row ID -> every local or remote branch named row/.""" + mapping: dict[str, list[str]] = {} + out = git("for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes") + for line in out.splitlines(): + name = line.strip() + if name.startswith("row/"): + item_id = name[len("row/") :] + elif "/row/" in name: + item_id = name.split("/row/", 1)[1] + else: + continue + mapping.setdefault(item_id, []).append(name) + return mapping + + +def main_commits(item_id: str) -> list[str]: + """Commits on origin/main whose message mentions the row ID literally.""" + out = git( + "log", "--oneline", "--fixed-strings", f"--grep={item_id}", "-n", "20", + "origin/main", + ) + return [line.strip() for line in out.splitlines() if line.strip()] + + +def unmerged(branch: str) -> list[str]: + """Commits on branch that are not yet on origin/main.""" + out = git("log", "--oneline", f"origin/main..{branch}") + return [line.strip() for line in out.splitlines() if line.strip()] +``` + +Make it executable: `chmod +x scripts/audit-live-rows.py` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: PASS, 3 tests. + +- [ ] **Step 5: Verify the loader sees the real census** + +Run: `python3 -c "import importlib.util,sys; s=importlib.util.spec_from_file_location('a','scripts/audit-live-rows.py'); m=importlib.util.module_from_spec(s); sys.modules['a']=m; s.loader.exec_module(m); rows=m.live_rows(); import collections; print(len(rows), collections.Counter(r.state for r in rows))"` +Expected: `160` total, with `ACTIVE` = 49, `PARTIAL` = 64, `SPIKE` = 24, `GATING` = 11, `BLOCKED` = 6, `READY` = 6. + +If the numbers differ, do **not** adjust the test to match — `main` has moved. Re-read the current census, record the new baseline in the commit message, and continue. + +- [ ] **Step 6: Run preflight and commit** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add scripts/audit-live-rows.py tests/scripts/test_audit_live_rows.py +git commit -F - <<'EOF' +tools(audit): load live matrix rows and gather Git evidence (P0 step 1) + +Reuses the row parser in check-agent-record.py rather than reimplementing it, +so the audit and the gate can never disagree about what a row is. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 2: The classifier + +**Files:** +- Modify: `scripts/audit-live-rows.py` +- Test: `tests/scripts/test_audit_live_rows.py` + +**Interfaces:** +- Consumes: `row_branches()`, `main_commits()`, `unmerged()` from Task 1. +- Produces: `classify_active(branches: list[str], unmerged_by_branch: dict[str, list[str]], commits: list[str]) -> tuple[str, str]` returning `(verdict, reason)` where verdict is one of `"IN-FLIGHT"`, `"LANDED"`, `"ABANDONED"`. Also `VERDICTS: frozenset[str]`. + +The classifier is pure — it takes evidence, not a repository — so it is testable without Git and cannot be flaky. + +- [ ] **Step 1: Write the failing test** + +Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: + +```python +class ClassifierTests(unittest.TestCase): + def test_unmerged_branch_commits_mean_in_flight(self): + verdict, reason = audit.classify_active( + branches=["row/ENG-FOO"], + unmerged_by_branch={"row/ENG-FOO": ["abc1234 wip"]}, + commits=[], + ) + self.assertEqual(verdict, "IN-FLIGHT") + self.assertIn("row/ENG-FOO", reason) + + def test_fully_merged_branch_means_landed(self): + verdict, reason = audit.classify_active( + branches=["row/ENG-FOO"], + unmerged_by_branch={"row/ENG-FOO": []}, + commits=[], + ) + self.assertEqual(verdict, "LANDED") + self.assertIn("merged", reason.lower()) + + def test_main_commits_without_branch_mean_landed(self): + verdict, reason = audit.classify_active( + branches=[], + unmerged_by_branch={}, + commits=["def5678 feat(eng): ENG-FOO"], + ) + self.assertEqual(verdict, "LANDED") + self.assertIn("def5678", reason) + + def test_no_evidence_at_all_means_abandoned(self): + verdict, reason = audit.classify_active( + branches=[], unmerged_by_branch={}, commits=[] + ) + self.assertEqual(verdict, "ABANDONED") + self.assertIn("no branch", reason.lower()) + + def test_in_flight_wins_over_landed_when_both_present(self): + # A row can have landed groundwork AND active follow-up work. + # Claiming it is finished would silently steal an open claim. + verdict, _ = audit.classify_active( + branches=["row/ENG-FOO"], + unmerged_by_branch={"row/ENG-FOO": ["abc1234 wip"]}, + commits=["def5678 feat(eng): ENG-FOO groundwork"], + ) + self.assertEqual(verdict, "IN-FLIGHT") + + def test_every_verdict_is_declared(self): + for branches, by_branch, commits in [ + (["row/X"], {"row/X": ["a b"]}, []), + (["row/X"], {"row/X": []}, []), + ([], {}, ["a b"]), + ([], {}, []), + ]: + verdict, _ = audit.classify_active(branches, by_branch, commits) + self.assertIn(verdict, audit.VERDICTS) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: FAIL with `AttributeError: module 'audit_live_rows' has no attribute 'classify_active'`. + +- [ ] **Step 3: Write minimal implementation** + +Append to `scripts/audit-live-rows.py`: + +```python +VERDICTS = frozenset({"IN-FLIGHT", "LANDED", "ABANDONED"}) + + +def classify_active( + branches: list[str], + unmerged_by_branch: dict[str, list[str]], + commits: list[str], +) -> tuple[str, str]: + """Classify one ACTIVE row from already-gathered evidence. + + IN-FLIGHT wins over LANDED whenever both are present: a row can have landed + groundwork and still have open follow-up work, and calling that finished + would silently steal a live claim. + """ + live_branches = [b for b in branches if unmerged_by_branch.get(b)] + if live_branches: + joined = ", ".join(sorted(live_branches)) + return "IN-FLIGHT", f"unmerged commits on {joined}" + if branches: + joined = ", ".join(sorted(branches)) + return "LANDED", f"branch {joined} exists and is fully merged into main" + if commits: + return "LANDED", f"on main: {commits[0]}" + return "ABANDONED", "no branch, no commit on main mentioning the row ID" +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: PASS, 9 tests. + +- [ ] **Step 5: Run preflight and commit** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add scripts/audit-live-rows.py tests/scripts/test_audit_live_rows.py +git commit -F - <<'EOF' +tools(audit): pure evidence classifier for ACTIVE rows (P0 step 2) + +IN-FLIGHT deliberately outranks LANDED: a row can have landed groundwork and +still have open follow-up, and calling that finished would steal a live claim. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 3: PARTIAL missing-modes flag + +**Files:** +- Modify: `scripts/audit-live-rows.py` +- Test: `tests/scripts/test_audit_live_rows.py` + +**Interfaces:** +- Produces: `GAP_MARKERS: tuple[str, ...]`; `names_missing_modes(row_text: str) -> bool`. + +The row contract already requires a `PARTIAL` row to make its missing modes explicit. Because `PARTIAL` rows become **public** issues in P2, a vague one becomes a vague public issue. This is a **report-only flag for human review** and must never become a hard failure — the detector is a keyword heuristic and gating on it would be exactly the fragile-checker trap the protocol warns about. + +- [ ] **Step 1: Write the failing test** + +Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: + +```python +class PartialGapTests(unittest.TestCase): + def test_explicit_gap_language_is_recognised(self): + for text in [ + "Works for bf16; fp8 is missing", + "Prefill only, decode not yet ported", + "Dense path supported, MoE unsupported", + "Image works; audio pending", + ]: + self.assertTrue(audit.names_missing_modes(text), text) + + def test_row_without_gap_language_is_flagged(self): + self.assertFalse(audit.names_missing_modes("Ported and gated on GB10")) + + def test_detection_is_case_insensitive(self): + self.assertTrue(audit.names_missing_modes("FP8 IS MISSING")) + + def test_markers_match_whole_words_not_substrings(self): + # "commonly" contains "only" and "node" contains "no". A substring + # match would mark these rows explicit and hide them from review. + self.assertFalse(audit.names_missing_modes("Commonly used decode node")) + self.assertTrue(audit.names_missing_modes("Decode only")) + + def test_flag_is_advisory_and_never_gates(self): + # check mode fails only on abandoned ACTIVE rows, never on a vague + # PARTIAL row -- the detector is a keyword heuristic. + self.assertNotIn("PARTIAL", audit.CHECK_FAILS_ON) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: FAIL with `AttributeError: module 'audit_live_rows' has no attribute 'names_missing_modes'`. + +- [ ] **Step 3: Write minimal implementation** + +Append to `scripts/audit-live-rows.py`: + +```python +GAP_MARKERS = ( + "missing", + "not yet", + "unsupported", + "pending", + "only", + "absent", + "gap", + "no", + "without", + "blocked", + "todo", +) + +# Whole words, never substrings: "only" must not match "commonly" and "no" +# must not match "node". A substring match would silently mark a vague row as +# explicit, which is the exact failure this flag exists to catch. +GAP_RE = re.compile( + r"\b(?:" + "|".join(marker.replace(" ", r"\s+") for marker in GAP_MARKERS) + r")\b", + re.IGNORECASE, +) + +# check mode fails on abandoned ACTIVE rows and nothing else. The PARTIAL flag +# is a keyword heuristic for human review; gating on it would be the fragile +# checker the protocol warns against. +CHECK_FAILS_ON = frozenset({"ACTIVE"}) + + +def names_missing_modes(row_text: str) -> bool: + """True when a PARTIAL row states what is NOT supported.""" + return GAP_RE.search(row_text) is not None +``` + +`re` is already imported at the top of the module from Task 1; if it is not, add it there rather than mid-file. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: PASS, 14 tests. + +- [ ] **Step 5: Run preflight and commit** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add scripts/audit-live-rows.py tests/scripts/test_audit_live_rows.py +git commit -F - <<'EOF' +tools(audit): advisory PARTIAL missing-modes flag (P0 step 3) + +Report-only by construction: CHECK_FAILS_ON is ACTIVE alone, so the keyword +heuristic can never fail a build. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 4: Report rendering and CLI + +**Files:** +- Modify: `scripts/audit-live-rows.py` +- Test: `tests/scripts/test_audit_live_rows.py` + +**Interfaces:** +- Consumes: everything from Tasks 1–3. +- Produces: `audit() -> list[dict]` (one record per live row, keys `id`, `state`, `path`, `line`, `verdict`, `reason`, `flag`); `render_markdown(records: list[dict]) -> str`; `main(argv: list[str] | None = None) -> int`. + +- [ ] **Step 1: Write the failing test** + +Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: + +```python +class ReportTests(unittest.TestCase): + RECORDS = [ + { + "id": "ENG-FOO", + "state": "ACTIVE", + "path": ".agents/engine-matrix.md", + "line": 42, + "verdict": "ABANDONED", + "reason": "no branch, no commit on main mentioning the row ID", + "flag": "", + }, + { + "id": "MODEL-BAR", + "state": "PARTIAL", + "path": ".agents/model-matrix.md", + "line": 7, + "verdict": "", + "reason": "", + "flag": "does not name its missing modes", + }, + ] + + def test_markdown_lists_every_record(self): + out = audit.render_markdown(self.RECORDS) + self.assertIn("ENG-FOO", out) + self.assertIn("MODEL-BAR", out) + self.assertIn("ABANDONED", out) + self.assertIn("does not name its missing modes", out) + + def test_markdown_cells_do_not_break_the_table(self): + records = [dict(self.RECORDS[0], reason="a | b")] + out = audit.render_markdown(records) + body = [ln for ln in out.splitlines() if "ENG-FOO" in ln] + self.assertEqual(len(body), 1) + self.assertNotIn("a | b", body[0]) + + def test_check_mode_fails_when_an_active_row_is_abandoned(self): + self.assertEqual(audit.exit_code(self.RECORDS, check=True), 1) + + def test_check_mode_passes_when_no_active_row_is_abandoned(self): + clean = [dict(self.RECORDS[0], verdict="IN-FLIGHT")] + self.RECORDS[1:] + self.assertEqual(audit.exit_code(clean, check=True), 0) + + def test_report_mode_always_exits_zero(self): + self.assertEqual(audit.exit_code(self.RECORDS, check=False), 0) + + def test_vague_partial_alone_never_fails_check_mode(self): + only_flag = [self.RECORDS[1]] + self.assertEqual(audit.exit_code(only_flag, check=True), 0) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: FAIL with `AttributeError: module 'audit_live_rows' has no attribute 'render_markdown'`. + +- [ ] **Step 3: Write minimal implementation** + +Append to `scripts/audit-live-rows.py`: + +```python +import argparse +import json + + +def audit() -> list[dict]: + """One record per live row, with verdict (ACTIVE) and flag (PARTIAL).""" + branches_by_id = row_branches() + records: list[dict] = [] + for row in live_rows(): + verdict = "" + reason = "" + flag = "" + if row.state == "ACTIVE": + branches = branches_by_id.get(row.item_id, []) + unmerged_by_branch = {b: unmerged(b) for b in branches} + verdict, reason = classify_active( + branches, unmerged_by_branch, main_commits(row.item_id) + ) + if row.state == "PARTIAL" and not names_missing_modes(row.raw): + flag = "does not name its missing modes" + records.append( + { + "id": row.item_id, + "state": row.state, + "path": str(row.path.relative_to(ROOT)), + "line": row.line_no, + "verdict": verdict, + "reason": reason, + "flag": flag, + } + ) + return records + + +def _cell(value: object) -> str: + """Table cells never contain a raw pipe -- it would split the row.""" + return str(value).replace("|", "\\|").replace("\n", " ").strip() + + +def render_markdown(records: list[dict]) -> str: + lines = [ + "| Row | State | Location | Verdict | Evidence | Flag |", + "|---|---|---|---|---|---|", + ] + for item in records: + lines.append( + "| `{id}` | `{state}` | {path}:{line} | {verdict} | {reason} | {flag} |".format( + id=_cell(item["id"]), + state=_cell(item["state"]), + path=_cell(item["path"]), + line=_cell(item["line"]), + verdict=_cell(item["verdict"]) or "-", + reason=_cell(item["reason"]) or "-", + flag=_cell(item["flag"]) or "-", + ) + ) + return "\n".join(lines) + + +def exit_code(records: list[dict], check: bool) -> int: + if not check: + return 0 + abandoned = [ + item + for item in records + if item["state"] in CHECK_FAILS_ON and item["verdict"] == "ABANDONED" + ] + return 1 if abandoned else 0 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--json", action="store_true", help="machine-readable output") + parser.add_argument( + "--check", + action="store_true", + help="exit 1 if any ACTIVE row is abandoned", + ) + args = parser.parse_args(argv) + + records = audit() + if args.json: + print(json.dumps(records, indent=2, sort_keys=True)) + else: + print(render_markdown(records)) + stale = [i for i in records if i["verdict"] == "ABANDONED"] + vague = [i for i in records if i["flag"]] + print( + f"\n{len(records)} live rows; {len(stale)} abandoned ACTIVE; " + f"{len(vague)} PARTIAL rows to review." + ) + return exit_code(records, args.check) + + +if __name__ == "__main__": + raise SystemExit(main()) +``` + +Move the `import argparse` and `import json` lines up into the module's import block at the top of the file so imports are not scattered mid-module. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: PASS, 20 tests. + +- [ ] **Step 5: Smoke-test the CLI against the real repository** + +Run: `git fetch -q origin && python3 scripts/audit-live-rows.py | tail -5` +Expected: a summary line reading `160 live rows; N abandoned ACTIVE; M PARTIAL rows to review.` + +Run: `python3 scripts/audit-live-rows.py --json | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"` +Expected: `160`. + +**Note:** `--check` is expected to exit 1 right now. That is the finding, not a bug. Do not wire it into preflight or CI until Task 7. + +- [ ] **Step 6: Run preflight and commit** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add scripts/audit-live-rows.py tests/scripts/test_audit_live_rows.py +git commit -F - <<'EOF' +tools(audit): report, JSON and check modes (P0 step 4) + +check mode is deliberately NOT wired into preflight or CI yet -- it fails +today, and that failure is the audit finding the record has to absorb first. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 5: Run the audit and record the findings + +**Files:** +- Create: `.agents/specs/live-state-audit-2026-08-06.md` + +**Interfaces:** +- Consumes: `scripts/audit-live-rows.py --json`. +- Produces: the findings artifact that Task 6 cites as justification for every correction. + +**No matrix is edited in this task.** Findings land first, corrections second, so the reasoning is reviewable independently of the churn. + +- [ ] **Step 1: Refresh remotes and capture the audit** + +```bash +git fetch -q origin +python3 scripts/audit-live-rows.py --json > /tmp/audit.json +python3 scripts/audit-live-rows.py > /tmp/audit.md +tail -3 /tmp/audit.md +``` + +- [ ] **Step 2: Summarise the verdict distribution** + +```bash +python3 -c " +import json, collections +records = json.load(open('/tmp/audit.json')) +print('ACTIVE verdicts:', collections.Counter(r['verdict'] for r in records if r['state']=='ACTIVE')) +print('PARTIAL flagged:', sum(1 for r in records if r['flag'])) +print('by matrix:', collections.Counter(r['path'] for r in records if r['verdict']=='ABANDONED')) +" +``` + +- [ ] **Step 3: Hand-verify a sample before trusting the tool** + +Pick three rows the tool called `ABANDONED` and one it called `IN-FLIGHT`. For each, run: + +```bash +git log --oneline --all --fixed-strings --grep="" | head -5 +git branch -a --list "*row/" +``` + +Confirm the tool's verdict matches what you see. A classifier that is wrong on a sample is wrong on all 49 — fix it and re-run rather than proceeding. Record the sample and its outcome in the artifact. + +- [ ] **Step 4: Write the findings artifact** + +Create `.agents/specs/live-state-audit-2026-08-06.md` with these sections: + +- **Scope** — the 160 live rows on `origin/main` @ ``; what the audit does and does not decide. +- **Method** — `scripts/audit-live-rows.py`, the classification rules verbatim, and the hand-verified sample from Step 3 with its result. +- **Findings** — the full report table from `/tmp/audit.md`, plus the verdict distribution from Step 2. +- **Proposed corrections** — one line per row needing a change, with its target state and the contract obligation that target carries. Apply the legality rule from Global Constraints: an abandoned `ACTIVE` row goes to `READY` if it has a real spec link, otherwise to `INVENTORIED`. +- **Rows left alone** — every `IN-FLIGHT` row, named, so the next reader can see the audit considered and kept them. +- **Risks/decisions** — every verdict the tool could not decide, and the human call made. + +- [ ] **Step 5: Run preflight and commit** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add .agents/specs/live-state-audit-2026-08-06.md +git commit -F - <<'EOF' +record(audit): live-state audit findings, no corrections applied yet (P0 step 5) + +Findings land before corrections so the reasoning is reviewable independently +of the churn. Includes the hand-verified sample that validates the classifier. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 6: Apply the corrections, one matrix per commit + +**Files:** +- Modify: `.agents/engine-matrix.md`, `.agents/model-matrix.md`, `.agents/kernel-matrix.md`, `.agents/quantization-matrix.md`, `.agents/backend-matrix.md`, `.agents/feature-matrix.md`, `.agents/sglang-matrix.md` (only those with corrections) +- Modify: `.agents/roadmap_v1.md` (only if a corrected row has a portfolio row) +- Modify: `.agents/state.md`, `.agents/NOW.md`, `docs/STATUS.md` + +**Interfaces:** +- Consumes: the **Proposed corrections** section of `.agents/specs/live-state-audit-2026-08-06.md`. +- Produces: matrices whose live states are true, so P2 can mint issues from a corrected record. + +**One commit per matrix.** A 49-row single commit is unreviewable, and a bad transition in one matrix should be revertible without losing the others. + +- [ ] **Step 1: Correct the first matrix** + +Work one matrix at a time, starting with the one holding the most corrections. For each row in the artifact's corrections list, edit **only** the `State` and `Owner` cells. Do not touch `Our code`, `Tests/evidence`, `Upstream` or `Spike/spec` — those are durable anchors and are not what this audit is about. + +Apply the legality rule: `READY` if the row has a real spec link, otherwise `INVENTORIED`. Clear the `Owner` cell to `-` for any row leaving `ACTIVE`. + +- [ ] **Step 2: Verify the record still validates** + +Run: `python3 scripts/check-agent-record.py; echo "EXIT=$?"` +Expected: `EXIT=0`. + +If it fails with a spec or evidence-anchor complaint, the target state was illegal for that row — re-read the legality rule and pick the correct target. **Never** weaken the checker or strip an anchor to make the transition pass. + +- [ ] **Step 3: Confirm the audit agrees** + +Run: `python3 scripts/audit-live-rows.py --json | python3 -c " +import json,sys +records=json.load(sys.stdin) +print('remaining abandoned ACTIVE:', sum(1 for r in records if r['verdict']=='ABANDONED')) +"` +Expected: the count has dropped by exactly the number of rows corrected in this matrix. + +- [ ] **Step 4: Run preflight and commit this matrix** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add .agents/-matrix.md +git commit -F - <<'EOF' +record(): live-state audit corrections — N rows off stale ACTIVE (P0 step 6) + +Evidence: .agents/specs/live-state-audit-2026-08-06.md. Only State and Owner +cells move; durable anchors are untouched. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +- [ ] **Step 5: Repeat Steps 1–4 for each remaining matrix with corrections** + +- [ ] **Step 6: Update the roadmap, state log and public status** + +The record obligation is that the roadmap portfolio row and its owning area matrix row move in the **same change** as the state they describe. If any corrected row has a portfolio row in `.agents/roadmap_v1.md`, update it now. + +Append one entry to `.agents/state.md` **below** the `` marker, carrying a `` anchor on the line after its heading. Refresh `.agents/NOW.md` in the same commit (the freshness coupling is CI-gated) and update `docs/STATUS.md`. + +- [ ] **Step 7: Verify chronology and doc obligations, then commit** + +```bash +python3 scripts/check-state-order.py; echo "state-order EXIT=$?" +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add .agents/roadmap_v1.md .agents/state.md .agents/NOW.md docs/STATUS.md +git commit -F - <<'EOF' +record(state): live-state audit checkpoint — the ACTIVE claim set is now true + +49 rows claimed ACTIVE simultaneously; the audit reconciled them against +branches and commits. Portfolio, state log, NOW and STATUS move together. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 7: Turn the audit into a gate + +**Files:** +- Modify: `scripts/agent-preflight.sh:50-63` (suite list) and its gate list +- Modify: `.github/workflows/ci.yml:42-46` +- Test: `tests/scripts/test_audit_live_rows.py` + +**Interfaces:** +- Consumes: a corrected record where no `ACTIVE` row classifies `ABANDONED`. +- Produces: a standing gate, so the rot cannot silently return before P1–P5 land. + +- [ ] **Step 1: Write the failing mutation test** + +Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: + +```python +class GateWiringTests(unittest.TestCase): + def test_preflight_runs_the_audit_suite(self): + text = (ROOT / "scripts/agent-preflight.sh").read_text(encoding="utf-8") + self.assertIn("test_audit_live_rows", text) + self.assertIn("audit-live-rows.py", text) + + def test_ci_runs_the_gate_and_its_suite(self): + text = (ROOT / ".github/workflows/ci.yml").read_text(encoding="utf-8") + self.assertIn("scripts/audit-live-rows.py --check", text) + self.assertIn("tests/scripts/test_audit_live_rows.py", text) + + def test_shipped_record_has_no_abandoned_active_row(self): + records = audit.audit() + stale = [r["id"] for r in records if r["verdict"] == "ABANDONED"] + self.assertEqual(stale, [], f"stale ACTIVE rows remain: {stale}") +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: FAIL on `test_preflight_runs_the_audit_suite` and `test_ci_runs_the_gate_and_its_suite`. + +`test_shipped_record_has_no_abandoned_active_row` must **already pass** — Task 6 corrected the record. If it fails, Task 6 is incomplete; finish it before wiring the gate. Never wire a gate around an unrepaired record. + +- [ ] **Step 3: Wire preflight** + +In `scripts/agent-preflight.sh`, add `test_audit_live_rows` to the suite list at lines 50–63 (after `test_check_now_current`), and add the gate itself alongside the other checkers: + +```sh +run audit-live-rows python3 scripts/audit-live-rows.py --check +``` + +- [ ] **Step 4: Wire CI** + +In `.github/workflows/ci.yml`, extend the record job (lines 42–46): + +```yaml + - name: Live-state rows are reconciled against Git reality + run: | + git fetch -q origin main + python3 scripts/audit-live-rows.py --check + python3 tests/scripts/test_audit_live_rows.py +``` + +`git fetch` is required because the classifier compares against `origin/main`, and Actions checkouts are shallow by default. + +- [ ] **Step 5: Run test to verify it passes** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: PASS, 23 tests. + +- [ ] **Step 6: Verify the whole gate is green** + +```bash +python3 scripts/audit-live-rows.py --check; echo "gate EXIT=$?" +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "preflight EXIT=$?" +``` +Expected: both `EXIT=0`. + +- [ ] **Step 7: Commit** + +```bash +git add scripts/agent-preflight.sh .github/workflows/ci.yml tests/scripts/test_audit_live_rows.py +git commit -F - <<'EOF' +gate(audit): ACTIVE rows stay reconciled with Git reality (P0 step 7) + +Wired only after the record was repaired, so the gate never had to be relaxed +to pass. Keeps the 49-row rot from returning before P1-P5 land. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +## Done when + +- `python3 scripts/audit-live-rows.py --check` exits 0 on a record where every `ACTIVE` row has real Git evidence behind it. +- `.agents/specs/live-state-audit-2026-08-06.md` justifies every correction, names every row left alone, and records the hand-verified classifier sample. +- `bash scripts/agent-preflight.sh` exits 0, with the new suite and gate registered. +- CI runs the gate and its mutation suite. +- P2's backfill can mint ~160 issues from a record that is true. + +## Out of scope + +Everything after P0. No labels, no milestones, no issue template, no `sync-rows.py`, no `check-issue-record.py`, no `State`/`Owner` column removal, no `coordination.md` retirement, no prose changes to `AGENTS.md`. This plan leaves the file-based protocol fully intact and merely truthful — which is why it is worth landing even if the rest of the migration never happens. From 37c189284e61cffbd6df6a3096301ac4a0c0945a Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:11:08 +0000 Subject: [PATCH 03/34] tools(audit): load live matrix rows and gather Git evidence (P0 step 1) Reuses the row parser in check-agent-record.py rather than reimplementing it, so the audit and the gate can never disagree about what a row is. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 95 +++++++++++++++++++++++++++ tests/scripts/test_audit_live_rows.py | 57 ++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100755 scripts/audit-live-rows.py create mode 100644 tests/scripts/test_audit_live_rows.py diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py new file mode 100755 index 00000000..f163e598 --- /dev/null +++ b/scripts/audit-live-rows.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +"""Audit the live-state matrix rows against Git reality. (P0) + +49 rows claim ACTIVE at once, which cannot be true: a stale ACTIVE cell inside +a several-hundred-row table is invisible rot. This tool makes it visible. + +It PROPOSES and REPORTS. It never rewrites a matrix -- corrections are applied +by a human/agent in reviewable per-matrix commits, because a state transition +carries contract obligations (a spec link, evidence anchors) that only a reader +of the row can satisfy. + +Row parsing is imported from scripts/check-agent-record.py rather than +reimplemented, so the audit and the gate can never disagree about what a row is. + + scripts/audit-live-rows.py # markdown report + scripts/audit-live-rows.py --json # machine-readable + scripts/audit-live-rows.py --check # exit 1 if an ACTIVE row is abandoned +""" + +from __future__ import annotations + +import argparse +import importlib.util +import json +import re +import subprocess +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] + + +def _load(name: str, relative: str): + path = ROOT / relative + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +record = _load("agent_record", "scripts/check-agent-record.py") + +LIVE_STATES = frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}) + + +def live_rows() -> list: + """Every row in the shipped matrices whose state is in LIVE_STATES.""" + rows = [] + for path in record.MATRIX_PATHS: + errors: list[str] = [] + for row in record.parse_claim_rows(path, errors): + if row.state in LIVE_STATES: + rows.append(row) + return rows + + +def git(*args: str) -> str: + result = subprocess.run( + ["git", *args], cwd=ROOT, capture_output=True, text=True, check=False + ) + return result.stdout if result.returncode == 0 else "" + + +def row_branches() -> dict[str, list[str]]: + """Map row ID -> every local or remote branch named row/.""" + mapping: dict[str, list[str]] = {} + out = git("for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes") + for line in out.splitlines(): + name = line.strip() + if name.startswith("row/"): + item_id = name[len("row/") :] + elif "/row/" in name: + item_id = name.split("/row/", 1)[1] + else: + continue + mapping.setdefault(item_id, []).append(name) + return mapping + + +def main_commits(item_id: str) -> list[str]: + """Commits on origin/main whose message mentions the row ID literally.""" + out = git( + "log", "--oneline", "--fixed-strings", f"--grep={item_id}", "-n", "20", + "origin/main", + ) + return [line.strip() for line in out.splitlines() if line.strip()] + + +def unmerged(branch: str) -> list[str]: + """Commits on branch that are not yet on origin/main.""" + out = git("log", "--oneline", f"origin/main..{branch}") + return [line.strip() for line in out.splitlines() if line.strip()] diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py new file mode 100644 index 00000000..da0ccdf7 --- /dev/null +++ b/tests/scripts/test_audit_live_rows.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python3 +"""Unit and mutation checks for scripts/audit-live-rows.py. + +The audit only helps if it is honest in both directions: it must not call a +live row abandoned when work is really in flight, and it must not call an +abandoned row live because a branch name happens to exist. +""" + +from __future__ import annotations + +import importlib.util +import sys +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] + + +def _load(name: str, relative: str): + path = ROOT / relative + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +audit = _load("audit_live_rows", "scripts/audit-live-rows.py") + + +class LiveRowLoadingTests(unittest.TestCase): + def test_live_states_are_exactly_the_six(self): + self.assertEqual( + audit.LIVE_STATES, + frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}), + ) + + def test_shipped_matrices_yield_only_live_rows(self): + rows = audit.live_rows() + self.assertTrue(rows, "the shipped matrices must contain live rows") + for row in rows: + self.assertIn(row.state, audit.LIVE_STATES) + + def test_every_live_state_is_represented_in_the_shipped_matrices(self): + # Guards the loader against silently dropping a whole state: if a + # header rename made one state unparseable, its count would go to + # zero while the other five still looked healthy. + rows = audit.live_rows() + present = {row.state for row in rows} + self.assertEqual(present, set(audit.LIVE_STATES)) + self.assertGreater(len(rows), 100, "the live set is ~160 rows") + + +if __name__ == "__main__": + unittest.main() From 3f6390c43d84e7e3eef7c9d312d9a73a6ce1201d Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:15:11 +0000 Subject: [PATCH 04/34] =?UTF-8?q?plan(protocol):=20correct=20the=20P0=20ce?= =?UTF-8?q?nsus=20=E2=80=94=20188=20live=20rows,=20and=202=20matrices=20we?= =?UTF-8?q?re=20invisible?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 160 baseline was an ad-hoc regex estimate, not a measurement. Measured with parse_claim_rows itself on the same base 027af9b0: 177 live rows across the 5 files in MATRIX_PATHS (ACTIVE 51, PARTIAL 60, SPIKE 43, GATING 10, BLOCKED 7, READY 6). More consequential: check-agent-record.py's MATRIX_PATHS covers only 5 of the 7 matrices. feature-matrix.md and sglang-matrix.md hold a further 11 live rows (3 ACTIVE, 8 PARTIAL) that would have become unaudited public issues in P2. The audit now defines AUDIT_MATRIX_PATHS over all 7, with a test asserting it. It deliberately does NOT widen MATRIX_PATHS itself: that governs a repo-wide CI gate, and these two files have never been held to its row contract. Total: 188 live rows, 54 claiming ACTIVE. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 57 +++++++++++++------ 1 file changed, 41 insertions(+), 16 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 40986636..10660c50 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -2,7 +2,7 @@ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. -**Goal:** Reconcile the 160 live-state matrix rows against Git reality — above all the 49 rows simultaneously claiming `ACTIVE`, which cannot all be true — so the record is truthful before any issue backfill mints ~160 public issues from it. +**Goal:** Reconcile the 188 live-state matrix rows against Git reality — above all the 54 rows simultaneously claiming `ACTIVE`, which cannot all be true — so the record is truthful before any issue backfill mints ~160 public issues from it. **Architecture:** A new reporting tool, `scripts/audit-live-rows.py`, reuses the row parser already inside `scripts/check-agent-record.py` (never reimplements it) and cross-references each live row against local/remote `row/` branches and `main` commits mentioning the ID. Classification is a **pure function** over already-gathered evidence, so it is unit-testable without Git. The tool **proposes and reports; it never rewrites a matrix.** A human/agent applies corrections per matrix in reviewable commits. Only after the record is corrected does the tool become a CI gate, so the rot cannot return. @@ -28,7 +28,15 @@ Copied from `AGENTS.md`, `.agents/coordination.md` and `.agents/specs/issue-nati - Therefore an abandoned `ACTIVE` row moves to **`READY` if it has a real spec, otherwise `INVENTORIED`** — it may not simply be blanked. - The live set is exactly: `SPIKE`, `READY`, `ACTIVE`, `GATING`, `PARTIAL`, `BLOCKED`. -**Baseline census on `origin/main` @ `027af9b0` (verified 2026-08-06):** 367 rows carry a state — `INVENTORIED` 125, `PARTIAL` 64, `ANCHOR-BACKFILL` 52, `ACTIVE` 49, `SPIKE` 24, `DONE` 22, `GATING` 11, `OUT-OF-SCOPE` 8, `BLOCKED` 6, `READY` 6. **Live total = 160.** +**Baseline census on `origin/main` @ `027af9b0`**, measured with `parse_claim_rows` itself (an earlier ad-hoc regex estimate of 160 was wrong and is superseded): + +| Source | Rows | Live rows | ACTIVE | PARTIAL | SPIKE | GATING | BLOCKED | READY | +|---|---|---|---|---|---|---|---|---| +| The 5 files in `MATRIX_PATHS` | 695 | 177 | 51 | 60 | 43 | 10 | 7 | 6 | +| `feature-matrix.md` + `sglang-matrix.md` | 19 | 11 | 3 | 8 | 0 | 0 | 0 | 0 | +| **Total across all 7 matrices** | **714** | **188** | **54** | **68** | **43** | **10** | **7** | **6** | + +**`check-agent-record.py`'s `MATRIX_PATHS` covers only 5 of the 7 matrices.** The audit must cover all 7: `feature-matrix.md` and `sglang-matrix.md` hold 11 live rows that would otherwise become unaudited public issues in P2. The audit therefore defines its own `AUDIT_MATRIX_PATHS`. It does **not** widen `MATRIX_PATHS` itself — that would change what the repo-wide CI gate validates and could turn CI red on rows never held to the row contract. The DRY constraint is about the *parser*, which is still imported and never reimplemented. --- @@ -54,7 +62,7 @@ Copied from `AGENTS.md`, `.agents/coordination.md` and `.agents/specs/issue-nati **Interfaces:** - Consumes: `scripts/check-agent-record.py` — `ClaimRow` (frozen dataclass with fields `path: Path`, `line_no: int`, `item_id: str`, `state: str`, `header: tuple[str, ...]`, `cells: tuple[str, ...]`, `raw: str`, and method `field(name: str) -> str`); `parse_claim_rows(path: Path, errors: list[str]) -> list[ClaimRow]`; `MATRIX_PATHS: list[Path]`. -- Produces: `LIVE_STATES: frozenset[str]`; `live_rows() -> list[ClaimRow]`; `row_branches() -> dict[str, list[str]]`; `main_commits(item_id: str) -> list[str]`; `unmerged(branch: str) -> list[str]`. +- Produces: `LIVE_STATES: frozenset[str]`; `AUDIT_MATRIX_PATHS: list[Path]` (= `record.MATRIX_PATHS` plus `.agents/feature-matrix.md` and `.agents/sglang-matrix.md`); `live_rows() -> list[ClaimRow]`; `row_branches() -> dict[str, list[str]]`; `main_commits(item_id: str) -> list[str]`; `unmerged(branch: str) -> list[str]`. - [ ] **Step 1: Write the failing test** @@ -100,6 +108,12 @@ class LiveRowLoadingTests(unittest.TestCase): frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}), ) + def test_all_seven_matrices_are_audited(self): + names = {path.name for path in audit.AUDIT_MATRIX_PATHS} + self.assertIn("feature-matrix.md", names) + self.assertIn("sglang-matrix.md", names) + self.assertEqual(len(names), 7) + def test_shipped_matrices_yield_only_live_rows(self): rows = audit.live_rows() self.assertTrue(rows, "the shipped matrices must contain live rows") @@ -113,7 +127,7 @@ class LiveRowLoadingTests(unittest.TestCase): rows = audit.live_rows() present = {row.state for row in rows} self.assertEqual(present, set(audit.LIVE_STATES)) - self.assertGreater(len(rows), 100, "the live set is ~160 rows") + self.assertGreater(len(rows), 100, "the live set is ~188 rows") if __name__ == "__main__": @@ -177,11 +191,22 @@ record = _load("agent_record", "scripts/check-agent-record.py") LIVE_STATES = frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}) +# check-agent-record.py's MATRIX_PATHS omits feature-matrix.md and +# sglang-matrix.md, which together hold 11 live rows. The audit covers all +# seven matrices so no live row escapes it, but deliberately does NOT widen +# MATRIX_PATHS itself: that governs a repo-wide CI gate whose row contract +# these two files have never been held to. +AUDIT_MATRIX_PATHS = [ + *record.MATRIX_PATHS, + record.AGENTS / "feature-matrix.md", + record.AGENTS / "sglang-matrix.md", +] + def live_rows() -> list: """Every row in the shipped matrices whose state is in LIVE_STATES.""" rows = [] - for path in record.MATRIX_PATHS: + for path in AUDIT_MATRIX_PATHS: errors: list[str] = [] for row in record.parse_claim_rows(path, errors): if row.state in LIVE_STATES: @@ -232,14 +257,14 @@ Make it executable: `chmod +x scripts/audit-live-rows.py` - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 3 tests. +Expected: PASS, 4 tests. - [ ] **Step 5: Verify the loader sees the real census** Run: `python3 -c "import importlib.util,sys; s=importlib.util.spec_from_file_location('a','scripts/audit-live-rows.py'); m=importlib.util.module_from_spec(s); sys.modules['a']=m; s.loader.exec_module(m); rows=m.live_rows(); import collections; print(len(rows), collections.Counter(r.state for r in rows))"` -Expected: `160` total, with `ACTIVE` = 49, `PARTIAL` = 64, `SPIKE` = 24, `GATING` = 11, `BLOCKED` = 6, `READY` = 6. +Expected: `188` total, with `ACTIVE` = 54, `PARTIAL` = 68, `SPIKE` = 43, `GATING` = 10, `BLOCKED` = 7, `READY` = 6. -If the numbers differ, do **not** adjust the test to match — `main` has moved. Re-read the current census, record the new baseline in the commit message, and continue. +If the numbers differ, do **not** adjust the test to match — `main` has moved. Re-read the current census, record the new baseline in the report, and continue. - [ ] **Step 6: Run preflight and commit** @@ -371,7 +396,7 @@ def classify_active( - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 9 tests. +Expected: PASS, 10 tests. - [ ] **Step 5: Run preflight and commit** @@ -483,7 +508,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 14 tests. +Expected: PASS, 15 tests. - [ ] **Step 5: Run preflight and commit** @@ -682,15 +707,15 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 20 tests. +Expected: PASS, 21 tests. - [ ] **Step 5: Smoke-test the CLI against the real repository** Run: `git fetch -q origin && python3 scripts/audit-live-rows.py | tail -5` -Expected: a summary line reading `160 live rows; N abandoned ACTIVE; M PARTIAL rows to review.` +Expected: a summary line reading `188 live rows; N abandoned ACTIVE; M PARTIAL rows to review.` Run: `python3 scripts/audit-live-rows.py --json | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"` -Expected: `160`. +Expected: `188`. **Note:** `--check` is expected to exit 1 right now. That is the finding, not a bug. Do not wire it into preflight or CI until Task 7. @@ -759,7 +784,7 @@ Confirm the tool's verdict matches what you see. A classifier that is wrong on a Create `.agents/specs/live-state-audit-2026-08-06.md` with these sections: -- **Scope** — the 160 live rows on `origin/main` @ ``; what the audit does and does not decide. +- **Scope** — the 188 live rows on `origin/main` @ ``; what the audit does and does not decide. - **Method** — `scripts/audit-live-rows.py`, the classification rules verbatim, and the hand-verified sample from Step 3 with its result. - **Findings** — the full report table from `/tmp/audit.md`, plus the verdict distribution from Step 2. - **Proposed corrections** — one line per row needing a change, with its target state and the contract obligation that target carries. Apply the legality rule from Global Constraints: an abandoned `ACTIVE` row goes to `READY` if it has a real spec link, otherwise to `INVENTORIED`. @@ -927,7 +952,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 23 tests. +Expected: PASS, 24 tests. - [ ] **Step 6: Verify the whole gate is green** @@ -960,7 +985,7 @@ EOF - `.agents/specs/live-state-audit-2026-08-06.md` justifies every correction, names every row left alone, and records the hand-verified classifier sample. - `bash scripts/agent-preflight.sh` exits 0, with the new suite and gate registered. - CI runs the gate and its mutation suite. -- P2's backfill can mint ~160 issues from a record that is true. +- P2's backfill can mint ~188 issues from a record that is true. ## Out of scope From fb9c1c9eb73ac95538260dc601d0316f89066206 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:17:06 +0000 Subject: [PATCH 05/34] =?UTF-8?q?spec(protocol):=20correct=20the=20census?= =?UTF-8?q?=20=E2=80=94=20714=20rows,=20188=20live,=202=20matrices=20were?= =?UTF-8?q?=20invisible?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Measured with parse_claim_rows itself (zero parse errors across all 7 matrices) rather than the ad-hoc regex that produced the earlier 393/367/160 figures. 714 ID'd rows: INVENTORIED 449, PARTIAL 68, ANCHOR-BACKFILL 57, ACTIVE 54, SPIKE 43, DONE 20, GATING 10, BLOCKED 7, READY 6. Live total 188, so the backfill mints ~188 issues, not ~160. Also records the coverage caveat that P0 must carry: MATRIX_PATHS covers 5 of the 7 matrices, and feature-matrix.md + sglang-matrix.md hold 11 live rows it never sees. Auditing and backfilling all seven is now explicit. 54 rows claim ACTIVE simultaneously. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .agents/specs/issue-native-tracking.md | 37 +++++++++++++++----------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/.agents/specs/issue-native-tracking.md b/.agents/specs/issue-native-tracking.md index 7279cb94..a8987817 100644 --- a/.agents/specs/issue-native-tracking.md +++ b/.agents/specs/issue-native-tracking.md @@ -21,9 +21,11 @@ ordering) and how to do it. ## Our baseline — why this exists -The record is 30 files and ~52k lines under `.agents/`, plus 393 ID'd rows across -seven area matrices, of which 367 carry a recognised lifecycle state. Two -properties of it are in tension: +The record is 30 files and ~52k lines under `.agents/`, plus **714 ID'd rows** +across seven area matrices, all of which carry a recognised lifecycle state (the +count comes from `parse_claim_rows` in `check-agent-record.py`, with zero parse +errors; an earlier ad-hoc regex estimate of 393/367 was wrong and is +superseded). Two properties of it are in tension: - **Evidence** is append-only, git-provenanced, greppable and shipped with the code. This works. `benchmark-record.md` exists precisely so a lever is not @@ -47,7 +49,7 @@ properties of it are in tension: Every one of those is the same bug: **one fact stored in two writable places, reconciled by a three-way merge.** -A second, quieter symptom: **49 rows are simultaneously marked `ACTIVE`.** That +A second, quieter symptom: **54 rows are simultaneously marked `ACTIVE`.** That cannot be true. A stale `ACTIVE` cell inside a several-hundred-row table is invisible rot; an issue with no assignee and no linked PR is visibly stale. @@ -59,21 +61,26 @@ mapping already exists by accident. | Bucket | Count | Gets an issue? | |---|---|---| -| `ACTIVE` 49, `SPIKE` 24, `GATING` 11, `BLOCKED` 6, `READY` 6 | **96** | yes — live work | -| `PARTIAL` | **64** | yes — a known open gap is roadmap content | -| `ANCHOR-BACKFILL` | 52 | not at backfill; on transition | -| `INVENTORIED` 125, `DONE` 22, `OUT-OF-SCOPE` 8 | 155 | no — inventory and history | +| `ACTIVE` 54, `SPIKE` 43, `GATING` 10, `BLOCKED` 7, `READY` 6 | **120** | yes — live work | +| `PARTIAL` | **68** | yes — a known open gap is roadmap content | +| `ANCHOR-BACKFILL` | 57 | not at backfill; on transition | +| `INVENTORIED` 449, `DONE` 20 | 469 | no — inventory and history | -**~160 issues at backfill** (user-directed 2026-08-06: include `PARTIAL`). A +**~188 issues at backfill** (user-directed 2026-08-06: include `PARTIAL`). A `PARTIAL` row is a capability with working modes and explicitly missing ones — on a public roadmap that is exactly the content outsiders need, and leaving the -64 of them invisible would undersell what is genuinely open. `ANCHOR-BACKFILL` +68 of them invisible would undersell what is genuinely open. `ANCHOR-BACKFILL` is evidence debt rather than a capability gap, so it stays file-side until someone picks it up. -A wholesale conversion would create 393 issues of mostly dead inventory. The +A wholesale conversion would create 714 issues, 449 of them dead inventory. The tracker is the **live window**; the matrices remain the **permanent inventory**. +**Coverage caveat carried into P0.** `check-agent-record.py`'s `MATRIX_PATHS` +covers only 5 of the 7 matrices; `feature-matrix.md` and `sglang-matrix.md` hold +11 live rows it never sees. The audit and the backfill must cover all seven, or +those rows become unaudited public issues. + ## Design ### The principle @@ -227,18 +234,18 @@ P2 backfill is verified.** | Phase | Work | |---|---| -| P0 | **The live-state audit** — reconcile the 49 `ACTIVE` rows against branches, PRs and commits → in-flight / landed / abandoned; confirm each of the 64 `PARTIAL` rows names its missing modes; correct the matrices. Pure file-side, no issue machinery | +| P0 | **The live-state audit** — reconcile the 54 `ACTIVE` rows against branches and commits → in-flight / landed / abandoned; confirm each of the 68 `PARTIAL` rows names its missing modes; correct the matrices, across all 7 matrices. Pure file-side, no issue machinery | | P1 | Label and milestone schema, `.github/ISSUE_TEMPLATE/row.yml`, `scripts/sync-rows.py`, `scripts/check-issue-record.py` (skip-when-offline, required-in-CI) | -| P2 | Idempotent backfill of the ~160 live rows into issues; dry-run first | +| P2 | Idempotent backfill of the ~188 live rows into issues; dry-run first | | P3 | Strip `State`/`Owner` from the seven matrices, add `Issue`; update `check-agent-record.py` **and its mutation suite** | | P4 | `agent-role.py claim` assigns instead of writing a row; `coordination.md` claim table retired to `completed/`; `NOW.md` generated; rewire `claim-view.py`, `ready-for-helper.py`, `check-now-current.py` | | P5 | Prose: `AGENTS.md` T0, `.agents/workflow.md`, `.agents/directives.md` | **P0 lands first and stands alone** (user-directed 2026-08-06). It is an audit, -not bookkeeping: it is the first time the 49 `ACTIVE` claims are tested against +not bookkeeping: it is the first time the 54 `ACTIVE` claims are tested against reality. Its value does not depend on the migration — a truthful matrix is worth having even if every later phase stalls — and running it first means the backfill -mints ~160 issues from a corrected record rather than publishing the rot. Because +mints ~188 issues from a corrected record rather than publishing the rot. Because `PARTIAL` rows now become public issues, P0 also checks that each states its missing modes, which the row contract already requires; a vague `PARTIAL` row would otherwise become a vague public issue. From 8601e9ba82ce4cbb83e9c749d20312955989a22c Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:17:20 +0000 Subject: [PATCH 06/34] tools(audit): cover all seven matrices, not the five MATRIX_PATHS gates feature-matrix.md and sglang-matrix.md sit outside check-agent-record.py's MATRIX_PATHS, hiding 11 live rows (3 ACTIVE, 8 PARTIAL) from the audit. Cover them via AUDIT_MATRIX_PATHS instead of widening MATRIX_PATHS itself: that list governs a repo-wide CI gate whose row contract these two files have never been held to. The parser stays imported, never reimplemented. Live census over all seven: 188 rows -- ACTIVE 54, PARTIAL 68, SPIKE 43, GATING 10, BLOCKED 7, READY 6. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 13 ++++++++++++- tests/scripts/test_audit_live_rows.py | 8 +++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index f163e598..25b1ae0e 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -45,11 +45,22 @@ def _load(name: str, relative: str): LIVE_STATES = frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}) +# check-agent-record.py's MATRIX_PATHS omits feature-matrix.md and +# sglang-matrix.md, which together hold 11 live rows. The audit covers all +# seven matrices so no live row escapes it, but deliberately does NOT widen +# MATRIX_PATHS itself: that governs a repo-wide CI gate whose row contract +# these two files have never been held to. +AUDIT_MATRIX_PATHS = [ + *record.MATRIX_PATHS, + record.AGENTS / "feature-matrix.md", + record.AGENTS / "sglang-matrix.md", +] + def live_rows() -> list: """Every row in the shipped matrices whose state is in LIVE_STATES.""" rows = [] - for path in record.MATRIX_PATHS: + for path in AUDIT_MATRIX_PATHS: errors: list[str] = [] for row in record.parse_claim_rows(path, errors): if row.state in LIVE_STATES: diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index da0ccdf7..ea93d5fd 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -37,6 +37,12 @@ def test_live_states_are_exactly_the_six(self): frozenset({"SPIKE", "READY", "ACTIVE", "GATING", "PARTIAL", "BLOCKED"}), ) + def test_all_seven_matrices_are_audited(self): + names = {path.name for path in audit.AUDIT_MATRIX_PATHS} + self.assertIn("feature-matrix.md", names) + self.assertIn("sglang-matrix.md", names) + self.assertEqual(len(names), 7) + def test_shipped_matrices_yield_only_live_rows(self): rows = audit.live_rows() self.assertTrue(rows, "the shipped matrices must contain live rows") @@ -50,7 +56,7 @@ def test_every_live_state_is_represented_in_the_shipped_matrices(self): rows = audit.live_rows() present = {row.state for row in rows} self.assertEqual(present, set(audit.LIVE_STATES)) - self.assertGreater(len(rows), 100, "the live set is ~160 rows") + self.assertGreater(len(rows), 100, "the live set is ~188 rows") if __name__ == "__main__": From e26535e60f2b932f47c66a9ef5f5b3fc096122a7 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:26:35 +0000 Subject: [PATCH 07/34] plan(protocol): repair 4 review findings in the P0 tool design Task 1's review found the plan's own code was wrong in three places where the failure mode is silent, plus a test that did not test its commit. 1. main_commits used --fixed-strings, an UNANCHORED substring match. 55 live ID pairs are prefixes of longer ones (MODEL-MM of seven MODEL-MM-* rows, LOAD-SAFETENSORS of LOAD-SAFETENSORS-DIRECT-DENSE). The classifier calls any commit LANDED, so an abandoned row would report as finished -- the exact false negative the tool exists to prevent. Now anchored via a pure id_grep_pattern() with a collision test. 2. live_rows discarded the parse-error sink. parse_claim_rows DROPS a row it cannot parse, so a malformed row would vanish from a census whose point is completeness -- worst on the two matrices no CI gate parses. Sink surfaced; audit() aborts on any error. 3. git() maps every failure to "", indistinguishable from "no evidence". An unfetched origin/main would make every row look abandoned and propose downgrading all 54 ACTIVE rows. require_origin_main() now fails loudly. 4. The seventh-matrix test asserted a filename was in a list, which passes even if feature-matrix.md yields zero rows. Now asserts it yields live rows. Also carries the duplicate-ID discovery the widened coverage surfaced: BACKEND-CUDA-SM121 and BACKEND-CPU are PARTIAL in BOTH backend-matrix.md and feature-matrix.md, so 188 live rows hold only 186 unique IDs, and check-agent-record.py has never seen it because it only walks MATRIX_PATHS. Task 4 reports duplicates; Task 5 must settle ownership before any backfill. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 129 +++++++++++++++--- 1 file changed, 113 insertions(+), 16 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 10660c50..31515189 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -62,7 +62,7 @@ Copied from `AGENTS.md`, `.agents/coordination.md` and `.agents/specs/issue-nati **Interfaces:** - Consumes: `scripts/check-agent-record.py` — `ClaimRow` (frozen dataclass with fields `path: Path`, `line_no: int`, `item_id: str`, `state: str`, `header: tuple[str, ...]`, `cells: tuple[str, ...]`, `raw: str`, and method `field(name: str) -> str`); `parse_claim_rows(path: Path, errors: list[str]) -> list[ClaimRow]`; `MATRIX_PATHS: list[Path]`. -- Produces: `LIVE_STATES: frozenset[str]`; `AUDIT_MATRIX_PATHS: list[Path]` (= `record.MATRIX_PATHS` plus `.agents/feature-matrix.md` and `.agents/sglang-matrix.md`); `live_rows() -> list[ClaimRow]`; `row_branches() -> dict[str, list[str]]`; `main_commits(item_id: str) -> list[str]`; `unmerged(branch: str) -> list[str]`. +- Produces: `LIVE_STATES: frozenset[str]`; `AUDIT_MATRIX_PATHS: list[Path]` (= `record.MATRIX_PATHS` plus `.agents/feature-matrix.md` and `.agents/sglang-matrix.md`); `live_rows(errors: list[str] | None = None) -> list[record.ClaimRow]`; `row_branches() -> dict[str, list[str]]`; `main_commits(item_id: str) -> list[str]` (**anchored** on ID boundaries); `unmerged(branch: str) -> list[str]`; `require_origin_main() -> None`. - [ ] **Step 1: Write the failing test** @@ -80,6 +80,7 @@ abandoned row live because a branch name happens to exist. from __future__ import annotations import importlib.util +import re import sys import unittest from pathlib import Path @@ -114,6 +115,21 @@ class LiveRowLoadingTests(unittest.TestCase): self.assertIn("sglang-matrix.md", names) self.assertEqual(len(names), 7) + def test_newly_covered_feature_matrix_actually_yields_live_rows(self): + # Asserting the path is in a list proves nothing: every other assertion + # here still passes if feature-matrix.md contributes zero rows. This is + # what the seventh-matrix commit actually bought. + rows = audit.live_rows() + self.assertTrue([r for r in rows if r.path.name == "feature-matrix.md"]) + + def test_shipped_record_parses_without_errors(self): + # parse_claim_rows DROPS a row it cannot parse. If a malformed row ever + # lands, the census silently shrinks -- so the sink must be surfaced, + # and it must be empty today. + errors: list[str] = [] + audit.live_rows(errors) + self.assertEqual(errors, []) + def test_shipped_matrices_yield_only_live_rows(self): rows = audit.live_rows() self.assertTrue(rows, "the shipped matrices must contain live rows") @@ -147,7 +163,7 @@ Create `scripts/audit-live-rows.py`: #!/usr/bin/env python3 """Audit the live-state matrix rows against Git reality. (P0) -49 rows claim ACTIVE at once, which cannot be true: a stale ACTIVE cell inside +54 rows claim ACTIVE at once, which cannot be true: a stale ACTIVE cell inside a several-hundred-row table is invisible rot. This tool makes it visible. It PROPOSES and REPORTS. It never rewrites a matrix -- corrections are applied @@ -203,12 +219,19 @@ AUDIT_MATRIX_PATHS = [ ] -def live_rows() -> list: - """Every row in the shipped matrices whose state is in LIVE_STATES.""" +def live_rows(errors: list[str] | None = None) -> list[record.ClaimRow]: + """Every row in the audited matrices whose state is in LIVE_STATES. + + Parse errors are appended to `errors` when a list is supplied. They must + not be swallowed: parse_claim_rows DROPS a row it cannot parse, so a + malformed row would vanish from a census whose whole point is + completeness -- and it bites hardest on feature-matrix.md and + sglang-matrix.md, which no CI gate parses today. + """ + sink = errors if errors is not None else [] rows = [] for path in AUDIT_MATRIX_PATHS: - errors: list[str] = [] - for row in record.parse_claim_rows(path, errors): + for row in record.parse_claim_rows(path, sink): if row.state in LIVE_STATES: rows.append(row) return rows @@ -237,15 +260,45 @@ def row_branches() -> dict[str, list[str]]: return mapping +def id_grep_pattern(item_id: str) -> str: + """POSIX-ERE pattern matching this row ID as a whole token, never a prefix.""" + return r"(^|[^A-Za-z0-9_-])" + re.escape(item_id) + r"([^A-Za-z0-9_-]|$)" + + def main_commits(item_id: str) -> list[str]: - """Commits on origin/main whose message mentions the row ID literally.""" + """Commits on origin/main whose message mentions this row ID as a whole token. + + The match is ANCHORED on ID boundaries, never a substring: 55 pairs of live + row IDs are prefixes of longer ones (MODEL-MM of seven MODEL-MM-* rows, + LOAD-SAFETENSORS of LOAD-SAFETENSORS-DIRECT-DENSE, ...). A substring match + would credit the short row with the long row's commits, and the classifier + calls any commit LANDED -- so an abandoned row would silently report as + finished, the exact false negative this tool exists to prevent. + """ out = git( - "log", "--oneline", "--fixed-strings", f"--grep={item_id}", "-n", "20", + "log", "--oneline", "-E", f"--grep={id_grep_pattern(item_id)}", "-n", "20", "origin/main", ) return [line.strip() for line in out.splitlines() if line.strip()] +def require_origin_main() -> None: + """Abort unless origin/main resolves. + + git() maps any failure to "", which downstream is indistinguishable from + "no evidence". An unfetched or missing origin/main would therefore make + EVERY row look abandoned and the audit would propose downgrading all 54 + ACTIVE rows at once. Absence of work and absence of information must never + look the same. + """ + if not git("rev-parse", "--verify", "--quiet", "origin/main").strip(): + raise SystemExit( + "origin/main does not resolve -- run `git fetch origin main` first. " + "Without it every row reports no Git evidence and this audit would " + "propose downgrading every ACTIVE row." + ) + + def unmerged(branch: str) -> list[str]: """Commits on branch that are not yet on origin/main.""" out = git("log", "--oneline", f"origin/main..{branch}") @@ -257,7 +310,7 @@ Make it executable: `chmod +x scripts/audit-live-rows.py` - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 4 tests. +Expected: PASS, 6 tests. - [ ] **Step 5: Verify the loader sees the real census** @@ -396,7 +449,7 @@ def classify_active( - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 10 tests. +Expected: PASS, 12 tests. - [ ] **Step 5: Run preflight and commit** @@ -432,6 +485,22 @@ The row contract already requires a `PARTIAL` row to make its missing modes expl Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: ```python +class IdMatchingTests(unittest.TestCase): + def test_pattern_matches_the_id_as_a_whole_token(self): + pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) + self.assertTrue(pattern.search("feat(mm): MODEL-MM decode path")) + self.assertTrue(pattern.search("MODEL-MM")) + + def test_pattern_does_not_match_a_longer_id_that_starts_with_it(self): + # 55 live ID pairs collide this way. A substring match would credit + # MODEL-MM with MODEL-MM-gemma4's commits, and the classifier calls any + # commit LANDED -- an abandoned row would report as finished. + pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) + self.assertFalse(pattern.search("feat(mm): MODEL-MM-gemma4-mm landed")) + pattern = re.compile(audit.id_grep_pattern("LOAD-SAFETENSORS")) + self.assertFalse(pattern.search("LOAD-SAFETENSORS-DIRECT-DENSE done")) + + class PartialGapTests(unittest.TestCase): def test_explicit_gap_language_is_recognised(self): for text in [ @@ -508,7 +577,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 15 tests. +Expected: PASS, 19 tests. - [ ] **Step 5: Run preflight and commit** @@ -536,7 +605,7 @@ EOF **Interfaces:** - Consumes: everything from Tasks 1–3. -- Produces: `audit() -> list[dict]` (one record per live row, keys `id`, `state`, `path`, `line`, `verdict`, `reason`, `flag`); `render_markdown(records: list[dict]) -> str`; `main(argv: list[str] | None = None) -> int`. +- Produces: `audit() -> list[dict]` (one record per live row, keys `id`, `state`, `path`, `line`, `verdict`, `reason`, `flag`, `duplicate`); `duplicate_live_ids(rows: list) -> dict[str, list[str]]`; `render_markdown(records: list[dict]) -> str`; `main(argv: list[str] | None = None) -> int`. `audit()` calls `require_origin_main()` first and aborts on any parse error. - [ ] **Step 1: Write the failing test** @@ -608,11 +677,35 @@ import argparse import json +def duplicate_live_ids(rows: list) -> dict[str, list[str]]: + """Row IDs that appear live in more than one matrix. + + BACKEND-CUDA-SM121 and BACKEND-CPU are PARTIAL in BOTH backend-matrix.md + and feature-matrix.md, so 188 live rows carry only 186 unique IDs. + check-agent-record.py's duplicate check only walks MATRIX_PATHS, so it has + never seen these. Left unresolved, the backfill would mint two issues for + one item and this audit would report each twice with identical evidence. + """ + seen: dict[str, list[str]] = {} + for row in rows: + seen.setdefault(row.item_id, []).append(f"{row.path.name}:{row.line_no}") + return {k: v for k, v in seen.items() if len(v) > 1} + + def audit() -> list[dict]: """One record per live row, with verdict (ACTIVE) and flag (PARTIAL).""" + require_origin_main() + parse_errors: list[str] = [] + rows = live_rows(parse_errors) + if parse_errors: + raise SystemExit( + "the matrices do not parse cleanly, so the census is incomplete:\n" + + "\n".join(parse_errors) + ) + duplicates = duplicate_live_ids(rows) branches_by_id = row_branches() records: list[dict] = [] - for row in live_rows(): + for row in rows: verdict = "" reason = "" flag = "" @@ -626,6 +719,7 @@ def audit() -> list[dict]: flag = "does not name its missing modes" records.append( { + "duplicate": ", ".join(duplicates.get(row.item_id, [])), "id": row.item_id, "state": row.state, "path": str(row.path.relative_to(ROOT)), @@ -691,9 +785,11 @@ def main(argv: list[str] | None = None) -> int: print(render_markdown(records)) stale = [i for i in records if i["verdict"] == "ABANDONED"] vague = [i for i in records if i["flag"]] + dupes = sorted({i["id"] for i in records if i["duplicate"]}) print( f"\n{len(records)} live rows; {len(stale)} abandoned ACTIVE; " - f"{len(vague)} PARTIAL rows to review." + f"{len(vague)} PARTIAL rows to review; " + f"{len(dupes)} IDs live in two matrices: {', '.join(dupes) or 'none'}." ) return exit_code(records, args.check) @@ -707,7 +803,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 21 tests. +Expected: PASS, 25 tests. - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -788,6 +884,7 @@ Create `.agents/specs/live-state-audit-2026-08-06.md` with these sections: - **Method** — `scripts/audit-live-rows.py`, the classification rules verbatim, and the hand-verified sample from Step 3 with its result. - **Findings** — the full report table from `/tmp/audit.md`, plus the verdict distribution from Step 2. - **Proposed corrections** — one line per row needing a change, with its target state and the contract obligation that target carries. Apply the legality rule from Global Constraints: an abandoned `ACTIVE` row goes to `READY` if it has a real spec link, otherwise to `INVENTORIED`. +- **Duplicate live IDs** — `BACKEND-CUDA-SM121` and `BACKEND-CPU` are `PARTIAL` in both `backend-matrix.md` and `feature-matrix.md`. Decide which matrix OWNS each row and what the other becomes (a non-claimable reference, a differently-keyed row, or deleted), and say why. This must be settled here: the backfill would otherwise mint two issues for one item. - **Rows left alone** — every `IN-FLIGHT` row, named, so the next reader can see the audit considered and kept them. - **Risks/decisions** — every verdict the tool could not decide, and the human call made. @@ -952,7 +1049,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 24 tests. +Expected: PASS, 28 tests. - [ ] **Step 6: Verify the whole gate is green** From 805da1600e7e60521226325f9a554b71003ba2ef Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:30:47 +0000 Subject: [PATCH 08/34] tools(audit): anchor ID matching, surface parse errors, refuse a silent CLI Four review findings, all in the direction the audit exists to prevent -- a dead row reporting as alive. Anchor main_commits on ID boundaries (id_grep_pattern, -E). 55 pairs of live row IDs are prefixes of longer ones, and the classifier calls any commit LANDED, so an abandoned MODEL-FACTORY was credited with MODEL-FACTORY-registry commits. Measured on origin/main: MODEL-FACTORY 4 hits -> 1, MODEL-MM 7 -> 5, LOAD-SAFETENSORS 4 -> 3; every excluded commit verified to mention only a longer ID, so no real evidence is lost. Give live_rows an errors sink. parse_claim_rows DROPS an unparseable row, so swallowing that list let a malformed row vanish from a census whose whole point is completeness -- worst on feature-matrix.md and sglang-matrix.md, which no CI gate parses. Add require_origin_main. git() maps every failure to "", which downstream reads as "no evidence": one unfetched ref would have proposed downgrading all 54 ACTIVE rows. Absence of work and absence of information must not look alike. Guard __main__. The file is executable and advertises --check, but the CLI lands in step 4; until then --check exited 0, the worst answer from a gate. Docstring says 54 ACTIVE, the measured figure. Census unchanged at 188. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 55 +++++++++++++++++++++---- tests/scripts/test_audit_live_rows.py | 59 +++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 7 deletions(-) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index 25b1ae0e..c4ba03f3 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 """Audit the live-state matrix rows against Git reality. (P0) -49 rows claim ACTIVE at once, which cannot be true: a stale ACTIVE cell inside +54 rows claim ACTIVE at once, which cannot be true: a stale ACTIVE cell inside a several-hundred-row table is invisible rot. This tool makes it visible. It PROPOSES and REPORTS. It never rewrites a matrix -- corrections are applied @@ -57,12 +57,19 @@ def _load(name: str, relative: str): ] -def live_rows() -> list: - """Every row in the shipped matrices whose state is in LIVE_STATES.""" +def live_rows(errors: list[str] | None = None) -> list[record.ClaimRow]: + """Every row in the audited matrices whose state is in LIVE_STATES. + + Parse errors are appended to `errors` when a list is supplied. They must + not be swallowed: parse_claim_rows DROPS a row it cannot parse, so a + malformed row would vanish from a census whose whole point is + completeness -- and it bites hardest on feature-matrix.md and + sglang-matrix.md, which no CI gate parses today. + """ + sink = errors if errors is not None else [] rows = [] for path in AUDIT_MATRIX_PATHS: - errors: list[str] = [] - for row in record.parse_claim_rows(path, errors): + for row in record.parse_claim_rows(path, sink): if row.state in LIVE_STATES: rows.append(row) return rows @@ -91,16 +98,50 @@ def row_branches() -> dict[str, list[str]]: return mapping +def id_grep_pattern(item_id: str) -> str: + """POSIX-ERE pattern matching this row ID as a whole token, never a prefix.""" + return r"(^|[^A-Za-z0-9_-])" + re.escape(item_id) + r"([^A-Za-z0-9_-]|$)" + + def main_commits(item_id: str) -> list[str]: - """Commits on origin/main whose message mentions the row ID literally.""" + """Commits on origin/main whose message mentions this row ID as a whole token. + + The match is ANCHORED on ID boundaries, never a substring: 55 pairs of live + row IDs are prefixes of longer ones (MODEL-MM of seven MODEL-MM-* rows, + LOAD-SAFETENSORS of LOAD-SAFETENSORS-DIRECT-DENSE, ...). A substring match + would credit the short row with the long row's commits, and the classifier + calls any commit LANDED -- so an abandoned row would silently report as + finished, the exact false negative this tool exists to prevent. + """ out = git( - "log", "--oneline", "--fixed-strings", f"--grep={item_id}", "-n", "20", + "log", "--oneline", "-E", f"--grep={id_grep_pattern(item_id)}", "-n", "20", "origin/main", ) return [line.strip() for line in out.splitlines() if line.strip()] +def require_origin_main() -> None: + """Abort unless origin/main resolves. + + git() maps any failure to "", which downstream is indistinguishable from + "no evidence". An unfetched or missing origin/main would therefore make + EVERY row look abandoned and the audit would propose downgrading all 54 + ACTIVE rows at once. Absence of work and absence of information must never + look the same. + """ + if not git("rev-parse", "--verify", "--quiet", "origin/main").strip(): + raise SystemExit( + "origin/main does not resolve -- run `git fetch origin main` first. " + "Without it every row reports no Git evidence and this audit would " + "propose downgrading every ACTIVE row." + ) + + def unmerged(branch: str) -> list[str]: """Commits on branch that are not yet on origin/main.""" out = git("log", "--oneline", f"origin/main..{branch}") return [line.strip() for line in out.splitlines() if line.strip()] + + +if __name__ == "__main__": + raise SystemExit("CLI arrives in P0 step 4; import this module for now") diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index ea93d5fd..af0d898d 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -9,6 +9,8 @@ from __future__ import annotations import importlib.util +import re +import subprocess import sys import unittest from pathlib import Path @@ -43,6 +45,21 @@ def test_all_seven_matrices_are_audited(self): self.assertIn("sglang-matrix.md", names) self.assertEqual(len(names), 7) + def test_newly_covered_feature_matrix_actually_yields_live_rows(self): + # Asserting the path is in a list proves nothing: every other assertion + # here still passes if feature-matrix.md contributes zero rows. This is + # what the seventh-matrix commit actually bought. + rows = audit.live_rows() + self.assertTrue([r for r in rows if r.path.name == "feature-matrix.md"]) + + def test_shipped_record_parses_without_errors(self): + # parse_claim_rows DROPS a row it cannot parse. If a malformed row ever + # lands, the census silently shrinks -- so the sink must be surfaced, + # and it must be empty today. + errors: list[str] = [] + audit.live_rows(errors) + self.assertEqual(errors, []) + def test_shipped_matrices_yield_only_live_rows(self): rows = audit.live_rows() self.assertTrue(rows, "the shipped matrices must contain live rows") @@ -59,5 +76,47 @@ def test_every_live_state_is_represented_in_the_shipped_matrices(self): self.assertGreater(len(rows), 100, "the live set is ~188 rows") +class IdGrepPatternTests(unittest.TestCase): + """The ID match must be a whole-token match, never a prefix match.""" + + def test_pattern_matches_the_id_as_a_whole_token(self): + pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) + for message in ( + "MODEL-MM", + "feat(mm): MODEL-MM decoder lands", + "closes MODEL-MM.", + "(MODEL-MM) golden captured", + ): + self.assertTrue(pattern.search(message), message) + + def test_pattern_rejects_a_longer_id_that_merely_starts_with_it(self): + # 55 pairs of live row IDs are prefixes of longer ones. A substring + # match would credit MODEL-MM with MODEL-MM-voxtral's commits, and the + # classifier calls any commit LANDED -- so an abandoned row would + # report as finished, the exact false negative this tool prevents. + pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) + for message in ( + "feat(mm): MODEL-MM-voxtral audio tower lands", + "MODEL-MM-QWEN3VL golden captured", + "record(mm): MODEL-MM_SUFFIX bookkeeping", + ): + self.assertIsNone(pattern.search(message), message) + + +class CommandLineGuardTests(unittest.TestCase): + def test_check_flag_does_not_silently_exit_zero(self): + # The file is executable and its docstring advertises --check, but the + # real CLI arrives in P0 step 4. Until then --check must NOT exit 0: + # a gate that reports success because it ignored its own flag is the + # worst possible answer. + result = subprocess.run( + [sys.executable, str(ROOT / "scripts/audit-live-rows.py"), "--check"], + capture_output=True, + text=True, + check=False, + ) + self.assertNotEqual(result.returncode, 0) + + if __name__ == "__main__": unittest.main() From fee54031191a0ac5614c5e8f96672dca98f7cd25 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:33:34 +0000 Subject: [PATCH 09/34] plan(protocol): put the anchoring tests in Task 1, where they belong MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit They were inserted into Task 3's test block by mistake, so regenerating Task 1's brief dropped them — the implementer noticed the orphaned `import re` and wrote them anyway rather than shipping the round's central correctness fix untested. Reconciled to what actually shipped, so a later brief cannot silently delete the anchoring coverage. Also records CommandLineGuardTests as transitional: Task 4 lands the real CLI and must delete it rather than leaving both. Counts: Task 1 now 9. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 69 +++++++++++++------ 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 31515189..26dbc28b 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -81,6 +81,7 @@ from __future__ import annotations import importlib.util import re +import subprocess import sys import unittest from pathlib import Path @@ -146,10 +147,54 @@ class LiveRowLoadingTests(unittest.TestCase): self.assertGreater(len(rows), 100, "the live set is ~188 rows") +class IdGrepPatternTests(unittest.TestCase): + """The ID match must be a whole-token match, never a prefix match.""" + + def test_pattern_matches_the_id_as_a_whole_token(self): + pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) + for message in ( + "MODEL-MM", + "feat(mm): MODEL-MM decoder lands", + "closes MODEL-MM.", + "(MODEL-MM) golden captured", + ): + self.assertTrue(pattern.search(message), message) + + def test_pattern_rejects_a_longer_id_that_merely_starts_with_it(self): + # 55 pairs of live row IDs are prefixes of longer ones. A substring + # match would credit MODEL-MM with MODEL-MM-voxtral's commits, and the + # classifier calls any commit LANDED -- so an abandoned row would + # report as finished, the exact false negative this tool prevents. + pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) + for message in ( + "feat(mm): MODEL-MM-voxtral audio tower lands", + "MODEL-MM-QWEN3VL golden captured", + "record(mm): MODEL-MM_SUFFIX bookkeeping", + ): + self.assertIsNone(pattern.search(message), message) + + +class CommandLineGuardTests(unittest.TestCase): + def test_check_flag_does_not_silently_exit_zero(self): + # The file is executable and its docstring advertises --check, but the + # real CLI arrives in P0 step 4. Until then --check must NOT exit 0: + # a gate that reports success because it ignored its own flag is the + # worst possible answer. + result = subprocess.run( + [sys.executable, str(ROOT / "scripts/audit-live-rows.py"), "--check"], + capture_output=True, + text=True, + check=False, + ) + self.assertNotEqual(result.returncode, 0) + + if __name__ == "__main__": unittest.main() ``` +**`CommandLineGuardTests` is transitional.** Task 4 lands the real CLI and replaces it with the `exit_code` tests — delete it there, do not leave both. + - [ ] **Step 2: Run test to verify it fails** Run: `python3 tests/scripts/test_audit_live_rows.py -v` @@ -310,7 +355,7 @@ Make it executable: `chmod +x scripts/audit-live-rows.py` - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 6 tests. +Expected: PASS, 9 tests. - [ ] **Step 5: Verify the loader sees the real census** @@ -449,7 +494,7 @@ def classify_active( - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 12 tests. +Expected: PASS, 15 tests. - [ ] **Step 5: Run preflight and commit** @@ -485,22 +530,6 @@ The row contract already requires a `PARTIAL` row to make its missing modes expl Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: ```python -class IdMatchingTests(unittest.TestCase): - def test_pattern_matches_the_id_as_a_whole_token(self): - pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) - self.assertTrue(pattern.search("feat(mm): MODEL-MM decode path")) - self.assertTrue(pattern.search("MODEL-MM")) - - def test_pattern_does_not_match_a_longer_id_that_starts_with_it(self): - # 55 live ID pairs collide this way. A substring match would credit - # MODEL-MM with MODEL-MM-gemma4's commits, and the classifier calls any - # commit LANDED -- an abandoned row would report as finished. - pattern = re.compile(audit.id_grep_pattern("MODEL-MM")) - self.assertFalse(pattern.search("feat(mm): MODEL-MM-gemma4-mm landed")) - pattern = re.compile(audit.id_grep_pattern("LOAD-SAFETENSORS")) - self.assertFalse(pattern.search("LOAD-SAFETENSORS-DIRECT-DENSE done")) - - class PartialGapTests(unittest.TestCase): def test_explicit_gap_language_is_recognised(self): for text in [ @@ -577,7 +606,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 19 tests. +Expected: PASS, 20 tests. - [ ] **Step 5: Run preflight and commit** @@ -803,7 +832,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 25 tests. +Expected: PASS, 25 tests (26 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** From 030e11847eddfa26fc5a9166ef663abbfe631067 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:42:55 +0000 Subject: [PATCH 10/34] tools(audit): pure evidence classifier for ACTIVE rows (P0 step 2) IN-FLIGHT deliberately outranks LANDED: a row can have landed groundwork and still have open follow-up, and calling that finished would steal a live claim. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 26 +++++++++++++ tests/scripts/test_audit_live_rows.py | 56 +++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index c4ba03f3..91a28871 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -143,5 +143,31 @@ def unmerged(branch: str) -> list[str]: return [line.strip() for line in out.splitlines() if line.strip()] +VERDICTS = frozenset({"IN-FLIGHT", "LANDED", "ABANDONED"}) + + +def classify_active( + branches: list[str], + unmerged_by_branch: dict[str, list[str]], + commits: list[str], +) -> tuple[str, str]: + """Classify one ACTIVE row from already-gathered evidence. + + IN-FLIGHT wins over LANDED whenever both are present: a row can have landed + groundwork and still have open follow-up work, and calling that finished + would silently steal a live claim. + """ + live_branches = [b for b in branches if unmerged_by_branch.get(b)] + if live_branches: + joined = ", ".join(sorted(live_branches)) + return "IN-FLIGHT", f"unmerged commits on {joined}" + if branches: + joined = ", ".join(sorted(branches)) + return "LANDED", f"branch {joined} exists and is fully merged into main" + if commits: + return "LANDED", f"on main: {commits[0]}" + return "ABANDONED", "no branch, no commit on main mentioning the row ID" + + if __name__ == "__main__": raise SystemExit("CLI arrives in P0 step 4; import this module for now") diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index af0d898d..70a6764d 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -118,5 +118,61 @@ def test_check_flag_does_not_silently_exit_zero(self): self.assertNotEqual(result.returncode, 0) +class ClassifierTests(unittest.TestCase): + def test_unmerged_branch_commits_mean_in_flight(self): + verdict, reason = audit.classify_active( + branches=["row/ENG-FOO"], + unmerged_by_branch={"row/ENG-FOO": ["abc1234 wip"]}, + commits=[], + ) + self.assertEqual(verdict, "IN-FLIGHT") + self.assertIn("row/ENG-FOO", reason) + + def test_fully_merged_branch_means_landed(self): + verdict, reason = audit.classify_active( + branches=["row/ENG-FOO"], + unmerged_by_branch={"row/ENG-FOO": []}, + commits=[], + ) + self.assertEqual(verdict, "LANDED") + self.assertIn("merged", reason.lower()) + + def test_main_commits_without_branch_mean_landed(self): + verdict, reason = audit.classify_active( + branches=[], + unmerged_by_branch={}, + commits=["def5678 feat(eng): ENG-FOO"], + ) + self.assertEqual(verdict, "LANDED") + self.assertIn("def5678", reason) + + def test_no_evidence_at_all_means_abandoned(self): + verdict, reason = audit.classify_active( + branches=[], unmerged_by_branch={}, commits=[] + ) + self.assertEqual(verdict, "ABANDONED") + self.assertIn("no branch", reason.lower()) + + def test_in_flight_wins_over_landed_when_both_present(self): + # A row can have landed groundwork AND active follow-up work. + # Claiming it is finished would silently steal an open claim. + verdict, _ = audit.classify_active( + branches=["row/ENG-FOO"], + unmerged_by_branch={"row/ENG-FOO": ["abc1234 wip"]}, + commits=["def5678 feat(eng): ENG-FOO groundwork"], + ) + self.assertEqual(verdict, "IN-FLIGHT") + + def test_every_verdict_is_declared(self): + for branches, by_branch, commits in [ + (["row/X"], {"row/X": ["a b"]}, []), + (["row/X"], {"row/X": []}, []), + ([], {}, ["a b"]), + ([], {}, []), + ]: + verdict, _ = audit.classify_active(branches, by_branch, commits) + self.assertIn(verdict, audit.VERDICTS) + + if __name__ == "__main__": unittest.main() From 9bdf10b9508dd7960a5883ed689e19f7d97e01b8 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:49:52 +0000 Subject: [PATCH 11/34] plan(protocol): classifier must fail loudly on an ungathered branch Task 2's review found the plan specified `unmerged_by_branch.get(b)`, which returns None for a branch that was never gathered -> falsy -> the row reports LANDED. That is a live claim reported as finished, the exact false negative the tool exists to prevent, and it contradicts the principle require_origin_main() already encodes: absence of work and absence of information must never look the same. `branches` is the authority for which keys must exist, so a missing key is a caller bug and a KeyError at the audit's boundary is the loud alternative. Also repairs two test gaps the review found: - assertIn("merged", reason.lower()) is near-vacuous because "unmerged" contains "merged", so it passed for BOTH verdicts; now "fully merged". - no test used more than one branch, so sorted() and the live-branch filter's effect on the reason text were unpinned -- deleting sorted() survived the whole suite. Adds a mixed two-branch case and a KeyError case. Counts: Task 2 now 17. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 66 +++++++++++++++++-- 1 file changed, 60 insertions(+), 6 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 26dbc28b..ce47b52f 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -416,7 +416,9 @@ class ClassifierTests(unittest.TestCase): commits=[], ) self.assertEqual(verdict, "LANDED") - self.assertIn("merged", reason.lower()) + # "unmerged" contains "merged", so a substring check on the bare word + # would pass for the IN-FLIGHT reason too. + self.assertIn("fully merged", reason) def test_main_commits_without_branch_mean_landed(self): verdict, reason = audit.classify_active( @@ -444,6 +446,27 @@ class ClassifierTests(unittest.TestCase): ) self.assertEqual(verdict, "IN-FLIGHT") + def test_reason_names_only_the_branches_with_unmerged_commits(self): + # With more than one branch, the reason must name the live one and not + # the merged one, and must be order-independent so a re-run does not + # produce a spuriously different report. + verdict, reason = audit.classify_active( + branches=["row/B-LIVE", "row/A-MERGED"], + unmerged_by_branch={"row/B-LIVE": ["abc1234 wip"], "row/A-MERGED": []}, + commits=[], + ) + self.assertEqual(verdict, "IN-FLIGHT") + self.assertIn("row/B-LIVE", reason) + self.assertNotIn("row/A-MERGED", reason) + + def test_missing_branch_key_is_a_loud_caller_bug(self): + # Silently treating an ungathered branch as merged would report a live + # claim as finished -- the exact false negative this tool prevents. + with self.assertRaises(KeyError): + audit.classify_active( + branches=["row/NEVER-GATHERED"], unmerged_by_branch={}, commits=[] + ) + def test_every_verdict_is_declared(self): for branches, by_branch, commits in [ (["row/X"], {"row/X": ["a b"]}, []), @@ -479,7 +502,12 @@ def classify_active( groundwork and still have open follow-up work, and calling that finished would silently steal a live claim. """ - live_branches = [b for b in branches if unmerged_by_branch.get(b)] + # Indexed, never .get(): `branches` is the authority for which keys must + # exist, so a missing key is a CALLER bug, not data. .get() would return + # None -> falsy -> the row reports LANDED, a live claim reported as + # finished. Absence of work and absence of information must never look the + # same; a KeyError at the audit's own boundary is the loud alternative. + live_branches = [b for b in branches if unmerged_by_branch[b]] if live_branches: joined = ", ".join(sorted(live_branches)) return "IN-FLIGHT", f"unmerged commits on {joined}" @@ -494,7 +522,7 @@ def classify_active( - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 15 tests. +Expected: PASS, 17 tests. - [ ] **Step 5: Run preflight and commit** @@ -606,7 +634,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 20 tests. +Expected: PASS, 22 tests. - [ ] **Step 5: Run preflight and commit** @@ -832,7 +860,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 25 tests (26 added minus the transitional CLI-guard test you delete here). +Expected: PASS, 27 tests (28 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -1078,7 +1106,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 28 tests. +Expected: PASS, 30 tests. - [ ] **Step 6: Verify the whole gate is green** @@ -1105,12 +1133,38 @@ EOF --- +## Branch-level obligation: the doc checkpoint + +`scripts/check-doc-checkpoint.py` requires that any commit touching `scripts/`, +`tests/` or `.agents/specs/` **also updates `docs/STATUS.md` and +`docs/BENCHMARKS.md` in the same commit**. CI enforces it **per commit** over the +PR range (`.github/workflows/ci.yml:126`), but `agent-preflight.sh` only runs it +`--staged` (line 109) — which passes vacuously once the work is already +committed. That asymmetry is why per-task commits accumulate violations while +every preflight reports green. + +**Do not add a trailing docs commit — it cannot fix earlier commits.** This +branch lands as a **squash** (the house practice: `gh pr merge` would attribute +the squash to `localai-bot`, so squashes are landed locally via `commit-tree` and +a direct push). The single squashed commit carries the `docs/STATUS.md` and +`docs/BENCHMARKS.md` updates, and satisfies the gate for the whole change. + +Verify before pushing, over the exact range that will be pushed: + +```bash +python3 scripts/check-doc-checkpoint.py --base --head HEAD +``` + +This is a real obligation, not a formality to route around: never weaken the +checker to pass it. + ## Done when - `python3 scripts/audit-live-rows.py --check` exits 0 on a record where every `ACTIVE` row has real Git evidence behind it. - `.agents/specs/live-state-audit-2026-08-06.md` justifies every correction, names every row left alone, and records the hand-verified classifier sample. - `bash scripts/agent-preflight.sh` exits 0, with the new suite and gate registered. - CI runs the gate and its mutation suite. +- The squashed commit updates `docs/STATUS.md` and `docs/BENCHMARKS.md`, and `check-doc-checkpoint.py` passes over the pushed range. - P2's backfill can mint ~188 issues from a record that is true. ## Out of scope From 732fdd62fa040de87cbdca37d7c80e3ae533e5e7 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:52:40 +0000 Subject: [PATCH 12/34] tools(audit): index unmerged_by_branch, pin the multi-branch reason paths A missing key is a CALLER bug, not evidence: .get() returned None -> falsy -> the branch dropped out of live_branches and the row reported LANDED, a live claim reported as finished. Indexing raises at the audit's own boundary instead, so absence of information can never pass for absence of work. Tests: KeyError on an ungathered branch; the reason names the live branch and not the merged one; the reason is order-independent on BOTH paths (the mixed case has one live branch, so sorted() is a no-op there and deleting it survives); and "fully merged", since "unmerged" contains "merged". FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 7 ++++- tests/scripts/test_audit_live_rows.py | 41 ++++++++++++++++++++++++++- 2 files changed, 46 insertions(+), 2 deletions(-) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index 91a28871..00585049 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -157,7 +157,12 @@ def classify_active( groundwork and still have open follow-up work, and calling that finished would silently steal a live claim. """ - live_branches = [b for b in branches if unmerged_by_branch.get(b)] + # Indexed, never .get(): `branches` is the authority for which keys must + # exist, so a missing key is a CALLER bug, not data. .get() would return + # None -> falsy -> the row reports LANDED, a live claim reported as + # finished. Absence of work and absence of information must never look the + # same; a KeyError at the audit's own boundary is the loud alternative. + live_branches = [b for b in branches if unmerged_by_branch[b]] if live_branches: joined = ", ".join(sorted(live_branches)) return "IN-FLIGHT", f"unmerged commits on {joined}" diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index 70a6764d..e4146d09 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -135,7 +135,9 @@ def test_fully_merged_branch_means_landed(self): commits=[], ) self.assertEqual(verdict, "LANDED") - self.assertIn("merged", reason.lower()) + # "unmerged" contains "merged", so a substring check on the bare word + # would pass for the IN-FLIGHT reason too. + self.assertIn("fully merged", reason) def test_main_commits_without_branch_mean_landed(self): verdict, reason = audit.classify_active( @@ -163,6 +165,43 @@ def test_in_flight_wins_over_landed_when_both_present(self): ) self.assertEqual(verdict, "IN-FLIGHT") + def test_reason_names_only_the_branches_with_unmerged_commits(self): + # With more than one branch, the reason must name the live one and not + # the merged one, and must be order-independent so a re-run does not + # produce a spuriously different report. + verdict, reason = audit.classify_active( + branches=["row/B-LIVE", "row/A-MERGED"], + unmerged_by_branch={"row/B-LIVE": ["abc1234 wip"], "row/A-MERGED": []}, + commits=[], + ) + self.assertEqual(verdict, "IN-FLIGHT") + self.assertIn("row/B-LIVE", reason) + self.assertNotIn("row/A-MERGED", reason) + + def test_reason_is_order_independent(self): + # The mixed case above has exactly ONE live branch, so sorted() is a + # no-op there and deleting it survives. Two branches on the same side + # of the filter are what pin determinism, on both reason paths: a + # report that reshuffles its own evidence between runs cannot be + # diffed by the human who has to act on it. + for label, by_branch in [ + ("in-flight", {"row/B": ["abc1234 wip"], "row/A": ["def5678 wip"]}), + ("landed", {"row/B": [], "row/A": []}), + ]: + with self.subTest(label): + forward = audit.classify_active(["row/A", "row/B"], by_branch, []) + reverse = audit.classify_active(["row/B", "row/A"], by_branch, []) + self.assertEqual(forward, reverse) + self.assertIn("row/A, row/B", forward[1]) + + def test_missing_branch_key_is_a_loud_caller_bug(self): + # Silently treating an ungathered branch as merged would report a live + # claim as finished -- the exact false negative this tool prevents. + with self.assertRaises(KeyError): + audit.classify_active( + branches=["row/NEVER-GATHERED"], unmerged_by_branch={}, commits=[] + ) + def test_every_verdict_is_declared(self): for branches, by_branch, commits in [ (["row/X"], {"row/X": ["a b"]}, []), From 5db478f2d1f442cfef5294eddde45baa2de4b15d Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 07:54:28 +0000 Subject: [PATCH 13/34] plan(protocol): pin sorted() with two branches on the SAME side of the filter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit My own fix for the multi-branch gap did not close it: the mixed case has exactly one LIVE branch, so sorted() is a no-op on that call and deleting it still survived the suite — the very mutation the finding named. Two branches on the same side of the filter are what pin determinism, on both reason paths. A report that reshuffles its own evidence between runs cannot be diffed by the human who has to act on it. Counts: Task 2 now 18. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 24 +++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index ce47b52f..7a9f3a5b 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -459,6 +459,22 @@ class ClassifierTests(unittest.TestCase): self.assertIn("row/B-LIVE", reason) self.assertNotIn("row/A-MERGED", reason) + def test_reason_is_order_independent(self): + # The mixed case above has exactly ONE live branch, so sorted() is a + # no-op there and deleting it survives. Two branches on the same side + # of the filter are what pin determinism, on both reason paths: a + # report that reshuffles its own evidence between runs cannot be + # diffed by the human who has to act on it. + for label, by_branch in [ + ("in-flight", {"row/B": ["abc1234 wip"], "row/A": ["def5678 wip"]}), + ("landed", {"row/B": [], "row/A": []}), + ]: + with self.subTest(label): + forward = audit.classify_active(["row/A", "row/B"], by_branch, []) + reverse = audit.classify_active(["row/B", "row/A"], by_branch, []) + self.assertEqual(forward, reverse) + self.assertIn("row/A, row/B", forward[1]) + def test_missing_branch_key_is_a_loud_caller_bug(self): # Silently treating an ungathered branch as merged would report a live # claim as finished -- the exact false negative this tool prevents. @@ -522,7 +538,7 @@ def classify_active( - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 17 tests. +Expected: PASS, 18 tests. - [ ] **Step 5: Run preflight and commit** @@ -634,7 +650,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 22 tests. +Expected: PASS, 23 tests. - [ ] **Step 5: Run preflight and commit** @@ -860,7 +876,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 27 tests (28 added minus the transitional CLI-guard test you delete here). +Expected: PASS, 28 tests (29 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -1106,7 +1122,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 30 tests. +Expected: PASS, 31 tests. - [ ] **Step 6: Verify the whole gate is green** From 3d5f314a90421a79adce6fe987a8de1336a4d0c6 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:02:10 +0000 Subject: [PATCH 14/34] tools(audit): advisory PARTIAL missing-modes flag (P0 step 3) Report-only by construction: CHECK_FAILS_ON is ACTIVE alone, so the keyword heuristic can never fail a build. Two test strengthenings past the brief, each because the briefed assertion provably did not pin what it named. `assertNotIn("PARTIAL", CHECK_FAILS_ON)` passes for frozenset() -- a gate that fails on nothing -- and for the bare string "ACTIVE", so the membership is now pinned exactly. And the substring trap's "node" half passes when "no" is dropped from GAP_MARKERS altogether, so each half now pins its marker as live. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 33 +++++++++++++++++++++ tests/scripts/test_audit_live_rows.py | 41 +++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index 00585049..89768067 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -174,5 +174,38 @@ def classify_active( return "ABANDONED", "no branch, no commit on main mentioning the row ID" +GAP_MARKERS = ( + "missing", + "not yet", + "unsupported", + "pending", + "only", + "absent", + "gap", + "no", + "without", + "blocked", + "todo", +) + +# Whole words, never substrings: "only" must not match "commonly" and "no" +# must not match "node". A substring match would silently mark a vague row as +# explicit, which is the exact failure this flag exists to catch. +GAP_RE = re.compile( + r"\b(?:" + "|".join(marker.replace(" ", r"\s+") for marker in GAP_MARKERS) + r")\b", + re.IGNORECASE, +) + +# check mode fails on abandoned ACTIVE rows and nothing else. The PARTIAL flag +# is a keyword heuristic for human review; gating on it would be the fragile +# checker the protocol warns against. +CHECK_FAILS_ON = frozenset({"ACTIVE"}) + + +def names_missing_modes(row_text: str) -> bool: + """True when a PARTIAL row states what is NOT supported.""" + return GAP_RE.search(row_text) is not None + + if __name__ == "__main__": raise SystemExit("CLI arrives in P0 step 4; import this module for now") diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index e4146d09..a8a7fbd3 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -213,5 +213,46 @@ def test_every_verdict_is_declared(self): self.assertIn(verdict, audit.VERDICTS) +class PartialGapTests(unittest.TestCase): + def test_explicit_gap_language_is_recognised(self): + for text in [ + "Works for bf16; fp8 is missing", + "Prefill only, decode not yet ported", + "Dense path supported, MoE unsupported", + "Image works; audio pending", + ]: + self.assertTrue(audit.names_missing_modes(text), text) + + def test_row_without_gap_language_is_flagged(self): + self.assertFalse(audit.names_missing_modes("Ported and gated on GB10")) + + def test_detection_is_case_insensitive(self): + self.assertTrue(audit.names_missing_modes("FP8 IS MISSING")) + + def test_markers_match_whole_words_not_substrings(self): + # "commonly" contains "only" and "node" contains "no". A substring + # match would mark these rows explicit and hide them from review. + self.assertFalse(audit.names_missing_modes("Commonly used decode node")) + # Both halves need their marker pinned as live, or the assertFalse + # above passes for the wrong reason: dropping "no" from GAP_MARKERS + # entirely also stops "node" matching, and nothing would notice. + self.assertTrue(audit.names_missing_modes("Decode only")) + self.assertTrue(audit.names_missing_modes("No fp8 path")) + + def test_flag_is_advisory_and_never_gates(self): + # check mode fails only on abandoned ACTIVE rows, never on a vague + # PARTIAL row -- the detector is a keyword heuristic. + self.assertNotIn("PARTIAL", audit.CHECK_FAILS_ON) + + def test_check_fails_on_active_and_nothing_else(self): + # assertNotIn above passes for frozenset() -- a check mode that fails + # on NOTHING -- and even for the bare string "ACTIVE", since "PARTIAL" + # is not a substring of it. Neither is what "report-only" means: the + # flag must be excluded from a set that still gates something. Pin the + # membership exactly, and pin that the gated state is a real live one. + self.assertEqual(audit.CHECK_FAILS_ON, frozenset({"ACTIVE"})) + self.assertTrue(audit.CHECK_FAILS_ON <= audit.LIVE_STATES) + + if __name__ == "__main__": unittest.main() From 83156ce68f6821c1ff8515c47aa8652cd7909f4e Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:04:22 +0000 Subject: [PATCH 15/34] plan(protocol): pin CHECK_FAILS_ON exactly, and pin both halves of the substring trap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task 3 found two more of the "passes with its subject deleted" class in my text: - assertNotIn("PARTIAL", CHECK_FAILS_ON) passes for frozenset() — a check mode that fails on NOTHING — and for the bare string "ACTIVE", since "PARTIAL" is not a substring of it. Report-only means excluded from a set that still gates something, so pin membership exactly and pin that the gated state is live. - The substring trap's "node" half also passed when "no" was dropped from GAP_MARKERS entirely, so assertFalse held for the wrong reason. Each half now pins its marker as live. Counts: Task 3 now 24. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 7a9f3a5b..08727810 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -594,12 +594,25 @@ class PartialGapTests(unittest.TestCase): # "commonly" contains "only" and "node" contains "no". A substring # match would mark these rows explicit and hide them from review. self.assertFalse(audit.names_missing_modes("Commonly used decode node")) + # Both halves need their marker pinned as live, or the assertFalse + # above passes for the wrong reason: dropping "no" from GAP_MARKERS + # entirely also stops "node" matching, and nothing would notice. self.assertTrue(audit.names_missing_modes("Decode only")) + self.assertTrue(audit.names_missing_modes("No fp8 path")) def test_flag_is_advisory_and_never_gates(self): # check mode fails only on abandoned ACTIVE rows, never on a vague # PARTIAL row -- the detector is a keyword heuristic. self.assertNotIn("PARTIAL", audit.CHECK_FAILS_ON) + + def test_check_fails_on_active_and_nothing_else(self): + # assertNotIn above passes for frozenset() -- a check mode that fails + # on NOTHING -- and even for the bare string "ACTIVE", since "PARTIAL" + # is not a substring of it. Neither is what "report-only" means: the + # flag must be excluded from a set that still gates something. Pin the + # membership exactly, and pin that the gated state is a real live one. + self.assertEqual(audit.CHECK_FAILS_ON, frozenset({"ACTIVE"})) + self.assertTrue(audit.CHECK_FAILS_ON <= audit.LIVE_STATES) ``` - [ ] **Step 2: Run test to verify it fails** @@ -650,7 +663,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 23 tests. +Expected: PASS, 24 tests. - [ ] **Step 5: Run preflight and commit** @@ -876,7 +889,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 28 tests (29 added minus the transitional CLI-guard test you delete here). +Expected: PASS, 29 tests (30 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -1122,7 +1135,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 31 tests. +Expected: PASS, 32 tests. - [ ] **Step 6: Verify the whole gate is green** From 90792feea6dee8b49646ac597c6d964693d239a5 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:09:06 +0000 Subject: [PATCH 16/34] plan(protocol): name the marker that fired, and escape the marker list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task 3's review measured the heuristic's failure direction: 11 of the 48 PARTIAL rows it reads as EXPLICIT qualify only via bare `no` or `gap`, on prose asserting goodness rather than absence — "no longer double-resides", "max gap 0.0 nats", "CLOSED the CPU RSS gap". Those are vague rows passing unreviewed, and 68 PARTIAL rows become public issues. Narrowing the input does not help (stripping code spans changes zero verdicts, measured). So the report names WHICH marker fired, letting a reviewer discount a bad hit at a glance rather than trusting the verdict. Cheaper and more honest than tuning the keyword list until it looks right. Also escapes markers before interpolation: the list invites human tuning, and an unescaped "(" would raise re.error at IMPORT time and take the module down, while "wip?" would silently compile to something matching "wi ". Counts: Task 3 now 26. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 37 ++++++++++++++++--- 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 08727810..64832a3f 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -642,8 +642,15 @@ GAP_MARKERS = ( # Whole words, never substrings: "only" must not match "commonly" and "no" # must not match "node". A substring match would silently mark a vague row as # explicit, which is the exact failure this flag exists to catch. +# Markers are ESCAPED before interpolation: the list above invites human +# tuning, and an unescaped marker containing "(" would raise re.error at +# IMPORT time and take the whole module down, while "wip?" would silently +# compile to something that matches "wi ". re.escape("not yet") is +# "not\\ yet", so widening the escaped space to \s+ still works. GAP_RE = re.compile( - r"\b(?:" + "|".join(marker.replace(" ", r"\s+") for marker in GAP_MARKERS) + r")\b", + r"\b(?:" + + "|".join(re.escape(marker).replace("\\ ", r"\s+") for marker in GAP_MARKERS) + + r")\b", re.IGNORECASE, ) @@ -656,6 +663,19 @@ CHECK_FAILS_ON = frozenset({"ACTIVE"}) def names_missing_modes(row_text: str) -> bool: """True when a PARTIAL row states what is NOT supported.""" return GAP_RE.search(row_text) is not None + + +def matched_marker(row_text: str) -> str: + """The gap marker that fired, or "" -- so a human can discount a bad hit. + + The heuristic under-flags: 11 of the 48 rows it reads as explicit qualify + only via bare `no` or `gap`, on prose asserting GOODNESS rather than + absence ("no longer double-resides", "max gap 0.0 nats", "CLOSED the CPU + RSS gap"). Naming the marker lets a reviewer dismiss those at a glance + instead of trusting the verdict. + """ + match = GAP_RE.search(row_text) + return match.group(0) if match else "" ``` `re` is already imported at the top of the module from Task 1; if it is not, add it there rather than mid-file. @@ -663,7 +683,7 @@ def names_missing_modes(row_text: str) -> bool: - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 24 tests. +Expected: PASS, 26 tests. - [ ] **Step 5: Run preflight and commit** @@ -801,8 +821,13 @@ def audit() -> list[dict]: verdict, reason = classify_active( branches, unmerged_by_branch, main_commits(row.item_id) ) - if row.state == "PARTIAL" and not names_missing_modes(row.raw): - flag = "does not name its missing modes" + if row.state == "PARTIAL": + marker = matched_marker(row.raw) + flag = ( + f"explicit via {marker!r}" + if marker + else "does not name its missing modes" + ) records.append( { "duplicate": ", ".join(duplicates.get(row.item_id, [])), @@ -889,7 +914,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 29 tests (30 added minus the transitional CLI-guard test you delete here). +Expected: PASS, 31 tests (32 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -1135,7 +1160,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 32 tests. +Expected: PASS, 34 tests. - [ ] **Step 6: Verify the whole gate is green** From 698fa8d28248df87fdfcd9f647ead150a1a93c74 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:13:47 +0000 Subject: [PATCH 17/34] tools(audit): name the marker that fired; escape markers before compiling Review finding 1: the heuristic fails in the UNSAFE direction. 11 of the 48 PARTIAL rows it reads as explicit qualify only via bare `no` or `gap`, on prose asserting goodness rather than absence ("no longer double-resides", "max gap 0.0 nats"). Tuning the keyword list would only move the boundary, so instead matched_marker() names the marker that fired and Task 4's report can show it: over-flagging costs a reviewer a glance, under-flagging ships a vague public issue. Review finding 2: markers were interpolated unescaped. GAP_MARKERS invites human tuning, and a marker containing "(" would raise re.error at IMPORT time and take the whole module down, while "not.yet" would compile silently into a wildcard matching "notXyet". They are now escaped, with the escaped space still widened to \s+ so multi-word markers behave as before. gap_pattern() takes its markers as an argument rather than closing over GAP_MARKERS: no shipped marker needs escaping today, so an inline expression could drop re.escape with no test able to notice. Mutation testing confirms dropping re.escape is now caught. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 45 ++++++++++++++++++++++----- tests/scripts/test_audit_live_rows.py | 43 +++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 7 deletions(-) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index 89768067..2a1eb513 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -188,13 +188,30 @@ def classify_active( "todo", ) -# Whole words, never substrings: "only" must not match "commonly" and "no" -# must not match "node". A substring match would silently mark a vague row as -# explicit, which is the exact failure this flag exists to catch. -GAP_RE = re.compile( - r"\b(?:" + "|".join(marker.replace(" ", r"\s+") for marker in GAP_MARKERS) + r")\b", - re.IGNORECASE, -) +def gap_pattern(markers: tuple[str, ...]) -> re.Pattern[str]: + """Compile markers into a whole-word, case-insensitive alternation. + + Whole words, never substrings: "only" must not match "commonly" and "no" + must not match "node". A substring match would silently mark a vague row as + explicit, which is the exact failure this flag exists to catch. + + Markers are ESCAPED before interpolation. GAP_MARKERS invites human tuning, + and a raw marker fails two ways: "fp4(" raises re.error at IMPORT time and + takes this whole module down with it, while "not.yet" compiles silently + into a wildcard that also matches "notXyet". re.escape("not yet") is + "not\\ yet", so widening that escaped space to \\s+ still works. + + Taking the markers as an argument is what makes the escaping testable: no + shipped marker needs escaping today, so an inline expression could drop + re.escape with nothing to notice. + """ + alternation = "|".join( + re.escape(marker).replace("\\ ", r"\s+") for marker in markers + ) + return re.compile(r"\b(?:" + alternation + r")\b", re.IGNORECASE) + + +GAP_RE = gap_pattern(GAP_MARKERS) # check mode fails on abandoned ACTIVE rows and nothing else. The PARTIAL flag # is a keyword heuristic for human review; gating on it would be the fragile @@ -207,5 +224,19 @@ def names_missing_modes(row_text: str) -> bool: return GAP_RE.search(row_text) is not None +def matched_marker(row_text: str) -> str: + """The gap marker that fired, or "" -- so a human can discount a bad hit. + + The heuristic under-flags: 11 of the 48 shipped rows it reads as explicit + qualify only via bare `no` or `gap`, on prose asserting GOODNESS rather + than absence ("no longer double-resides", "max gap 0.0 nats", "CLOSED the + CPU RSS gap"). Naming the marker lets a reviewer dismiss those at a glance + instead of trusting the verdict. Over-flagging costs a glance; + under-flagging ships a vague public issue. + """ + match = GAP_RE.search(row_text) + return match.group(0) if match else "" + + if __name__ == "__main__": raise SystemExit("CLI arrives in P0 step 4; import this module for now") diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index a8a7fbd3..5b696d07 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -253,6 +253,49 @@ def test_check_fails_on_active_and_nothing_else(self): self.assertEqual(audit.CHECK_FAILS_ON, frozenset({"ACTIVE"})) self.assertTrue(audit.CHECK_FAILS_ON <= audit.LIVE_STATES) + def test_matched_marker_names_the_marker_that_fired(self): + # The heuristic under-flags: 11 of the 48 shipped rows it reads as + # explicit qualify only via bare "no" or "gap", on prose asserting + # GOODNESS rather than absence. Naming the hit is what lets a reviewer + # discount those at a glance instead of trusting the verdict. + self.assertEqual( + audit.matched_marker("Works for bf16; fp8 is missing"), "missing" + ) + self.assertEqual( + audit.matched_marker("the mirror build no longer double-resides"), "no" + ) + self.assertEqual(audit.matched_marker("max gap 0.0 nats, 0 divergent"), "gap") + # The text AS WRITTEN, not the canonical marker, so the reviewer reads + # the row's own words back. + self.assertEqual(audit.matched_marker("FP8 IS MISSING"), "MISSING") + # No hit is "", never None: a vague row must not be reported through + # the same falsy channel as a row whose marker failed to render. + self.assertEqual(audit.matched_marker("Ported and gated on GB10"), "") + + def test_a_marker_needing_escaping_is_treated_literally(self): + # GAP_MARKERS invites human tuning, and an unescaped marker fails two + # ways. "not.yet" compiles to a wildcard that also matches "notXyet", + # silently widening the flag... + literal = audit.gap_pattern(("not.yet",)) + self.assertTrue(literal.search("decode not.yet ported")) + self.assertIsNone(literal.search("decode notXyet ported")) + # ...and "fp4(" raises re.error at IMPORT time, taking the whole + # module -- loader, classifier and all -- down with it. + audit.gap_pattern(("fp4(",)) + # Escaping must not cost the multi-word widening: re.escape("not yet") + # is "not\\ yet", and that escaped space is what gets widened. + self.assertTrue(audit.gap_pattern(("not yet",)).search("decode not yet")) + # The shipped regex must be the one this builder returns. Mutation + # testing shows what this does NOT buy: rebuilding GAP_RE inline + # WITHOUT re.escape survives, because no shipped marker needs escaping + # today, so both spellings compile to the identical pattern. It pins + # the marker set and the structure, not the escaping -- and that + # unobservability is exactly why gap_pattern takes its markers as an + # argument instead of closing over GAP_MARKERS. + self.assertEqual( + audit.GAP_RE.pattern, audit.gap_pattern(audit.GAP_MARKERS).pattern + ) + if __name__ == "__main__": unittest.main() From 547516edcc78bd5c4916bdecd3882dd3b5701686 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:15:45 +0000 Subject: [PATCH 18/34] plan(protocol): take the markers as an argument so the escaping is testable My inline GAP_RE expression could not be tested: no shipped marker needs escaping, so a test would have to rebuild the pattern and would only test its own copy. gap_pattern(markers) lets a test hand the real shipped code "not.yet" and "fp4(". Regex is byte-identical. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 146 +++--------------- 1 file changed, 22 insertions(+), 124 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 64832a3f..6c1c4a51 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -565,7 +565,7 @@ EOF - Test: `tests/scripts/test_audit_live_rows.py` **Interfaces:** -- Produces: `GAP_MARKERS: tuple[str, ...]`; `names_missing_modes(row_text: str) -> bool`. +- Produces: `GAP_MARKERS: tuple[str, ...]`; `gap_pattern(markers: tuple[str, ...]) -> re.Pattern[str]`; `GAP_RE`; `CHECK_FAILS_ON: frozenset[str]`; `names_missing_modes(row_text: str) -> bool`; `matched_marker(row_text: str) -> str`. The row contract already requires a `PARTIAL` row to make its missing modes explicit. Because `PARTIAL` rows become **public** issues in P2, a vague one becomes a vague public issue. This is a **report-only flag for human review** and must never become a hard failure — the detector is a keyword heuristic and gating on it would be exactly the fragile-checker trap the protocol warns about. @@ -642,132 +642,30 @@ GAP_MARKERS = ( # Whole words, never substrings: "only" must not match "commonly" and "no" # must not match "node". A substring match would silently mark a vague row as # explicit, which is the exact failure this flag exists to catch. -# Markers are ESCAPED before interpolation: the list above invites human -# tuning, and an unescaped marker containing "(" would raise re.error at -# IMPORT time and take the whole module down, while "wip?" would silently -# compile to something that matches "wi ". re.escape("not yet") is -# "not\\ yet", so widening the escaped space to \s+ still works. -GAP_RE = re.compile( - r"\b(?:" - + "|".join(re.escape(marker).replace("\\ ", r"\s+") for marker in GAP_MARKERS) - + r")\b", - re.IGNORECASE, -) - -# check mode fails on abandoned ACTIVE rows and nothing else. The PARTIAL flag -# is a keyword heuristic for human review; gating on it would be the fragile -# checker the protocol warns against. -CHECK_FAILS_ON = frozenset({"ACTIVE"}) - - -def names_missing_modes(row_text: str) -> bool: - """True when a PARTIAL row states what is NOT supported.""" - return GAP_RE.search(row_text) is not None - - -def matched_marker(row_text: str) -> str: - """The gap marker that fired, or "" -- so a human can discount a bad hit. - - The heuristic under-flags: 11 of the 48 rows it reads as explicit qualify - only via bare `no` or `gap`, on prose asserting GOODNESS rather than - absence ("no longer double-resides", "max gap 0.0 nats", "CLOSED the CPU - RSS gap"). Naming the marker lets a reviewer dismiss those at a glance - instead of trusting the verdict. +def gap_pattern(markers: tuple[str, ...]) -> re.Pattern[str]: + """Compile markers into a whole-word, case-insensitive alternation. + + Whole words, never substrings: "only" must not match "commonly" and "no" + must not match "node". A substring match would silently mark a vague row as + explicit, which is the exact failure this flag exists to catch. + + Markers are ESCAPED before interpolation. GAP_MARKERS invites human tuning, + and a raw marker fails two ways: "fp4(" raises re.error at IMPORT time and + takes this whole module down with it, while "not.yet" compiles silently + into a wildcard that also matches "notXyet". re.escape("not yet") is + "not\\ yet", so widening that escaped space to \\s+ still works. + + Taking the markers as an argument is what makes the escaping testable: no + shipped marker needs escaping today, so an inline expression could drop + re.escape with nothing to notice. """ - match = GAP_RE.search(row_text) - return match.group(0) if match else "" -``` - -`re` is already imported at the top of the module from Task 1; if it is not, add it there rather than mid-file. - -- [ ] **Step 4: Run test to verify it passes** - -Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 26 tests. - -- [ ] **Step 5: Run preflight and commit** - -```bash -bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" -git add scripts/audit-live-rows.py tests/scripts/test_audit_live_rows.py -git commit -F - <<'EOF' -tools(audit): advisory PARTIAL missing-modes flag (P0 step 3) - -Report-only by construction: CHECK_FAILS_ON is ACTIVE alone, so the keyword -heuristic can never fail a build. - -FOLLOWING_AGENTS_PROTOCOL -Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] -EOF -``` - ---- - -### Task 4: Report rendering and CLI - -**Files:** -- Modify: `scripts/audit-live-rows.py` -- Test: `tests/scripts/test_audit_live_rows.py` - -**Interfaces:** -- Consumes: everything from Tasks 1–3. -- Produces: `audit() -> list[dict]` (one record per live row, keys `id`, `state`, `path`, `line`, `verdict`, `reason`, `flag`, `duplicate`); `duplicate_live_ids(rows: list) -> dict[str, list[str]]`; `render_markdown(records: list[dict]) -> str`; `main(argv: list[str] | None = None) -> int`. `audit()` calls `require_origin_main()` first and aborts on any parse error. - -- [ ] **Step 1: Write the failing test** - -Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: + alternation = "|".join( + re.escape(marker).replace("\\ ", r"\s+") for marker in markers + ) + return re.compile(r"\b(?:" + alternation + r")\b", re.IGNORECASE) -```python -class ReportTests(unittest.TestCase): - RECORDS = [ - { - "id": "ENG-FOO", - "state": "ACTIVE", - "path": ".agents/engine-matrix.md", - "line": 42, - "verdict": "ABANDONED", - "reason": "no branch, no commit on main mentioning the row ID", - "flag": "", - }, - { - "id": "MODEL-BAR", - "state": "PARTIAL", - "path": ".agents/model-matrix.md", - "line": 7, - "verdict": "", - "reason": "", - "flag": "does not name its missing modes", - }, - ] - def test_markdown_lists_every_record(self): - out = audit.render_markdown(self.RECORDS) - self.assertIn("ENG-FOO", out) - self.assertIn("MODEL-BAR", out) - self.assertIn("ABANDONED", out) - self.assertIn("does not name its missing modes", out) - - def test_markdown_cells_do_not_break_the_table(self): - records = [dict(self.RECORDS[0], reason="a | b")] - out = audit.render_markdown(records) - body = [ln for ln in out.splitlines() if "ENG-FOO" in ln] - self.assertEqual(len(body), 1) - self.assertNotIn("a | b", body[0]) - - def test_check_mode_fails_when_an_active_row_is_abandoned(self): - self.assertEqual(audit.exit_code(self.RECORDS, check=True), 1) - - def test_check_mode_passes_when_no_active_row_is_abandoned(self): - clean = [dict(self.RECORDS[0], verdict="IN-FLIGHT")] + self.RECORDS[1:] - self.assertEqual(audit.exit_code(clean, check=True), 0) - - def test_report_mode_always_exits_zero(self): - self.assertEqual(audit.exit_code(self.RECORDS, check=False), 0) - - def test_vague_partial_alone_never_fails_check_mode(self): - only_flag = [self.RECORDS[1]] - self.assertEqual(audit.exit_code(only_flag, check=True), 0) -``` +GAP_RE = gap_pattern(GAP_MARKERS)``` - [ ] **Step 2: Run test to verify it fails** From 4cb357c995607cd4cae63a04ca1058fac9a3417e Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:23:17 +0000 Subject: [PATCH 19/34] plan(protocol): restore Task 4, which an index-based edit had deleted 547516ed used an index slice (t.index(start) .. t.index(")\n```")) to swap the GAP_RE expression. The end anchor was not unique, so the slice ran far past its intended region and silently removed Task 4 entirely along with CHECK_FAILS_ON, names_missing_modes and matched_marker, and glued a code fence. Nothing failed: the plan still parsed as Markdown and preflight stayed green, so the loss only surfaced when task-brief could not find Task 4. Rebuilt from 90792fee and reapplied the three intended changes with COUNTED replacements (assert count == 1 per anchor), then asserted 7 task headings, balanced fences, and every public symbol present. The lesson is the one already in the record: assert anchor UNIQUENESS, never existence, and never slice a document by a non-unique end marker. Also lands the VAGUE_FLAG repair 547516ed was carrying: every PARTIAL row now has a flag, so "needs review" must key on the vague string, not on a non-empty flag, or all 68 PARTIAL rows count as vague instead of the 20 that are. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 142 ++++++++++++++++-- 1 file changed, 133 insertions(+), 9 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 6c1c4a51..92506198 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -665,7 +665,129 @@ def gap_pattern(markers: tuple[str, ...]) -> re.Pattern[str]: return re.compile(r"\b(?:" + alternation + r")\b", re.IGNORECASE) -GAP_RE = gap_pattern(GAP_MARKERS)``` +GAP_RE = gap_pattern(GAP_MARKERS) + +# check mode fails on abandoned ACTIVE rows and nothing else. The PARTIAL flag +# is a keyword heuristic for human review; gating on it would be the fragile +# checker the protocol warns against. +CHECK_FAILS_ON = frozenset({"ACTIVE"}) + + +def names_missing_modes(row_text: str) -> bool: + """True when a PARTIAL row states what is NOT supported.""" + return GAP_RE.search(row_text) is not None + + +def matched_marker(row_text: str) -> str: + """The gap marker that fired, or "" -- so a human can discount a bad hit. + + The heuristic under-flags: 11 of the 48 rows it reads as explicit qualify + only via bare `no` or `gap`, on prose asserting GOODNESS rather than + absence ("no longer double-resides", "max gap 0.0 nats", "CLOSED the CPU + RSS gap"). Naming the marker lets a reviewer dismiss those at a glance + instead of trusting the verdict. + """ + match = GAP_RE.search(row_text) + return match.group(0) if match else "" +``` + +`re` is already imported at the top of the module from Task 1; if it is not, add it there rather than mid-file. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `python3 tests/scripts/test_audit_live_rows.py -v` +Expected: PASS, 26 tests. + +- [ ] **Step 5: Run preflight and commit** + +```bash +bash scripts/agent-preflight.sh > /tmp/preflight.log 2>&1; echo "EXIT=$?" +git add scripts/audit-live-rows.py tests/scripts/test_audit_live_rows.py +git commit -F - <<'EOF' +tools(audit): advisory PARTIAL missing-modes flag (P0 step 3) + +Report-only by construction: CHECK_FAILS_ON is ACTIVE alone, so the keyword +heuristic can never fail a build. + +FOLLOWING_AGENTS_PROTOCOL +Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] +EOF +``` + +--- + +### Task 4: Report rendering and CLI + +**Files:** +- Modify: `scripts/audit-live-rows.py` +- Test: `tests/scripts/test_audit_live_rows.py` + +**Interfaces:** +- Consumes: everything from Tasks 1–3. +- Produces: `audit() -> list[dict]` (one record per live row, keys `id`, `state`, `path`, `line`, `verdict`, `reason`, `flag`, `duplicate`); `duplicate_live_ids(rows: list) -> dict[str, list[str]]`; `render_markdown(records: list[dict]) -> str`; `main(argv: list[str] | None = None) -> int`. `audit()` calls `require_origin_main()` first and aborts on any parse error. + +- [ ] **Step 1: Write the failing test** + +Append to `tests/scripts/test_audit_live_rows.py`, above the `if __name__` block: + +```python +class ReportTests(unittest.TestCase): + RECORDS = [ + { + "id": "ENG-FOO", + "state": "ACTIVE", + "path": ".agents/engine-matrix.md", + "line": 42, + "verdict": "ABANDONED", + "reason": "no branch, no commit on main mentioning the row ID", + "flag": "", + }, + { + "id": "MODEL-BAR", + "state": "PARTIAL", + "path": ".agents/model-matrix.md", + "line": 7, + "verdict": "", + "reason": "", + "flag": "does not name its missing modes", + }, + ] + + def test_markdown_lists_every_record(self): + out = audit.render_markdown(self.RECORDS) + self.assertIn("ENG-FOO", out) + self.assertIn("MODEL-BAR", out) + self.assertIn("ABANDONED", out) + self.assertIn("does not name its missing modes", out) + + def test_markdown_cells_do_not_break_the_table(self): + records = [dict(self.RECORDS[0], reason="a | b")] + out = audit.render_markdown(records) + body = [ln for ln in out.splitlines() if "ENG-FOO" in ln] + self.assertEqual(len(body), 1) + self.assertNotIn("a | b", body[0]) + + def test_check_mode_fails_when_an_active_row_is_abandoned(self): + self.assertEqual(audit.exit_code(self.RECORDS, check=True), 1) + + def test_check_mode_passes_when_no_active_row_is_abandoned(self): + clean = [dict(self.RECORDS[0], verdict="IN-FLIGHT")] + self.RECORDS[1:] + self.assertEqual(audit.exit_code(clean, check=True), 0) + + def test_only_the_vague_flag_counts_as_needing_review(self): + # Every PARTIAL row carries a flag: the marker that fired, or the vague + # string. Counting non-empty flags would report all 68 as vague. + explicit = dict(self.RECORDS[1], flag="explicit via 'missing'") + self.assertNotEqual(explicit["flag"], audit.VAGUE_FLAG) + self.assertEqual(self.RECORDS[1]["flag"], audit.VAGUE_FLAG) + + def test_report_mode_always_exits_zero(self): + self.assertEqual(audit.exit_code(self.RECORDS, check=False), 0) + + def test_vague_partial_alone_never_fails_check_mode(self): + only_flag = [self.RECORDS[1]] + self.assertEqual(audit.exit_code(only_flag, check=True), 0) +``` - [ ] **Step 2: Run test to verify it fails** @@ -681,6 +803,12 @@ import argparse import json +# Every PARTIAL row carries a flag string now -- either the marker that fired +# or this. So "needs review" is THIS string, never merely a non-empty flag; +# counting non-empty flags would report all 68 PARTIAL rows as vague. +VAGUE_FLAG = "does not name its missing modes" + + def duplicate_live_ids(rows: list) -> dict[str, list[str]]: """Row IDs that appear live in more than one matrix. @@ -721,11 +849,7 @@ def audit() -> list[dict]: ) if row.state == "PARTIAL": marker = matched_marker(row.raw) - flag = ( - f"explicit via {marker!r}" - if marker - else "does not name its missing modes" - ) + flag = f"explicit via {marker!r}" if marker else VAGUE_FLAG records.append( { "duplicate": ", ".join(duplicates.get(row.item_id, [])), @@ -793,7 +917,7 @@ def main(argv: list[str] | None = None) -> int: else: print(render_markdown(records)) stale = [i for i in records if i["verdict"] == "ABANDONED"] - vague = [i for i in records if i["flag"]] + vague = [i for i in records if i["flag"] == VAGUE_FLAG] dupes = sorted({i["id"] for i in records if i["duplicate"]}) print( f"\n{len(records)} live rows; {len(stale)} abandoned ACTIVE; " @@ -812,7 +936,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 31 tests (32 added minus the transitional CLI-guard test you delete here). +Expected: PASS, 33 tests (34 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -1058,7 +1182,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 34 tests. +Expected: PASS, 36 tests. - [ ] **Step 6: Verify the whole gate is green** From 2ef64fef620cf02a60c0f9dda22be7d519f444a9 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:29:19 +0000 Subject: [PATCH 20/34] tools(audit): report, JSON and check modes (P0 step 4) check mode is deliberately NOT wired into preflight or CI yet -- it fails today, and that failure is the audit finding the record has to absorb first. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- scripts/audit-live-rows.py | 126 ++++++++++++++++- tests/scripts/test_audit_live_rows.py | 194 +++++++++++++++++++++++--- 2 files changed, 303 insertions(+), 17 deletions(-) diff --git a/scripts/audit-live-rows.py b/scripts/audit-live-rows.py index 2a1eb513..70fb73a7 100755 --- a/scripts/audit-live-rows.py +++ b/scripts/audit-live-rows.py @@ -238,5 +238,129 @@ def matched_marker(row_text: str) -> str: return match.group(0) if match else "" +# Every PARTIAL row carries a flag string now -- either the marker that fired +# or this. So "needs review" is THIS string, never merely a non-empty flag; +# counting non-empty flags would report all 68 PARTIAL rows as vague. +VAGUE_FLAG = "does not name its missing modes" + + +def duplicate_live_ids(rows: list) -> dict[str, list[str]]: + """Row IDs that appear live in more than one matrix. + + BACKEND-CUDA-SM121 and BACKEND-CPU are PARTIAL in BOTH backend-matrix.md + and feature-matrix.md, so 188 live rows carry only 186 unique IDs. + check-agent-record.py's duplicate check only walks MATRIX_PATHS, so it has + never seen these. Left unresolved, the backfill would mint two issues for + one item and this audit would report each twice with identical evidence. + """ + seen: dict[str, list[str]] = {} + for row in rows: + seen.setdefault(row.item_id, []).append(f"{row.path.name}:{row.line_no}") + return {k: v for k, v in seen.items() if len(v) > 1} + + +def audit() -> list[dict]: + """One record per live row, with verdict (ACTIVE) and flag (PARTIAL).""" + require_origin_main() + parse_errors: list[str] = [] + rows = live_rows(parse_errors) + if parse_errors: + raise SystemExit( + "the matrices do not parse cleanly, so the census is incomplete:\n" + + "\n".join(parse_errors) + ) + duplicates = duplicate_live_ids(rows) + branches_by_id = row_branches() + records: list[dict] = [] + for row in rows: + verdict = "" + reason = "" + flag = "" + if row.state == "ACTIVE": + branches = branches_by_id.get(row.item_id, []) + unmerged_by_branch = {b: unmerged(b) for b in branches} + verdict, reason = classify_active( + branches, unmerged_by_branch, main_commits(row.item_id) + ) + if row.state == "PARTIAL": + marker = matched_marker(row.raw) + flag = f"explicit via {marker!r}" if marker else VAGUE_FLAG + records.append( + { + "duplicate": ", ".join(duplicates.get(row.item_id, [])), + "id": row.item_id, + "state": row.state, + "path": str(row.path.relative_to(ROOT)), + "line": row.line_no, + "verdict": verdict, + "reason": reason, + "flag": flag, + } + ) + return records + + +def _cell(value: object) -> str: + """Table cells never contain a raw pipe -- it would split the row.""" + return str(value).replace("|", "\\|").replace("\n", " ").strip() + + +def render_markdown(records: list[dict]) -> str: + lines = [ + "| Row | State | Location | Verdict | Evidence | Flag |", + "|---|---|---|---|---|---|", + ] + for item in records: + lines.append( + "| `{id}` | `{state}` | {path}:{line} | {verdict} | {reason} | {flag} |".format( + id=_cell(item["id"]), + state=_cell(item["state"]), + path=_cell(item["path"]), + line=_cell(item["line"]), + verdict=_cell(item["verdict"]) or "-", + reason=_cell(item["reason"]) or "-", + flag=_cell(item["flag"]) or "-", + ) + ) + return "\n".join(lines) + + +def exit_code(records: list[dict], check: bool) -> int: + if not check: + return 0 + abandoned = [ + item + for item in records + if item["state"] in CHECK_FAILS_ON and item["verdict"] == "ABANDONED" + ] + return 1 if abandoned else 0 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--json", action="store_true", help="machine-readable output") + parser.add_argument( + "--check", + action="store_true", + help="exit 1 if any ACTIVE row is abandoned", + ) + args = parser.parse_args(argv) + + records = audit() + if args.json: + print(json.dumps(records, indent=2, sort_keys=True)) + else: + print(render_markdown(records)) + stale = [i for i in records if i["verdict"] == "ABANDONED"] + vague = [i for i in records if i["flag"] == VAGUE_FLAG] + dupes = sorted({i["id"] for i in records if i["duplicate"]}) + print( + f"\n{len(records)} live rows; {len(stale)} abandoned ACTIVE; " + f"{len(vague)} PARTIAL rows to review; " + f"{len(dupes)} IDs live in two matrices: {', '.join(dupes) or 'none'}." + ) + return exit_code(records, args.check) + + if __name__ == "__main__": - raise SystemExit("CLI arrives in P0 step 4; import this module for now") + raise SystemExit(main()) diff --git a/tests/scripts/test_audit_live_rows.py b/tests/scripts/test_audit_live_rows.py index 5b696d07..b82e1c25 100644 --- a/tests/scripts/test_audit_live_rows.py +++ b/tests/scripts/test_audit_live_rows.py @@ -8,12 +8,15 @@ from __future__ import annotations +import contextlib import importlib.util +import io +import json import re -import subprocess import sys import unittest from pathlib import Path +from unittest import mock ROOT = Path(__file__).resolve().parents[2] @@ -103,21 +106,6 @@ def test_pattern_rejects_a_longer_id_that_merely_starts_with_it(self): self.assertIsNone(pattern.search(message), message) -class CommandLineGuardTests(unittest.TestCase): - def test_check_flag_does_not_silently_exit_zero(self): - # The file is executable and its docstring advertises --check, but the - # real CLI arrives in P0 step 4. Until then --check must NOT exit 0: - # a gate that reports success because it ignored its own flag is the - # worst possible answer. - result = subprocess.run( - [sys.executable, str(ROOT / "scripts/audit-live-rows.py"), "--check"], - capture_output=True, - text=True, - check=False, - ) - self.assertNotEqual(result.returncode, 0) - - class ClassifierTests(unittest.TestCase): def test_unmerged_branch_commits_mean_in_flight(self): verdict, reason = audit.classify_active( @@ -297,5 +285,179 @@ def test_a_marker_needing_escaping_is_treated_literally(self): ) +class ReportTests(unittest.TestCase): + RECORDS = [ + { + "id": "ENG-FOO", + "state": "ACTIVE", + "path": ".agents/engine-matrix.md", + "line": 42, + "verdict": "ABANDONED", + "reason": "no branch, no commit on main mentioning the row ID", + "flag": "", + }, + { + "id": "MODEL-BAR", + "state": "PARTIAL", + "path": ".agents/model-matrix.md", + "line": 7, + "verdict": "", + "reason": "", + "flag": "does not name its missing modes", + }, + ] + + def test_markdown_lists_every_record(self): + out = audit.render_markdown(self.RECORDS) + self.assertIn("ENG-FOO", out) + self.assertIn("MODEL-BAR", out) + self.assertIn("ABANDONED", out) + self.assertIn("does not name its missing modes", out) + + def test_markdown_cells_do_not_break_the_table(self): + records = [dict(self.RECORDS[0], reason="a | b")] + out = audit.render_markdown(records) + body = [ln for ln in out.splitlines() if "ENG-FOO" in ln] + self.assertEqual(len(body), 1) + self.assertNotIn("a | b", body[0]) + + def test_check_mode_fails_when_an_active_row_is_abandoned(self): + self.assertEqual(audit.exit_code(self.RECORDS, check=True), 1) + + def test_check_mode_passes_when_no_active_row_is_abandoned(self): + clean = [dict(self.RECORDS[0], verdict="IN-FLIGHT")] + self.RECORDS[1:] + self.assertEqual(audit.exit_code(clean, check=True), 0) + + def test_only_the_vague_flag_counts_as_needing_review(self): + # Every PARTIAL row carries a flag: the marker that fired, or the vague + # string. Counting non-empty flags would report all 68 as vague. + explicit = dict(self.RECORDS[1], flag="explicit via 'missing'") + self.assertNotEqual(explicit["flag"], audit.VAGUE_FLAG) + self.assertEqual(self.RECORDS[1]["flag"], audit.VAGUE_FLAG) + + def test_report_mode_always_exits_zero(self): + self.assertEqual(audit.exit_code(self.RECORDS, check=False), 0) + + def test_vague_partial_alone_never_fails_check_mode(self): + only_flag = [self.RECORDS[1]] + self.assertEqual(audit.exit_code(only_flag, check=True), 0) + + +class SummaryTests(unittest.TestCase): + """The counting the summary line actually does, not just the constant. + + test_only_the_vague_flag_counts_as_needing_review above compares two + literals and never calls the code: rewriting the summary to count every + non-empty flag leaves it green while the report claims all 68 PARTIAL rows + need review instead of the ~20 that do. This drives the real counter. + """ + + VAGUE = { + "id": "MODEL-VAGUE", + "state": "PARTIAL", + "path": ".agents/model-matrix.md", + "line": 7, + "verdict": "", + "reason": "", + "flag": "does not name its missing modes", + "duplicate": "", + } + EXPLICIT = dict(VAGUE, id="MODEL-EXPLICIT", flag="explicit via 'missing'") + + def run_main(self, records: list[dict], argv: list[str]) -> tuple[int, str]: + buffer = io.StringIO() + with mock.patch.object(audit, "audit", lambda: records): + with contextlib.redirect_stdout(buffer): + code = audit.main(argv) + return code, buffer.getvalue() + + def test_summary_counts_only_the_vague_partial_rows(self): + code, out = self.run_main([self.VAGUE, self.EXPLICIT], []) + self.assertEqual(code, 0) + self.assertIn("2 live rows; 0 abandoned ACTIVE", out) + self.assertIn("1 PARTIAL rows to review", out) + + def test_summary_names_the_ids_living_in_two_matrices(self): + both = dict(self.VAGUE, id="BACKEND-CPU", duplicate="backend-matrix.md:12") + _, out = self.run_main([both, self.EXPLICIT], []) + self.assertIn("1 IDs live in two matrices: BACKEND-CPU", out) + + def test_json_mode_emits_every_record_and_no_report_table(self): + code, out = self.run_main([self.VAGUE, self.EXPLICIT], ["--json"]) + self.assertEqual(code, 0) + self.assertEqual(json.loads(out), [self.VAGUE, self.EXPLICIT]) + self.assertNotIn("PARTIAL rows to review", out) + + +class AuditGuardTests(unittest.TestCase): + """audit() must abort rather than emit a quietly wrong census.""" + + def test_origin_main_is_verified_before_any_row_is_read(self): + # git() maps every failure to "", so an unfetched origin/main makes + # each row look ABANDONED and the audit would propose downgrading all + # 54 ACTIVE rows at once. The guard has to fire first, not eventually. + calls: list[str] = [] + + def guard() -> None: + calls.append("guard") + raise SystemExit("origin/main does not resolve") + + def rows(errors=None): + calls.append("rows") + return [] + + with mock.patch.object(audit, "require_origin_main", guard), mock.patch.object( + audit, "live_rows", rows + ): + with self.assertRaises(SystemExit): + audit.audit() + self.assertEqual(calls, ["guard"]) + + def test_a_row_that_fails_to_parse_aborts_the_audit(self): + # parse_claim_rows DROPS a row it cannot parse. A census whose whole + # point is completeness must not quietly return one row short. + def broken(errors=None): + if errors is not None: + errors.append(".agents/engine-matrix.md:9: ENG-X has 4 cells") + return [] + + with mock.patch.object( + audit, "require_origin_main", lambda: None + ), mock.patch.object(audit, "live_rows", broken): + with self.assertRaises(SystemExit) as caught: + audit.audit() + self.assertIn("ENG-X", str(caught.exception)) + + +class DuplicateLiveIdTests(unittest.TestCase): + @staticmethod + def _row(item_id: str, matrix: str, line_no: int): + return audit.record.ClaimRow( + path=audit.record.AGENTS / matrix, + line_no=line_no, + item_id=item_id, + state="PARTIAL", + header=(), + cells=(), + raw="", + ) + + def test_only_ids_live_in_more_than_one_matrix_are_reported(self): + # A row ID living in two matrices would mint two issues for one item + # and report the same item twice with identical evidence. Every other + # ID must stay out of the result, or the report calls all 186 duplicates. + dupes = audit.duplicate_live_ids( + [ + self._row("BACKEND-CPU", "backend-matrix.md", 12), + self._row("BACKEND-CPU", "feature-matrix.md", 40), + self._row("ENG-SOLO", "engine-matrix.md", 5), + ] + ) + self.assertEqual(list(dupes), ["BACKEND-CPU"]) + self.assertEqual( + dupes["BACKEND-CPU"], ["backend-matrix.md:12", "feature-matrix.md:40"] + ) + + if __name__ == "__main__": unittest.main() From 4aaa9a8cdda920cd2528ab9afea0d69cfb6ef52a Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:31:55 +0000 Subject: [PATCH 21/34] =?UTF-8?q?plan(protocol):=20Task=204=20ships=2038?= =?UTF-8?q?=20tests=20=E2=80=94=20the=20briefed=20vague-flag=20test=20prov?= =?UTF-8?q?ed=20inert?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit test_only_the_vague_flag_counts_as_needing_review compares two literals and calls nothing, so mutating main()'s counter to `if i["flag"]` — the exact 68-vs-20 bug it was written to prevent — leaves it green. Task 4 adds a main()-level counting test that kills that mutation, plus five covering audit()'s two abort guards, duplicate_live_ids, the duplicate summary line, and --json, none of which any briefed test exercised. Counts: Task 4 now 38, Task 7 now 41. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- docs/superpowers/plans/2026-08-06-p0-live-state-audit.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 92506198..e26edf76 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -936,7 +936,7 @@ Move the `import argparse` and `import json` lines up into the module's import b - [ ] **Step 4: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 33 tests (34 added minus the transitional CLI-guard test you delete here). +Expected: PASS, 38 tests (39 added minus the transitional CLI-guard test you delete here). - [ ] **Step 5: Smoke-test the CLI against the real repository** @@ -1182,7 +1182,7 @@ In `.github/workflows/ci.yml`, extend the record job (lines 42–46): - [ ] **Step 5: Run test to verify it passes** Run: `python3 tests/scripts/test_audit_live_rows.py -v` -Expected: PASS, 36 tests. +Expected: PASS, 41 tests. - [ ] **Step 6: Verify the whole gate is green** From 4174bde524bda43c307d97c688845bd39878ee7d Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:50:01 +0000 Subject: [PATCH 22/34] record(audit): live-state audit findings, no corrections applied yet (P0 step 5) Findings land before corrections so the reasoning is reviewable independently of the churn. Includes the hand-verified sample that validates the classifier. 188 live rows; ACTIVE 54 -> 0 IN-FLIGHT, 44 LANDED, 10 ABANDONED. Zero rows have a row/ branch, so every LANDED verdict rests on the weakest rule in the classifier -- a commit message mentioning the ID -- and 8 of the 44 are credited to a commit whose diff is records and docs ONLY. LANDED is recorded as "has evidence worth reading", never "finished"; no row is proposed for DONE. All 10 abandoned rows resolve a real spec link, so all 10 are legal at READY and none needs INVENTORIED -- but READY is the legality FLOOR, not a recommendation: each carries in-row anchors asserting passing gates, so the final state is deferred to a human for all ten. Every one also sits inside an active claim, and 11 claims reference nothing but abandoned rows, so the correcting change must retire them in the same commit or check_row_contracts goes red. Duplicate live IDs settled here: backend-matrix.md OWNS BACKEND-CPU and BACKEND-CUDA-SM121; the feature-matrix entries become non-claimable pointers, so the backfill mints one issue per item rather than two. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .agents/specs/live-state-audit-2026-08-06.md | 709 +++++++++++++++++++ 1 file changed, 709 insertions(+) create mode 100644 .agents/specs/live-state-audit-2026-08-06.md diff --git a/.agents/specs/live-state-audit-2026-08-06.md b/.agents/specs/live-state-audit-2026-08-06.md new file mode 100644 index 00000000..fd10df7c --- /dev/null +++ b/.agents/specs/live-state-audit-2026-08-06.md @@ -0,0 +1,709 @@ +# Live-state audit — 2026-08-06 (P0) + +Read-only census of every LIVE matrix row against Git reality. It PROPOSES; it +changes no matrix. Corrections land in a separate reviewable change so this +reasoning can be read independently of the churn it justifies. + +## Scope + +- **Rows.** The 188 rows in a live state (`SPIKE`, `READY`, `ACTIVE`, `GATING`, + `PARTIAL`, `BLOCKED`) across all seven `.agents/*-matrix.md` files. The five in + `check-agent-record.py`'s `MATRIX_PATHS`, plus `feature-matrix.md` and + `sglang-matrix.md`, which no CI gate parses as claim rows and which together + hold 11 live rows. +- **Trees.** Rows are read from the working tree on `spec/issue-native-tracking` + @ `4aaa9a8c`. Git evidence is read from `origin/main` @ `cf32c619` (fetched + 2026-08-06). The only matrix delta between the two is `engine-matrix.md` + dropping nine `INVENTORIED` spec-decode rows and its count table; every one of + those is `INVENTORIED`, so the LIVE census is identical to `origin/main`'s. +- **What this audit decides.** Which `ACTIVE` claims are unsupportable by Git; + which `PARTIAL` rows fail to name their own missing modes; which stable IDs are + live in two matrices at once; and, for each unsupportable `ACTIVE` row, which + target states the state contracts actually permit. +- **What it does NOT decide.** Whether any row is *finished*. No verdict in this + document promotes a row to `DONE`, and none may be cited as evidence that work + completed. The strongest thing the tool can say is that a commit message + mentions the row ID — see Findings ➁. + +## Method + +[`scripts/audit-live-rows.py`](../../scripts/audit-live-rows.py) — three modes: +markdown report (default), `--json`, and `--check` (exit 1 iff an `ACTIVE` row is +abandoned). Row parsing is *imported* from `check-agent-record.py` rather than +reimplemented, so the audit and the gate can never disagree about what a row is. + +### Classification rules, verbatim + +```python +def classify_active(branches, unmerged_by_branch, commits): + live_branches = [b for b in branches if unmerged_by_branch[b]] + if live_branches: + return "IN-FLIGHT", f"unmerged commits on {joined}" + if branches: + return "LANDED", f"branch {joined} exists and is fully merged into main" + if commits: + return "LANDED", f"on main: {commits[0]}" + return "ABANDONED", "no branch, no commit on main mentioning the row ID" +``` + +Supporting rules that matter when reading a verdict: + +- **`IN-FLIGHT` beats `LANDED`.** A row can have landed groundwork and still have + open follow-up; calling that finished would silently steal a live claim. +- **ID matching is anchored, never a substring** — + `(^|[^A-Za-z0-9_-])([^A-Za-z0-9_-]|$)`. 55 pairs of live IDs are prefixes of + longer ones, and a substring match would credit the short row with the long + row's commits. +- **`origin/main` must resolve or the tool aborts.** Absence of information must + never look like absence of work; without the guard every row would report + abandoned at once. +- **The `PARTIAL` flag is a keyword heuristic, not a gate.** It reports the marker + that fired so a reviewer can discount a bad hit; `--check` deliberately fails + only on abandoned `ACTIVE` rows. + +### Hand-verified sample + +A classifier wrong on a sample is wrong on all 54, so six rows were checked by +hand before any of this was believed — four the tool called `ABANDONED`, two it +called `LANDED`. For each: `git log --oneline --all --fixed-strings --grep=` +(deliberately BROADER than the tool: all refs, substring match), `git branch -a +--list "*row/"`, and the tool's own anchored `origin/main` query. + +| Row | Tool verdict | `--all --fixed-strings` hits | `row/` branches | Anchored `origin/main` hits | Holds? | +|---|---|---|---|---|---| +| `ENG-MM-AUDIO-ENCODER` | ABANDONED | none | none | none | yes | +| `KERNEL-GDN-SCRATCH` | ABANDONED | none | none | none | yes | +| `BACKEND-DISTRIBUTED-TP` | ABANDONED | none | none | none | yes | +| `QUANT-GGUF-IQ3_XXS` | ABANDONED | none | none | none | yes | +| `BACKEND-MLX` | LANDED | 1 (`d45c8cda`) | none | 1 (`d45c8cda`) | yes | +| `BACKEND-CUDA-OTHER` | LANDED | 1 (`d45c8cda`) | none | 1 (`d45c8cda`) | yes | + +**Outcome: the sample holds, with a caveat that reshapes the whole report.** The +four `ABANDONED` rows have *zero* mentions anywhere in the repository — not on +`origin/main`, not on any other ref, not under a substring match. The verdict is +not a matching artefact; there is genuinely no ID-keyed Git evidence. + +The caveat is on the `LANDED` side. Both sampled `LANDED` rows are credited to +`d45c8cda docs(reconcile): ... (records-only)`, whose entire diff is +`.agents/*`, `README.md` and `docs/BENCHMARKS.md` — **no code**. A record edit +that mentions a row ID satisfies the `LANDED` rule while proving nothing about the +work. `LANDED` therefore means *"has evidence worth reading"*, never *"finished"*. + +## Findings + +### ➀ Verdict distribution + +| Measure | Value | +|---|---| +| Live rows | 188 | +| States | `PARTIAL` 68, `ACTIVE` 54, `SPIKE` 43, `GATING` 10, `BLOCKED` 7, `READY` 6 | +| `ACTIVE` verdicts | LANDED 44, ABANDONED 10 | +| `PARTIAL` rows that do not name their missing modes | 20 of 68 | +| Unique IDs among live rows | 186 (2 IDs live twice) | + +**Zero rows classify `IN-FLIGHT`, and there is no merged-branch evidence anywhere.** +Not one live row has a `row/` branch, local or remote. Every `LANDED` verdict +in this repository rests on the weakest rule in the classifier — a commit message +mentioning the ID. + +### ➁ What the 44 `LANDED` verdicts are actually worth + +All 44 rest on `on main: `. Splitting them by whether that commit +touched code at all: + +- **36 rows** are credited to a commit that touched `src/`, `include/`, + `tests/`, `cmake/` or `scripts/`. That commit *mentions* the row ID; it is not + established here that it implemented the row. +- **8 rows** are credited to a commit whose diff is records and docs ONLY. + For these the "evidence" is somebody editing a record: + + - `BACKEND-CUDA-OTHER` — `d45c8cda` (.agents/feature-matrix.md:276) + - `BACKEND-CUDA-SM087` — `aca8d7d7` (.agents/backend-matrix.md:170) + - `BACKEND-CUDA-SM110` — `b34f9909` (.agents/backend-matrix.md:176) + - `BACKEND-MLX` — `d45c8cda` (.agents/feature-matrix.md:279) + - `KERNEL-GEMM-CPU-ELEM` — `428e20f0` (.agents/kernel-matrix.md:126) + - `MODEL-SPEC` — `d45c8cda` (.agents/feature-matrix.md:154) + - `MODEL-TEXT-deepseek-v2-deepseek-v2-for-causal-lm` — `2ff7252a` (.agents/model-matrix.md:174) + - `MODEL-TEXT-kimi-linear-kimi-linear-for-causal-lm` — `2ff7252a` (.agents/model-matrix.md:219) + +**No row is proposed for a `DONE` downgrade anywhere in this document.** A commit +mention is not a completion proof, and a records-only commit is not even a work +proof. Establishing completion requires a human reading the row's own code/test +anchors against the gate output — outside this audit's reach. + +### ➂ The 10 abandoned `ACTIVE` rows + +No `row/` branch and no commit on `origin/main` naming the ID: + +| Row | Location | Active claims in `coordination.md` | +|---|---|---| +| `BACKEND-DISTRIBUTED-TP` | .agents/backend-matrix.md:273 | `CLAIM-PARALLELISM-MODES-SPIKE`, `CLAIM-SCALE-OUT-SPIKE`, `CLAIM-SCALE-OUT-W2` | +| `ENG-MM-INPUT-PIPELINE` | .agents/engine-matrix.md:72 | `CLAIM-MULTIMODAL-M1` | +| `ENG-MM-VIDEO-FORWARD` | .agents/engine-matrix.md:76 | `CLAIM-MULTIMODAL-M3C`, `CLAIM-MULTIMODAL-TOWER-FIDELITY` | +| `ENG-MM-AUDIO-ENCODER` | .agents/engine-matrix.md:78 | `CLAIM-AUDIO-ENCODER` | +| `KERNEL-GDN-AOT-BF16` | .agents/kernel-matrix.md:154 | `CLAIM-PR3`, `CLAIM-TRITON-AOT-PER-ARCH` | +| `KERNEL-GDN-SCRATCH` | .agents/kernel-matrix.md:155 | `CLAIM-PR3` | +| `MODEL-TEXT-glm4-glm4-for-causal-lm` | .agents/model-matrix.md:195 | `CLAIM-GLM-DSA-LATEST-DEEPSEEK` | +| `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` | .agents/model-matrix.md:380 | `CLAIM-GEMMA4-G1`, `CLAIM-GEMMA4-G1B`, `CLAIM-GEMMA4-G2`, `CLAIM-GEMMA4-G2-IMPL`, `CLAIM-GEMMA4-G3`, `CLAIM-GEMMA4-MM-E2E`, `CLAIM-GEMMA4-MULTIMODAL`, `CLAIM-MULTIMODAL-TRACK` | +| `MODEL-MM-voxtral-voxtral-for-conditional-generation` | .agents/model-matrix.md:458 | `CLAIM-AUDIO-E2E` | +| `QUANT-GGUF-IQ3_XXS` | .agents/quantization-matrix.md:71 | `CLAIM-DEEPSEEK-V4-W8` | + +By matrix: .agents/engine-matrix.md 3, .agents/model-matrix.md 3, .agents/kernel-matrix.md 2, .agents/quantization-matrix.md 1, .agents/backend-matrix.md 1. + +**These rows are not necessarily unstarted work.** Every one of the ten carries +in-row anchors asserting passing gates (`ENG-MM-AUDIO-ENCODER`: "A2 encoder-tower +fidelity gate PASS 203/203"; `MODEL-MM-voxtral-...`: "audio→text e2e gate PASS +14/14"; `BACKEND-DISTRIBUTED-TP`: "CPU multi-rank TP gate 60/60"). What the +verdict establishes is narrower and still damning: **the `ACTIVE` claim is +unverifiable from Git**, because the convention of naming the stable row ID in the +commit message was not followed. The row says it is being worked on; the history +cannot corroborate that anyone ever did. + +### ➃ `PARTIAL` rows that do not say what is missing + +`PARTIAL` asserts partial support. 20 of 68 rows never name the missing +part, so a reader cannot tell what is absent: + +| Row | Location | +|---|---| +| `BACKEND-CUDA-COMP-MARLIN` | .agents/backend-matrix.md:190 | +| `BACKEND-CUDA-COMP-SCALEDMM-C3X` | .agents/backend-matrix.md:194 | +| `BACKEND-CUDA-COMP-FP4` | .agents/backend-matrix.md:197 | +| `ENG-CUDAGRAPH` | .agents/engine-matrix.md:60 | +| `ENG-SCHED-KNOBS` | .agents/engine-matrix.md:67 | +| `TOOLS-STRUCTURED-CORE` | .agents/engine-matrix.md:149 | +| `TOOLS-STRUCTURAL-TAG` | .agents/engine-matrix.md:151 | +| `SERVE-DISCOVERY-HEALTH` | .agents/engine-matrix.md:188 | +| `SERVE-CLI-BENCH` | .agents/engine-matrix.md:198 | +| `LOAD-CONFIG-SURFACE` | .agents/engine-matrix.md:243 | +| `QUANT-VLLM-BREADTH` | .agents/feature-matrix.md:168 | +| `BACKEND-CUDA-SM121` | .agents/feature-matrix.md:275 | +| `BACKEND-CPU` | .agents/feature-matrix.md:277 | +| `KERNEL-ROPE-QKNORM` | .agents/kernel-matrix.md:131 | +| `KERNEL-MOE-UNQUANTIZED` | .agents/kernel-matrix.md:150 | +| `KERNEL-MOE-QUANTIZED` | .agents/kernel-matrix.md:151 | +| `MODEL-TEXT-stablelm-stablelm-for-causal-lm` | .agents/model-matrix.md:267 | +| `QUANT-GGUF-F32` | .agents/quantization-matrix.md:57 | +| `QUANT-MIXED-MODELOPT` | .agents/quantization-matrix.md:129 | +| `QUANT-KV-FP8` | .agents/quantization-matrix.md:158 | + +Marker distribution over all `PARTIAL` rows: + +| Flag | Rows | +|---|---| +| does not name its missing modes | 20 | +| explicit via 'no' | 15 | +| explicit via 'only' | 14 | +| explicit via 'gap' | 5 | +| explicit via 'PENDING' | 4 | +| explicit via 'NO' | 4 | +| explicit via 'pending' | 3 | +| explicit via 'blocked' | 2 | +| explicit via 'absent' | 1 | + +**The true vague count is higher than 20.** Of the 48 rows the flag reads as +explicit, **11** qualify ONLY via a bare `no`/`gap` with no stronger marker +anywhere in the row — and in ten of the eleven the marker fires on prose asserting +GOODNESS, not absence: + +| Row | Location | Prose the marker fired on | Genuine gap statement? | +|---|---|---|---| +| `LOAD-SAFETENSORS` | engine-matrix.md:236 | "the mirror build **no** longer double-resides with the full source mmap" | no — asserts a fix | +| `LOAD-GGUF` | engine-matrix.md:240 | "Pinned vLLM has **no** GGUF loader" | no — describes UPSTREAM's absence, not ours | +| `MODEL-TEXT-internlm2-intern-lm2-for-causal-lm` | model-matrix.md:215 | "max **gap** 0.0 nats, 0 divergent" | no — a passing near-tie metric | +| `QUANT-GGUF-F16` | quantization-matrix.md:58 | "Its speed **gap** ... was CLOSED" | no — asserts a closed gap | +| `QUANT-GGUF-Q4_0` | quantization-matrix.md:59 | "**no** bf16 expansion on the executed path" | no — asserts a good property | +| `QUANT-GGUF-Q8_0` | quantization-matrix.md:63 | "**no** bf16 expansion on the executed path" | no — asserts a good property | +| `QUANT-GGUF-Q3_K` | quantization-matrix.md:65 | "**no** bf16 expansion on the executed path" | no — asserts a good property | +| `QUANT-GGUF-Q4_K` | quantization-matrix.md:66 | "**no** bf16 expansion on the executed path" | no — asserts a good property | +| `QUANT-GGUF-Q5_K` | quantization-matrix.md:67 | "**no** bf16 expansion on the executed path" | no — asserts a good property | +| `QUANT-GGUF-Q6_K` | quantization-matrix.md:68 | "**no** bf16 expansion on the executed path" | no — asserts a good property | +| `MODEL-FACTORY` | feature-matrix.md:150 | "the two-model GPU **no**-regression campaign" | marker is a false hit inside a hyphenated word, but the surrounding prose DOES name an open campaign — the one of eleven that survives | + +So at least **30 of 68** `PARTIAL` rows fail to state their missing modes +(20 flagged outright, 10 passing only on a marker that means the opposite of a +gap). The heuristic UNDER-flags; that is why the report names the marker rather +than printing a bare boolean. The remaining 13 bare-`no`/`gap` first-matches +(`KV-BLOCK-POOL`, `TOOLS-CALLING-CORE`, `MODEL-TEXT-minicpm...`, +`MODEL-TEXT-minicpm3...`, `MODEL-TEXT-mistral...`, `MODEL-TEXT-olmo2...`, +`MODEL-TEXT-phi...`, `MODEL-TEXT-phi3...`, `MODEL-MM-qwen3-vl...`, +`QUANT-GGUF-NVFP4`, `BACKEND-CUDA-COMP-FA`, `BACKEND-CPU`, `MODEL-MM`) also carry +a stronger marker (`absent`, `pending`, `missing`, `only`, `without`) elsewhere in +the row, so their explicit reading does not depend on the weak hit. + +### ➄ Full report + +Verbatim output of `scripts/audit-live-rows.py`: + +| Row | State | Location | Verdict | Evidence | Flag | +|---|---|---|---|---|---| +| `KV-PREFIX-MATCH-UNIT` | `PARTIAL` | .agents/engine-matrix.md:58 | - | - | explicit via 'absent' | +| `ENG-CUDAGRAPH` | `PARTIAL` | .agents/engine-matrix.md:60 | - | - | does not name its missing modes | +| `ENG-PRIORITY-SCHED` | `GATING` | .agents/engine-matrix.md:63 | - | - | - | +| `ENG-CORE-BUSY-LOOP` | `GATING` | .agents/engine-matrix.md:66 | - | - | - | +| `ENG-SCHED-KNOBS` | `PARTIAL` | .agents/engine-matrix.md:67 | - | - | does not name its missing modes | +| `ENG-CASCADE-ATTN` | `SPIKE` | .agents/engine-matrix.md:68 | - | - | - | +| `ENG-RUNNER-MODELSHAPE` | `ACTIVE` | .agents/engine-matrix.md:71 | LANDED | on main: 5ab3f111 docs(record): anchor backfill batch 1 — 12 engine rows made precise, 10 more leave ACTIVE | - | +| `ENG-MM-INPUT-PIPELINE` | `ACTIVE` | .agents/engine-matrix.md:72 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `ENG-MM-VISION-TOWER` | `ACTIVE` | .agents/engine-matrix.md:73 | LANDED | on main: d796187a docs(record): anchor backfill batch 4 — manual pass, 11 hand-verified anchors and the real blocker named | - | +| `ENG-MM-TEXT-BACKBONE` | `ACTIVE` | .agents/engine-matrix.md:74 | LANDED | on main: 2a8ff336 feat(multimodal): M2b/M2c — Qwen3-VL text-backbone numeric contracts unit-green vs vLLM 0.25.0 | - | +| `ENG-MM-QWEN36-VL-FORWARD` | `ACTIVE` | .agents/engine-matrix.md:75 | LANDED | on main: e89d51d8 feat(mm-speed): Qwen VISION-FORWARD — §14 flash kernel extended to the tower (byte-exact); ATTRIBUTION REFUTES the assumed lever, tower already BEATS vLLM (CLAIM-MM-SPEED-QWEN-IMAGE) | - | +| `ENG-MM-VIDEO-FORWARD` | `ACTIVE` | .agents/engine-matrix.md:76 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `ENG-MM-AUDIO-PIPELINE` | `ACTIVE` | .agents/engine-matrix.md:77 | LANDED | on main: adcac8e6 feat(multimodal): AUDIO track A0+A1 — audio INPUT pipeline on whisper-small, feature-parity gate PASS 77/77 | - | +| `ENG-MM-AUDIO-ENCODER` | `ACTIVE` | .agents/engine-matrix.md:78 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `ENG-MM-AUDIO-E2E` | `ACTIVE` | .agents/engine-matrix.md:79 | LANDED | on main: 9e34a19c perf(mm): ROAD-V1-MM lever #3 — ADOPT FA2 varlen as Voxtral audio decode; BEATS vLLM (0.97x), closes the LAST mm decode-speed gap | - | +| `KV-BLOCK-POOL` | `PARTIAL` | .agents/engine-matrix.md:92 | - | - | explicit via 'gap' | +| `KV-HYBRID-COORD` | `PARTIAL` | .agents/engine-matrix.md:95 | - | - | explicit via 'only' | +| `KV-MAMBA-ALIGN` | `SPIKE` | .agents/engine-matrix.md:96 | - | - | - | +| `KV-SLIDING-LOCAL-SPECS` | `READY` | .agents/engine-matrix.md:97 | - | - | - | +| `KV-SLIDING-WINDOW-SPEC` | `GATING` | .agents/engine-matrix.md:98 | - | - | - | +| `KV-CHUNKED-LOCAL-SPEC` | `GATING` | .agents/engine-matrix.md:99 | - | - | - | +| `KV-EVENTS` | `ACTIVE` | .agents/engine-matrix.md:105 | LANDED | on main: d796187a docs(record): anchor backfill batch 4 — manual pass, 11 hand-verified anchors and the real blocker named | - | +| `KV-SIZING` | `PARTIAL` | .agents/engine-matrix.md:108 | - | - | explicit via 'only' | +| `ENG-EXPERT-STREAM` | `READY` | .agents/engine-matrix.md:110 | - | - | - | +| `PAR-TP` | `READY` | .agents/engine-matrix.md:118 | - | - | - | +| `SAMPLE-PROMPT-LOGPROBS` | `PARTIAL` | .agents/engine-matrix.md:132 | - | - | explicit via 'pending' | +| `SERVE-COMPLETION-LONGTAIL` | `PARTIAL` | .agents/engine-matrix.md:135 | - | - | explicit via 'only' | +| `SAMPLE-BEAM` | `ACTIVE` | .agents/engine-matrix.md:136 | LANDED | on main: 0151314f feat(serve): async/production beam search (SAMPLE-BEAM) — BeamSearchAsync over AsyncLLM, token-identical to sync; C7 CLAIM-C7-BEAM-ASYNC | - | +| `SAMPLE-N` | `ACTIVE` | .agents/engine-matrix.md:142 | LANDED | on main: aed4718e feat(serve): best_of + use_beam_search OpenAI-endpoint surface — C7 SAMPLE-BEST-OF + SAMPLE-BEAM endpoint | - | +| `SAMPLE-BEST-OF` | `ACTIVE` | .agents/engine-matrix.md:143 | LANDED | on main: aed4718e feat(serve): best_of + use_beam_search OpenAI-endpoint surface — C7 SAMPLE-BEST-OF + SAMPLE-BEAM endpoint | - | +| `TOOLS-STRUCTURED-CORE` | `PARTIAL` | .agents/engine-matrix.md:149 | - | - | does not name its missing modes | +| `TOOLS-XGRAMMAR` | `ACTIVE` | .agents/engine-matrix.md:150 | LANDED | on main: d796187a docs(record): anchor backfill batch 4 — manual pass, 11 hand-verified anchors and the real blocker named | - | +| `TOOLS-STRUCTURAL-TAG` | `PARTIAL` | .agents/engine-matrix.md:151 | - | - | does not name its missing modes | +| `TOOLS-CALLING-CORE` | `PARTIAL` | .agents/engine-matrix.md:153 | - | - | explicit via 'no' | +| `TOOLS-STREAMING-PARSER` | `ACTIVE` | .agents/engine-matrix.md:154 | LANDED | on main: 05237562 feat(parser): JSON-schema tool-arg type coercion (_fix_arg_types) — ROAD-V1-C8 residual CLOSED | - | +| `SPEC-REJECTION` | `ACTIVE` | .agents/engine-matrix.md:164 | LANDED | on main: dfa610b2 feat(spec-decode): generic separate draft-model proposer (SPEC-DRAFT-MODEL) — W0 spike + W1 CPU greedy propose brick; Medusa spiked (SPEC-MEDUSA) | - | +| `SPEC-GDN-SEGMENTS` | `ACTIVE` | .agents/engine-matrix.md:165 | LANDED | on main: 3ae5cfe0 feat(spec-decode): SPEC-MTP I5a — GDN layer spec routing + runner spec-metadata upload | - | +| `SPEC-NGRAM` | `ACTIVE` | .agents/engine-matrix.md:169 | LANDED | on main: d796187a docs(record): anchor backfill batch 4 — manual pass, 11 hand-verified anchors and the real blocker named | - | +| `SPEC-EAGLE3` | `BLOCKED` | .agents/engine-matrix.md:170 | - | - | - | +| `SPEC-DRAFT-MODEL` | `ACTIVE` | .agents/engine-matrix.md:180 | LANDED | on main: dfa610b2 feat(spec-decode): generic separate draft-model proposer (SPEC-DRAFT-MODEL) — W0 spike + W1 CPU greedy propose brick; Medusa spiked (SPEC-MEDUSA) | - | +| `SPEC-MEDUSA` | `SPIKE` | .agents/engine-matrix.md:181 | - | - | - | +| `SERVE-DISCOVERY-HEALTH` | `PARTIAL` | .agents/engine-matrix.md:188 | - | - | does not name its missing modes | +| `SERVE-STREAM-USAGE` | `GATING` | .agents/engine-matrix.md:191 | - | - | - | +| `SERVE-ASYNC-LLM` | `GATING` | .agents/engine-matrix.md:194 | - | - | - | +| `SERVE-CLI-BENCH` | `PARTIAL` | .agents/engine-matrix.md:198 | - | - | does not name its missing modes | +| `SERVE-POOLING-ENDPOINTS` | `SPIKE` | .agents/engine-matrix.md:202 | - | - | - | +| `ENG-POOLER-SEQ` | `ACTIVE` | .agents/engine-matrix.md:203 | LANDED | on main: 2191f771 feat(pooling): W2 pooler HEADS composite + W3 pooling RUNNER path (CLAIM-POOLING) — CPU-gated, RED-first | - | +| `ENG-POOLING-RUNNER` | `ACTIVE` | .agents/engine-matrix.md:204 | LANDED | on main: 2191f771 feat(pooling): W2 pooler HEADS composite + W3 pooling RUNNER path (CLAIM-POOLING) — CPU-gated, RED-first | - | +| `ATTN-ROPE-FAMILY` | `READY` | .agents/engine-matrix.md:222 | - | - | - | +| `ATTN-CHUNKED-LOCAL` | `GATING` | .agents/engine-matrix.md:227 | - | - | - | +| `LOAD-SAFETENSORS` | `PARTIAL` | .agents/engine-matrix.md:236 | - | - | explicit via 'no' | +| `LOAD-SAFETENSORS-DIRECT-DENSE` | `GATING` | .agents/engine-matrix.md:237 | - | - | - | +| `LOAD-GGUF` | `PARTIAL` | .agents/engine-matrix.md:240 | - | - | explicit via 'no' | +| `LOAD-CONFIG-SURFACE` | `PARTIAL` | .agents/engine-matrix.md:243 | - | - | does not name its missing modes | +| `MODEL-FACTORY-registry` | `GATING` | .agents/model-matrix.md:152 | - | - | - | +| `MODEL-TEXT-chatglm-chat-glmfor-causal-lm` | `SPIKE` | .agents/model-matrix.md:167 | - | - | - | +| `MODEL-TEXT-commandr-cohere-for-causal-lm` | `BLOCKED` | .agents/model-matrix.md:168 | - | - | - | +| `MODEL-TEXT-llama-llama-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:170 | - | - | explicit via 'PENDING' | +| `MODEL-TEXT-deepseek-v2-deepseek-for-causal-lm` | `SPIKE` | .agents/model-matrix.md:173 | - | - | - | +| `MODEL-TEXT-deepseek-v2-deepseek-v2-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:174 | LANDED | on main: 2ff7252a docs(mla): campaign W10 — the blocked-row honesty pass; the W-plan is COMPLETE, the block is NOT closeable | - | +| `MODEL-TEXT-deepseek-v2-deepseek-v3-for-causal-lm` | `BLOCKED` | .agents/model-matrix.md:175 | - | - | - | +| `MODEL-TEXT-deepseek-v4-deepseek-v4-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:176 | LANDED | on main: ee3d5960 spike(model): DeepSeek-V4 (DeepseekV4ForCausalLM) W1/W2 — registry stub + config parse + loader VERIFIED vs real NVFP4 header; HW-fit REVERSAL (156.7 GiB, does not fit GB10) | - | +| `MODEL-TEXT-gemma-gemma-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:187 | - | - | explicit via 'only' | +| `MODEL-TEXT-gemma2-gemma2-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:188 | - | - | explicit via 'PENDING' | +| `MODEL-TEXT-gemma3-gemma3-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:189 | - | - | explicit via 'PENDING' | +| `MODEL-TEXT-gemma4-gemma4-for-causal-lm` | `BLOCKED` | .agents/model-matrix.md:192 | - | - | - | +| `MODEL-TEXT-glm-glm-for-causal-lm` | `SPIKE` | .agents/model-matrix.md:194 | - | - | - | +| `MODEL-TEXT-glm4-glm4-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:195 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `MODEL-TEXT-glm4-moe-glm4-moe-for-causal-lm` | `SPIKE` | .agents/model-matrix.md:196 | - | - | - | +| `MODEL-TEXT-glm4-moe-lite-glm4-moe-lite-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:197 | LANDED | on main: d85fd04f feat(model): Glm4MoeLiteForCausalLM (GLM-4.7-Flash) G1 — SACRED gate 8/8 vs vLLM 0.25.0; closes the MLA campaign's q_lora + noaux_tc coverage gaps | - | +| `MODEL-TEXT-deepseek-v2-glm-moe-dsa-for-causal-lm` | `BLOCKED` | .agents/model-matrix.md:198 | - | - | - | +| `MODEL-TEXT-granite-granite-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:203 | - | - | explicit via 'pending' | +| `MODEL-TEXT-internlm2-intern-lm2-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:215 | - | - | explicit via 'gap' | +| `MODEL-TEXT-kimi-linear-kimi-linear-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:219 | LANDED | on main: 2ff7252a docs(mla): campaign W10 — the blocked-row honesty pass; the W-plan is COMPLETE, the block is NOT closeable | - | +| `MODEL-TEXT-laguna-laguna-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:222 | LANDED | on main: bfaea5cb feat(model): Laguna-S-2.1 W4 — fetch UD-Q4_K GGUF + 3 fidelity corrections from the real bytes | - | +| `MODEL-TEXT-minicpm-mini-cpmfor-causal-lm` | `PARTIAL` | .agents/model-matrix.md:227 | - | - | explicit via 'NO' | +| `MODEL-TEXT-minicpm3-mini-cpm3-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:228 | - | - | explicit via 'no' | +| `MODEL-TEXT-minimax-m2-mini-max-m2-for-causal-lm` | `BLOCKED` | .agents/model-matrix.md:229 | - | - | - | +| `MODEL-TEXT-mistral-mistral-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:231 | - | - | explicit via 'NO' | +| `MODEL-TEXT-olmo2-olmo2-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:241 | - | - | explicit via 'NO' | +| `MODEL-TEXT-opt-optfor-causal-lm` | `PARTIAL` | .agents/model-matrix.md:244 | - | - | explicit via 'PENDING' | +| `MODEL-TEXT-phi-phi-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:252 | - | - | explicit via 'NO' | +| `MODEL-TEXT-phi3-phi3-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:253 | - | - | explicit via 'gap' | +| `MODEL-TEXT-qwen3-qwen3-for-causal-lm` | `ACTIVE` | .agents/model-matrix.md:259 | LANDED | on main: 6eee4437 fix(quant): Qwen3-32B-NVFP4A16 W4A16 — teacher-forcing PROVES the 4/6 is bf16 near-tie drift, not our defect; gate closes 6/6 | - | +| `MODEL-TEXT-qwen3-moe-qwen3-moe-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:260 | - | - | explicit via 'only' | +| `MODEL-TEXT-stablelm-stablelm-for-causal-lm` | `PARTIAL` | .agents/model-matrix.md:267 | - | - | does not name its missing modes | +| `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` | `ACTIVE` | .agents/model-matrix.md:380 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `MODEL-MM-gemma4-unified-gemma4-unified-for-conditional-generation` | `SPIKE` | .agents/model-matrix.md:381 | - | - | - | +| `MODEL-MM-kimi-k3-kimi-k3-for-conditional-generation` | `SPIKE` | .agents/model-matrix.md:404 | - | - | - | +| `MODEL-MM-qwen3-vl-qwen3-vlfor-conditional-generation` | `PARTIAL` | .agents/model-matrix.md:447 | - | - | explicit via 'gap' | +| `MODEL-MM-qwen3-5-qwen3-5-for-conditional-generation` | `PARTIAL` | .agents/model-matrix.md:449 | - | - | explicit via 'only' | +| `MODEL-MM-qwen3-5-qwen3-5-moe-for-conditional-generation` | `PARTIAL` | .agents/model-matrix.md:450 | - | - | explicit via 'only' | +| `MODEL-MM-voxtral-voxtral-for-conditional-generation` | `ACTIVE` | .agents/model-matrix.md:458 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `MODEL-SPEC-deepseek-v4-deep-seek-v4-mtp` | `ACTIVE` | .agents/model-matrix.md:487 | LANDED | on main: 28b5e866 feat(model): DeepSeek-V4 native MTP self-speculative draft head — W1 wiring (loader + draft forward + lossless gate) | - | +| `QUANT-GGUF-COMPUTE` | `READY` | .agents/quantization-matrix.md:33 | - | - | - | +| `QUANT-GGUF-F32` | `PARTIAL` | .agents/quantization-matrix.md:57 | - | - | does not name its missing modes | +| `QUANT-GGUF-F16` | `PARTIAL` | .agents/quantization-matrix.md:58 | - | - | explicit via 'gap' | +| `QUANT-GGUF-Q4_0` | `PARTIAL` | .agents/quantization-matrix.md:59 | - | - | explicit via 'no' | +| `QUANT-GGUF-Q8_0` | `PARTIAL` | .agents/quantization-matrix.md:63 | - | - | explicit via 'no' | +| `QUANT-GGUF-Q2_K` | `ACTIVE` | .agents/quantization-matrix.md:64 | LANDED | on main: d0bc0f41 feat(gguf): IQ2_XXS + Q2_K dequant — DeepSeek-V4-Flash single-Spark GGUF quant-path (W1) | - | +| `QUANT-GGUF-Q3_K` | `PARTIAL` | .agents/quantization-matrix.md:65 | - | - | explicit via 'no' | +| `QUANT-GGUF-Q4_K` | `PARTIAL` | .agents/quantization-matrix.md:66 | - | - | explicit via 'no' | +| `QUANT-GGUF-Q5_K` | `PARTIAL` | .agents/quantization-matrix.md:67 | - | - | explicit via 'no' | +| `QUANT-GGUF-Q6_K` | `PARTIAL` | .agents/quantization-matrix.md:68 | - | - | explicit via 'no' | +| `QUANT-GGUF-IQ2_XXS` | `ACTIVE` | .agents/quantization-matrix.md:69 | LANDED | on main: d0bc0f41 feat(gguf): IQ2_XXS + Q2_K dequant — DeepSeek-V4-Flash single-Spark GGUF quant-path (W1) | - | +| `QUANT-GGUF-IQ3_XXS` | `ACTIVE` | .agents/quantization-matrix.md:71 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `QUANT-GGUF-NVFP4` | `PARTIAL` | .agents/quantization-matrix.md:82 | - | - | explicit via 'no' | +| `QUANT-NVFP4-CT-W4A16` | `ACTIVE` | .agents/quantization-matrix.md:122 | LANDED | on main: 80d1da09 feat(quant): Qwen3-32B-NVFP4A16 (compressed-tensors W4A16) — quant-scheme additivity; strict gate GATING 4/6 | - | +| `QUANT-FP8-GENERIC` | `PARTIAL` | .agents/quantization-matrix.md:125 | - | - | explicit via 'only' | +| `QUANT-MIXED-MODELOPT` | `PARTIAL` | .agents/quantization-matrix.md:129 | - | - | does not name its missing modes | +| `QUANT-KV-FP8` | `PARTIAL` | .agents/quantization-matrix.md:158 | - | - | does not name its missing modes | +| `KERNEL-ACCEL-PROVIDER-SELECT` | `ACTIVE` | .agents/kernel-matrix.md:115 | LANDED | on main: 3a2d05d8 feat(backend): vt::OpProvider acceleration seam + MLX GEMM provider on Metal | - | +| `KERNEL-GEMM-CPU-ELEM` | `ACTIVE` | .agents/kernel-matrix.md:126 | LANDED | on main: 428e20f0 docs(roadmap): correct C4 punch-list — GGUF CPU decode is at parity, not a 10x-open blocker | - | +| `KERNEL-QUANT-CIQ-IQUANT` | `SPIKE` | .agents/kernel-matrix.md:127 | - | - | - | +| `KERNEL-QUANT-CIQ-GEMM-CUDA` | `ACTIVE` | .agents/kernel-matrix.md:128 | LANDED | on main: 3fb3149f feat(cuda): keep-quant GGUF k-quant GEMM (kCUDA kMatmulBTQuant) — DeepSeek-V4 experts on the GPU | - | +| `KERNEL-EW-NORM-QUANT` | `PARTIAL` | .agents/kernel-matrix.md:130 | - | - | explicit via 'only' | +| `KERNEL-ROPE-QKNORM` | `PARTIAL` | .agents/kernel-matrix.md:131 | - | - | does not name its missing modes | +| `KERNEL-ATTN-MLA-SPARSE` | `PARTIAL` | .agents/kernel-matrix.md:139 | - | - | explicit via 'only' | +| `KERNEL-ATTN-DSA-SPARSE-INDEX` | `SPIKE` | .agents/kernel-matrix.md:142 | - | - | - | +| `KERNEL-ATTN-DSA-COMPRESSOR` | `SPIKE` | .agents/kernel-matrix.md:143 | - | - | - | +| `KERNEL-MHC-SINKHORN` | `SPIKE` | .agents/kernel-matrix.md:144 | - | - | - | +| `KERNEL-MOE-SQRTSOFTPLUS-HASH` | `SPIKE` | .agents/kernel-matrix.md:145 | - | - | - | +| `KERNEL-DSV4-W7-DEVICE` | `SPIKE` | .agents/kernel-matrix.md:146 | - | - | - | +| `KERNEL-KDA-DELTA` | `SPIKE` | .agents/kernel-matrix.md:147 | - | - | - | +| `KERNEL-ATTN-DENSE-FLASH` | `ACTIVE` | .agents/kernel-matrix.md:148 | LANDED | on main: e89d51d8 feat(mm-speed): Qwen VISION-FORWARD — §14 flash kernel extended to the tower (byte-exact); ATTRIBUTION REFUTES the assumed lever, tower already BEATS vLLM (CLAIM-MM-SPEED-QWEN-IMAGE) | - | +| `KERNEL-MOE-UNQUANTIZED` | `PARTIAL` | .agents/kernel-matrix.md:150 | - | - | does not name its missing modes | +| `KERNEL-MOE-QUANTIZED` | `PARTIAL` | .agents/kernel-matrix.md:151 | - | - | does not name its missing modes | +| `KERNEL-GDN-AOT-BF16` | `ACTIVE` | .agents/kernel-matrix.md:154 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `KERNEL-GDN-SCRATCH` | `ACTIVE` | .agents/kernel-matrix.md:155 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `BACKEND-CUDA-SM060` | `SPIKE` | .agents/backend-matrix.md:164 | - | - | - | +| `BACKEND-CUDA-SM061` | `SPIKE` | .agents/backend-matrix.md:165 | - | - | - | +| `BACKEND-CUDA-SM070` | `SPIKE` | .agents/backend-matrix.md:166 | - | - | - | +| `BACKEND-CUDA-SM075` | `SPIKE` | .agents/backend-matrix.md:167 | - | - | - | +| `BACKEND-CUDA-SM080` | `SPIKE` | .agents/backend-matrix.md:168 | - | - | - | +| `BACKEND-CUDA-SM086` | `SPIKE` | .agents/backend-matrix.md:169 | - | - | - | +| `BACKEND-CUDA-SM087` | `ACTIVE` | .agents/backend-matrix.md:170 | LANDED | on main: aca8d7d7 feat(cuda-arch): Orin sm_87 RUNTIME gate — BACKEND-CUDA-SM087 portable bf16 SYNC path RUNTIME-VERIFIED (13/16 strict vs vLLM, 2nd non-GB10 proof) | - | +| `BACKEND-CUDA-SM089` | `SPIKE` | .agents/backend-matrix.md:171 | - | - | - | +| `BACKEND-CUDA-SM090` | `SPIKE` | .agents/backend-matrix.md:172 | - | - | - | +| `BACKEND-CUDA-SM100` | `SPIKE` | .agents/backend-matrix.md:173 | - | - | - | +| `BACKEND-CUDA-SM103` | `SPIKE` | .agents/backend-matrix.md:175 | - | - | - | +| `BACKEND-CUDA-SM110` | `ACTIVE` | .agents/backend-matrix.md:176 | LANDED | on main: b34f9909 feat(cuda): sm_110 (Jetson Thor) portable path RUNTIME-VERIFIED — first non-GB10 runtime proof | - | +| `BACKEND-CUDA-SM120` | `ACTIVE` | .agents/backend-matrix.md:177 | LANDED | on main: 88a0b869 feat(backend): sm_120a (consumer Blackwell) — BUILD-supported CUDA target, first arch through the additive seams | - | +| `BACKEND-CUDA-SM121` | `PARTIAL` | .agents/backend-matrix.md:178 | - | - | explicit via 'only' | +| `BACKEND-CUDA-ARCH-ADDITIVITY` | `ACTIVE` | .agents/backend-matrix.md:187 | LANDED | on main: 8a379182 feat(cuda-arch): cross-family BUILD-SUPPORTED fan-out (W10) — sm_80/86/87/89, sm_100a/103a, sm_110 portable-only; sm_70/75/101a scoped | - | +| `BACKEND-CUDA-COMP-CORE` | `PARTIAL` | .agents/backend-matrix.md:188 | - | - | explicit via 'only' | +| `BACKEND-CUDA-COMP-MARLIN` | `PARTIAL` | .agents/backend-matrix.md:190 | - | - | does not name its missing modes | +| `BACKEND-CUDA-COMP-MACHETE` | `SPIKE` | .agents/backend-matrix.md:191 | - | - | - | +| `BACKEND-CUDA-COMP-DSV3` | `SPIKE` | .agents/backend-matrix.md:192 | - | - | - | +| `BACKEND-CUDA-COMP-ALLSPARK` | `SPIKE` | .agents/backend-matrix.md:193 | - | - | - | +| `BACKEND-CUDA-COMP-SCALEDMM-C3X` | `PARTIAL` | .agents/backend-matrix.md:194 | - | - | does not name its missing modes | +| `BACKEND-CUDA-COMP-SCALEDMM-C2X` | `SPIKE` | .agents/backend-matrix.md:195 | - | - | - | +| `BACKEND-CUDA-COMP-MOE-CUTLASS` | `SPIKE` | .agents/backend-matrix.md:196 | - | - | - | +| `BACKEND-CUDA-COMP-FP4` | `PARTIAL` | .agents/backend-matrix.md:197 | - | - | does not name its missing modes | +| `BACKEND-CUDA-COMP-W4A8` | `SPIKE` | .agents/backend-matrix.md:198 | - | - | - | +| `BACKEND-CUDA-COMP-MLA` | `SPIKE` | .agents/backend-matrix.md:199 | - | - | - | +| `BACKEND-CUDA-COMP-FLASHMLA` | `SPIKE` | .agents/backend-matrix.md:212 | - | - | - | +| `BACKEND-CUDA-COMP-DEEPGEMM` | `SPIKE` | .agents/backend-matrix.md:213 | - | - | - | +| `BACKEND-CUDA-COMP-FA` | `PARTIAL` | .agents/backend-matrix.md:215 | - | - | explicit via 'no' | +| `BACKEND-CUDA-COMP-JIT` | `PARTIAL` | .agents/backend-matrix.md:216 | - | - | explicit via 'only' | +| `BACKEND-CPU` | `PARTIAL` | .agents/backend-matrix.md:226 | - | - | explicit via 'no' | +| `BACKEND-XPU` | `SPIKE` | .agents/backend-matrix.md:229 | - | - | - | +| `BACKEND-ACCEL-PROVIDER` | `ACTIVE` | .agents/backend-matrix.md:231 | LANDED | on main: 3a2d05d8 feat(backend): vt::OpProvider acceleration seam + MLX GEMM provider on Metal | - | +| `BACKEND-METAL-MLX` | `ACTIVE` | .agents/backend-matrix.md:232 | LANDED | on main: c351dff2 feat(model): Qwen3-dense (Qwen3ForCausalLM) on Metal — SECOND non-CUDA model, SACRED gate 16/16 + first ours-vs-MLX benchmark (INDICATIVE) | - | +| `BACKEND-VULKAN` | `ACTIVE` | .agents/backend-matrix.md:233 | LANDED | on main: 1cb5f643 feat(backend): Vulkan W0/V1 — vt::Backend/Platform skeleton with committed SPIR-V compute (BACKEND-VULKAN SPIKE->ACTIVE) | - | +| `BACKEND-GATE-CUDA-VLLM` | `PARTIAL` | .agents/backend-matrix.md:244 | - | - | explicit via 'blocked' | +| `BACKEND-BENCH-CUDA-SGLANG-PREFLIGHT` | `GATING` | .agents/backend-matrix.md:245 | - | - | - | +| `BACKEND-GATE-CUDA-SGLANG` | `BLOCKED` | .agents/backend-matrix.md:246 | - | - | - | +| `BACKEND-GATE-CUDA-SGLANG-PREFIX` | `READY` | .agents/backend-matrix.md:247 | - | - | - | +| `BACKEND-GATE-METAL-MLXLM` | `ACTIVE` | .agents/backend-matrix.md:254 | LANDED | on main: 41d7f8d7 test(metal): pin the S5 reference-tier contract, and record the MLX provider A/B | - | +| `BACKEND-DISTRIBUTED-COMM` | `ACTIVE` | .agents/backend-matrix.md:272 | LANDED | on main: 9b516ab2 feat(scale-out): W1 vt::Communicator + CPU collective gate — BACKEND-DISTRIBUTED-COMM SPIKE→ACTIVE | - | +| `BACKEND-DISTRIBUTED-TP` | `ACTIVE` | .agents/backend-matrix.md:273 | ABANDONED | no branch, no commit on main mentioning the row ID | - | +| `BACKEND-DISTRIBUTED-PP` | `SPIKE` | .agents/backend-matrix.md:274 | - | - | - | +| `BACKEND-DISTRIBUTED-DP` | `SPIKE` | .agents/backend-matrix.md:275 | - | - | - | +| `BACKEND-DISTRIBUTED-EP` | `SPIKE` | .agents/backend-matrix.md:276 | - | - | - | +| `BACKEND-DISTRIBUTED-SP` | `SPIKE` | .agents/backend-matrix.md:277 | - | - | - | +| `BACKEND-DISTRIBUTED-MULTINODE-SPARK` | `SPIKE` | .agents/backend-matrix.md:278 | - | - | - | +| `BACKEND-DISTRIBUTED-MLX-RING` | `SPIKE` | .agents/backend-matrix.md:279 | - | - | - | +| `MODEL-GATE-QWEN35` | `PARTIAL` | .agents/feature-matrix.md:149 | - | - | explicit via 'pending' | +| `MODEL-FACTORY` | `PARTIAL` | .agents/feature-matrix.md:150 | - | - | explicit via 'no' | +| `MODEL-TEXT` | `PARTIAL` | .agents/feature-matrix.md:151 | - | - | explicit via 'blocked' | +| `MODEL-MM` | `PARTIAL` | .agents/feature-matrix.md:153 | - | - | explicit via 'no' | +| `MODEL-SPEC` | `ACTIVE` | .agents/feature-matrix.md:154 | LANDED | on main: d45c8cda docs(reconcile): fix behind/stale drift across records to match code state (records-only) | - | +| `QUANT-GGUF` | `PARTIAL` | .agents/feature-matrix.md:167 | - | - | explicit via 'only' | +| `QUANT-VLLM-BREADTH` | `PARTIAL` | .agents/feature-matrix.md:168 | - | - | does not name its missing modes | +| `BACKEND-CUDA-SM121` | `PARTIAL` | .agents/feature-matrix.md:275 | - | - | does not name its missing modes | +| `BACKEND-CUDA-OTHER` | `ACTIVE` | .agents/feature-matrix.md:276 | LANDED | on main: d45c8cda docs(reconcile): fix behind/stale drift across records to match code state (records-only) | - | +| `BACKEND-CPU` | `PARTIAL` | .agents/feature-matrix.md:277 | - | - | does not name its missing modes | +| `BACKEND-MLX` | `ACTIVE` | .agents/feature-matrix.md:279 | LANDED | on main: d45c8cda docs(reconcile): fix behind/stale drift across records to match code state (records-only) | - | + +## Proposed corrections + +### The legality rule + +`scripts/check-agent-record.py` enforces state contracts, so an illegal target +breaks the build: + +- `READY`, `ACTIVE`, `GATING`, `DONE`, `BLOCKED` (`READY_STATES`) require a real + `.agents/specs/.md` link that resolves, names the exact token `` `` ``, + and carries the structured spec sections. +- `PARTIAL`, `ANCHOR-BACKFILL`, `GATING`, `DONE`, `BUILD-ONLY`, `UNTRACED` + (`EVIDENCED_STATES`) require resolving code AND test/evidence anchors. +- `SPIKE` and `ACTIVE` require a `CLAIM-*` owner that claims the row in + `coordination.md`; conversely `coordination.md` may only reference rows in state + `SPIKE` or `ACTIVE` (`check_row_contracts`, "references {id} in state X, not + SPIKE/ACTIVE"). + +Therefore an abandoned `ACTIVE` row goes to `READY` if it has a real spec link and +to `INVENTORIED` otherwise. It may never simply be blanked. + +### Per-row legality determination + +Every one of the ten was checked with the checker's own `local_spec_paths` + +`check_spec`. **All ten resolve to a real spec that names their exact token and +passes the structured-section requirement, so all ten are legal at `READY` and +none needs `INVENTORIED`:** + +| Row | Spec cell | Resolves | Names `` `` `` | Legal target | +|---|---|---|---|---| +| `BACKEND-DISTRIBUTED-TP` | `specs/scale-out-distributed.md` | yes | yes | `READY` | +| `ENG-MM-INPUT-PIPELINE` | `specs/multimodal-track.md` §3 (M0/M1) | yes | yes | `READY` | +| `ENG-MM-VIDEO-FORWARD` | `specs/multimodal-track.md` §M3 (M3c) | yes | yes | `READY` | +| `ENG-MM-AUDIO-ENCODER` | `specs/audio-track.md` §0b (A2) | yes | yes | `READY` | +| `KERNEL-GDN-AOT-BF16` | `specs/kernel-family-inventory.md` | yes | yes | `READY` | +| `KERNEL-GDN-SCRATCH` | `specs/kernel-family-inventory.md` | yes | yes | `READY` | +| `MODEL-TEXT-glm4-glm4-for-causal-lm` | `specs/glm-dsa-latest-deepseek.md` | yes | yes | `READY` | +| `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` | `specs/gemma4-multimodal.md` §G1b (+ `specs/sweep-gemma.md`) | yes | yes | `READY` | +| `MODEL-MM-voxtral-voxtral-for-conditional-generation` | `specs/audio-track.md` §0c/§1 (A3) | yes | yes | `READY` | +| `QUANT-GGUF-IQ3_XXS` | `specs/cuda-keepquant-gemm.md`; `specs/gguf-iquant-dsv4.md` | yes | yes | `READY` | + +For `MODEL-MM-gemma4-...` and `QUANT-GGUF-IQ3_XXS` only ONE of the two linked +specs names the token (`gemma4-multimodal.md` and `gguf-iquant-dsv4.md` +respectively); `check_spec` is satisfied by any one match, so both are legal. + +### The coupled obligation nobody can skip + +`READY` is not in `{SPIKE, ACTIVE}`, so leaving the row inside an active claim +turns the transition RED. **Every one of the ten is referenced by at least one +active claim**, and several by many, so each correction must retire or amend the +claim in `coordination.md` in the SAME change: + +| Row | Claims that must be amended | +|---|---| +| `BACKEND-DISTRIBUTED-TP` | `CLAIM-PARALLELISM-MODES-SPIKE`, `CLAIM-SCALE-OUT-SPIKE`, `CLAIM-SCALE-OUT-W2` | +| `ENG-MM-AUDIO-ENCODER` | `CLAIM-AUDIO-ENCODER` | +| `ENG-MM-INPUT-PIPELINE` | `CLAIM-MULTIMODAL-M1` | +| `ENG-MM-VIDEO-FORWARD` | `CLAIM-MULTIMODAL-M3C`, `CLAIM-MULTIMODAL-TOWER-FIDELITY` | +| `KERNEL-GDN-AOT-BF16` | `CLAIM-PR3`, `CLAIM-TRITON-AOT-PER-ARCH` | +| `KERNEL-GDN-SCRATCH` | `CLAIM-PR3` | +| `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` | `CLAIM-GEMMA4-G1`, `CLAIM-GEMMA4-G1B`, `CLAIM-GEMMA4-G2`, `CLAIM-GEMMA4-G2-IMPL`, `CLAIM-GEMMA4-G3`, `CLAIM-GEMMA4-MM-E2E`, `CLAIM-GEMMA4-MULTIMODAL`, `CLAIM-MULTIMODAL-TRACK` | +| `MODEL-MM-voxtral-voxtral-for-conditional-generation` | `CLAIM-AUDIO-E2E` | +| `MODEL-TEXT-glm4-glm4-for-causal-lm` | `CLAIM-GLM-DSA-LATEST-DEEPSEEK` | +| `QUANT-GGUF-IQ3_XXS` | `CLAIM-DEEPSEEK-V4-W8` | + +`MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` alone is claimed by EIGHT +live claims (`CLAIM-GEMMA4-G1`, `-G1B`, `-G2`, `-G2-IMPL`, `-G3`, `-MM-E2E`, +`-MULTIMODAL`, and `CLAIM-MULTIMODAL-TRACK`) — the same rot in a second surface. +`BACKEND-DISTRIBUTED-TP` is claimed by three; `coordination.md` carries 110 active +claim entries in total. + +Note the second half of the same contract: `check_row_contracts` also fails an +active claim with NO stable row IDs. **These claims reference nothing BUT the +abandoned rows, so removing the rows empties them — they must be RETIRED outright, +not merely emptied:** + +- `CLAIM-AUDIO-ENCODER` (claims only `ENG-MM-AUDIO-ENCODER`) +- `CLAIM-GEMMA4-G1` (claims only `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation`) +- `CLAIM-GEMMA4-G2` (claims only `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation`) +- `CLAIM-GEMMA4-G2-IMPL` (claims only `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation`) +- `CLAIM-GEMMA4-G3` (claims only `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation`) +- `CLAIM-GEMMA4-MM-E2E` (claims only `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation`) +- `CLAIM-MULTIMODAL-M1` (claims only `ENG-MM-INPUT-PIPELINE`) +- `CLAIM-MULTIMODAL-M3C` (claims only `ENG-MM-VIDEO-FORWARD`) +- `CLAIM-MULTIMODAL-TOWER-FIDELITY` (claims only `ENG-MM-VIDEO-FORWARD`) +- `CLAIM-PR3` (claims only `KERNEL-GDN-AOT-BF16`, `KERNEL-GDN-SCRATCH`) +- `CLAIM-TRITON-AOT-PER-ARCH` (claims only `KERNEL-GDN-AOT-BF16`) + +### Rows proposed for correction: 10. Rows needing human inspection: 10. + +These are the same ten, and the distinction the brief demands is between two +different questions: + +- **What the tool settles (no human needed):** the `ACTIVE` claim on all ten is + unsupportable. Nothing in Git corroborates active work. Vacating `ACTIVE` is + justified by the evidence in this document. +- **What the tool CANNOT settle (human required, all ten):** which state each row + should land in. `READY` is the legality FLOOR from the rule above, not a + semantic verdict — and for these rows it is probably the WRONG semantic answer, + because each row's own anchors assert landed code and passing gates. Applying + `READY` blindly would trade one records lie ("actively being worked") for + another ("spec'd, not started"). + +**Nothing in this audit is sufficient to pick between `READY`, `PARTIAL`, +`GATING` and `DONE` for any of the ten.** The correcting change must have a human +read each row's code/test anchors and the linked spec, then pick the state whose +contract that evidence actually satisfies: + +| Row | In-row evidence a human must adjudicate | Contract if promoted instead of `READY` | +|---|---|---| +| `BACKEND-DISTRIBUTED-TP` | "LANDED tensor_parallel.h"; CPU multi-rank TP gate 60/60 RED-verified | `PARTIAL` fits (CPU only, no GPU/multi-node); needs named missing modes | +| `ENG-MM-INPUT-PIPELINE` | processor-parity 23/23 BIT-identical vs the M0 oracle fixture | `PARTIAL`/`GATING` need resolving code AND test anchors | +| `ENG-MM-VIDEO-FORWARD` | "M3c BUILT + UNIT-GATED", video-processor 41/41, pixel_values_videos bit-exact | `PARTIAL`/`GATING` need resolving code AND test anchors | +| `ENG-MM-AUDIO-ENCODER` | "A2 encoder-tower fidelity gate PASS 203/203" | `PARTIAL`/`GATING` need resolving code AND test anchors | +| `KERNEL-GDN-AOT-BF16` | "AOT/safety/native gates green", 1.007989x, 16/20 timing, 2/4 memory — explicitly incomplete | `PARTIAL` fits the evidence; needs anchors + named missing modes | +| `KERNEL-GDN-SCRATCH` | stream-owned pool + poison/reuse/growth assertions | `PARTIAL`/`GATING` need resolving code AND test anchors | +| `MODEL-TEXT-glm4-glm4-for-causal-lm` | `test_glm4_paged_engine` 16/16 on dgx; rope 6692/6692 | `DONE` additionally needs an exact parity-ledger link and a commit-SHA owner | +| `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` | "G1b LANDED — TEXT PATH STRICT 32/32 TOKEN-EXACT"; MM path open | `PARTIAL` needs anchors AND must name what is missing (see ➃) | +| `MODEL-MM-voxtral-voxtral-for-conditional-generation` | "audio→text e2e gate PASS 14/14" (near-tie-robust, GPU dgx-only) | `DONE` additionally needs an exact parity-ledger link and a commit-SHA owner | +| `QUANT-GGUF-IQ3_XXS` | reader trait + codebook anchors, "ADDED W8" | `PARTIAL` needs anchors AND must name what is missing | + +### `PARTIAL` rows + +No `PARTIAL` state change is proposed. The correction owed by the 30-odd rows in +➃ is EDITORIAL — name the missing mode in the row text — and it cannot be +mechanised, because only a reader of the row knows what is absent. Proposing a +state change for them would be inventing confidence. + +## Duplicate live IDs + +`BACKEND-CUDA-SM121` and `BACKEND-CPU` are each `PARTIAL` in TWO matrices, so the +188 live rows carry only 186 unique IDs: + +| ID | Occurrence A | Occurrence B | +|---|---|---| +| `BACKEND-CUDA-SM121` | backend-matrix.md:178 | feature-matrix.md:275 | +| `BACKEND-CPU` | backend-matrix.md:226 | feature-matrix.md:277 | + +`check-agent-record.py` never caught this because its duplicate check only walks +`MATRIX_PATHS`, which omits `feature-matrix.md`. + +### Decision: `backend-matrix.md` OWNS both IDs + +Reasons, in order of weight: + +1. **Only the backend rows carry the contract.** The `backend-matrix.md` rows have + the full semantic column set (upstream / code / tests / spec / owner) with + resolving anchors. The `feature-matrix.md` entries are five-column roll-ups + whose evidence column is one sentence of prose. +2. **Only the backend matrix is gated.** `backend-matrix.md` is in `MATRIX_PATHS`, + so CI holds it to the row contract. `feature-matrix.md` is in `REQUIRED` (it + must exist) but is never parsed for claim rows, so a state written there is + enforced by nothing. +3. **The feature rows already declare themselves pointers.** Both link out — their + spec cells are markdown links to `backend-matrix.md` (one to the + `#cuda-target-rows` anchor). They were authored as references; they merely kept + the stable ID in the first cell, which is what makes them parse as claims. + +### What the feature-matrix entries become: non-claimable references + +Change the FIRST CELL of `feature-matrix.md:275` and `:277` from the bare stable ID +to a markdown link naming the owner — the link TEXT keeps the ID for readers, the +cell stops being a bare ID for the parser. +`parse_claim_rows` skips a row whose first cell fails `ID_RE.fullmatch` (line 439) +**silently and without an error**, so the roll-up view survives verbatim, the +duplicate disappears, and the backfill mints exactly one issue per item. + +Two alternatives were considered and rejected: + +- **Blank the state cell — ILLEGAL.** `parse_claim_rows` reports "must have exactly + one canonical state" for a row whose first cell is still an ID, and + `audit-live-rows.py` aborts the whole census on any parse error. +- **Delete the two feature rows — legal but lossy.** `feature-matrix.md` is the + feature-level roll-up; deleting the rows removes CPU and sm121 from the roll-up + to fix a keying problem. The pointer keeps both. + +Widening `check-agent-record.py`'s duplicate check to `feature-matrix.md` is NOT +proposed here: that file has never been held to the row contract, and turning the +gate on it would fail for reasons unrelated to this audit. Note this leaves the +duplicate check unable to see a future recurrence — `scripts/audit-live-rows.py` +is the only thing that would, so it should keep being run. + +## Rows left alone + +### `IN-FLIGHT` rows: none + +**Zero of the 54 `ACTIVE` rows classify `IN-FLIGHT`, so this section is empty by +measurement, not by omission.** No live row has a `row/` branch at all, so no +row can show unmerged commits. The audit considered all 54 and kept none on that +basis. + +### The 44 `LANDED` rows: kept `ACTIVE`, untouched + +Kept because a commit mention is not grounds to move a row in either direction — +not up to `DONE` (it proves nothing finished) and not down (it is real evidence +worth reading). They stay `ACTIVE` until a human reads them. Ordered as reported: + +| Row | Location | Evidence commit | Commit touched code? | +|---|---|---|---| +| `ENG-RUNNER-MODELSHAPE` | .agents/engine-matrix.md:71 | `5ab3f111` | yes | +| `ENG-MM-VISION-TOWER` | .agents/engine-matrix.md:73 | `d796187a` | yes | +| `ENG-MM-TEXT-BACKBONE` | .agents/engine-matrix.md:74 | `2a8ff336` | yes | +| `ENG-MM-QWEN36-VL-FORWARD` | .agents/engine-matrix.md:75 | `e89d51d8` | yes | +| `ENG-MM-AUDIO-PIPELINE` | .agents/engine-matrix.md:77 | `adcac8e6` | yes | +| `ENG-MM-AUDIO-E2E` | .agents/engine-matrix.md:79 | `9e34a19c` | yes | +| `KV-EVENTS` | .agents/engine-matrix.md:105 | `d796187a` | yes | +| `SAMPLE-BEAM` | .agents/engine-matrix.md:136 | `0151314f` | yes | +| `SAMPLE-N` | .agents/engine-matrix.md:142 | `aed4718e` | yes | +| `SAMPLE-BEST-OF` | .agents/engine-matrix.md:143 | `aed4718e` | yes | +| `TOOLS-XGRAMMAR` | .agents/engine-matrix.md:150 | `d796187a` | yes | +| `TOOLS-STREAMING-PARSER` | .agents/engine-matrix.md:154 | `05237562` | yes | +| `SPEC-REJECTION` | .agents/engine-matrix.md:164 | `dfa610b2` | yes | +| `SPEC-GDN-SEGMENTS` | .agents/engine-matrix.md:165 | `3ae5cfe0` | yes | +| `SPEC-NGRAM` | .agents/engine-matrix.md:169 | `d796187a` | yes | +| `SPEC-DRAFT-MODEL` | .agents/engine-matrix.md:180 | `dfa610b2` | yes | +| `ENG-POOLER-SEQ` | .agents/engine-matrix.md:203 | `2191f771` | yes | +| `ENG-POOLING-RUNNER` | .agents/engine-matrix.md:204 | `2191f771` | yes | +| `MODEL-TEXT-deepseek-v2-deepseek-v2-for-causal-lm` | .agents/model-matrix.md:174 | `2ff7252a` | **no — records/docs only** | +| `MODEL-TEXT-deepseek-v4-deepseek-v4-for-causal-lm` | .agents/model-matrix.md:176 | `ee3d5960` | yes | +| `MODEL-TEXT-glm4-moe-lite-glm4-moe-lite-for-causal-lm` | .agents/model-matrix.md:197 | `d85fd04f` | yes | +| `MODEL-TEXT-kimi-linear-kimi-linear-for-causal-lm` | .agents/model-matrix.md:219 | `2ff7252a` | **no — records/docs only** | +| `MODEL-TEXT-laguna-laguna-for-causal-lm` | .agents/model-matrix.md:222 | `bfaea5cb` | yes | +| `MODEL-TEXT-qwen3-qwen3-for-causal-lm` | .agents/model-matrix.md:259 | `6eee4437` | yes | +| `MODEL-SPEC-deepseek-v4-deep-seek-v4-mtp` | .agents/model-matrix.md:487 | `28b5e866` | yes | +| `QUANT-GGUF-Q2_K` | .agents/quantization-matrix.md:64 | `d0bc0f41` | yes | +| `QUANT-GGUF-IQ2_XXS` | .agents/quantization-matrix.md:69 | `d0bc0f41` | yes | +| `QUANT-NVFP4-CT-W4A16` | .agents/quantization-matrix.md:122 | `80d1da09` | yes | +| `KERNEL-ACCEL-PROVIDER-SELECT` | .agents/kernel-matrix.md:115 | `3a2d05d8` | yes | +| `KERNEL-GEMM-CPU-ELEM` | .agents/kernel-matrix.md:126 | `428e20f0` | **no — records/docs only** | +| `KERNEL-QUANT-CIQ-GEMM-CUDA` | .agents/kernel-matrix.md:128 | `3fb3149f` | yes | +| `KERNEL-ATTN-DENSE-FLASH` | .agents/kernel-matrix.md:148 | `e89d51d8` | yes | +| `BACKEND-CUDA-SM087` | .agents/backend-matrix.md:170 | `aca8d7d7` | **no — records/docs only** | +| `BACKEND-CUDA-SM110` | .agents/backend-matrix.md:176 | `b34f9909` | **no — records/docs only** | +| `BACKEND-CUDA-SM120` | .agents/backend-matrix.md:177 | `88a0b869` | yes | +| `BACKEND-CUDA-ARCH-ADDITIVITY` | .agents/backend-matrix.md:187 | `8a379182` | yes | +| `BACKEND-ACCEL-PROVIDER` | .agents/backend-matrix.md:231 | `3a2d05d8` | yes | +| `BACKEND-METAL-MLX` | .agents/backend-matrix.md:232 | `c351dff2` | yes | +| `BACKEND-VULKAN` | .agents/backend-matrix.md:233 | `1cb5f643` | yes | +| `BACKEND-GATE-METAL-MLXLM` | .agents/backend-matrix.md:254 | `41d7f8d7` | yes | +| `BACKEND-DISTRIBUTED-COMM` | .agents/backend-matrix.md:272 | `9b516ab2` | yes | +| `MODEL-SPEC` | .agents/feature-matrix.md:154 | `d45c8cda` | **no — records/docs only** | +| `BACKEND-CUDA-OTHER` | .agents/feature-matrix.md:276 | `d45c8cda` | **no — records/docs only** | +| `BACKEND-MLX` | .agents/feature-matrix.md:279 | `d45c8cda` | **no — records/docs only** | + +### The other live states: out of scope for a verdict + +`SPIKE` 43, `GATING` 10, `BLOCKED` 7, `READY` 6 — 66 rows. The +classifier runs on `ACTIVE` only, and the flag on `PARTIAL` only, so these rows +appear in the census (they are live and they count toward the 188) but carry no +verdict. Nothing is proposed for them. + +## Risks/decisions + +| # | Question the tool could NOT decide | Human call made here | +|---|---|---| +| 1 | Does a commit mentioning a row ID mean the row is finished? | **No.** `LANDED` is renamed in this document to "has evidence worth reading". No `DONE` proposal anywhere. | +| 2 | Do the 8 records-only-backed `LANDED` rows have any work behind them? | **Unknown, and the audit cannot say.** A `.agents/`-only diff proves a record was edited. Flagged individually in ➁. | +| 3 | What state should each abandoned `ACTIVE` row actually land in? | **Deferred to a human, all ten.** `READY` is the legality floor and is recorded as such, NOT as a recommendation. Each row's own anchors assert passing gates, so `READY` is likely wrong semantically. | +| 4 | Is `ABANDONED` a true statement about the work? | **No — it is a statement about Git.** It means no branch and no ID-naming commit. In all ten cases the row asserts landed work, so the real defect is that commits never named the stable ID. | +| 5 | Which matrix owns a duplicated ID? | **`backend-matrix.md`**, for both. Reasons above. The feature-matrix entries become non-claimable pointers. | +| 6 | Is the `PARTIAL` flag trustworthy as a count? | **No — it UNDER-flags.** 20 flagged, but 11 more pass only on a bare `no`/`gap`, 10 of those on prose asserting goodness. The real count is ~30 of 68. This is why the report names the marker. | +| 7 | Should the correcting change edit `coordination.md` too? | **Yes, unavoidably.** All ten abandoned rows sit inside active claims, and `check_row_contracts` fails a claim that references a non-`SPIKE`/`ACTIVE` row. The matrix edit and the claim edit are one atomic change. | +| 8 | Should `check-agent-record.py`'s duplicate check be widened? | **Not here.** Widening a repo-wide gate onto a file that has never met the row contract is a separate decision with its own fallout; never weaken (or blindly widen) a checker to service an audit. | + +### Method risks a reader should know + +- **The classifier's `LANDED` rule is the weakest link and it fires 44 of 54 + times.** Its stronger rules (unmerged branch, merged branch) never fire in this + repository because the `row/` branch convention is not in use. Any future + reading of these verdicts must not treat them as equivalent. +- **`main_commits` caps at 20 and reports `commits[0]`,** the most recent mention. + A row with many mentions is represented by one; the cited commit is not + necessarily the one that did the work. +- **The census is the branch's working tree, not `origin/main`'s.** Verified + equivalent for live rows (the only delta is nine `INVENTORIED` rows), but a + re-run after that branch changes must re-verify. +- **`docs/STATUS.md` / `docs/BENCHMARKS.md` are not updated by this commit.** + `check-doc-checkpoint.py` is already RED for every commit on this branch for the + same reason (pre-existing, `--base origin/main --head HEAD`); this document + records findings and moves no feature, and the debt is called out rather than + silently carried. + From 795da240fbe027746d232f44685c4744e8e101cd Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 08:53:00 +0000 Subject: [PATCH 23/34] plan(protocol): Task 6 must retire 11 coordination claims atomically Task 5 found that every abandoned row also sits in an active claim in coordination.md, and check_row_contracts cross-checks a row's Owner against that claim table. Moving a row off ACTIVE without retiring its claim in the SAME commit turns check-agent-record.py red between the two edits. Claims are RETIRED (moved to the completed block with their outcome), never emptied. Also records the LANDED caveat the audit surfaced: all 44 rest on a commit merely MENTIONING the row ID, and 8 on records-only commits that changed no code. LANDED means "has evidence worth reading", never "finished". FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index e26edf76..2a334390 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -1018,7 +1018,8 @@ Create `.agents/specs/live-state-audit-2026-08-06.md` with these sections: - **Findings** — the full report table from `/tmp/audit.md`, plus the verdict distribution from Step 2. - **Proposed corrections** — one line per row needing a change, with its target state and the contract obligation that target carries. Apply the legality rule from Global Constraints: an abandoned `ACTIVE` row goes to `READY` if it has a real spec link, otherwise to `INVENTORIED`. - **Duplicate live IDs** — `BACKEND-CUDA-SM121` and `BACKEND-CPU` are `PARTIAL` in both `backend-matrix.md` and `feature-matrix.md`. Decide which matrix OWNS each row and what the other becomes (a non-claimable reference, a differently-keyed row, or deleted), and say why. This must be settled here: the backfill would otherwise mint two issues for one item. -- **Rows left alone** — every `IN-FLIGHT` row, named, so the next reader can see the audit considered and kept them. +- **Rows left alone** — every row the audit did not propose changing, named, so the next reader can see it was considered and kept. There are **no `IN-FLIGHT` rows**: not one of the 54 `ACTIVE` claims has an unmerged `row/` branch. +- **The `LANDED` caveat** — all 44 `LANDED` verdicts rest on a commit *mentioning* the row ID, and **8 of them on records-only commits that changed no code**. `LANDED` means "has evidence worth reading", never "finished". No row may be proposed `DONE` on a commit mention alone. - **Risks/decisions** — every verdict the tool could not decide, and the human call made. - [ ] **Step 5: Run preflight and commit** @@ -1090,7 +1091,19 @@ Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] EOF ``` -- [ ] **Step 5: Repeat Steps 1–4 for each remaining matrix with corrections** +- [ ] **Step 4b: Retire the coordination claims in the SAME commit** + +Every abandoned row sits in an active claim in `.agents/coordination.md`, and +`check_row_contracts` cross-checks a row's `Owner` against that claim table. +**11 claims must be RETIRED, not emptied** — moved to the completed block with +their outcome — and it has to happen in the same commit as the matrix edit, or +`scripts/check-agent-record.py` goes red between the two. + +Run `python3 scripts/check-agent-record.py; echo "EXIT=$?"` and confirm `EXIT=0` +before committing. If it complains about a claim/owner mismatch, the claim +retirement is missing or partial — repair the record, never the checker. + +- [ ] **Step 5: Repeat Steps 1–4b for each remaining matrix with corrections** - [ ] **Step 6: Update the roadmap, state log and public status** From 7211dba6ad1e86ec3a006cc18b011656b77805d8 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 09:02:48 +0000 Subject: [PATCH 24/34] plan(protocol): name the claim-retirement mechanic, and re-fetch before Task 6 Task 5's review found the retirement instruction was ambiguous in a way that would have left the gate red: parse_active_claims keys on a line starting with "| `CLAIM-", so a claim moved to a table row in another section is still parsed as ACTIVE. The repo's own archival convention uses prose bullets. Also adds a re-fetch step: the artifact pins origin/main at cf32c619 and the remote has advanced, so Task 6 must re-run the audit rather than apply a possibly stale proposal list. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index 2a334390..d21e1d9e 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -1053,6 +1053,13 @@ EOF **One commit per matrix.** A 49-row single commit is unreviewable, and a bad transition in one matrix should be revertible without losing the others. +- [ ] **Step 0: Re-fetch and re-run the audit** + +The artifact pins `origin/main` at `cf32c619` and the remote has since advanced. +Run `git fetch -q origin` and re-run `python3 scripts/audit-live-rows.py --json` +before editing anything. If the verdict set has changed, the artifact's proposals +are stale — re-verify the affected rows rather than applying a stale list. + - [ ] **Step 1: Correct the first matrix** Work one matrix at a time, starting with the one holding the most corrections. For each row in the artifact's corrections list, edit **only** the `State` and `Owner` cells. Do not touch `Our code`, `Tests/evidence`, `Upstream` or `Spike/spec` — those are durable anchors and are not what this audit is about. @@ -1099,6 +1106,11 @@ Every abandoned row sits in an active claim in `.agents/coordination.md`, and their outcome — and it has to happen in the same commit as the matrix edit, or `scripts/check-agent-record.py` goes red between the two. +**Retirement has an exact mechanic.** `parse_active_claims` keys on +`line.startswith("| \`CLAIM-")`, so a claim moved to a table row in another +section is *still parsed as active* and still red. The repo's existing archival +convention (`.agents/coordination.md:1643+`) uses **prose bullets** — follow it. + Run `python3 scripts/check-agent-record.py; echo "EXIT=$?"` and confirm `EXIT=0` before committing. If it complains about a claim/owner mismatch, the claim retirement is missing or partial — repair the record, never the checker. From 0bb5ac7f8953937c95f4fefd2a9078bc781a6af9 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 10:21:34 +0000 Subject: [PATCH 25/34] plan(protocol): scope Task 6 to the 10 abandoned ACTIVE rows only User-directed 2026-08-06. The 44 LANDED rows, the ~30 vague PARTIAL rows and the 2 duplicate IDs stay as they are, documented in the audit artifact rather than changed. Smallest truthful correction: the ACTIVE claim is the only thing the tool can settle on its own evidence. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .../plans/2026-08-06-p0-live-state-audit.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md index d21e1d9e..f725b8b8 100644 --- a/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md +++ b/docs/superpowers/plans/2026-08-06-p0-live-state-audit.md @@ -1051,7 +1051,23 @@ EOF - Consumes: the **Proposed corrections** section of `.agents/specs/live-state-audit-2026-08-06.md`. - Produces: matrices whose live states are true, so P2 can mint issues from a corrected record. -**One commit per matrix.** A 49-row single commit is unreviewable, and a bad transition in one matrix should be revertible without losing the others. +**One commit per matrix.** A single sweeping commit is unreviewable, and a bad +transition in one matrix should be revertible without losing the others. The 10 +rows sit in 5 matrices: engine 3, model 3, kernel 2, quantization 1, backend 1. + +**SCOPE, user-directed 2026-08-06 — the 10 abandoned `ACTIVE` rows and nothing +else.** Explicitly OUT of scope, left as-is and already documented in the +artifact: + +- the **44 `LANDED`** rows — every verdict rests on a commit merely mentioning + the ID, 8 of them on commits that changed no code, so none is touched; +- the **~30 vague `PARTIAL`** rows — the repair is editorial and needs per-row + knowledge of what actually works, which the tool cannot supply; +- the **2 duplicate IDs** (`BACKEND-CPU`, `BACKEND-CUDA-SM121`) — the ownership + decision is recorded in the artifact and deliberately not applied here. + +Touching any of those is scope creep. The artifact keeps them visible for a +later, separately-decided change. - [ ] **Step 0: Re-fetch and re-run the audit** @@ -1062,7 +1078,7 @@ are stale — re-verify the affected rows rather than applying a stale list. - [ ] **Step 1: Correct the first matrix** -Work one matrix at a time, starting with the one holding the most corrections. For each row in the artifact's corrections list, edit **only** the `State` and `Owner` cells. Do not touch `Our code`, `Tests/evidence`, `Upstream` or `Spike/spec` — those are durable anchors and are not what this audit is about. +Work one matrix at a time, starting with the one holding the most corrections. For each of the 10 rows in the artifact's corrections list, edit **only** the `State` and `Owner` cells. Do not touch `Our code`, `Tests/evidence`, `Upstream` or `Spike/spec` — those are durable anchors and are not what this audit is about. Apply the legality rule: `READY` if the row has a real spec link, otherwise `INVENTORIED`. Clear the `Owner` cell to `-` for any row leaving `ACTIVE`. From 5de5f40652690dc6864f5b657e6da5776e99e4c5 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Thu, 6 Aug 2026 11:13:07 +0000 Subject: [PATCH 26/34] =?UTF-8?q?record(engine):=20live-state=20audit=20co?= =?UTF-8?q?rrections=20=E2=80=94=203=20rows=20off=20stale=20ACTIVE=20(P0?= =?UTF-8?q?=20step=206)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Evidence: .agents/specs/live-state-audit-2026-08-06.md ➂. ENG-MM-INPUT-PIPELINE, ENG-MM-VIDEO-FORWARD and ENG-MM-AUDIO-ENCODER each claimed ACTIVE with no row/ branch anywhere and no commit on origin/main naming the stable ID, so the claim is unverifiable from Git. They move to READY — the legality floor, all three resolve a real spec that names their token — NOT a judgement that the work is unstarted; each row's own anchors assert a passing gate, which is exactly why the audit refused to recommend anything stronger. Only the State and Owner cells move; Our code / Tests-evidence / Upstream / Spike-spec are durable anchors and are untouched. The area rollup moves with the rows (Engine and scheduling ACTIVE 9->6, READY 0->3). check_row_contracts cross-checks a row's Owner against coordination.md, so the four claims that reference ONLY these rows are RETIRED as prose bullets in the SAME commit (emptying them is illegal too — an active claim with no row IDs fails the same gate): CLAIM-MULTIMODAL-M1, CLAIM-MULTIMODAL-M3C, CLAIM-MULTIMODAL-TOWER-FIDELITY, CLAIM-AUDIO-ENCODER, each with its recorded outcome. check-agent-record EXIT=0; agent-preflight.sh EXIT=0; audit-live-rows abandoned 10 -> 7. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- .agents/coordination.md | 33 ++++++++++++++++++++++++++---- .agents/engine-matrix.md | 10 ++++----- docs/BENCHMARKS.md | 2 +- docs/STATUS.md | 2 +- scripts/check-public-doc-tables.py | 2 +- 5 files changed, 37 insertions(+), 12 deletions(-) diff --git a/.agents/coordination.md b/.agents/coordination.md index 672bc58f..ec19e01f 100644 --- a/.agents/coordination.md +++ b/.agents/coordination.md @@ -1552,17 +1552,13 @@ items a-runner/b stay with the async/GDN `runner.cpp` owners. | `CLAIM-KERNEL-CPU-ELEM-GEMM-1` | `KERNEL-GEMM-CPU-ELEM` (work rows **E1-E4**) — the elementwise f32/f16/bf16 CPU GEMM: hoist the per-element dtype switch out of the K loop, replace the single serial f32 accumulator with 16 independent ones, add bit-exact per-arch SIMD tiers with a runtime probe, and M-block the `[N,K]` micro-kernel. Promoted to the #1 CPU lever by the CIQ G4 claim's own measurement (60 % of the bench file's weight bytes are `f16`, which no block encoding covers) | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp/.claude/worktrees/agent-a0080369412fcd2a7`; dgx CPU source/build `~/work/vllm.cpp-elemgemm`, CUDA gate build `~/work/vllm.cpp-elemgemm-cuda`; benchmark host dgx `~/work/bench-cpu-llama` (the x86 dev box is VOID for timing) | `main` (worktree), base `72f5db2` | Owned files: new `src/vt/cpu/cpu_matmul_elem.{h,cpp}`, `src/vt/cpu/cpu_ops.cpp` (`MatmulOneChunk` ONLY), new `tests/vt/test_ops_matmul_elem.cpp`, `CMakeLists.txt` + `tests/CMakeLists.txt` (one source and one test row), the new leaf spec `.agents/specs/cpu-elementwise-gemm.md`, the `KERNEL-GEMM-CPU-ELEM` row in `kernel-matrix.md`, the `QUANT-GGUF-CIQ-GEMM` row in `quantization-matrix.md`, roadmap, ledger, state, README §CPU, BENCHMARKS. MUST NOT touch a model forward, a loader, the quant GEMM, or any golden; MUST NOT trade bit-exactness for speed. | `DONE` | 2026-07-22 — **BIT-EXACT AND 3.1-3.4× FASTER.** Two defects removed from the elementwise chunk worker: the per-element `LoadF32` dtype switch is gone (the activation row is widened to f32 once per 16-row tile, the weight dtype resolves once per chunk into a typed micro-kernel), and the ONE serial f32 accumulator became 16 — the old 0.77-0.84 GFLOP/s/thread was a loop-carried FP-add latency chain, not an ISA limit. SIMD is ported from llama.cpp `vec.cpp:139,264` (`ggml_vec_dot_bf16`/`_f16`) with ONE recorded deviation: we vectorize across OUTPUT COLUMNS instead of along K, so every output keeps its sequential reduction and the whole change is **BYTE-IDENTICAL** to the historical kernel. Tiers: portable 16-accumulator (always built), AArch64 NEON (`vshll_n_u16`/`vcvt_f32_f16` widen, `vtrnq_f32` 4×4 transpose, MR=4), x86-64 SSE2 + probed F16C (MR=2). **CORRECTNESS:** new [test_ops_matmul_elem](../tests/vt/test_ops_matmul_elem.cpp) 5 cases / **654 assertions**, gate is `memcmp` not `Approx`, green on x86-64 AND dgx **aarch64** and under all three `VT_CPU_MATMUL_TIER` settings; the exhaustive case proves `vcvt_f32_f16`/`_mm_cvtph_ps` agree with `vt::F16ToF32` on **all 65,536 patterns including every inf/NaN** — no sNaN quieting, so no divergence to quantify and the NMSE ≤ 5e-4 fallback was not needed. E2E the BEFORE / AFTER / `VT_CPU_REF=1` token streams are one md5 `d235db12f2cd304007530286a1755c95` — the same md5 G4 recorded. **REGRESSIONS ALL UNCHANGED**, each STANDALONE on a clean CUDA `-Werror` build (**0 warnings**, production flags, one `flock $HOME/gpu.lock`, `git archive` transfer, goldens md5 `2965ef5772b556d3f3f86fedf4221b2f` identical before/after): 27B **235/235**, 35B **315/315**, Qwen3-Coder **6/6**, Qwen3-dense **16/16**, OPT **6/6**, DeepSeek-V2 **223/223 assertions (8/8 prompts)**, gguf **28/28**, plus `test_gguf_keep_quant`, `test_ops_quant_dot`, `test_ops_quant_traits`, `test_gguf_dequant`. ONE TRANSIENT RECORDED HONESTLY: the first DeepSeek-V2 pass returned the known co-scheduled-memory abort signature (95 of 223 assertions, 1 failure) while ANOTHER agent was running 27B gates on the same box; re-run STANDALONE under the flock it passes 223/223 — the same signature the CIQ G3 record documents, not a regression. Dev box full CPU ctest **157/157** (two co-scheduled HTTP-server flakes, both green standalone). **BENCHMARK (binding, idle dgx aarch64, one flock, SAME binary, 3 reps, medians):** prefill 21.67 -> **73.97 t/s (3.41×)**, decode 7.649 -> **23.79 t/s (3.11×)**, peak RSS unchanged 6.401 GiB; vs llama.cpp (pp128 173.28±1.75, tg32 24.52±0.45, RSS 2.798 GiB) **8.00× -> 2.34× behind on prefill and 3.21× -> 1.03× behind on decode — decode is AT PARITY within 3.1 %**, RSS still 2.29× worse. Op-level bf16 `[N,K]`: ref 18-24 -> portable 35-52 -> NEON 69-351 GFLOP/s (prefill shapes 14.4-14.5×), which puts the elementwise GEMM (347-351) level with the quant tier-0 (388-417). **RE-RANKS THE PLAN AGAIN, on a measured NEGATIVE:** E4's M-blocking gave 1.63× op-level on prefill and **0.0 % end-to-end**, so prefill is NO LONGER elementwise-GEMM-bound and the 95.37 % `kMatmul` attribution is STALE. Next step is a FRESH op-dispatch profile of the current binary before any further lever is started; RSS (loader **L5**) is now the largest single deficit at 2.29×; decode needs no further kernel work. Claim released | | `CLAIM-MULTIMODAL-TRACK` | `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` (this spike advanced it `INVENTORIED`→`SPIKE`; now `ACTIVE` — text path STRICT 32/32 gated per `CLAIM-GEMMA4-G1B`, mm towers pending), `MODEL-MM-gemma4-unified-gemma4-unified-for-conditional-generation` (`INVENTORIED`→`SPIKE`). The two Qwen3.6 mm rows (27B `Qwen3_5ForConditionalGeneration` + 35B MoE) stay `PARTIAL`/narrative-only — annotated with the mm-completion plan, NOT claimed as work rows here (the mm implementation re-claims them at M3). | Claude Code (opus-4-8) | isolated worktree `/tmp/claude-1000/.../scratchpad/mm-tree` (SPIKE ONLY — no build, no GPU work, no download; one oracle-metadata + safetensors-header read on dgx) | detached HEAD, base `origin/main` `72f9fb1` | SPIKE ONLY, no implementation. Owns `.agents/specs/multimodal-track.md` plus the four `MODEL-MM-*` rows above. Covers: the multimodal seam map (input pipeline + `*ForConditionalGeneration` wrapper + engine/encoder-cache seams, vLLM `file:line`); per-target modality + oracle + GB10-fit + checkpoint gateability; the reuse-vs-new factoring; the M0–M5 W-plan. **HEADLINE:** our GATE models are ALREADY multimodal (`Qwen3_5ForConditionalGeneration`/`…Moe…`, image+video, subclass `Qwen3VLForConditionalGeneration` + `Qwen3_VisionTransformer`) brought up text-only, so the track COMPLETES them. Oracle 0.25.0 SHIPS the mm files (`qwen3_5.py`,`qwen3_vl.py`,`qwen2_5_vl.py`,`gemma4_mm.py`), so the mm path is oracle-constructible; but the cached NVFP4 gate checkpoints are TEXT-ONLY (no `visual.*`) so Qwen3.6 mm is CHECKPOINT-gated, not HW/oracle-blocked. First vehicle = `Qwen/Qwen3-VL-4B-Instruct` (same tower). Gemma-4 = image+video+AUDIO, ≥12B mm-wrapped HF-gated + PLE/YOCO/MoE backbone → SPIKE/BLOCKED-for-now; audio reachable ONLY via Gemma-4/gemma3n (Qwen3.6 has none), deferred M5. **NO SHARED-WORK COLLISION:** records-only spike; keeps the README/BENCHMARKS footprint to a single status line (per the docs-refresh + DFlash-spike coordination), does NOT touch `dflash-spec-decode.md`. | `SPIKE` | 2026-07-25 spike committed (spec + records only). No implementation, no build, no gate. Not pushed. NEXT (future, out of this claim): M0 fetch Qwen3-VL-4B + vision-inclusive Qwen3.6 checkpoint + oracle mm reference. **SUPERSEDED (annotation 2026-07-27):** the M0-M3 work this parent spike scoped has since LANDED under the DONE/ACTIVE child increment claims (`CLAIM-MULTIMODAL-M1`, `CLAIM-MULTIMODAL-M2A`, `CLAIM-MULTIMODAL-M2BC`, the M3 image/video + audio A0-A3 claims); Qwen3-VL-4B + Qwen3.6-27B image+video are e2e STRICT 32/32 and Voxtral audio is e2e 14/14. This row is retained for provenance; the two gemma4 mm rows stay `SPIKE` (owned per the row-owner column). | | `CLAIM-GEMMA4-MULTIMODAL` | `MODEL-MM-gemma4-mm-gemma4-for-conditional-generation` (now `ACTIVE` — text path STRICT 32/32 gated per `CLAIM-GEMMA4-G1B`; mm towers pending), `MODEL-MM-gemma4-unified-gemma4-unified-for-conditional-generation` (stays `SPIKE`; ownership transferred here from `CLAIM-MULTIMODAL-TRACK` — that spike advanced them to `SPIKE`, this one owns the dedicated Gemma-4 mm + AUDIO spec + the sharpened oracle-blocked verdict). | Claude Code (opus-4-8) | isolated worktree `/tmp/claude-1000/.../scratchpad/g4mm-tree` (SPIKE ONLY — no build, no GPU, no download; oracle-metadata reads only) | detached HEAD, base `origin/main` `64a01af` | SPIKE ONLY, no implementation. Owns `.agents/specs/gemma4-multimodal.md` (new) + the two `MODEL-MM-gemma4-*` rows. **Coordination: does NOT touch `multimodal-track.md` or the Qwen `MODEL-MM-*` rows** (owned by the concurrent Qwen3.6-video agent). **DECISIVE FINDING:** Gemma-4 mm is oracle-BLOCKED — the vision/audio towers load via Transformers `AutoModel.from_config` (`gemma4_mm.py:1040,1056`) but the dgx oracle's transformers 5.13.1 has NO `gemma4` module (measured; `gemma3n` present) → mm path unconstructible, no gate. Architecture: SigLIP vision tower (REUSES M2a scaffold) + USM-Conformer audio tower (NEW) + PLE/YOCO/Gemma-4-MoE backbone (NEW, sweep-gemma §0.1); the Unified 12B variant is encoder-free. AUDIO is the genuinely-new modality (nothing built) — land it FIRST on the smallest oracle-runnable vehicle (`whisper-small`→`Voxtral-Mini-3B` on our LANDED Mistral backbone), Gemma-4 audio (G3) reuses it; Conformer tower delta proven on Granite-Speech-2b. | `SPIKE` | 2026-07-25 spike committed (spec + records only). No implementation, no build, no gate. Not pushed. NEXT (future, out of this claim): the AUDIO track A0 (fetch whisper-small + Voxtral-Mini-3B, oracle references); Gemma-4 stays blocked until the oracle Transformers carries `gemma4`. **SUPERSEDED (annotation 2026-07-27):** the AUDIO track this spike identified as the genuinely-new work has since LANDED (A0-A3, Voxtral-Mini-3B e2e 14/14 + Whisper encoder 203/203, DONE child claims). The Gemma-4 oracle block is now DISSOLVED (the pin advanced to transformers 5.14.1, which ships `gemma4`); Gemma-4 mm is reachable, implementation pending. This row is retained for provenance; the two gemma4 mm rows stay `SPIKE`. | -| `CLAIM-MULTIMODAL-M1` | `ENG-MM-INPUT-PIPELINE` (engine-matrix, `ACTIVE`). The two Qwen3.6 mm rows — 27B `Qwen3_5ForConditionalGeneration` + 35B `Qwen3_5MoeForConditionalGeneration` — stay `PARTIAL`/narrative-only (their narrative is advanced with the landed M0/M1 input pipeline; the tower re-claims them at M2/M3). Covers the new `src/vllm/multimodal/*` + the engine mm seam + `multimodal-track.md` (M0/M1 status). | Claude Code (opus-4-8) | isolated worktree `~/work/mm-m0m1` (CPU `build-cpu` + CPU ctest); dgx `~/work/mm-m0m1-cuda` (`git archive`, CUDA `build`, all GPU under ONE `flock $HOME/gpu.lock`, big-model gates STANDALONE one at a time) | branch `mm-m0m1`, base `origin/main` `39943fc` | Multimodal **M0+M1**: the M0 oracle reference (`scripts/mm/m0_oracle_capture.py` + committed fixtures) + the M1 mm INPUT pipeline (`src/vllm/multimodal/{inputs.h,hasher.*,qwen3vl_processor.*}`), the encoder-cache engine seam (`include/vllm/v1/core/encoder_cache_manager.h` + `src/vllm/v1/core/encoder_cache_manager.cpp`), the additive inert `mm_features` on `Request`/`EngineCoreRequest`, the `extra_keys` seam on `ChunkedTokenDatabase`, and the M0/M1 status in `multimodal-track.md`. Owns ONLY those NEW files + the four additive engine edits (`include/vllm/v1/request.h`, `src/vllm/v1/request.cpp`, `include/vllm/v1/engine/types.h`, `include/vllm/v1/kv_offload/lmcache/chunked_token_database.h` + `.cpp`) + tests `tests/vllm/multimodal/test_qwen3vl_processor.cpp`, `tests/vllm/v1/core/test_encoder_cache_manager.cpp` + 3 CMake lines. **NON-COLLISION:** does NOT build the vision tower / embed-merge (M2), does NOT touch the frontier-models spike files (`sweep-kimi-minimax-glm-latest.md`, `MODEL-TEXT-*`) or DFlash. NO vision forward. | `ACTIVE` | 2026-07-25 — **M0+M1 LANDED + PROCESSOR-PARITY GATE PASS.** Processor parity 23/23 BIT-identical vs the M0 vLLM-0.25.0 oracle (pixel_values bf16, grid_thw, mm-hash `ef6f5bea...`, placeholder expansion) — RED-first (wrong shift -> 1.2M mismatches); encoder-cache 32/32; CPU inertness green STANDALONE (request/engine_types/lmcache_codec/lmcache_key_agreement/openai_conformance); clean CPU `-Werror`; `check-device-leakage` OK. SACRED CUDA text-inertness STANDALONE under flock, cutlass-ON banner CONFIRMED: **27B 235/235, 35B 315/315, Coder 138/138 ALL PASS**; clean CUDA `-Werror` 0 warnings. `benchmark_binding=false`, no speed. Not pushed. NEXT (M2): `Qwen3_VisionTransformer` forward + `_merge_multimodal_embeddings` on Qwen3-VL-4B -> first image token-exact gate. | | `CLAIM-MULTIMODAL-M2A` | `ENG-MM-VISION-TOWER` (engine-matrix, `ACTIVE`). Owns the NEW vision-tower TU + 2 additive vt ops + the tower unit gate + tower reference/weight dump scripts + fixtures. The `Qwen3VLForConditionalGeneration` model-matrix row is narrative-advanced `INVENTORIED`→`PARTIAL` (tower faithful, e2e pending); the two Qwen3.6 mm rows stay `PARTIAL`/narrative-only (the tower attaches to them at M3). | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp-m2a` (branch `m2a-vision-tower`); dgx build+gate `~/m2a_build` (tar-transfer, CUDA `build`, ALL GPU under ONE `flock $HOME/gpu.lock`) | branch `m2a-vision-tower`, base `origin/main` `463633d` | Multimodal **M2a — vision TOWER proven faithful**: `src/vllm/model_executor/models/qwen3_vl_vision.{h,cpp}` (`Qwen3_VisionTransformer` forward: patch-embed matmul+bias, host pos-embed bilinear-interp+reorder, 24 ViT blocks [LayerNorm + partial-rotary vision RoPE via `vt::RopeFromCache` + non-causal `vt::Attention` + tanh-GELU MLP], patch merger [LN + exact-erf-GELU + 2 FCs], DeepStack 3 post-shuffle mergers at 5/11/17 → `[196,10240]`); 2 additive vt ops `GeluTanh`/`GeluErf` (`include/vt/ops.h`, `src/vt/ops.cpp`, `src/vt/cuda/cuda_layernorm.cu`, `src/vt/cpu/cpu_layernorm.cpp`); the tower gate `tests/vllm/multimodal/test_qwen3vl_tower.cpp` + fixtures `tests/vllm/multimodal/fixtures/qwen3vl_tower/`; dump scripts `scripts/mm/m2a_tower_{ref,weight}_dump.py`; 2 CMake lines. **NON-COLLISION:** additive-only — NO model runner / model TU / registry edit (text SACRED byte-identical BY CONSTRUCTION); does NOT build the MRoPE text backbone (M2b) or the merge/e2e image gate (M2c); does NOT touch M1's `src/vllm/multimodal/*`. | `ACTIVE` | 2026-07-25 — **M2a LANDED + TOWER FAITHFULNESS GATE PASS.** 4 RED-first unit gates vs the dumped vLLM-0.25.0 tower reference (patch-embed relL2 2.1e-3, block0 6.8e-3, merger 6.5e-2, DeepStack taps 1.2e-2/3.3e-2/4.4e-2, full tower 5.1e-2; NEW-kernel gates pos-embed 2.5e-3 + rope 1.9e-3 TIGHT) — bf16-depth envelope RCA'd (smooth ~0.25%/layer, no discontinuity); RED = vision-rope disabled → block0 0.149, tower 0.75, 6 fails. Build cutlass-ON+FA2 banner CONFIRMED; clean CUDA `-Werror` 0 warnings; compute-sanitizer 0 errors on the tower + new kernels. Text inertness BY CONSTRUCTION (`git diff --stat`: 128 insertions, 0 deletions, additive vt ops only). `benchmark_binding=false`, no speed. Not pushed. NEXT (M2b): MRoPE 3-D positions + DeepStack decoder injection on the Qwen3-VL text backbone; then (M2c) merge + e2e image token-exact gate. | | `CLAIM-MULTIMODAL-M2BC` | `ENG-MM-TEXT-BACKBONE` (engine-matrix, `ACTIVE`). Owns the NEW text-backbone helper TU + its unit gate + reference dump + fixtures. The `Qwen3VLForConditionalGeneration` model-matrix row stays `PARTIAL`/narrative-only (M2b/M2c numeric contracts unit-green; the e2e image gate is the remaining wire-up). The two Qwen3.6 mm rows stay `PARTIAL`/narrative-only. | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp/.claude/worktrees/m2bc` (branch `m2bc-multimodal`, CPU `build-cpu` + CPU ctest); dgx used only for the vLLM-0.25.0 reference dump under `flock $HOME/gpu.lock` (CPU-only oracle) | branch `m2bc-multimodal`, base `origin/main` `0eed915` | Multimodal **M2b/M2c — text-backbone numeric contracts, unit-green**: `src/vllm/model_executor/models/qwen3_vl_text.{h,cpp}` (`Qwen3VLGetRopeIndex` MRoPE 3-D positions [3,T]; `Qwen3VLMergeMultimodal` masked-scatter; `Qwen3VLComputeDeepstack` [L,T,H] scatter); the unit gate `tests/vllm/multimodal/test_qwen3vl_text.cpp` (4 RED-first gates incl. the 3-section MRoPE application through the existing `vt::RopeFromCache` mrope path) + fixtures `tests/vllm/multimodal/fixtures/qwen3vl_text/`; dump `scripts/mm/m2b_text_ref_dump.py`; 1 CMake line + 1 lib source line. **NON-COLLISION:** additive-only — NO model runner / shared dense forward / registry edit (text SACRED byte-identical BY CONSTRUCTION); the e2e image forward (VL weight loader + forked MRoPE/DeepStack decode loop + greedy) is NOT yet built. | `ACTIVE` | 2026-07-25 — **M2b/M2c NUMERIC CONTRACTS UNIT-GREEN (CPU, no weights).** 4 RED-first gates vs the dumped vLLM-0.25.0 reference (`scripts/mm/m2b_text_ref_dump.py`) PASS 85/85: get_rope_index BIT-exact [3,204] (delta −182); 3-section MRoPE application (interleaved, section=[24,20,20]) via `vt::RopeFromCache` q rel-L2 1.5e-3 / k 1.5e-3 (bf16 band), RED guard interleaved-off diverges >5e-2; DeepStack scatter + embed-merge BIT-exact; clean CPU `-Werror`. Text inertness BY CONSTRUCTION (additive TU only, shared dense forward untouched). `benchmark_binding=false`, no speed. Not pushed. **REMAINING (M2c e2e):** VL weight loader (`language_model.*`+`visual.*`) + forked VL decode (inputs_embeds + MRoPE + DeepStack inject) + greedy loop → image token-exact gate vs vLLM 0.25.0 on Qwen3-VL-4B; risk = bf16-envelope tower (M2a rel-L2 ~5e-2) vs deterministic vLLM near-ties. | | `CLAIM-MULTIMODAL-M2C` | `ENG-MM-TEXT-BACKBONE` (engine-matrix, `ACTIVE`) — the forked VL decode. Narrative-advances the Qwen3-VL model-matrix row (`PARTIAL`→IMAGE e2e WORKING; not `DONE`, speed pending). Owns the NEW VL loader + forked-decode TU + the STRICT e2e image gate + the input-ids dump. M2 CLOSED. | Claude Code (opus-4-8) | dgx build+gate `~/work/mm-m0m1-cuda` (tar-transfer via `git archive`, reused Makefiles build cache, ALL GPU under ONE `flock $HOME/gpu.lock`) | branch `feat/mm-m2c-e2e`, base `origin/main` `1cd5710` | Multimodal **M2c — e2e IMAGE forward, STRICT gate PASS**: `src/vllm/model_executor/models/qwen3_vl.{h,cpp}` (VL weight loader `model.language_model.*`+`model.visual.*`; forked greedy VL decode = embed+`Qwen3VLMergeMultimodal` scatter + 3-section MRoPE via `vt::RopeFromCache` global cache + DeepStack inject at layers 0/1/2 + paged greedy); STRICT e2e gate `tests/vllm/multimodal/test_qwen3vl_e2e.cpp`; input-ids dump `scripts/mm/m2c_e2e_inputs.py` + fixture `input_ids_i32.bin`; 3 CMake lines. One M2a fix: `qwen3_vl_vision.cpp` `cap==nullptr` DeepStack concat (an explicit deferred-to-M2c stub — M2a capture output byte-identical). **NON-COLLISION:** additive VL path gated on mm input; NO shared dense forward / model runner / registry edit (text SACRED byte-identical BY CONSTRUCTION). | `ACTIVE` | 2026-07-25 — **M2c LANDED, STRICT e2e IMAGE gate PASS 32/32.** Full pipeline (image→C++ processor→M2a tower→merge→forked MRoPE/DeepStack greedy decode) == committed vLLM 0.25.0 golden token-for-token on Qwen3-VL-4B; no near-tie needed (STRICT passed exactly, first try after the stub fix). Clean CUDA `-Werror` 0 warnings. Text inertness: additive (`git diff --stat` shared forward untouched) + SACRED regressions re-run (27B/35B/Coder). `benchmark_binding=false`, speed pending. FULL SHA in commit; NOT pushed. NEXT (M3): Qwen3.6-27B image reusing this tower+backbone+loader on the GDN-hybrid backbone, then video. | | `CLAIM-MULTIMODAL-M3` | `ENG-MM-QWEN36-VL-FORWARD` (engine-matrix, `SPIKE` — the GDN-hybrid VL forward design grounded by M3-W0, implementation OWED as M3-b). The 27B mm model (`Qwen3_5ForConditionalGeneration`) stays `PARTIAL`/text-only, narrative-only (NOT claimed as a work row here — M3-b re-claims it); its narrative is advanced with the M3-W0 checkpoint verdict + the grounded GDN-hybrid VL forward design. Owns `.agents/specs/multimodal-track.md` (M3 section), `scripts/mm/m3_oracle_capture.py`, and the committed golden/input fixtures `tests/vllm/multimodal/fixtures/qwen3_5_27b/`. | Claude Code (opus-4-8) | isolated worktree `/home/mudler/work-m3/tree` (branch `m3-qwen36-27b-image`); dgx `~/work/m3-golden` (oracle golden under `flock $HOME/gpu.lock`, ALONE, GMU 0.6, local-ai-worker verified Exited) | branch `m3-qwen36-27b-image`, base `origin/main` `3c8af64` | Multimodal **M3-W0** — resolve the GATING FACT (vision-inclusive checkpoint) + ground the GDN-hybrid VL forward design + capture the vLLM 0.25.0 oracle golden. **KEY FINDINGS:** checkpoint = **`Qwen/Qwen3.6-27B`** (51.7 GiB uniform bf16, 333 `visual.*` tensors, NOT gated; fits GB10 after reclaiming mine-only `~/work` trees, apex/darwin untouched); 27B vision config DIFFERS (depth 27/hidden 1152/out 5120/16 heads, **EMPTY deepstack** — no DeepStack, simpler than 4B); MRoPE `[11,11,10]`/rot 64/theta 1e7; backbone 48 GDN + 16 full-attn; **the bf16 GDN-hybrid LLM loader ALREADY EXISTS** (`LoadQwen3_5Dense` routes bf16 by `.weight_packed` absence) so M3-b needs only the `visual.*` loader + the forked forward (inputs_embeds + MRoPE + merge, gated ⇒ text byte-identical). **NON-COLLISION:** records + oracle scripts + fixtures only; NO shared-forward edit landed here (M3-b owns the `qwen3_5.cpp` forked forward + greedy driver + e2e gate). | `ACTIVE` | 2026-07-25 — **M3-W0 LANDED (checkpoint resolved + fetched + oracle golden captured + design grounded).** vLLM 0.25.0 CONSTRUCTS + LOADS + RUNS the 27B mm path (encoder cache profiled 1 image item; NOT oracle-blocked); golden = 214-token input (196 image toks @ off 4), 32-token greedy, **K=5 DETERMINISTIC ⇒ STRICT** (sha256 `ead4b484…`), GB10 held 54 GiB bf16 (GMU 0.6, no OOM). Fixtures `tests/vllm/multimodal/fixtures/qwen3_5_27b/`. NO e2e gate this session — M3-b (the forked GDN-hybrid VL forward + token-exact image gate + text-inertness) is the cleanly-scoped next brick, exactly as M2 landed as M2a/M2b/M2c. Not pushed. | | `CLAIM-MULTIMODAL-M3B` | `ENG-MM-QWEN36-VL-FORWARD` (engine-matrix, `SPIKE`→`ACTIVE`). The 27B mm model (`Qwen3_5ForConditionalGeneration`) narrative advances PARTIAL(text-only)→**IMAGE e2e working** (video + speed still pending; the model-matrix row stays `PARTIAL`, NOT claimed as a work row here). Owns EXACTLY: the forked GDN-hybrid VL forward + greedy driver `Qwen3_5VLGenerateGreedy` + `BuildMropeCosSinHost` + the `mrope_cos_sin` param on `DenseForwardLayers` (`src/vllm/model_executor/models/qwen3_5.cpp`); the vision-only loader `LoadQwen3VLVisionWeights` + 4B-loader refactor (`src/vllm/model_executor/models/qwen3_vl.{h,cpp}`); the `Qwen3_5VLGenerateGreedy` decl (`include/.../qwen3_5_dense.h`); the STRICT gate `tests/vllm/multimodal/test_qwen3_5_vl_e2e.cpp` + its CMake. Owns NO text forward algorithm change (mm path gated on mm input), NO scheduler/runner, NO other model. | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp/.claude/worktrees/m3b-vl` (branch `m3b-qwen36-vl`), base `origin/main` `abde069`; dgx build+gate `dgx.casa:~/work/m3b-vl` under `flock $HOME/gpu.lock` (sole GPU owner, local-ai-worker stopped) | branch `m3b-qwen36-vl`, base `origin/main` `abde069` | Multimodal **M3-b** — build the GDN-hybrid VL image→text forward + RUN the STRICT image token-exact gate (complete our own gate model's image path). | `DONE` | 2026-07-25 — **M3-b LANDED: STRICT image token-exact 32/32 vs vLLM 0.25.0.** Full pipeline (M1 processor → M2a tower 27B config `[196,5120]` → embed+scatter into image_token(248056) rows, no deepstack → 3-section MRoPE `[11,11,10]` interleaved on the 16 full-attn layers → GDN-hybrid backbone → paged greedy) == golden `ead4b484…` (gate 54/54 assertions). Text-inertness re-run cutlass-ON+FA2: **27B 235/235, 35B 315/315, Coder 138/138** (the 3-point fork is byte-identical on text — `mrope_cos_sin==nullptr` on every text caller). Clean CUDA `-Werror` 0 warn (Release, arch 121a, cutlass NVFP4 + FA2 ENABLED banner); compute-sanitizer on the 27B VL forward. Weights via `LoadQwen3_5Dense(shards,cfg,&queue)` direct device load + host release (no unified-pool OOM). Generated text = the coherent image-conditioned "The user wants me to identify what is in the image.\n\n1. **Analyze the image:**…". Not pushed; FULL SHA reported. Video = M3c (owed); speed unmeasured. | -| `CLAIM-MULTIMODAL-M3C` | `ENG-MM-VIDEO-FORWARD` (engine-matrix, NEW `ACTIVE` — the video path). The `Qwen3VLForConditionalGeneration` model-matrix row narrative-advances IMAGE-only → **image + video preprocessing/wiring landed + unit-gated** (row stays `PARTIAL`/`🚧` — video e2e token-exact PENDING on tower fidelity, speed pending). The two Qwen3.6 mm rows stay `PARTIAL`/narrative-only (27B-video reuses this path, owed). Owns EXACTLY: the video additions to `src/vllm/multimodal/qwen3vl_processor.cpp` + `include/vllm/multimodal/{qwen3vl_processor.h,inputs.h}` (`ProcessVideo`/`VideoSmartResize`/`ComputeVideoTimestamps`/`BuildVideoRepl`/`VideoKwargs`); the per-frame windowed attention in `src/vllm/model_executor/models/qwen3_vl_vision.cpp`; `Qwen3VLGetRopeIndexVideo` in `qwen3_vl_text.{h,cpp}`; `Qwen3VLGenerateGreedyVideo` + the `VLGenerateCore` refactor in `qwen3_vl.{h,cpp}`; the two video tests + fixtures `tests/vllm/multimodal/fixtures/qwen3vl_video/` + 4 `scripts/mm/m3c_*.py` + CMake. NO text-path TU (text SACRED byte-identical BY CONSTRUCTION); the image driver is byte-identical (proven by the image gate). | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/wt-m3c-video` (branch `m3c-video`), base `origin/main` `ed4bc11`; dgx build+gate `dgx.casa:~/work/m3b-vl` (reused build cache) under `flock $HOME/gpu.lock` (sole GPU owner, local-ai-worker Exited) | branch `m3c-video`, base `origin/main` `ed4bc11` | Multimodal **M3c** — extend the image pipeline to VIDEO (frame sampling + temporal grid + timestamp-interleaved expansion + per-frame windowed tower attention + temporal MRoPE) and RUN the video token-exact gate on Qwen3-VL-4B. | `DONE` | 2026-07-25 — **M3c LANDED: video preprocessing + wiring UNIT-GATED; video e2e 22/32, divergence RCA'd OUT of the new video path.** (Gate-form follow-on RESOLVED by `CLAIM-MULTIMODAL-TOWER-FIDELITY`: the divergence is a MEASURED genuine 0.125-nat bf16 near-tie ⇒ near-tie-robust gate PASS; the "PENDING on tower fidelity / tighten envelope" note below is SUPERSEDED — the tower already f32-accumulates everywhere, no kernel change.) Video-processor UNIT gate 41/41 (pixel_values_videos BIT-exact 0/393216, RED-first 195838 mismatch on the image-duplicate mapping); video MRoPE positions BIT-exact vs vLLM (delta −48); video tower faithful rel-L2 0.072 (within the bf16 envelope, image ~0.05); video e2e 22/32 (23-token exact prefix, token-24 bf16 near-tie flip) — every discrete video element bit-exact/faithful ⇒ residual is the shared-decode bf16 tower envelope (M2a ceiling), STRICT token-exact PENDING on tower fidelity, NOT loosened. NO REGRESSION: image e2e 4B STRICT 32/32, CPU units 23/41/85; text SACRED byte-identical BY CONSTRUCTION (zero text-path TU touched). Build cutlass+FA2, clean `-Werror` RC=0, arch 121a. Not pushed; FULL SHA reported. NEXT: tighten tower bf16 envelope to close video token-exact; then 27B-video + speed. | -| `CLAIM-MULTIMODAL-TOWER-FIDELITY` | `ENG-MM-VIDEO-FORWARD` (engine-matrix, `ACTIVE`). Resolves the M3c video e2e gate FORM by MEASUREMENT and closes it. Narrative-advances the `Qwen3VLForConditionalGeneration` model-matrix row IMAGE-only-STRICT + video-PENDING → **image STRICT + video NEAR-TIE-ROBUST, both correct (speed pending)** (row stays `PARTIAL`/`🚧`). Owns EXACTLY: `tests/vllm/multimodal/test_qwen3vl_video_e2e.cpp` (STRICT→near-tie-robust gate), the new `scripts/mm/m3c_video_neartie_gap.py`, and the two new fixture goldens `tests/vllm/multimodal/fixtures/qwen3vl_video/{our_ids_i32.bin,neartie_gap_mnats_i32.bin}`. NO src/kernel/shared-op edit (text SACRED byte-identical BY CONSTRUCTION); image driver unchanged (proven by the image gate). | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp/.claude/worktrees/mm-tower-fidelity` (branch `mm-tower-fidelity`), base `origin/main` `648a5f1`; dgx measure+build+gate `dgx.casa:~/work/m3b-vl` (reused build cache) under `flock $HOME/gpu.lock` (sole GPU owner, local-ai-worker Exited) | branch `mm-tower-fidelity`, base `origin/main` `648a5f1` | Multimodal **M3c tower-fidelity/gate-form** — MEASURE whether the video token divergence is a genuine near-tie or a real fidelity gap (teacher-force vLLM 0.25.0 on OUR prefix), then close it the right way. | `DONE` | 2026-07-25 — **MEASURED: GENUINE bf16 near-tie ⇒ near-tie-robust gate PASS (NOT a fidelity gap, NO kernel change).** The prior spike RCA was WRONG (mislocated the flip at tok24; never teacher-forced). Teacher-forcing vLLM 0.25.0 on OUR exact sequence (`scripts/mm/m3c_video_neartie_gap.py`): the SOLE divergence is ONE near-tie at **tok22** (' colorful' 33866 vs vLLM ' static' 1099, **gap 0.125 nats**, our token vLLM's 2nd of 4 tokens tied within 0.25 nats), and EVERY downstream token (tok23-31) IS vLLM's teacher-forced argmax at gap **0.0000** (the 22/32-vs-greedy is the deterministic one-token shift from that single tie). vLLM is fully self-consistent on the golden (teacher-forced argmax == golden 32/32) ⇒ a clean STRICT target, so our divergence is REAL but a genuine tie, not vLLM jitter. Tower-accumulation analysis: our tower ALREADY accumulates f32 everywhere (cuBLASLt `CUBLAS_COMPUTE_32F` GEMMs + f32 online-softmax attention + f32 LayerNorm) = matches vLLM's cuBLAS/FlashAttention, so rel-L2 0.072 is the irreducible inter-op bf16 rounding envelope, NOT a fixable numeric choice ⇒ NO kernel work (unnecessary; the correct path per the DATA). Adopted the ratified near-tie gate (mirrors olmo2/qwen3-dense/glm4): anchor `our_ids_i32.bin` + `neartie_gap_mnats_i32.bin`, PASS iff all gaps ≤ 0.5 nats — max 0.125 << 0.5 ⇒ `test_qwen3vl_video_e2e` PASS (22/22 assertions). Image e2e 4B STRICT **32/32** (the deterministic strict-pass proof, unchanged). `git diff --stat`: only the video test + new script + 2 fixtures — text SACRED byte-identical BY CONSTRUCTION (zero src/kernel/shared-op ⇒ 27B/35B/Coder re-run NOT required; no kernel ⇒ compute-sanitizer N/A). `benchmark_binding=false`, no speed. Not pushed; FULL SHA reported. | | `CLAIM-AUDIO-PIPELINE` | `ENG-MM-AUDIO-PIPELINE` (engine-matrix, NEW `ACTIVE`). The genuinely-new AUDIO modality (audio-track A0+A1) on the modality-agnostic mm spine, on the smallest oracle-runnable vehicle `openai/whisper-small`. Owns EXACTLY the NEW `src/vllm/multimodal/audio_processor.{h,cpp}` + `include/vllm/multimodal/audio_processor.h`, the `AudioKwargs`+`audio_data` additions to `include/vllm/multimodal/inputs.h`, `MultiModalHasher::HashAudioF32` (`include/vllm/multimodal/hasher.h` + `src/vllm/multimodal/hasher.cpp` refactor), `tests/vllm/multimodal/test_audio_processor.cpp` + fixtures `tests/vllm/multimodal/fixtures/whisper_audio/`, `scripts/mm/a0_audio_ref.py`, 1 `CMakeLists.txt` source line + 2 `tests/CMakeLists.txt` lines, and `.agents/specs/audio-track.md` (NEW). **NON-COLLISION:** additive-only, gated on audio mm input (NO shared forward/kernel/runner/registry edit ⇒ text+image+video byte-identical BY CONSTRUCTION); does NOT touch `multimodal-track.md` / the Qwen3.6 mm model-matrix rows (Qwen3.6-video agent) / the Gemma-4 mm model-matrix rows + `gemma4-multimodal.md` (Gemma-4 agent). Does NOT build the audio ENCODER tower (A2) or the e2e audio→text (A3). | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp-audio-a0a1` (branch `audio-a0a1`, CPU `build-cpu` + CPU test); dgx used only for the A0 oracle reference capture (`~/venvs/vllm-oracle`, feature extraction is CPU, no GPU/flock) | branch `audio-a0a1`, base `origin/main` `435ba70` | Audio-track **A0+A1** — ground the whisper-small vehicle + capture the audio-processor oracle reference (A0), then build the C++ audio INPUT pipeline (WAV decode → identity resample → log-mel `input_features` → placeholder expansion → mm-hash) + the inert engine seam (A1), gated by feature-parity + inertness. NOT audio→text (that is A2 encoder tower + A3 e2e). | `ACTIVE` | 2026-07-25 — **A0+A1 LANDED: audio-processor parity gate PASS 77/77.** A0: `whisper-small` confirmed oracle-constructible on dgx (transformers 5.13.1); captured the WhisperFeatureExtractor log-mel `input_features` `[80,3000]` (real torch STFT path) + mel filterbank `[201,80]` + placeholder `[0]*1500` + mm-hash `2d0c7e4c…` for a deterministic PCM16-mono-16kHz clip (`scripts/mm/a0_audio_ref.py` + committed fixtures, content-hashed). A1: the C++ `WhisperAudioProcessor` — **log-mel rel-L2 1.96e-7** vs the oracle (stated 2e-4 band, torch.stft-FFT vs our DFT summation order; transformers' own torch/numpy claim 1e-5, we sit 2 orders tighter), WAV-decode + placeholder-ids + mm-hash BIT/BYTE-exact, **RED-first** (mel-perturb 2.6e-3 / hop-161 0.70 / no-normalize 9.27 all blow the band). Inertness (shared `hasher.cpp`/`inputs.h` re-run byte-identical): image 23/23 (hasher refactor inert), video 41/41, request 71/71, encoder-cache 32/32, text 85/85; clean CPU `-Werror` 0 warn; `check-device-leakage` unchanged (32==baseline); no CUDA kernel ⇒ compute-sanitizer N/A. All seven record checkers green by bare RC. `benchmark_binding=false`, speed pending. Not pushed; FULL SHA reported. NEXT (A2): the Whisper-class audio encoder tower proven faithful in isolation, then the USM Conformer delta (Granite-Speech-2b); then A3 e2e audio→text on Voxtral-Mini-3B (LANDED Mistral backbone). | | `CLAIM-MULTIMODAL-M3D` | `ENG-MM-QWEN36-VL-FORWARD` (engine-matrix, `ACTIVE`). Completes the Qwen video modalities on our own gate model: the 27B `Qwen3_5ForConditionalGeneration` row narrative-advances IMAGE-e2e-working → **IMAGE+VIDEO e2e working** (the model-matrix row stays `PARTIAL` — speed pending). Owns EXACTLY: the video driver `Qwen3_5VLGenerateGreedyVideo` + the `VLGenerateCoreGdn` refactor of the image driver (`src/vllm/model_executor/models/qwen3_5.cpp`); the video-driver decl (`include/.../qwen3_5_dense.h`); the STRICT gate `tests/vllm/multimodal/test_qwen3_5_vl_video_e2e.cpp` + its CMake + fixtures `tests/vllm/multimodal/fixtures/qwen3_5_27b_video/`; the oracle script `scripts/mm/m3d_video_oracle_capture.py` (reuses the M3c `m3c_video_neartie_gap.py` with `--model Qwen/Qwen3.6-27B`). REUSES (verified, NOT modified) the M3c `ProcessVideo`/`BuildVideoRepl`/`Qwen3VLGetRopeIndexVideo`/per-frame windowed tower attention. NO shared TEXT-forward algorithm change (the video driver is purely additive; the shared `DenseForwardLayers`/`DenseForwardBody`/etc. UNTOUCHED per `git diff --stat`), NO scheduler/runner, NO other model. | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/wt-m3d-video` (branch `m3d-27b-video`), base `origin/main` `64a01af`; dgx build+gate `dgx.casa:~/work/m3d-video` under `flock $HOME/gpu.lock` (sole GPU owner, local-ai-worker Exited) | branch `m3d-27b-video`, base `origin/main` `64a01af` | Multimodal **M3d** — run VIDEO through the 27B GDN-hybrid VL forward (reuse the landed M3c video path) + RUN the STRICT video token-exact gate (complete our own gate model's video path). | `DONE` | 2026-07-25 — **M3d LANDED: STRICT video→text token-exact 32/32 vs vLLM 0.25.0 — Qwen3.6-27B video works e2e; the Qwen video modalities (image+video) are COMPLETE.** Full pipeline (M3c `ProcessVideo` → M2a tower 27B config per-frame windowed attn `[64,5120]` → embed+scatter into video_token(248057) rows [no deepstack] → temporal MRoPE `[11,11,10]` interleaved on the 16 full-attn layers via `Qwen3VLGetRopeIndexVideo` → GDN-hybrid backbone → paged greedy) == golden (gate 27/27 assertions). Oracle `scripts/mm/m3d_video_oracle_capture.py` on the M3c synthetic clip (raw sha `8a111599…`, grid `[4,8,8]`, 64 video tokens) K=5 DETERMINISTIC (first_divergence=None) ⇒ STRICT golden; teacher-forced near-tie gaps 0.0000 nats at every position (0 divergent positions). Generated text: coherent video-conditioned "The user wants me to describe the video…I see a sequence of 6 images…". **Inertness:** 27B IMAGE e2e re-run STRICT **32/32** (54/54, the driver refactor is byte-identical on image); text SACRED **27B 235/235, 35B 315/315, Coder 138/138** byte-identical BY CONSTRUCTION (`git diff --stat`: the qwen3_5.cpp change is confined to the VL-only driver region; the shared text forward is untouched; the video path is gated on mm input ⇒ `mrope_cos_sin==nullptr` on every text caller). Clean CUDA `-Werror` 0 warn (Release, arch 121a, cutlass NVFP4+FP8+Marlin+FA2 ENABLED banner); compute-sanitizer memcheck 0 on the 27B video forward. Not pushed; FULL SHA reported. SPEED unmeasured (`benchmark_binding=false`). | -| `CLAIM-AUDIO-ENCODER` | `ENG-MM-AUDIO-ENCODER` (engine-matrix, NEW `ACTIVE`). The Whisper-class AUDIO ENCODER TOWER (audio-track A2) — the encoder half of audio understanding, proven faithful in ISOLATION on `openai/whisper-small`, consuming the A1 log-mel `input_features` `[80,3000]` → encoder hidden states `[1500,768]`. Owns EXACTLY the NEW `include/vllm/model_executor/models/whisper_audio.h` + `src/vllm/model_executor/models/whisper_audio.cpp`, `tests/vllm/multimodal/test_whisper_audio.cpp` + committed golden fixtures `tests/vllm/multimodal/fixtures/whisper_audio/enc_*`, `scripts/mm/a2_audio_encoder_{ref,weight}_dump.py`, 1 `CMakeLists.txt` source line + 2 `tests/CMakeLists.txt` lines, and its section of `.agents/specs/audio-track.md` (§0b, A2→DONE; A3 kept OWED). **NON-COLLISION:** additive-only (NO shared forward/kernel/runner/registry/other-model TU edit ⇒ text+image+video+audio-pipeline byte-identical BY CONSTRUCTION); does NOT touch `multimodal-track.md` / the Qwen3.6 mm model-matrix rows (Qwen3.6-video agent) / the Gemma-4 mm model-matrix rows + `gemma4-multimodal.md` (Gemma-4 agent); does NOT touch the A0/A1 `audio_processor.*`/`hasher.*`/`inputs.h`. Does NOT build the projector/merge or the e2e audio→text (A3), nor the USM Conformer tower (A2-follow, Granite-Speech-2b). | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm-a2-audio-enc` (branch `feat/audio-a2-encoder`, CPU `build-cpu`); dgx `~/work/a2-audio` (`git archive`, CUDA `build-cuda` cutlass-ON, the A2 reference/weight DUMP on CPU in `~/venvs/vllm-oracle` NO flock, the parity GATE under ONE `flock $HOME/gpu.lock` FOREGROUND, sibling 27B NOT co-resident) | branch `feat/audio-a2-encoder`, base `origin/main` `adcac8e` | Audio-track **A2** — the Whisper-class encoder tower (2×Conv1d im2col+`vt::MatmulBT` frontend + fixed sinusoidal pos + 12 pre-norm bidirectional encoder blocks + final `layer_norm`), proven faithful in isolation vs a dumped bf16 `WhisperEncoder` reference (mirror M2a, bf16-envelope tol). NOT audio→text (A3). | `ACTIVE` | 2026-07-25 — **A2 LANDED: encoder-tower fidelity gate PASS 203/203.** C++ `WhisperAudioEncoderForward` mirrors transformers `WhisperEncoder` (`modeling_whisper.py:641-721,400-430,298-368,54` @ 5.13.1; cross-checked vLLM `whisper.py:458,353,322,473-476`): conv frontend as im2col+`vt::MatmulBT` (no new CUDA kernel), GELU-erf, k_proj no-bias, full bidirectional `vt::Attention(causal=false)`. Reference dumped in bf16 on CPU (`scripts/mm/a2_audio_encoder_ref.py`, post_pos recon maxdev 0.0); embed_positions committed as a golden constant. **GATE (GPU under flock, cutlass-ON banner CONFIRMED, sibling 27B NOT co-resident):** post_conv rel-L2 **4.7e-3**, post_pos **2.8e-3**, block0 **6.6e-3**, encoder-output **3.0e-2** (bf16-depth envelope ~0.28%/layer over 12 layers, matches M2a; bands post_conv/post_pos<8e-3, block0<1.5e-2, final<5e-2 = measured×1.6–2.3). **RED-first (revert-experiment, GPU under flock):** wrong conv-stride → post_conv 0.34 (72×, FAIL); missing sinusoid → post_pos 0.86 (FAIL); skipped final-LN → 4.22 (140×, FAIL); honest non-discriminators recorded (GELU-tanh≈erf in-envelope, single conv-weight aggregate-insensitive). **INERT:** `git diff --stat` vs `adcac8e` = 7 additive entries + committed fixtures, NO shared TU ⇒ text/image/video/audio-pipeline byte-identical BY CONSTRUCTION; `check-device-leakage` unchanged; im2col+existing GEMM ⇒ no new kernel, no compute-sanitizer. Clean CUDA + CPU `-Werror` 0 warn; all seven record checkers green by bare RC. `benchmark_binding=false`, speed pending. Not pushed; FULL SHA reported. NEXT (A3): projector (RMSNorm+Linear) + masked-scatter merge into the LANDED Mistral decoder on Voxtral-Mini-3B → e2e audio→text token-exact vs vLLM 0.25.0 (gate form by measurement). | | `CLAIM-AUDIO-E2E` | `ENG-MM-AUDIO-E2E` (engine-matrix, NEW `ACTIVE`) + `MODEL-MM-voxtral-voxtral-for-conditional-generation` (model-matrix, `INVENTORIED`→`ACTIVE`). Audio-track **A3** — the FIRST e2e AUDIO→TEXT understanding, on `mistralai/Voxtral-Mini-3B-2507` (Whisper-large-v3-class encoder + AudioLanguageAdapter projector + the LANDED Mistral/Llama text decoder). Owns EXACTLY the NEW `include/vllm/model_executor/models/voxtral.h` + `src/vllm/model_executor/models/voxtral.cpp`, `tests/vllm/multimodal/test_voxtral_e2e.cpp` + committed fixtures `tests/vllm/multimodal/fixtures/voxtral_audio/`, `scripts/mm/a3_voxtral_{oracle_capture,neartie_gate,textonly,wcheck,debug_dump}.py`, 1 `CMakeLists.txt` source line + `tests/CMakeLists.txt` test wiring, and its §1 (A3) of `.agents/specs/audio-track.md`, plus this row + the Voxtral model-matrix row + the `ENG-MM-AUDIO-E2E` engine row + README/BENCHMARKS/state/ledger. **NON-COLLISION:** additive-only (NO shared forward/kernel/runner/registry/other-model TU edit ⇒ text/image/video/audio-pipeline byte-identical BY CONSTRUCTION); does NOT touch the Qwen/Gemma-4 mm rows or `multimodal-track.md`/`gemma4-multimodal.md`; reuses (does NOT edit) `whisper_audio.*` (A2), `audio_processor.*` (A1), `qwen3.*`/`dense_attn_block.h` (Mistral decoder), `qwen3_vl_text.*` (merge). | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm.cpp-a3` (branch `a3-voxtral-e2e`); dgx build+gate `~/vllm-cpp-a3-build` (CUDA cutlass-ON `-DCMAKE_CUDA_ARCHITECTURES=121a`, oracle capture in `~/venvs/vllm-oracle`, e2e gate under ONE `flock $HOME/gpu.lock` FOREGROUND, sibling 27B NOT co-resident) | branch `a3-voxtral-e2e`, base `origin/main` `c4f4dfcc` | Audio-track **A3** — encoder-at-Voxtral-config + downsample-concat + AudioLanguageAdapter projector + masked-scatter merge into the LANDED Mistral decoder → forked greedy; audio→text gate form BY MEASUREMENT. | `ACTIVE` | 2026-07-25 — **A3 LANDED: e2e audio→text gate PASS 14/14.** Voxtral-Mini-3B downloadable (NOT HF-gated) + oracle-runnable (vLLM 0.25.0 `load_format=mistral`, K=5 DETERMINISTIC greedy → STRICT bar). Full C++ pipeline (A1 log-mel [128,3000] rel-L2 7.7e-7 → A2 encoder at Voxtral config → downsample4 → projector [375,3072] → merge at token-24 → Mistral greedy). STRICT prefix 33/48 vs vLLM greedy; decoder proven token-exact (vLLM ref-audio→48/48); bit-exact infeasible (encoder different bf16 GEMM/attn kernels, 8.7% = A2 envelope over 32 layers) ⇒ ratified near-tie-robust gate PASS (worst teacher-forced gap 0.0 nats, sole branch a 4-way bf16 tie at -2.069 nats; `scripts/mm/a3_voxtral_neartie_gate.py`). **KEY FIX:** mistral-consolidated q/k need vLLM's Meta→NeoX rope PERMUTE (verified `permute(wq)==vLLM q_proj`); RED text-only 1/22→22/22. **INERT:** additive (`git diff --stat` = 2 modified lines); Mistral 541/541 + A1 77/77 + A2 203/203 byte-identical; `check-device-leakage` unchanged; no new CUDA kernel ⇒ no compute-sanitizer. Clean CUDA `-Werror` 0-warn, cutlass-ON banner CONFIRMED, all seven checkers green by bare RC. `benchmark_binding=false`, speed pending. NOT pushed; FULL SHA reported. NEXT: A2-follow USM-Conformer (Granite-Speech-2b) for the Gemma-4 audio family; A3 speed grid vs vLLM. | | `CLAIM-MULTIMODAL-SPEED-TOWER` | `ENG-MM-QWEN36-VL-FORWARD` (engine-matrix, `ACTIVE`) + `ENG-MM-VISION-TOWER` (narrative). Executes mm speed lever #1 (the vision encoder tower). Owns EXACTLY: the vision tower forward + resident-weights path `src/vllm/model_executor/models/qwen3_vl_vision.{cpp,h}`; the NEW additive attention op `AttentionDenseFast` (`src/vt/cuda/cuda_ops.cu` `AttentionWarpKernel`/`LaunchAttentionWarp`/registration; `include/vt/ops.h` enum+decl; `src/vt/ops.cpp` wrapper; `src/vt/cpu/cpu_ops.cpp` CPU registration reusing the existing reference); the bench `tests/vllm/multimodal/bench_qwen3_5_vl_tower.cpp` + its CMake; the records. **NON-COLLISION:** purely additive — the existing `kAttention`/`AttentionKernel` and every text/audio kernel UNCHANGED (`git diff`); text never calls `kAttentionDenseFast` ⇒ text/audio byte-identical BY CONSTRUCTION (`test_ops_attention` 37239/37239, 27B text SACRED 235/235). Does NOT touch scheduler/runner/registry/other-model TUs. | Claude Code (opus-4-8) | isolated worktree `/home/mudler/_git/vllm-tower-speed` (branch `spike/mm-tower-speed`); dgx build+profile+gate `dgx.casa:~/work/mm-tower-speed` (CUDA cutlass 4.5.0 `-DCMAKE_CUDA_ARCHITECTURES=121a` + FA2 + Triton, ALL GPU under `flock $HOME/gpu.lock` sole owner) | branch `spike/mm-tower-speed`, base `origin/main` `27bc3054` | Multimodal SPEED **tower lever #1** — profile the tower (W0), port the dominant divergent kernel (W1), keep image e2e STRICT 32/32. | `DONE` | 2026-07-26 — **TOWER LEVER CLOSED + BEATEN.** W0 (nsys `cuda_gpu_kern_sum`): 98.9% of the tower forward = the naive `vt::cuda::AttentionKernel` (56 ms/block over 784 patches; NOT QKV/FA2-routing — the `cuda_api_sum` cudaFree-93% was a sync-artifact). W1: warp-scoped online-softmax op `AttentionDenseFast` (no `__syncthreads`, `__shfl_xor` head_dim reduce, register accumulator; separate op ⇒ text byte-identical) + one-time resident-weight load ⇒ **per-image tower 2114→148 ms (14.3×), 0.59× vs vLLM's ~250 ms eager encode = FASTER.** RED-line HELD: 27B image STRICT 32/32, 27B video STRICT 32/32, 4B DeepStack image STRICT 32/32, `test_ops_attention` 37239/37239, 27B text SACRED 235/235; clean `-Werror` 0 warn (cutlass+FA2 banner), compute-sanitizer memcheck 0. `benchmark_binding=false`; DONE-bar still unmet (batched/graphed mm serving c2+ + audio our-side). NOT pushed; FULL SHA reported. | @@ -1798,3 +1794,32 @@ list of what the project supports. Evidence: [2026-07-25 4B repair](../docs/bench-evidence/qwen35-4b-main-repair-20260725.md). **DFlash D14 note (2026-07-27, `CLAIM-DFLASH-D14`, GPU-GATED on dgx, SPEED GATE MET → `SPEC-DFLASH` DONE, NOT pushed — FULL SHA reported to caller).** Closes `SPEC-DFLASH` (engine-matrix row `SPEC-DFLASH` + kernel-matrix `KERNEL-ATTN-DFLASH-PAGED-BLOCK` + model-matrix `MODEL-SPEC-qwen3-dflash-dflash-qwen3-for-causal-lm`) → `DONE`. Base `origin/main` `4657f6f3`, isolated worktree `/home/mudler/_git/wt-dflash-d14` (branch `dflash-d14`); dgx reused tree `~/work/dflash-d12/tree/build-cuda`, one `flock $HOME/gpu.lock`. An nsys of the graphed spec-on step attributed the D13 ~2% residual to the from-scratch draft-attention kernel; ported it to a WARP-scoped online-softmax variant (`DFlashPagedBlockAttentionWarpKernel`, 3.1× faster) → our-ON graphed 29.32 ≥ vLLM-ON graphed 29.240 (non-overlapping 3-rep bands, 1.003×). Correctness UNCHANGED (27/27 graph==eager, acceptance 19/39/29/25, 1629 accepted identical warp-vs-block, CUDA==CPU 795648/795648 + sanitizer 0); inertness SACRED 235/235 + MTP 9/9. **Owned files ONLY:** `src/vt/cuda/cuda_ops.cu` (additive: `DFlashPagedBlockAttentionWarpKernel` + `UseDflashAttnBlockKernel` + a launcher branch; the D12 block kernel retained under `VT_DFLASH_ATTN_BLOCK=1`) + the record surfaces (spec §0 D14 RESULT, engine-matrix, kernel-matrix, model-matrix + checklist rollup, roadmap, ledger, state, this note, README, `docs/BENCHMARKS.md`). **EXPLICIT NON-COLLISION:** does NOT touch the causal `kAttention`/`kPagedAttention`, any non-DFlash op, the runner, or the models — the warp kernel is reached ONLY via `DFlashPagedBlockAttention` (DFlash draft path). Roadmap's FINAL open speed item; SPEC-DFLASH is now correctness-complete AND at/above vLLM throughput. + +- 2026-08-06: `CLAIM-MULTIMODAL-M1`, `CLAIM-MULTIMODAL-M3C`, + `CLAIM-MULTIMODAL-TOWER-FIDELITY` and `CLAIM-AUDIO-ENCODER` RETIRED by the + live-state audit ([live-state-audit-2026-08-06.md](specs/live-state-audit-2026-08-06.md) + ➂). Each references ONLY a row the audit found abandoned — no `row/` branch + anywhere and no commit on `origin/main` naming the stable ID — so emptying the + claim would leave it with no rows, which the row contract also rejects; they are + retired outright and their rows move `ACTIVE` → `READY` (the legality floor: all + three resolve a real spec that names their token). **`ABANDONED` is a statement + about Git, not about the work** — each row asserts a passing gate, and the real + defect is that the commits never named the stable row ID. Outcomes as the claims + last recorded them: + - `CLAIM-MULTIMODAL-M1` (row `ENG-MM-INPUT-PIPELINE`, last state `ACTIVE`) — + 2026-07-25 M0+M1 landed: processor parity 23/23 BIT-identical vs the vLLM + 0.25.0 M0 oracle, encoder-cache 32/32, SACRED text-inertness 27B 235/235 / + 35B 315/315 / Coder 138/138. `benchmark_binding=false`, speed never measured. + - `CLAIM-MULTIMODAL-M3C` (row `ENG-MM-VIDEO-FORWARD`, last state `DONE`) — + 2026-07-25 M3c video preprocessing + wiring unit-gated: video-processor 41/41 + with `pixel_values_videos` BIT-exact 0/393216, video MRoPE BIT-exact vs vLLM. + - `CLAIM-MULTIMODAL-TOWER-FIDELITY` (row `ENG-MM-VIDEO-FORWARD`, last state + `DONE`) — 2026-07-25 the M3c video e2e gate FORM resolved by measurement: + teacher-forcing vLLM 0.25.0 proved a single genuine 0.125-nat bf16 near-tie at + tok22, every downstream token vLLM's argmax at gap 0.0000 ⇒ near-tie-robust + PASS, no kernel change. + - `CLAIM-AUDIO-ENCODER` (row `ENG-MM-AUDIO-ENCODER`, last state `ACTIVE`) — + 2026-07-25 A2 encoder-tower fidelity gate PASS 203/203 (post_conv rel-L2 + 4.7e-3, post_pos 2.8e-3, block0 6.6e-3, encoder-output 3.0e-2), RED-first + proven. `benchmark_binding=false`, speed pending. The projector/merge and the + audio→text e2e (A3) were never in this claim's scope. diff --git a/.agents/engine-matrix.md b/.agents/engine-matrix.md index d9e1e45e..b7b56e28 100644 --- a/.agents/engine-matrix.md +++ b/.agents/engine-matrix.md @@ -36,7 +36,7 @@ forensics: roadmap_v1.md and the parity ledger. | Area | Rows | `ANCHOR-BACKFILL` | `PARTIAL` | `SPIKE` | `READY` | `ACTIVE` | `GATING` | `DONE` | `INVENTORIED` | |---|---:|---:|---:|---:|---:|---:|---:|---:|---:| -| Engine and scheduling | 27 | 6 | 3 | 1 | 0 | 9 | 2 | 2 | 4 | +| Engine and scheduling | 27 | 6 | 3 | 1 | 3 | 6 | 2 | 2 | 4 | | KV cache and memory | 21 | 7 | 3 | 1 | 2 | 1 | 2 | 0 | 5 | | Parallelism | 6 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 5 | | Sampling and generation | 15 | 4 | 2 | 0 | 0 | 3 | 0 | 1 | 5 | @@ -46,7 +46,7 @@ forensics: roadmap_v1.md and the parity ledger. | LoRA and adapters | 2 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | | Long context and attention | 10 | 5 | 0 | 0 | 1 | 0 | 1 | 0 | 3 | | Loading, tokenizer, config | 9 | 3 | 3 | 0 | 0 | 0 | 1 | 1 | 1 | -| **Total** | **131** | **36** | **16** | **4** | **4** | **21** | **8** | **9** | **32** | +| **Total** | **131** | **36** | **16** | **4** | **7** | **18** | **8** | **9** | **32** | ## Engine core and scheduling @@ -69,13 +69,13 @@ forensics: roadmap_v1.md and the parity ledger. | `ENG-DBO-UBATCH` | DBO and ubatch overlap | T2 | `vllm/config/parallel.py:208,524` | - | - | `planned: specs/dbo-ubatch.md` | `INVENTORIED` | - | | `ENG-MOE-SHARED-AUX` | MoE shared-expert MLP on an aux CUDA stream concurrent with the routed-expert router/align/grouped-GEMMs (mirror vLLM's decode overlap; the largest remaining 35B c1/c2 engine lever). Fork the shared MLP onto a 2nd persistent per-device stream, join before the combine → byte-identical to serial (independent shared/routed paths both complete before combine; overlap changes WHEN not WHAT). Gated `T <= threshold` decode + CUDA. The aux stream draws scratch from a SEPARATE `AuxPool` so the concurrent main-stream routed allocations never share a live block with it (the `DevicePool` reuse invariant is single-stream ordering; vLLM sidesteps this with its stream-aware caching allocator's `record_stream`). `VT_MOE_SHARED_AUX_STREAM` **DEFAULT ON** (`=0` rollback); `VT_MOE_SHARED_AUX_THRESHOLD` (default 128; GB10 48-SM calibration). Captured in the decode CUDA-graph via the fork/join event edges (`ThreadLocal` capture, no abort). Only the committed Marlin MoE decode path; wmma fallback/CPU/GGUF and 27B dense unaffected | T1 | `vllm/model_executor/layers/fused_moe/runner/shared_experts.py:99-104,125-142`; `vllm/utils/multi_stream_utils.py:20-58` (`maybe_execute_in_parallel`, TRT-LLM port); `vllm/utils/torch_utils.py:736-756` (`aux_stream`); `vllm/envs.py:260` (threshold 256) | fork/join `src/vllm/model_executor/models/qwen3_5.cpp:3999,4114` (`MoeBlockFusedMarlinCuda`); aux stream+events `src/vllm/model_executor/models/qwen3_5.cpp:3575,3581` (`MoeAuxStream`/`MoeAuxStreamFor`); predicates `:3553,3560`; aux-pool isolation `:496,3538` (`AuxPool`/`ActivePool`/`ActivePoolScope`) + `DBuf pool_` routing `:645` | **DGX (prod flags, one flock):** overlap ON==OFF BYTE-IDENTICAL — `tests/parity/test_qwen36_paged_engine.cpp:116` 35B **315/315** + `tests/parity/test_qwen27_paged_engine.cpp` 27B **235/235** under `VT_MOE_SHARED_AUX_STREAM`∈{0,1}; captured-vs-eager (`VLLM_CPP_CUDAGRAPH=0`, ON) 315/315; shipping default (no env) 315/315+235/235, rollback `=0` 315/315+235/235; `compute-sanitizer memcheck` (default ON, captured) 0 errors; in-situ interleaved TPOT A/B (drop cold rep1) c1 −5.6% / c2 −2.7% / c4 −3.7% / c8 −3.4% / c16 −1.6% / c32 −1.5% (WINS every conc, zero regression); ledger [parity-ledger.md](parity-ledger.md) 2026-07-19 row | [moe-shared-aux-stream.md](specs/moe-shared-aux-stream.md) | `ANCHOR-BACKFILL` | `CLAIM-MOE-SHARED-AUX-1` | | `ENG-RUNNER-MODELSHAPE` | **Runner is model-shape-agnostic over the KV-cache group structure** — the extensibility deliverable the first additive-model bring-up (Qwen3 dense) forced. Before W1 the `GPUModelRunner` had only ever executed the Qwen3.6 HYBRID topology and hardcoded it in two places: (#1) the KV-buffer alloc loop indexed `config_.layer_types[l]`, out-of-bounds on a pure-dense model's EMPTY `layer_types`; (#2) each `execute_model` step unconditionally built the GDN metadata (`gather_block_table(gdn_group_id_)` / `remap_gdn_state_slots` / `GDNAttentionMetadataBuilder`), which reads `block_table[-1]` when there is no mamba group. W1 drives both off the resolved KV-group structure — a model-agnostic `has_mamba_group` / `gdn_group_id_ >= 0` predicate (NOT a model-name check): empty/absent `layer_types` ⇒ all full-attention; no mamba group ⇒ the whole GDN metadata/state path is skipped and `gdn_meta` stays default-empty. A full-attention-only KV config (one FA group, no MambaSpec) now allocates + steps cleanly; the hybrid gate models keep their GDN group so their path is BYTE-IDENTICAL. This is a one-time generalization: every future dense/non-hybrid arch (Llama, Mistral) now adds new-files-only, zero further runner edits. **PER-LAYER KV head_dim extension (Gemma-4 G1b, 2026-07-28, `CLAIM-GEMMA4-G1B`):** the runner's full-attn alloc/view loops now consume an OPTIONAL `KVCacheConfig::per_layer_attn_specs` (index == layer) so a HETEROGENEOUS-head_dim model (Gemma-4: sliding 256 / global 512, same num_kv_heads) sizes each non-GDN layer's paged KV + PagedKvCache view from its OWN spec. The field is EMPTY for every uniform-KV model ⇒ the loop collapses to the single group spec ⇒ byte-identical allocation/view/indexing/dispatch (same additive-identical property as the model-shape generalization above). Block table / KV manager / scheduler stay head_dim-independent (num_blocks + block_size, uniform) so no per-group block table is introduced | T0 | model-agnostic runner drives off `kv_cache_config.kv_cache_groups` — `vllm/v1/worker/gpu/model_runner.py` `initialize_kv_cache` / attention-metadata build (per-group, no hardcoded hybrid) @ `e24d1b24` | `src/vllm/v1/worker/gpu/runner.cpp:458-470` (alloc loop: `has_mamba_group && !layer_types.empty()` gate) + `:651-680` (GDN metadata build gated on `gdn_group_id_ >= 0`, default-empty `gdn_meta` otherwise); per-layer KV head_dim: `include/vllm/v1/kv_cache_interface.h` (`KVCacheConfig::per_layer_attn_specs`) consumed in `src/vllm/v1/worker/gpu/runner.cpp` `initialize_kv_cache` (per-layer `FaDims` alloc+view), published by `src/vllm/model_executor/models/gemma4_registry.cpp` (`MakeGemma4ForConditionalGenerationKVCache`); the full-attention-only KV spec that exercises the base path `src/vllm/model_executor/models/qwen3_dense.cpp` (`MakeQwen3ForCausalLMKVCache`) | `tests/vllm/v1/worker/test_runner.cpp:1129` — "full-attention-only KV config allocates without the GDN path" + "full-attention-only step skips GDN metadata build (no OOB)" (RED→GREEN: both SIGSEGV pre-generalization; GREEN post). Behaviour-preservation gate: DGX **27B 235/235 + 35B 315/315 UNCHANGED** under the fix; per-layer-KV inertness: full CPU runner/KV suite green + **OLMo-2 SACRED GPU re-gate 16/16 UNCHANGED**; heterogeneous path proven by **Gemma-4 E4B STRICT 32/32** (`tests/parity/test_gemma4_paged_engine.cpp`); ASan/UBSan clean on the affected paths | [first-additive-model-qwen3-dense.md](specs/first-additive-model-qwen3-dense.md) §3 (seam gaps #1/#2), §6 (W1); [gemma4-multimodal.md](specs/gemma4-multimodal.md) §G1b | `ACTIVE` | `CLAIM-MODEL-QWEN3-DENSE` | -| `ENG-MM-INPUT-PIPELINE` | **Multimodal INPUT pipeline + encoder-cache engine seam (M1), INERT when no mm input.** The C++ mirror of `vllm/multimodal/`: `MultiModalKwargs`/`MultiModalFeatureSpec`/`MultiModalInputs`, the `MultiModalHasher` mm-hash (blake3), the Qwen3-VL image processor (smart_resize + fused rescale/normalize + patchify -> `pixel_values`+`image_grid_thw`) and placeholder-token expansion, plus the `EncoderCacheManager` (+`ComputeMmEncoderBudget`) and the LMCache `extra_keys` seam. Additive `mm_features` carried on `Request`/`EngineCoreRequest`; with NO mm input every field is empty and every path is byte-identical to the text engine. Processor output is BIT/BYTE-identical to the vLLM 0.25.0 oracle (M0 fixture). Does NOT build the vision tower / embed-merge (M2). **SERVING wiring (ROAD-V1-MM `MM-SERVE-ENGINE`, 2026-07-28, `CLAIM-MM-SERVING-W2`):** the OpenAI server now carries the parsed `MultiModalInputs` into the engine — additive `LLMEngine`/`AsyncLLM` `add_request(MultiModalInputs)`+`generate(MultiModalInputs)` overloads via `InputProcessor::process_inputs_mm` (mirror `input_processor.py:333-379`, empty mm_features == the tokens path), the chat-template placeholder-STRING helpers (`get_placeholder_str`/`_add_placeholder` mirror), and the serving_chat `MultiModalChatFn` seam (default unset ⇒ text byte-identical). **SEAM BODY (ROAD-V1-MM `MM-SERVE-E2E` W3, 2026-07-28, `CLAIM-MM-SERVING-E2E`):** `MakeQwen3VLImageChatFn` (chat_mm.cpp) is the seam body the server sets — messages → marker-inject → chat template → `EncodeWithSpecialTokens` (the single image_pad marker → one image_token_id) → `RouteImageRgb` EXPAND to 196 image tokens + mm_features; wired in `examples/server/main.cpp` (guarded on `preprocessor_config.json`; text-only unset ⇒ byte-identical). Gated `test_chat_mm` 8/8 + `test_openai_serving` (seam invoked + routed). **ENGINE MM-FORWARD LANDED (ROAD-V1-MM `MM-SERVE-E2E`, 2026-07-28, `CLAIM-ENGINE-MM-FORWARD`):** the engine model runner now HAS an mm forward — `ModelForwardInput` gains an ADDITIVE default-nullopt `std::optional mm` (merged inputs_embeds + 3-D MRoPE positions + DeepStack, borrowed handles; nullopt-for-text ⇒ shared runner path byte-identical BY CONSTRUCTION), `Qwen3VLForConditionalGeneration` is `REGISTER_VLLM_MODEL`-registered (`qwen3_vl_registry.cpp`), and the registered forward FOLDS the M2c decode into `ModelRegistry::Forward` via the SHARED `Qwen3VLForwardStepLastLogits` (`Qwen3VLGenerateGreedyViaRegistry` drives every step through the registry). GPU token-exact gate `test_qwen3vl_registry_e2e` (image→text THROUGH `ModelRegistry::Forward` == M2c golden 32/32 STRICT, dgx.casa GB10); text inertness `test_runner` 16/16 + `test_scheduler` 36/36 + `test_model_registry` 24/24 + `test_chat_mm` 8/8 + `test_openai_serving` 41/41 all green. RESIDUAL: the FULL in-runner scheduler-fed tower run (batched-loop mm building the field from staged encoder outputs) + the real server `/v1/chat/completions` GPU e2e — recipe in `specs/mm-serving.md`. | T1 | `vllm/multimodal/{inputs.py,hasher.py:50,processing/processor.py:1663,processing/inputs.py:62}`; `vllm/model_executor/models/qwen3_vl.py:{1400,1233}`; `vllm/v1/core/encoder_cache_manager.py:17`; transformers `image_processing_qwen2_vl.py:62`, `image_processing_backends.py:327`; tests `tests/multimodal/test_processing.py`, `tests/multimodal/test_hasher.py`, `tests/v1/core/test_encoder_cache_manager.py` @ `e24d1b24` | `src/vllm/multimodal/hasher.cpp`, `src/vllm/multimodal/qwen3vl_processor.cpp`, `include/vllm/multimodal/{inputs.h,hasher.h,qwen3vl_processor.h}`; `src/vllm/v1/core/encoder_cache_manager.cpp` + `include/vllm/v1/core/encoder_cache_manager.h`; additive inert fields `include/vllm/v1/request.h` + `src/vllm/v1/request.cpp` + `include/vllm/v1/engine/types.h`; `extra_keys` seam `include/vllm/v1/kv_offload/lmcache/chunked_token_database.h` + `.cpp`; M0 `scripts/mm/m0_oracle_capture.py` — anchor `src/vllm/multimodal/hasher.cpp:56` | `tests/vllm/multimodal/test_qwen3vl_processor.cpp` (processor-parity 23/23 BIT-identical vs the M0 oracle fixture `tests/vllm/multimodal/fixtures/qwen3vl/`, RED-first: wrong normalize shift -> 1.2M mismatches); `tests/vllm/v1/core/test_encoder_cache_manager.cpp` 32/32. Text-inertness: `test_request`/`test_engine_types`/`test_lmcache_codec`/`test_lmcache_key_agreement`/`test_openai_conformance` all green standalone; SACRED CUDA 27B/35B/Coder = GPU inertness proof; `check-device-leakage` OK — anchor `tests/vllm/multimodal/test_qwen3vl_processor.cpp:59` | [multimodal-track.md](specs/multimodal-track.md) §3 (M0/M1) | `ACTIVE` | `CLAIM-MULTIMODAL-M1` | +| `ENG-MM-INPUT-PIPELINE` | **Multimodal INPUT pipeline + encoder-cache engine seam (M1), INERT when no mm input.** The C++ mirror of `vllm/multimodal/`: `MultiModalKwargs`/`MultiModalFeatureSpec`/`MultiModalInputs`, the `MultiModalHasher` mm-hash (blake3), the Qwen3-VL image processor (smart_resize + fused rescale/normalize + patchify -> `pixel_values`+`image_grid_thw`) and placeholder-token expansion, plus the `EncoderCacheManager` (+`ComputeMmEncoderBudget`) and the LMCache `extra_keys` seam. Additive `mm_features` carried on `Request`/`EngineCoreRequest`; with NO mm input every field is empty and every path is byte-identical to the text engine. Processor output is BIT/BYTE-identical to the vLLM 0.25.0 oracle (M0 fixture). Does NOT build the vision tower / embed-merge (M2). **SERVING wiring (ROAD-V1-MM `MM-SERVE-ENGINE`, 2026-07-28, `CLAIM-MM-SERVING-W2`):** the OpenAI server now carries the parsed `MultiModalInputs` into the engine — additive `LLMEngine`/`AsyncLLM` `add_request(MultiModalInputs)`+`generate(MultiModalInputs)` overloads via `InputProcessor::process_inputs_mm` (mirror `input_processor.py:333-379`, empty mm_features == the tokens path), the chat-template placeholder-STRING helpers (`get_placeholder_str`/`_add_placeholder` mirror), and the serving_chat `MultiModalChatFn` seam (default unset ⇒ text byte-identical). **SEAM BODY (ROAD-V1-MM `MM-SERVE-E2E` W3, 2026-07-28, `CLAIM-MM-SERVING-E2E`):** `MakeQwen3VLImageChatFn` (chat_mm.cpp) is the seam body the server sets — messages → marker-inject → chat template → `EncodeWithSpecialTokens` (the single image_pad marker → one image_token_id) → `RouteImageRgb` EXPAND to 196 image tokens + mm_features; wired in `examples/server/main.cpp` (guarded on `preprocessor_config.json`; text-only unset ⇒ byte-identical). Gated `test_chat_mm` 8/8 + `test_openai_serving` (seam invoked + routed). **ENGINE MM-FORWARD LANDED (ROAD-V1-MM `MM-SERVE-E2E`, 2026-07-28, `CLAIM-ENGINE-MM-FORWARD`):** the engine model runner now HAS an mm forward — `ModelForwardInput` gains an ADDITIVE default-nullopt `std::optional mm` (merged inputs_embeds + 3-D MRoPE positions + DeepStack, borrowed handles; nullopt-for-text ⇒ shared runner path byte-identical BY CONSTRUCTION), `Qwen3VLForConditionalGeneration` is `REGISTER_VLLM_MODEL`-registered (`qwen3_vl_registry.cpp`), and the registered forward FOLDS the M2c decode into `ModelRegistry::Forward` via the SHARED `Qwen3VLForwardStepLastLogits` (`Qwen3VLGenerateGreedyViaRegistry` drives every step through the registry). GPU token-exact gate `test_qwen3vl_registry_e2e` (image→text THROUGH `ModelRegistry::Forward` == M2c golden 32/32 STRICT, dgx.casa GB10); text inertness `test_runner` 16/16 + `test_scheduler` 36/36 + `test_model_registry` 24/24 + `test_chat_mm` 8/8 + `test_openai_serving` 41/41 all green. RESIDUAL: the FULL in-runner scheduler-fed tower run (batched-loop mm building the field from staged encoder outputs) + the real server `/v1/chat/completions` GPU e2e — recipe in `specs/mm-serving.md`. | T1 | `vllm/multimodal/{inputs.py,hasher.py:50,processing/processor.py:1663,processing/inputs.py:62}`; `vllm/model_executor/models/qwen3_vl.py:{1400,1233}`; `vllm/v1/core/encoder_cache_manager.py:17`; transformers `image_processing_qwen2_vl.py:62`, `image_processing_backends.py:327`; tests `tests/multimodal/test_processing.py`, `tests/multimodal/test_hasher.py`, `tests/v1/core/test_encoder_cache_manager.py` @ `e24d1b24` | `src/vllm/multimodal/hasher.cpp`, `src/vllm/multimodal/qwen3vl_processor.cpp`, `include/vllm/multimodal/{inputs.h,hasher.h,qwen3vl_processor.h}`; `src/vllm/v1/core/encoder_cache_manager.cpp` + `include/vllm/v1/core/encoder_cache_manager.h`; additive inert fields `include/vllm/v1/request.h` + `src/vllm/v1/request.cpp` + `include/vllm/v1/engine/types.h`; `extra_keys` seam `include/vllm/v1/kv_offload/lmcache/chunked_token_database.h` + `.cpp`; M0 `scripts/mm/m0_oracle_capture.py` — anchor `src/vllm/multimodal/hasher.cpp:56` | `tests/vllm/multimodal/test_qwen3vl_processor.cpp` (processor-parity 23/23 BIT-identical vs the M0 oracle fixture `tests/vllm/multimodal/fixtures/qwen3vl/`, RED-first: wrong normalize shift -> 1.2M mismatches); `tests/vllm/v1/core/test_encoder_cache_manager.cpp` 32/32. Text-inertness: `test_request`/`test_engine_types`/`test_lmcache_codec`/`test_lmcache_key_agreement`/`test_openai_conformance` all green standalone; SACRED CUDA 27B/35B/Coder = GPU inertness proof; `check-device-leakage` OK — anchor `tests/vllm/multimodal/test_qwen3vl_processor.cpp:59` | [multimodal-track.md](specs/multimodal-track.md) §3 (M0/M1) | `READY` | - | | `ENG-MM-VISION-TOWER` | **Qwen3-VL vision tower `Qwen3_VisionTransformer` (M2a), proven faithful vs vLLM 0.25.0 in isolation.** The reusable vision half of the whole Qwen3-VL family + Qwen3.6 (27B/35B share this exact tower). Pure-additive C++ forward composed from public vt:: ops: patch-embed (Conv3d-as-matmul + bias), host pos-embed bilinear-interp+spatial-merge-reorder, 24 ViT blocks (LayerNorm + vision attention with partial-rotary NeoX vision RoPE via `vt::RopeFromCache` + non-causal `vt::Attention(causal=false)` + tanh-GELU MLP), patch merger (LayerNorm + exact-erf-GELU + 2 FCs), DeepStack 3 post-shuffle-norm mergers at layers 5/11/17 → `[196,10240]`. Adds 2 additive elementwise vt ops (`GeluTanh`/`GeluErf`). NO runner/model/registry edit → text engines byte-identical by construction. Proven faithful in ISOLATION; the merge into `input_embeds` + the MRoPE/DeepStack text backbone + the e2e image gate are M2b/M2c. | T1 | `vllm/model_executor/models/qwen3_vl.py` `Qwen3_VisionPatchEmbed:347`, `Qwen3_VisionBlock:413`, `Qwen3_VisionPatchMerger:467`, `Qwen3_VisionTransformer:519`, `forward:800`, `pos_embed_interpolate_native:277`, `rot_pos_emb:667`; `qwen2_5_vl.py::Qwen2_5_VisionAttention.forward:397`; `rotary_embedding/common.py::ApplyRotaryEmb.forward_static:151` @ `e24d1b24` | `src/vllm/model_executor/models/qwen3_vl_vision.{h,cpp}`; 2 vt ops `include/vt/ops.h` + `src/vt/ops.cpp` + `src/vt/cuda/cuda_layernorm.cu` + `src/vt/cpu/cpu_layernorm.cpp`; dumps `scripts/mm/m2a_tower_{ref,weight}_dump.py`; fixtures `tests/vllm/multimodal/fixtures/qwen3vl_tower/` | `tests/vllm/multimodal/test_qwen3vl_tower.cpp` — 4 RED-first tower gates vs the dumped vLLM-0.25.0 reference 348/348 (patch-embed 2.1e-3, block0 6.8e-3, merger 6.5e-2, DeepStack 1.2e-2/3.3e-2/4.4e-2, full tower 5.1e-2; pos-embed 2.5e-3 + rope 1.9e-3 TIGHT); bf16-depth envelope RCA'd; RED = rope disabled → block0 0.149/tower 0.75/6 fails; cutlass-ON+FA2 banner; clean `-Werror`; compute-sanitizer 0 — anchor `tests/vllm/multimodal/test_qwen3vl_tower.cpp:96` | [multimodal-track.md](specs/multimodal-track.md) §3 (M2a) | `ACTIVE` | `CLAIM-MULTIMODAL-M2A` | | `ENG-MM-TEXT-BACKBONE` | **Qwen3-VL text-backbone numeric contracts `Qwen3VLGetRopeIndex`/`Qwen3VLMergeMultimodal`/`Qwen3VLComputeDeepstack` (M2b/M2c), unit-green vs vLLM 0.25.0.** The deterministic pieces that fork the plain Qwen3-dense text path for a vision-conditioned decode: (1) MRoPE 3-D `get_rope_index` positions [3,T] (image tokens get (t,h,w) grid positions, text sequential); (2) the 3-section MRoPE APPLICATION — proven to be the EXISTING `vt::RopeFromCache` mrope path (positions [3,T] + `mrope_section=[24,20,20]` interleaved), faithful to `MRotaryEmbedding.forward_native` for Qwen3-VL's exact config; (3) `_compute_deepstack_embeds` scatter → [L,T,H] decoder-injection tensor; (4) `_merge_multimodal_embeddings` masked scatter of the tower's `[:,:2560]` into `input_embeds`. Pure-additive TU — NO shared dense forward / runner / registry edit → text engines byte-identical by construction. The e2e image forward (VL weight loader + forked MRoPE/DeepStack decode loop) is the remaining M2c wire-up. | T1 | `vllm/model_executor/models/qwen3_vl.py` `_get_mrope_input_positions:2567`, `_iter_mm_grid_hw:2482`, `_compute_deepstack_embeds:2761`, `Qwen3LLMModel.forward` deepstack `:1589`; `vllm/model_executor/models/utils.py::_merge_multimodal_embeddings:524`; `vllm/model_executor/layers/rotary_embedding/mrope.py` MRotaryEmbedding @ `e24d1b24` | `src/vllm/model_executor/models/qwen3_vl_text.{h,cpp}`; existing `vt::RopeFromCache` mrope path (`src/vt/{cpu,cuda}/*`); dump `scripts/mm/m2b_text_ref_dump.py`; fixtures `tests/vllm/multimodal/fixtures/qwen3vl_text/` — anchor `src/vllm/model_executor/models/qwen3_vl_text.cpp:9` | `tests/vllm/multimodal/test_qwen3vl_text.cpp` — 4 RED-first gates vs the dumped vLLM-0.25.0 reference 85/85 (get_rope_index BIT-exact [3,204], delta −182; MRoPE q rel-L2 1.5e-3 / k 1.5e-3, RED interleaved-off >5e-2; DeepStack + merge BIT-exact); CPU-only, no weights; clean CPU `-Werror` — anchor `tests/vllm/multimodal/test_qwen3vl_text.cpp:99` | [multimodal-track.md](specs/multimodal-track.md) §3 (M2b/M2c) | `ACTIVE` | `CLAIM-MULTIMODAL-M2BC` | | `ENG-MM-QWEN36-VL-FORWARD` | **Qwen3.6-27B (`Qwen3_5ForConditionalGeneration`) GDN-hybrid VL forward — IMAGE (M3-b) + VIDEO (M3d) BOTH e2e, STRICT gates PASS 32/32. Our own gate model's image+video paths now work end-to-end (speed pending).** The genuinely-new integration completing our own gate model's mm paths: fork the landed bf16 `Qwen3_5DenseModel` GDN-hybrid forward (48 GDN + 16 full-attn) on gated, default-off points so a text-only 27B request stays byte-identical — (a) `inputs_embeds` entry (embed ids + `Qwen3VLMergeMultimodal` scatter of the 27B tower merger `[N,5120]` into the visual-token rows; 27B has EMPTY `deepstack_visual_indexes` ⇒ NO DeepStack); (b) 3-section MRoPE (`mrope_section=[11,11,10]` interleaved, rotary_dim 64, theta 1e7) in the 16 full-attn layers only via the proven `vt::RopeFromCache` mrope path (GDN layers carry no rope); (c) mixed load = the M2a `Qwen3_VisionTransformer` (27B vision config, empty deepstack) bf16 tower + the bf16 GDN-hybrid LLM via the EXISTING `LoadQwen3_5Dense`. **M3d (2026-07-25) added VIDEO by REUSE:** the M3-b image driver refactored into a shared `VLGenerateCoreGdn`, image+video wrappers differ ONLY in the merge mask (`image_token` vs `video_token` across frames) + the get_rope_index (`Qwen3VLGetRopeIndex` vs `Qwen3VLGetRopeIndexVideo`); the M3c processor/windowed-tower/video-MRoPE are reused verbatim. | T1 | `vllm/model_executor/models/qwen3_5.py:389` (`Qwen3_5ForConditionalGeneration` subclasses `Qwen3VLForConditionalGeneration`; `visual = Qwen3_VisionTransformer`, modalities {"image","video"}); `qwen3_vl.py` `_process_video_input:2165`, `_get_mrope_input_positions:2567` video branch, `get_video_repl:1479`; the 27B `config.json` (`mrope_section=[11,11,10]`, empty `deepstack_visual_indexes`) @ `e24d1b24` / vLLM 0.25.0 | **M3-b + M3d BUILT + GATED 2026-07-25:** vision-only loader `LoadQwen3VLVisionWeights` (`src/vllm/model_executor/models/qwen3_vl.cpp`, 27B config) + shared `VLGenerateCoreGdn` + image driver `Qwen3_5VLGenerateGreedy` + **video driver `Qwen3_5VLGenerateGreedyVideo`** + `BuildMropeCosSinHost` + the `mrope_cos_sin` param on `DenseForwardLayers` (`src/vllm/model_executor/models/qwen3_5.cpp`, nullptr on every text caller ⇒ byte-identical; the video driver is purely additive, the shared text forward UNTOUCHED per `git diff --stat`) reusing M2a tower + `LoadQwen3_5Dense` bf16 LLM | **IMAGE:** golden `tests/vllm/multimodal/fixtures/qwen3_5_27b/` (STRICT sha256 `ead4b484…`); STRICT image gate PASS **32/32** (`test_qwen3_5_vl_e2e.cpp`, 54/54, re-run post-refactor). **VIDEO (M3d):** oracle `scripts/mm/m3d_video_oracle_capture.py` on the M3c synthetic clip (raw sha `8a111599…`, grid `[4,8,8]`, 64 video tokens) K=5 DETERMINISTIC ⇒ STRICT golden; **STRICT video gate PASS 32/32** (`test_qwen3_5_vl_video_e2e.cpp`, 27/27; near-tie gaps 0.0000 nats everywhere), fixtures `tests/vllm/multimodal/fixtures/qwen3_5_27b_video/`. Text-inertness 27B 235/235, 35B 315/315, Coder 138/138 (by construction); clean `-Werror` 0 warn; compute-sanitizer 0 on the 27B video forward. **SPEED MEASURED (2026-07-26, `CLAIM-MULTIMODAL-SPEED`): image c1 vs vLLM 0.25.0 GRAPHED — decode TPOT 225.0 ms/tok vs 226.9 = AT PARITY (0.99×), LLM prefill 326 ms vs vLLM TTFT 321 ms = at parity; vision tower WAS 2114 ms vs vLLM encode ≤~250 ms = ~10× (THE gap). TOWER LEVER EXECUTED (2026-07-26, `CLAIM-MULTIMODAL-SPEED-TOWER`, [multimodal-speed.md](specs/multimodal-speed.md) §7): nsys `cuda_gpu_kern_sum` attributed 98.9 % of the tower forward to the naive `vt::cuda::AttentionKernel` (56 ms/block; NOT QKV/FA2-routing); fixed by a warp-scoped online-softmax op `AttentionDenseFast` (separate op ⇒ `kAttention`/text byte-identical) + one-time resident-weight load ⇒ per-image tower 2114 → 148 ms (14.3×), **0.59× vs vLLM eager encode = FASTER**. STRICT image/video e2e HELD 32/32 (+4B DeepStack 32/32), `test_ops_attention` 37239/37239, 27B text SACRED 235/235, compute-sanitizer memcheck 0, clean `-Werror`. `benchmark_binding=false`, single-seq driver (no c2+/server). Remaining: batched/graphed mm serving (c2+) + audio our-side — DONE bar not yet met.** | [multimodal-track.md](specs/multimodal-track.md) §M3 + [multimodal-speed.md](specs/multimodal-speed.md) §7 + §8 (decode lever #2 CLOSED 2026-07-27: on-GPU greedy argmax + decode embed round-trip removed on `VLGenerateCoreGdn`; bit-exact — image/video STRICT 32/32 held; 27B decode NEUTRAL at the ~222 ms bandwidth floor) + §9 (lever #3 FIRST BRICK 2026-07-27, `CLAIM-MULTIMODAL-SPEED-GRAPH`: the shared `VLGenerateCoreGdn` decode step now routes through the production `Qwen3_5DenseDecodeGraph` cold→warm→replay captured decode — the mm decode is now GRAPH-CAPTURABLE, closing the un-graphed-eager-loop structural gap; S==B==1 bit-identical rebuild; token-exact HELD image/video STRICT 32/32 with 30 graph replays confirmed; A/B graphed 232.5 vs eager 233.4 ms/tok = NEUTRAL at the 27B bandwidth floor; the launch-overhead win + batched c2+ + serving ingestion are the recorded W-plan W1-W3) + §16 (vision-forward flash kernel 2026-07-28, `CLAIM-MM-SPEED-QWEN-IMAGE`: ATTRIBUTION-FIRST nsys attributed ~85% of the 148 ms tower forward to the dense attention `AttentionWarpKernel` [4.66 ms/block×27]; routed it to the §14 flash-tiled `vt::AttentionDenseFlash` [head_dim 72, byte-identical — per-warp math verbatim, only K/V from shared-mem tiles]. STRICT image/video e2e HELD 32/32 [27B+4B], `test_ops_attention` 37239/37239, goldens md5 UNCHANGED, nsys proof `AttentionDenseFlashKernel` 24 inst/zero warp, RED 30/46→46/46, sanitizer 0. A/B warp 148.3→flash 142.3 ms = 1.04× — the profile REFUTED a big lever: at t=784 the vision attention is serial-latency-bound not bandwidth-bound [audio §14 was 1.82× at t=1500], flash recovers only ~6 ms. **HONEST: the tower ALREADY BEATS vLLM — 142 ms vs ~250 ms eager encode = 0.57×**; image/video mm-forward is correctness-DONE + speed-BEATS-vLLM; residual = tensor-core MMA hd-72 attention [not needed for parity] + batched c2+/serving) | `ACTIVE` | `CLAIM-MULTIMODAL-SPEED-TOWER` + `CLAIM-MULTIMODAL-SPEED-DECODE` + `CLAIM-MULTIMODAL-SPEED-GRAPH` + `CLAIM-MM-SPEED-QWEN-IMAGE` | -| `ENG-MM-VIDEO-FORWARD` | **Qwen3-VL VIDEO understanding (M3c) — preprocessing + full wiring LANDED + unit-gated; e2e token-exact PENDING on tower fidelity.** Extends the landed image path to video: the genuinely-new piece is video PREPROCESSING (frame sampling + temporal grid + timestamp-interleaved placeholder); the tower handles temporal patches and MRoPE the temporal axis. NEW (additive to qwen3_vl*/multimodal TUs, ZERO text-path TU ⇒ text SACRED byte-identical): (a) `ProcessVideo`+`VideoSmartResize`+`ComputeVideoTimestamps`+`BuildVideoRepl`+`VideoKwargs` — video patchify fuses `temporal_patch_size` REAL frames/row (source frame = grid_t_idx*tp + t, NOT the image duplicate); `BuildVideoRepl` = per-frame `[ts_ids]+vision_start+video_token*Nf+vision_end` interleave; (b) tower per-frame windowed attention (cu_seqlens per frame; grid_t==1 image == byte-identical); (c) `Qwen3VLGetRopeIndexVideo` (per-frame scan); (d) `Qwen3VLGenerateGreedyVideo` via a shared `VLGenerateCore` (image driver unchanged). | T1 | `qwen3_vl.py`: `_process_video_input:2165` (same `self.visual`), `_iter_mm_grid_hw:2482`/`_get_mrope_input_positions:2567` video branch, `get_video_repl:1479`, cu_seqlens per-frame `:744`; transformers `video_processing_qwen3_vl.py:35,249` @ vLLM 0.25.0 | **M3c BUILT + UNIT-GATED 2026-07-25:** `src/vllm/multimodal/qwen3vl_processor.cpp` (+`inputs.h`), `qwen3_vl_vision.cpp` (windowed attn), `qwen3_vl_text.{h,cpp}` (`Qwen3VLGetRopeIndexVideo`), `qwen3_vl.{h,cpp}` (`Qwen3VLGenerateGreedyVideo`+`VLGenerateCore`) | Video-processor UNIT gate `test_qwen3vl_video_processor` **41/41, pixel_values_videos BIT-exact 0/393216** (RED-first: image-duplicate mapping → 195838 mismatch); video MRoPE BIT-exact vs vLLM (`m3c_mrope_check.py`, delta −48); video tower rel-L2 **0.072** (within bf16 envelope, `m3c_video_tower_ref_dump.py`); video e2e `test_qwen3vl_video_e2e` **NEAR-TIE-ROBUST PASS** (gate form selected BY MEASUREMENT 2026-07-25, `CLAIM-MULTIMODAL-TOWER-FIDELITY`): teacher-forcing vLLM 0.25.0 on OUR exact sequence proves the sole divergence is ONE genuine bf16 near-tie at tok22 (' colorful' 33866 vs vLLM ' static' 1099, gap **0.125 nats**, our token vLLM's 2nd of 4 tokens tied within 0.25 nats) and EVERY downstream token (tok23-31) IS vLLM's teacher-forced argmax at gap **0.0000** — 22/32 vs greedy is the one-token shift from that single tie. Tower accumulation ALREADY f32 everywhere (cuBLASLt `CUBLAS_COMPUTE_32F` GEMMs + f32 online-softmax attn + f32 LayerNorm) = matches vLLM's cuBLAS/FlashAttention; the residual rel-L2 is the irreducible inter-op bf16 rounding envelope, NOT a fixable numeric choice — so NO kernel change (methodology fix, mirrors the olmo2/qwen3-dense/glm4 near-tie gates). Gate: `our_ids_i32.bin` anchor + `neartie_gap_mnats_i32.bin` (from `scripts/mm/m3c_video_neartie_gap.py`), max gap 0.125 << 0.5-nat band. NO REGRESSION image e2e 4B STRICT **32/32** (the deterministic strict-pass proof); fixtures `tests/vllm/multimodal/fixtures/qwen3vl_video/` + `scripts/mm/m3c_*.py` | [multimodal-track.md](specs/multimodal-track.md) §M3 (M3c) | `ACTIVE` | `CLAIM-MULTIMODAL-TOWER-FIDELITY` | +| `ENG-MM-VIDEO-FORWARD` | **Qwen3-VL VIDEO understanding (M3c) — preprocessing + full wiring LANDED + unit-gated; e2e token-exact PENDING on tower fidelity.** Extends the landed image path to video: the genuinely-new piece is video PREPROCESSING (frame sampling + temporal grid + timestamp-interleaved placeholder); the tower handles temporal patches and MRoPE the temporal axis. NEW (additive to qwen3_vl*/multimodal TUs, ZERO text-path TU ⇒ text SACRED byte-identical): (a) `ProcessVideo`+`VideoSmartResize`+`ComputeVideoTimestamps`+`BuildVideoRepl`+`VideoKwargs` — video patchify fuses `temporal_patch_size` REAL frames/row (source frame = grid_t_idx*tp + t, NOT the image duplicate); `BuildVideoRepl` = per-frame `[ts_ids]+vision_start+video_token*Nf+vision_end` interleave; (b) tower per-frame windowed attention (cu_seqlens per frame; grid_t==1 image == byte-identical); (c) `Qwen3VLGetRopeIndexVideo` (per-frame scan); (d) `Qwen3VLGenerateGreedyVideo` via a shared `VLGenerateCore` (image driver unchanged). | T1 | `qwen3_vl.py`: `_process_video_input:2165` (same `self.visual`), `_iter_mm_grid_hw:2482`/`_get_mrope_input_positions:2567` video branch, `get_video_repl:1479`, cu_seqlens per-frame `:744`; transformers `video_processing_qwen3_vl.py:35,249` @ vLLM 0.25.0 | **M3c BUILT + UNIT-GATED 2026-07-25:** `src/vllm/multimodal/qwen3vl_processor.cpp` (+`inputs.h`), `qwen3_vl_vision.cpp` (windowed attn), `qwen3_vl_text.{h,cpp}` (`Qwen3VLGetRopeIndexVideo`), `qwen3_vl.{h,cpp}` (`Qwen3VLGenerateGreedyVideo`+`VLGenerateCore`) | Video-processor UNIT gate `test_qwen3vl_video_processor` **41/41, pixel_values_videos BIT-exact 0/393216** (RED-first: image-duplicate mapping → 195838 mismatch); video MRoPE BIT-exact vs vLLM (`m3c_mrope_check.py`, delta −48); video tower rel-L2 **0.072** (within bf16 envelope, `m3c_video_tower_ref_dump.py`); video e2e `test_qwen3vl_video_e2e` **NEAR-TIE-ROBUST PASS** (gate form selected BY MEASUREMENT 2026-07-25, `CLAIM-MULTIMODAL-TOWER-FIDELITY`): teacher-forcing vLLM 0.25.0 on OUR exact sequence proves the sole divergence is ONE genuine bf16 near-tie at tok22 (' colorful' 33866 vs vLLM ' static' 1099, gap **0.125 nats**, our token vLLM's 2nd of 4 tokens tied within 0.25 nats) and EVERY downstream token (tok23-31) IS vLLM's teacher-forced argmax at gap **0.0000** — 22/32 vs greedy is the one-token shift from that single tie. Tower accumulation ALREADY f32 everywhere (cuBLASLt `CUBLAS_COMPUTE_32F` GEMMs + f32 online-softmax attn + f32 LayerNorm) = matches vLLM's cuBLAS/FlashAttention; the residual rel-L2 is the irreducible inter-op bf16 rounding envelope, NOT a fixable numeric choice — so NO kernel change (methodology fix, mirrors the olmo2/qwen3-dense/glm4 near-tie gates). Gate: `our_ids_i32.bin` anchor + `neartie_gap_mnats_i32.bin` (from `scripts/mm/m3c_video_neartie_gap.py`), max gap 0.125 << 0.5-nat band. NO REGRESSION image e2e 4B STRICT **32/32** (the deterministic strict-pass proof); fixtures `tests/vllm/multimodal/fixtures/qwen3vl_video/` + `scripts/mm/m3c_*.py` | [multimodal-track.md](specs/multimodal-track.md) §M3 (M3c) | `READY` | - | | `ENG-MM-AUDIO-PIPELINE` | **AUDIO INPUT pipeline (audio-track A0+A1), the genuinely-new AUDIO modality on the modality-agnostic mm spine; INERT when no audio input.** Stands audio up on the smallest oracle-runnable vehicle `openai/whisper-small` (native `WhisperEncoder`; transformers 5.13.1 constructs it — unlike Gemma-4 which is oracle-blocked). The C++ Whisper-class audio processor `WhisperAudioProcessor`: canonical PCM16-mono WAV decode (`int16/32768.0`), identity resample at 16 kHz (genuine windowed-sinc DEFERRED, mirrors the image SmartResize/bicubic deferral), log-mel `input_features` `[80,3000]` (pad/truncate 480000 → torch.stft-equiv: reflect-pad `n_fft/2`, periodic Hann, hop 160, drop last frame, direct DFT over 201 bins → `abs(stft)^2` → `mel_filters.T@mag` → `log10(clamp 1e-10)` → `max(x,x.max()-8)` → `(x+4)/4`), audio placeholder expansion (`[0]`→`[0]*1500`, num_audio_tokens = `max_source_positions` = encoder output length), and `MultiModalHasher::HashAudioF32` (float32 1-D ndarray `"