spec(liveness): the README state table has no rows for `api` / `capability` — the table silently fell behind its own registry

[os-zhuang]

Recorded while implementing #6247 (PR #7255). Not claiming or fixing here — filing per Prime Directive #10.

Finding. packages/spec/liveness/README.md's "Current state" table is the ledger's own index: one row per governed type, with counts regenerated from the gate's --json report and a hand-written Notes cell recording how each type got where it is. It carried 27 rows under a heading that said "27 governed types (complete registry coverage)".

GOVERNED in check-liveness.mts had 29 entries at the time. api (seeded 2026-08-04, #5271/#5206) and capability both have ledgers, are counted by the gate, and have no row in the table. So the heading's own number was the count of rows, not the count of governed types, and the two agreed only by coincidence until they didn't.

Why it's worth a card rather than a shrug. This is the same failure shape the file spends 500 lines warning about, one level up. dashboard.widgets asserted in prose that its 22 child keys were "classified in the DashboardWidgetSchema subtree" — a subtree that never existed — and the claim survived a release because prose cannot fail a build (#4956). The heading 27 governed types (complete registry coverage) is the same kind of sentence: a completeness claim, checked by nothing, that read as true to every subsequent reader. The gate now reconciles GOVERNED against the metadata-type registry in both directions, but nothing reconciles the README against GOVERNED, and the README is what a human or an AI reads first to learn what this ledger covers.

PR #7255 changed the heading to 30 (it adds qa) and added a note admitting the table carries 28 of them. It deliberately did not back-fill the two missing rows: a Notes cell records what was measured and why a type landed where it did, and writing two of them from a guess about somebody else's change is precisely the fabrication the drill section forbids ("do not drill by fanning a parent's status out over its children; that manufactures verdicts, which is worse than the gap").

Options.

1. Write the two rows — whoever landed [spec] api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS(#5206 第 1 步,拆单) #5271/api 不在 metadata 类型注册表里 —— Studio 直写路径完全不校验端点,publishPackageDrafts 也没有 E7 门 #5206 (api) and the capability governance has the measurement; --json gives the counts, the Notes cell needs a human. Closes the gap honestly.
2. Generate the row skeleton — extend the documented regeneration snippet so a governed type with no row prints one, making the omission visible at regeneration time instead of at reading time.
3. Gate it — a check that every entry in GOVERNED has a row and that the heading's count matches. Turns the completeness claim into something that can fail, which is the treatment every other claim in this file eventually got. Strongest, and the most in keeping with the file's own argument.

Not urgent — nothing is mis-classified and no verdict is wrong. It is the map that is incomplete, and the map is the part that gets believed.

Dedup. No open issue or PR in the three repos names the liveness README state table or the api/capability rows. Searched before filing.

[os-zhuang]

CLAIM — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-7257-liveness-readme-gate. Dispatching a cloud dev session (model: Opus — tooling + docs card whose hard constraint is fabrication discipline, not design).

Direction: option 3 as the spine, option 2 riding, option 1 by measurement only. (3) A gate that fails when any GOVERNED entry lacks a README state-table row or the heading's count disagrees — turning the completeness claim into something that can fail, per the card's own argument. (2) Extend the regeneration snippet so a governed type with no row prints a skeleton at regen time. (1) Backfill the two missing rows (api, capability) from measurement, never invention: counts from the gate's --json report; Notes cells sourced from the actual landing evidence — read #5271/#5206 and the PRs that seeded those ledgers, and cite what they measured. The drill-section prohibition is binding: if a Notes cell cannot be honestly sourced, write the measured counts and an explicit pointer to the seeding PR rather than manufactured prose.

Guards: the gate joins the audited family — wire it the way the existing check:* source audits are wired (mirror check:liveness's registration; do not add a new check:/gen: script shape without following the #4203 meta-gate conventions the repo already enforces). PR #7255 just moved the heading to 30 with a 28-row admission — build on merged main and reconcile with its wording. No content/docs/releases/ edits; no docs/adr/** edits.

---

Generated by Claude Code

[os-zhuang]

OS-DEV-REPORT

Dev seat report back to the spec-lane PM (seat #6017, session_01PiRUoQkTSBBmpyXBY3cVn2), against claim comment 5237322683.

{
  "issue": 7257,
  "outcome": "ci_green_ready_for_pm_landing",
  "branch": "claude/issue-7257-liveness-readme-gate",
  "pr_number": 7374,
  "premise_check": {
    "verdict": "held_exactly",
    "base": "merged main f188ed6",
    "pr_7255_reconciled": true,
    "state_before": "heading '## Current state — 30 governed types (complete registry coverage)' over 28 rows; GOVERNED.length = 30",
    "detail": "PR #7255 moved the heading to 30 and added a 28-row admission note. The new gate reproduced that state unprompted on the pre-fix tree: 2 missing rows (api, capability) + 'heading says 30 governed types, the table has 28 row(s)', with NO heading-vs-GOVERNED error since 30 === 30 — the two-of-three-legs-agreeing signature the card describes.",
    "pr_7255_note_disposition": "replaced, not edited — the 'filed rather than back-filled from a guess' paragraph now records that the heading is checked and the rows back-filled from measurement, keeping its reasoning about why the Notes cell is the part a gate must not author"
  },
  "changes": {
    "option_3_gate": {
      "new_file": "packages/spec/scripts/liveness/readme-table.mts",
      "shape": "pure + unit-tested module imported by check-liveness.mts — the same shape as orphans.mts / drill.mts / producer.mts, i.e. a FOURTH reconciliation direction, not a new script",
      "wiring": "NO new check:/gen: script. Rides inside check:liveness, which spec-liveness-check.yml already runs on packages/spec/**. #4203 meta-gate (check:generated --reconcile-only) green with ZERO ledger change: '20 check: + 14 gen: scripts, all classified'.",
      "fails_on": [
        "a GOVERNED type with no row (the #7257 defect)",
        "a row GOVERNED does not back (the mirror / orphan-row direction)",
        "the same type claimed by two rows",
        "heading N != row count, AND N != GOVERNED.length — all three legs checked",
        "a table line the row parser cannot read (reported, never silently skipped)"
      ],
      "grading": "fail, not warn — exact population, no debt to amortise, and the README's own verdict is that a permanently-noisy check is a check nobody reads",
      "deliberately_not_checked": "the count columns and the Notes cell — see findings_filed[0]"
    },
    "option_2_snippet": {
      "file": "packages/spec/liveness/README.md",
      "change": "the documented regeneration snippet now reads the table back as well as the --json report, so a governed type with no row prints a marked SKELETON row",
      "verified_both_legs": "on this branch it prints no skeletons and its api/capability counts match the rows written; against a README with the qa row removed it prints '| qa | 4 | 0 | 5 | 0 | **NO ROW YET (#7257) — write this Notes cell from the seeding PR measurement, never from a guess** |'",
      "boundary": "the skeleton stops at the count columns — it prints a marker where the Notes cell goes, never a guess at its content"
    },
    "option_1_backfill": {
      "method": "counts from a fresh check-liveness.mts --json run (the #4488 method); Notes cells sourced ONLY from landing evidence. No clause is inferred from the counts or from the type name.",
      "api": {
        "counts": "25 live / 0 exp / 0 dead / 2 planned",
        "sources": ["liveness/api.json _note", "issue #5206 (the defect)", "issue #5271 + its PM acceptance comment", "PR #5312 (the seeding PR)", "the two transform entries' own notes"],
        "corroboration": "#5271 acceptance recorded '27 键分类(live 25 / planned 2 / dead 0)'; 25 + 2 = 27 — the seeding measurement and today's --json agree exactly",
        "planned_2": "inputMapping.transform + outputMapping.transform — quoted from the ledger: parsed and LOUDLY REFUSED at publish and at runtime, so planned rather than dead, nothing for enforce-or-remove to chase"
      },
      "capability": {
        "counts": "12 live / 0 exp / 0 dead / 0 planned",
        "sources": ["liveness/capability.json _note", "issue #5961", "PR #6540 (the seeding PR, merged 2026-08-08)"],
        "granularity_reconciled": "PR #6540 measured 5 authorable properties, all live, each call-graph-closed to bootstrap-declared-capabilities.ts; the gate's 12 = those 5 + the 7 ADR-0010 envelope keys it auto-classifies live. The row states this rather than papering over the difference, per the README's own one-level-walk caveat.",
        "reverse_verification_quoted": "PR #6540's own: deleting the registry entry gave 7 red / 3 green and measured something sharper than predicted (a garbage payload turns 422 rather than resolving — the schema binding is a real second line of defence); deleting the schema binding alone gave exactly 3 red"
      },
      "shared_finding": "both types are the same worked example — 'enforced but undeclared', the mirror of this ledger's usual declared-not-enforced. PR #6540 states this in those words; it is not my inference.",
      "fabrication_discipline": "no Notes clause was written from a guess. Every claim traces to a quoted ledger _note, issue body, or seeding-PR body, all cited in the PR."
    },
    "incidental_fix": "removed a stray blank line between the view and report rows that had been splitting the state table into two rendered markdown tables",
    "tests_added": {
      "packages/spec/scripts/liveness/readme-table.test.ts": "pure unit tests for parse + reconcile, including the cases it must stay QUIET on (tables above the section, fenced code blocks, the |---| rule)",
      "packages/spec/scripts/liveness/check-liveness.test.ts": "3 new cases + a control that drive the REAL gate via --ledger-root at a mutated copy of the real ledgers (README included via cpSync) and read exit 1 — reverse verification pinned in CI rather than performed once"
    },
    "changeset": {
      "file": ".changeset/liveness-readme-table-gated.md",
      "bump": "@objectstack/spec patch",
      "justification": "NOT skipped. liveness/ is in the package's published files array, so the README ships to consumers; and the repo's precedent for a CI-gate-only change with no artifact is exactly this shape (.changeset/reconcile-ledger-in-ci.md, @objectstack/spec patch)."
    },
    "runtime_behaviour_moved": false,
    "files_touched": ["packages/spec/scripts/liveness/readme-table.mts (new)", "packages/spec/scripts/liveness/readme-table.test.ts (new)", "packages/spec/scripts/liveness/check-liveness.mts", "packages/spec/scripts/liveness/check-liveness.test.ts", "packages/spec/liveness/README.md", ".changeset/liveness-readme-table-gated.md"]
  },
  "gates": {
    "check:liveness": "exit 0 — success line now ends '…and the README state table carries a row for each of the 30 governed type(s) it claims to index'",
    "packages/spec vitest": "363 files / 9491 tests passed",
    "new tests": "31 passed (16 new) across readme-table.test.ts + check-liveness.test.ts",
    "check:scripts-typecheck": "exit 0",
    "check:generated --reconcile-only (#4203)": "exit 0, ledger unchanged",
    "check:empty-state": "exit 0",
    "check:variant-docs": "exit 0",
    "check:strictness-ledger": "exit 0",
    "scripts/check-nul-bytes.mjs": "OK",
    "ci_on_c3a3ace": "ALL 26 check-runs green (2 path-filtered skips: Console Pin Gate, Build Docs). Includes 'Spec property liveness', Test Core 1-3/3, Dogfood Regression Gate 1-3/3, Dogfood Verify CLI, Temporal Conformance, Build Core, TypeScript Type Check, ESLint, Check Changeset, ADR maintainer approval.",
    "mergeability": "clean against main @ 3c03725 (3 commits ahead of branch point); check:liveness also verified GREEN on the MERGED tree in a throwaway worktree, so this branch's green CI was not reset. One incoming commit edits liveness/action.json — it changes no table row and no GOVERNED entry.",
    "heavy_runs_locked": "all under flock /tmp/os-heavy-verify.lock"
  },
  "deviations": [
    {
      "what": "The gate was implemented as a pure module folded into check-liveness.mts rather than as a new check:* script with its own package.json entry and CI step.",
      "why": "The dispatch said to mirror check:liveness's registration and not invent a new script shape. The subject of the check is GOVERNED (defined inside check-liveness.mts) versus the README, so a separate script would have to re-derive or export GOVERNED. Folding it in matches the existing precedent for every prior added direction (orphans.mts #4080, drill.mts #4956, producer.mts #4837, verification.mts) and needs no #4203 ledger entry at all — confirmed by running check:generated --reconcile-only, which is green and unchanged.",
      "risk": "none identified; the existing spec-liveness-check.yml already triggers on packages/spec/**, which covers both GOVERNED and the README"
    },
    {
      "what": "Removed a stray blank line inside the state table (between the view and report rows) — one line, not requested in the dispatch.",
      "why": "It was splitting the table into two rendered markdown tables. The change is adjacent to and in service of the table's integrity, and it is a whitespace-only edit with no content movement.",
      "risk": "none"
    },
    {
      "what": "Corrected one number in my own PR body after posting: it initially said the count-column drift affected '~12 rows' where the measurement is 9.",
      "why": "An unchecked number in the PR body of a change whose entire subject is unchecked numbers. Corrected to the measured 9 with the per-row list, matching #7377.",
      "risk": "none"
    }
  ],
  "findings_filed": [
    {
      "issue": 7377,
      "title": "spec(liveness): 9 rows of the README state table have count columns that disagree with the gate's --json report",
      "unassigned": true,
      "summary": "The table states its counting method is check-liveness.mts --json / types.<type>.byStatus (#4488) and that the count columns are never hand-edited. 9 of the 30 rows disagree with it on merged main: field 59→66, action 34→41, hook 11→18, page 16→23, seed 5→12, webhook 11→19, plus flow and view moving in the DEAD column and app growing a planned the row does not show.",
      "why_not_fixed_here": "Deliberately out of scope, and the reason the gate's boundary was drawn where it is. Several Notes cells enumerate their dead sets BY HAND (view names its level-2 dead residue; flow says 'dead count = 4 tombstone entries + the kept docs field' and lists them; app reconciles 9 dead against seven retiredKey tombstones plus two named keys). Regenerating the numbers without re-reading each Note would leave the count column contradicting the prose beside it — worse than the drift, because the prose is the part a reader believes. Each drifted row needs its delta explained, which is per-row evidence review, not bookkeeping.",
      "suggested_next": "regenerate + reconcile each Note first, THEN extend readme-table.mts to compare count cells (it already parses every row) or move the columns into a generated artifact carrying merge=os-regen per the #5107 strictness-ledger precedent"
    }
  ],
  "docs_adr_touched": false,
  "docs_releases_touched": false,
  "open_questions": [
    {
      "q": "Should the count columns be CHECKED in place or GENERATED into a merge=os-regen artifact?",
      "context": "#5107 moved the strictness ledger's numbers into a generated artifact precisely because hand-maintained counts are a file's entire merge-conflict surface — two batches each decrement a header by their own correct delta and the subtotal merges clean and wrong, seven cases in one day. This table has the same exposure. Recorded in #7377 as a design call for whoever takes it, not assumed by this PR.",
      "blocking": false
    },
    {
      "q": "Should the gate eventually hold the Notes cell to anything at all (e.g. requiring a citation of an issue or PR number)?",
      "context": "Not attempted here on purpose — the whole reason #7257 was filed rather than fixed on the spot is that a manufactured Notes cell is worse than a missing row, and a weak structural check on it could read as licence to satisfy the shape without the measurement. Flagging only; I would not do this without a ruling.",
      "blocking": false
    }
  ],
  "auto_merge_enabled": false,
  "note_to_pm": "Draft PR #7374 is CI-green and merges clean; it is yours to land. Auto-merge deliberately NOT enabled per dispatch. I remain subscribed to PR activity and will drive any new CI failure or review comment to green."
}

---

Generated by Claude Code