Skip to content

docs(spec): APR-RELEASE-001 — feature matrix, examples, debt tax, continuous triage, decision procedure, ontology kaizen (§11), and the chain of reasoning (§12) - #3268

Merged
noahgift merged 12 commits into
mainfrom
PMAT-1098-spec-amend
Sep 15, 2026

Conversation

@noahgift

@noahgift noahgift commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

What

A day on T-1 surfaced five things APR-RELEASE-001 did not name. Four become clauses; the fifth was already covered and is only made precise.

§ Clause Why
§4.1 Feature matrix T-1 named it from the start and it was never built. First run (#3262): 100 of 430 pairs RED, every one unreachable from any default set.
§4.2 Examples run, not built T-1 says every cargo run --example; building them is a different, far cheaper clause (83 s vs ~2 h).
§5.1 The debt tax The largest single time sink of the day, and no step owned it.
§10 Decision procedure §6 is deliberately "no judgement calls", so design forks had nowhere to go.
§6 untriaged per surface One number reported the clean surface and hid the breached one.

§4.1 — why the matrix could go dark

cargo check --workspace stays green over all 100 failures, because feature unification hands each crate whatever its siblings enabled. The section fixes the universe (per (crate, feature) pair from cargo metadata — never a powerset; aprender-orchestrate alone declares 78 features), records the five shapes that accounted for all 100, and specifies:

  • the known-red list: reported not fatal, dated, issue-referenced — a lane born red is a lane taught to be ignored; and a listed pair that passes is fatal, so the list can only shrink
  • the compile_error! + private __x-linked form for a feature that cannot be built at all
  • struct drift as shape 5, because nothing else in the train watches for an upstream type growing a field

§4.2 — timeout is a PASS

Measured on five random examples with -- --help and a 60 s cap: three ran past it. They are compute demos that ignore argv, not CLIs. The assertion T-1 owes is starts and does not crash; asserting a duration would be a wall-clock assertion in a required check. Both clauses carry a vacuity floor — a discovery that finds nothing reports zero failures, which reads exactly like a pass.

§5.1 — the tax, now at least measured

The pre-commit gate refuses any commit touching a file with a function over cyclomatic 30 / cognitive 25, and --no-verify is banned. So a one-line fix costs decomposing every offender in that file. Measured in one day: 11 pre-existing violations paid down — worst cognitive 91, 73, 61 — none in code that day's changes wrote.

It is not a build row because it is not schedulable; it is a toll on whatever you touch. It now has rules (extraction not rewriting; same commit as the fix that triggered it; refuse by name, never panic) and a debt: line in §7.

§10 — what actually worked

Fan out through agy, not more Claude subagents. The brief carries the measurements, so lanes don't each measure the premise differently. Plant one trap question — a rename that looks mechanical and isn't; all three lanes caught Lz4WarpShuffleKernelLz4WarpCompressKernel swapping a literal-only encoder for a real match-finder. A verdict is a claim until the orchestrator re-runs the acceptance command.

Two rules the session paid for:

§6 and §8

untriaged is counted per surface: measured 2026-09-14, issues were 319/320 triaged while PRs were 20 of 34 with no milestone at all. And triage is not disposal — the ledger grew net +149 over ten days while ~100 % triaged, with 312 of 320 open issues opened by the agent itself. This is the same finding §6 already recorded for the 0.67 train ("filing was the work product and closing was nobody's"); it now has a stop rule.

§8 gains three conditions: a declared full-time build host at 0 % occupancy while a queue has pressure is a routing defect, not spare capacity (mini, measured all day); a stale known-red list; a design fork goes to §10.

Verified

readme_contract 15/15 — the drift gate that checks every repo-relative path cited in the docs.

Refs #3262, #3179

no-close: this is the spec amendment; #3262 is the umbrella measurement and #3179 wants a working CUDA path.

ont-delta: resolves scripts/check_pr_ont_delta.sh — §11.1 said "absent is a PR-body lint
failure, not a review comment" and grep -rl ont-delta scripts/ .github/ Makefile returned
nothing, so the rule WAS a review comment. This PR now ships the lint and its ci.yml caller,
turning §11.1 from a prose claim into a checkable one (form 4). The counters in §11.2 remain
at 0 — ONT-1 (pv census) is the first of those, epic #3269.

🤖 Generated with Claude Code

…id not name

A day spent on T-1 surfaced five things the spec did not cover. Four are now
clauses; the fifth turned out to be covered already and is only made precise.

§4.1 FEATURE MATRIX — T-1 named it from the start and it was never built. Its
first run (#3262) measured 100 of 430 (crate, feature) pairs RED, every one
unreachable from any default set — which is exactly why it could go dark:
`cargo check --workspace` stays green over all of it because feature
unification hands each crate whatever its siblings enabled. The section defines
the universe (per-pair from `cargo metadata`, never a powerset — aprender-
orchestrate alone declares 78 features), the five shapes that accounted for all
100, the known-red list and why a listed pair that PASSES must be fatal, and the
`compile_error!` + private `__x-linked` form for a feature that cannot be built
at all. Struct drift is listed as shape 5 because nothing else in the train
watches for an upstream type growing a field.

§4.2 EXAMPLES — T-1 says every `cargo run --example`, which is a different
clause from building them (83 s vs ~2 h). Measured: three of five random
examples ran past a 60 s cap. They are compute demos, not CLIs, so TIMEOUT IS A
PASS and the assertion owed is "starts and does not crash". Asserting a duration
would be a wall-clock assertion in a required check. Both clauses carry a
vacuity floor: a discovery that finds nothing reports zero failures, which reads
exactly like a pass.

§5.1 THE DEBT TAX — the pre-commit gate refuses any commit touching a file with
a function over cyclomatic 30 / cognitive 25, and `--no-verify` is banned, so a
one-line fix costs the decomposition of every offender in that file. Measured in
one day: 11 pre-existing violations paid down, worst cognitive 91, 73, 61, none
in code that day's changes wrote. It is not a build row because it is not
schedulable — it is a toll on whatever you touch. Now it is at least measured:
`debt:` in §7.

§10 DECISION PROCEDURE — §6 is deliberately "no judgement calls", so design
forks had nowhere to go. Codifies what worked: fan out through agy not Claude
subagents; the brief carries the measurements so lanes do not each measure the
premise differently; plant one trap question; a verdict is a claim until the
orchestrator re-runs the acceptance command; **a premise error voids the vote
and the fix is another round, not the orchestrator's judgement** (#3179 round 2
overturned round 1 unanimously once three facts were read out of the tree);
overriding the majority is allowed once, only on a fact no lane had, and must be
recorded with the losing argument quoted; prefer the reversible option when the
vote is close.

§6 — `untriaged` must be counted PER SURFACE. Measured 2026-09-14: issues were
319/320 triaged while PRs were 20 of 34 with no milestone at all, and one number
reported the clean surface while hiding the breached one. Also states plainly
that triage is not disposal: the ledger grew net +149 over ten days while ~100 %
triaged, with 312 of 320 open issues opened by the agent itself. This is the
same finding §6 already recorded for the 0.67 train ("filing was the work
product and closing was nobody's"); it now has a stop rule.

§8 — three stop conditions: a declared full-time build host at 0 % occupancy
while a queue has pressure (mini, measured all of 2026-09-14) is a routing
defect, not spare capacity; a stale known-red list; a design fork goes to §10.

readme_contract 15/15.

Pmat-Ticket: PMAT-1098

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@noahgift noahgift added this to the 0.68.0 milestone Sep 14, 2026
@noahgift
noahgift enabled auto-merge September 14, 2026 12:56
…nd a milestone must fit its date

Three gaps in §6, each measured 2026-09-14.

§6.1 CADENCE. "Once per train" is what let 20 of 34 open PRs carry no milestone
at all, every one opened in the preceding two days. A train is 48-72 h; a PR
opened an hour after the pass is invisible for the rest of it. Triage now runs
on the P0 · Pack wakeup, beside the fleet sample — same cadence, same receipt,
and equally P0 per the operator ("ticket, pull requests, branches that are not
triaged are P0"). The per-wakeup pass is mechanical and bounded; the
once-per-train pass keeps only what needs the whole window: the §6.3 capacity
check and the T-5 reconcile.

§6.2 BRANCHES were the unwatched surface. 107 remote branches, 35 with an open
PR, 72 without: 32 younger than 7 d, 27 in a 7-14 d band NO RULE LOOKS AT, 13
already R-3-eligible. R-3 archives a branch with no PR and a tip older than
14 d, so work that stalls on day 8 is invisible for six more days and is then
deleted without ever having been seen. New test: no open PR and a tip older than
7 d must get a PR (draft is fine) or be archived now. A branch with no PR is not
work in progress, it is work nobody can see.

§6.3 PRIORITISATION. §4 says scope is assigned after the fact — right for what a
train CONTAINS, wrong as a plan for what it PROMISES. With no capacity rule a
milestone is a dumping ground with a date on it. Measured at closure = 6.1
issues/day over the trailing 7 days:

    0.68.0   280 open   due in 1 d   needs ~46 d   OVER BY 45 DAYS
    0.69.0    53 open   due in 4 d   needs  ~9 d   over by 5 d
    0.70.0    15 open   due in 7 d   needs  ~2 d   fits

A date 45 days of arithmetic away from its content is not a commitment; it is a
label, and every number computed from it is fiction.

The rule is arithmetic, so it stays inside §6's no-judgement-calls design:
capacity = days_remaining x measured closure_rate_p50. Over capacity is reported
every wakeup, not treated as an error. At T-0 an overcommitted next milestone
SPILLS lowest-priority-first until it fits — P0 never spills, then P1, then
unlabelled, then oldest kept. The operator sets priority by labelling; the
arithmetic sets the cut line, so no train needs a judgement call about scope. A
P0 set that alone exceeds capacity is a STOP (§8): that is over-promising at the
one level the operator controls, and only the operator can cut it.

closure_rate is MEASURED; under 7 days of data it reports [U] and spills nothing.

Arrival is the other half: 6.1/day closure against a ledger that grew net +149
in ten days means the cut line moves further out every train however it is drawn.
R-5 is the control on that; capacity only decides what a date may claim.

readme_contract 15/15.

Pmat-Ticket: PMAT-1098

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@noahgift

Copy link
Copy Markdown
Contributor Author

Second commit adds the three §6 gaps: triage is continuous, covers branches, and a milestone must fit its date.

§6.1 Cadence

"Once per train" is what let 20 of 34 open PRs carry no milestone at all — every one opened in the preceding two days. A train is 48–72 h; a PR opened an hour after the pass is invisible for the rest of it. Triage moves to the P0 · Pack wakeup, same cadence and receipt as the fleet sample, and is equally P0 per the operator's own wording. Only the capacity check and the T-5 reconcile stay once-per-train.

§6.2 Branches — the unwatched surface

Measured: 107 remote branches, 35 with an open PR, 72 without.

<7d      32
7-14d    27   <- no rule looks at this band
14-30d   13   <- R-3 eligible
>30d      0

R-3 archives a branch with no PR and a tip older than 14 d. So work that stalls on day 8 is invisible for six more days and is then deleted without ever having been seen. New test: no PR and a tip older than 7 d → open a PR (draft is fine) or archive now. A branch with no PR is not work in progress, it is work nobody can see.

§6.3 Prioritisation — the gap you named

§4 says scope is assigned after the fact. That is right for what a train contains and wrong as a plan for what it promises. Measured at closure = 6.1 issues/day (trailing 7 d):

Milestone Open Due in Needs Verdict
0.68.0 280 1 d ~46 d over by 45 d
0.69.0 53 4 d ~9 d over by 5 d
0.70.0 15 7 d ~2 d fits

capacity = days_remaining × measured closure_rate_p50. Over capacity is reported, not errored. At T-0 an overcommitted milestone spills lowest-priority-first until it fits — P0 never spills, then P1, then unlabelled, then oldest kept.

The operator sets priority by labelling; the arithmetic sets the cut line — so prioritisation gets answered without §6 having to make a judgement call. A P0 set that alone exceeds capacity is a stop: that is over-promising at the one level the operator controls.

🤖 Generated with Claude Code

ONT-001 v4.3 §6 assigns aprender every ontology row but three. Measured at
fa6e35f: 1 of 17 merged, 0 of 1818 contracts carry `entity:`, `shape:` or
`evidence:`, no `pv census`, no `pv extract`, no `ontology/` module.

Two of those measurements are the reason for this section.

`pv kaizen` IS the kaizen loop and it is code-only — bindings, call sites,
E0/E1/E2 assertions. The train sweeps features, examples, README, CLAUDE.md,
workflows, model files and CSVs, and the loop that is supposed to improve on
each sweep cannot see one of them.

The upstream spec is UNTRACKED in infra. No commit, no history, unfetchable
from gx10, yoga or mini — so a quorum lane cannot read the premise at all and
every ontology verdict it returns is unverifiable by construction. Stop
condition, fixed in infra (ONT-P), not here.

§11.1 makes the rule mechanical: a surface sweep closes with one of four
deltas — an entity type + extractor, a shape whose violation is the defect
class just found, a new Unknown{} reason, or a `resolves:` target — or with a
named `ont-delta: none <reason>`. Unnamed is P0. This spec's own §4.1 is the
counter-example: 100 red pairs as an awk matcher inside night.yml, no
contract, no shape, re-derived by hand before every undraft.

§11.4 is why this makes the quorum more effective, which is the point.
Premises cite ids, verdicts are ONT-6 lattice elements, reduce is meet=min
rather than a vote count, and the planted trap becomes
Unknown{PositiveControlFailed} by rule instead of by the orchestrator
noticing. #3179 round 1 was a 2/3 majority over verdicts that had no lattice
meaning; under §11.4 it does not reduce to Pass.

§11.2 ratchets five counters, §11.3 puts one row per train (16 rows, ~40 days
[A]) and lands every gate unarmed, §11.5 adds the `ontology:` report line and
`lattice` to `quorum:`, §11.7 gives five falsifiers.

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@noahgift

Copy link
Copy Markdown
Contributor Author

§11 added — ontology kaizen

ONT-001 v4.3 §6 assigns aprender every ontology row but three. Measured on main @ fa6e35f23:

ONT-001 requires aprender has
contracts may carry entity: / shape: / evidence: 0 / 0 / 0 of 1818
pv census · pv extract · ontology/ module absent · absent · does not exist
every ONT row implemented (§6) 1 of 17 (ONT-2a, #3224)
a ticket per row 1 of 17 (#3222, closed, no milestone) → now epic #3269

Two findings drive the section:

pv kaizen is the kaizen loop and it is code-only — bindings, call sites, E0/E1/E2 assertions (crates/aprender-contracts-cli/src/commands/kaizen.rs). The train sweeps features, examples, README.md, CLAUDE.md, workflows, model files and CSVs; the loop meant to improve on each sweep sees none of them. ONT-001 R-17 is exactly this: one structure, any entity type.

The upstream spec is untracked in infra — no commit, no history, unfetchable from gx10, yoga or mini, and not gitignored (23 of its 25 sibling specs are tracked). A quorum lane on another host cannot read the premise, so every ontology verdict it returns is unverifiable by construction. §11.6 makes that a stop condition; the fix belongs to infra (ONT-P).

§11.1 makes the rule mechanical: a surface sweep closes with one of four deltas — entity type + extractor, a shape whose violation is the defect class found, a new Unknown{} reason, or a resolves: target — or with a named ont-delta: none <reason>. This spec's own §4.1 is the counter-example it exists to stop: 100 red pairs as an awk matcher inside night.yml, no contract, no shape, re-derived by hand before every undraft.

§11.4 is why this makes the quorum more effective. §10 already says the brief must carry the measurements; #3179 round 1 is what it costs when it cannot. Under §11.4 premises cite ids, verdicts are ONT-6 lattice elements, reduce is meet = min rather than a vote count, and the planted trap becomes Unknown{PositiveControlFailed} by rule instead of by the orchestrator noticing — #3179 round 1 was a 2/3 majority over verdicts with no lattice meaning, and it would not reduce to Pass.

Also in this commit: ontology: added to the §7 report block, and | lattice <ok|prose> to quorum:.

🤖 Generated with Claude Code

noahgift and others added 3 commits September 14, 2026 15:15
…ops and report lines in one place

Review of the §11 draft against ONT-001 and against this spec's own conventions:

- ONT-001's R-n/F-n/§n ids collided with this spec's T-5 predicates R-1..R-5.
  Upstream ids are now written `ONT R-n` / `ONT F-n` / `ONT §n` throughout §11.
- The draft said #3179 round 1 was "a 2/3 majority over lattice-invalid
  verdicts". It was not: the verdicts were well-formed, the PREMISE was false
  (a launched kernel entry point that does not exist in the tree). Corrected
  to what the ontology actually does about it — `resolves: symbol` on the
  premise returns Unknown{…} at extraction, before any lane votes.
- `contracts/lint-baseline.json` and `make ont-ratchet` do not exist in
  aprender yet; §11.0 and §11.2 now say so instead of naming them as if
  present.
- A "sweep PR" is now a file predicate (night.yml, docs/specifications/**,
  the CLI registry, README.md, CLAUDE.md, any known-red list) so FR-1 can be
  a `check_pr_closes_issue.sh`-class PR-body check rather than a reading.
  #3268 itself is one and carries `ont-delta: none`.
- The four stop conditions live in §8 and the two report lines in §7, once;
  §11.5/§11.6 point there instead of duplicating them. `ontology:` gains
  `deltas <n>/<sweep PRs>` so §11.1 is measurable at T-5.
- ONT §0.2's push constraint (never while a release-titled run is in
  progress) is named as §3's one-PR rule seen from the other repo.

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ext in seven places

Read start to finish. Every finding is a place where a dated amendment (§3.4
merge-queue parallelism, §3.5 SSH, §6.1 continuous triage, #3205 mini, the
one-subagent rule) was landed beside original text that still said the
opposite, so a reader could cite either.

- §1 measured the fleet with `gh api …/actions/runners` — the call the
  operator rejected, a `busy` snapshot that cannot see ephemeral runners, and
  the hourly average that read 9.5 % while 15/16 workers were busy. Now the
  fleet-pack ledger record, instantaneous busy/online, both traps named.
- §1 said "one PR in CI at a time means gate latency IS throughput"; §3.4
  was amended to 3-parallel on 2026-09-12. Bound is now 3 × 72 h / p95.
- `mini` is a declared full-time build host (#3205) and appeared only in a
  §8 bullet. Added to §0 row 0, §1, §5 P0·Pack fields and Done, §7 pack:, §8.
- §0 row 3 still scheduled triage once per train; §6.1 made it per-wakeup.
- §2 named the required check `ci / gate`; the rules API says `gate` and
  `workspace-test`, and `present` is not required.
- §3.4 allowed "≤ 3 read-only subagents" against the one-at-a-time rule and
  §10's fan-out-through-agy.
- §8's last bullet stopped on "a second concurrent aprender PR in CI" and on
  "SSH into a host" — both allowed by the amended §3.4/§3.5. Now stops on a
  host CONFIG change over SSH instead of forjar.
- §9 asked for the 0.67 cascade wall to be measured; it was: 70 min,
  attended 0. That is 3.5× the [A] line, so by §9's own rule the cascade is
  the next kaizen target; where the minutes go is [U].
- §7 train: line said T-0..T-4; T-5 exists. §6's tail paragraph gets a §6.4
  heading. §11.3 cited the one-PR rule §3.4 no longer has; fixed.
- `make build-report` does not exist on main (P0·Instrument not done) — said
  so where p95 is marked [U].

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…es and the four things it moves

The spec had eleven sections of mechanism and no argument. §12 is the argument,
step by step, each with its mechanism and its falsifier:

§12.1 why it runs forever — the selector is total (row 4 always matches), a
stop stops the session never the loop (every §8 line names the mechanism that
prevents its recurrence), every counter is a ratchet, no number is a guess and
a guess that becomes measurable is replaced (§9's 70-min cascade is the worked
example), the ledger is the memory, the clock cuts the train.

§12.2 the four axes — the repo, the released binaries, the CRUX competitors,
the fleet — on the pv/ontology substrate. Each with its dated position, its
mechanism, its ratchet and its §7 line.

The spec had NO competitor axis before this: the train shipped binaries and
nothing in it said where they stand. CRUX monitors 9 competitors through 275
stories (✅39 🔨80 ❌156 at v2.2 intake [C]; FALSIFY-CRUX-010 declared, not
found under crates/ or scripts/ on main — [U] until landed). BEATS has 16
contracts; Ollama GPU decode is PARITY with a 0.90 floor, llama.cpp c=1 a
narrow loss, fail-closed WON. Approaching = ❌→🔨→✅ by demand tier, which
§6.3 already schedules; surpassing = a beat threshold that is a floor first
and moves above 1.0 only on three agreeing medians on the PUBLISHED binary —
which is why the post-publish dogfood (#3202) precedes any ratio.

Hooks: `beats:` line in §7, a §8 stop on a beat RED on the published binary
or a `measured-on published` claim from a dev build, a §0 pointer.

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@noahgift

Copy link
Copy Markdown
Contributor Author

Final review pass — 7f94d8bb5 (contradictions) + 9678009c2 (§12)

Read start to finish. Seven places where a dated amendment had been landed beside original text still saying the opposite, so a reader could cite either:

Where Said Now
§1 fleet measured with gh api …/actions/runners (rejected; blind to ephemeral runners; hourly average read 9.5 % at 15/16 busy) the fleet-pack ledger record, instantaneous busy/online, both traps named
§1 "one PR in CI at a time means gate latency IS throughput" §3.4 is 3-parallel since 2026-09-12 → 3 × 72 h / p95
§0 §1 §5 §7 §8 mini only in one §8 bullet full-time host (#3205) on every fleet rule and the pack: line
§0 row 3 triage once per train per-wakeup (§6.1); row 3 is the capacity check + T-5 receipt
§2 required check ci / gate rules API: gate + workspace-test; present not required
§3.4 "≤ 3 read-only subagents" one at a time, fan-out through agy (§10)
§8 stop on "a second concurrent PR in CI" and "SSH into a host" both allowed by amended §3.4/§3.5; stop is a host CONFIG change over SSH instead of forjar
§9 "record the 0.67 cascade wall" recorded: 70 min, attended 0 — 3.5× the [A] line, so by §9's own rule the cascade is the next target; where the minutes go is [U]
§7 T-0..T-4 T-0..T-5
§11.3 cited the one-PR rule §3.4 no longer has fixed

§12 — the chain of reasoning. The spec had eleven sections of mechanism and no argument for why it can run indefinitely. §12.1 gives six steps, each with its mechanism and falsifier: the selector is total; a stop stops the session never the loop; every counter is a ratchet; no number is a guess and a measurable one replaces it (§9 is the worked example); the ledger is the memory; the clock cuts the train.

§12.2 names the four axes — repo, released binaries, CRUX competitors, fleet — on the pv/ontology substrate. The spec had no competitor axis at all. CRUX monitors 9 competitors through 275 stories (✅ 39 · 🔨 80 · ❌ 156 at v2.2 intake [C]; its declared FALSIFY-CRUX-010 is not found under crates/ or scripts/ on main, so the count is [U] and landing it is the first CRUX row). BEATS: Ollama GPU decode at parity with a 0.90 floor, llama.cpp c=1 a narrow loss, fail-closed WON. Approaching is ❌→🔨→✅ by demand tier — already scheduled by §6.3's arithmetic; surpassing is a beat threshold that is a floor first and moves above 1.0 only on three agreeing medians on the published binary, which is why the post-publish dogfood (#3202) precedes any ratio.

Hooks: beats: line in §7, a §8 stop on a beat RED on the published binary or a measured-on published claim from a dev build, a §0 pointer.

🤖 Generated with Claude Code

@noahgift noahgift changed the title docs(spec): APR-RELEASE-001 §4.1/§4.2/§5.1/§10 — the work the train did not name docs(spec): APR-RELEASE-001 — feature matrix, examples, debt tax, continuous triage, decision procedure, ontology kaizen (§11), and the chain of reasoning (§12) Sep 14, 2026
…untracked

The previous wording said the upstream spec was untracked with "no commit,
no history". Measured against origin/main in a fresh worktree: main has
v3.1 (414 lines, f1269d0, infra#570). The untracked file is v4.3 (972
lines, sha256 512a16d5…), the version §11 is measured against. Substance
unchanged — no other host can fetch v4.3 — detail corrected in §11.0 and §8.

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@noahgift

Copy link
Copy Markdown
Contributor Author

Correction to the earlier comments, and the infra side landed as a PR. I said the upstream spec was "untracked in infra — no commit, no history". Measured against origin/main in a fresh worktree: infra main tracks ONT-001 v3.1 (f1269d0, #570). What is untracked is v4.3 — the version §11 is measured against and whose sha256 512a16d5e09c §11.0 pins. Substance unchanged (no other host could fetch v4.3); wording fixed in §11.0/§8 at af7adb229, in #3269, and v4.3 is now committed byte-for-byte as paiml/infra#583 (auto-merge armed, closes paiml/infra#582).

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Sep 14, 2026

Copy link
Copy Markdown

§13.11 rung 1 — quorum shadow verdict

S13-SHADOW pr=3268 head=7cba065fadee69c125f51a0add15dbdcd7cb8012 verdict=REFUSE class=Q1 arm_rc=1

Shadow mode: this records a verdict and merges nothing. A refusal
to arm is not a block (§13 adds zero rows to §7) — the pull request is
exactly as green as it was.

noahgift and others added 2 commits September 14, 2026 19:33
…y the lane merely EXISTING

This spec named `ci / deep` in five places. No such check can exist in this repo, so
T-1's already-done test was reading for a string that would never appear.

GitHub prefixes a check with the job that CALLS it. `ci.yml` calls the org-wide
`sovereign-ci.yml` as a job named `ci`, which is why this repo reports `ci / lint`,
`ci / test`, `ci / gate` — and why `workspace-test`, `guard-tree`, `guard-cargo` and
`gate`, which are top-level jobs in a workflow file, appear bare. Measured on this
PR's own check list, both halves.

`ci / deep` would therefore require a `deep` job inside the ORG-WIDE reusable workflow,
with blast radius across every consuming repo. #3260's lane is `.github/workflows/deep.yml`
with a job named `deep`, emitting `deep`. Amending this document is the cheap half of that
trade; amending an org-wide workflow to match a string this document happened to write is
the expensive half.

§4.3 also records the sequencing hazard, which is the part that would have cost a train:

    $ gh workflow run deep.yml --ref PMAT-1098-ci-deep-lane
    HTTP 404: workflow deep.yml not found on the default branch

`workflow_dispatch` is honoured only on the default branch, and a deep lane deliberately
has no `pull_request` trigger. So the lane cannot be exercised AT ALL before it merges —
its first execution would be the cut it gates — and §4 turns a red step into SKIPPED, so
a lane born red costs the train silently instead of failing loudly.

T-1 is consequently not satisfied by `deep` existing. The already-done test is a green
`deep` run recorded against a sha ON MAIN, and the first such run must be a deliberate
`gh workflow run deep.yml --ref main` after the lane lands and before a cut is attempted.
A gate whose first run is the thing it certifies is the defect class this document exists
to remove.

spec_conformance.sh: exit 0.

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@noahgift

Copy link
Copy Markdown
Contributor Author

Pushed §4.3 and renamed the check in all five places: ci / deepdeep.

GitHub prefixes a check with the job that calls it. ci.yml calls the org-wide sovereign-ci.yml as a job named ci, which is why this repo reports ci / lint / ci / test / ci / gate — and why workspace-test, guard-tree, guard-cargo and gate appear bare. So ci / deep would have required a deep job inside the org-wide reusable workflow. #3260's lane is its own deep.yml with a job named deep, and emits deep.

§4.3 also records the part that would have cost a train:

$ gh workflow run deep.yml --ref PMAT-1098-ci-deep-lane
HTTP 404: workflow deep.yml not found on the default branch

workflow_dispatch is honoured only on the default branch, and a deep lane deliberately has no pull_request trigger — so it cannot be exercised at all before it merges. Its first run would be the cut it gates, and §4 turns a red step into SKIPPED rather than a loud failure. T-1 is therefore not satisfied by the lane existing; it needs a green deep run recorded against a sha on main first.

Branch was BEHIND; merged origin/main, now 0 behind. spec_conformance.sh exit 0.

🤖 Generated with Claude Code

…as itself only a review comment

§11.1 states: "Every sweep PR body carries one line ... Absent is a PR-body lint
failure, not a review comment."

    $ grep -rl ont-delta scripts/ .github/ Makefile
    (nothing)

The rule shipped as prose in #3268 and nothing read it. A rule whose enforcement is
"not a review comment", enforced only by review comment, is this repo's anti-theater
class one level up from the guard it now sits beside in ci.yml.

WHAT A SWEEP PR IS — and only half of it may be a list.

  * the prose sinks §11.1 NAMES are constants here, quoted, and printed on every
    run so drift between spec and guard is visible instead of silent.
  * "a known-red list anywhere" is DERIVED: the union of a working-tree `find` and
    the index, the same rule check_baseline_ratchets.sh uses and for the same two
    reasons — a new baseline arriving unclassified is how the class survives, and a
    tracked-only universe is a free pass for a file present but not yet added.

The derived half is what makes it non-trivial, measured on real PRs:

  #3268  sweep via prose sink docs/specifications/...        PASS (carries none+reason)
  #3277  sweep via KNOWN-RED LIST scripts/cb200_baseline.txt FAIL -> now fixed
  #3278  not a sweep                                          PASS
  #3245  not a sweep                                          PASS

#3277 touches no prose sink at all. A hand-typed sink list would have passed it, and
it is a true positive: that PR withdraws a wrong FAIL and adds an ONT-6 Unknown
reason, which is precisely §11.1 form 3. Its body now carries
`ont-delta: reason ont6-unread-window`.

Case table, 15 rows, and it DISCRIMINATES: deleting the vocabulary check turns the
table red (verified by mutation, not by reading). Rows cover kind-outside-the-
vocabulary, none-without-a-reason, id-absent, case, leading space, and empty body.

Vacuity floor: an empty changed-file list exits 2, because "not a sweep PR" is a
verdict this guard could not have reached.

Two defects found writing it, both kept as comments:
  * a RETURN trap runs after bash destroys the function's locals, so `rm -rf "$tmp"`
    died on an unbound variable AFTER fifteen green rows — a self-test that passed
    and exited 1.
  * bashrs SEC011: an unvalidated `rm -rf "$var"` is a delete-anything primitive.
    Now shape-checked before the sweep. bashrs 7.4.1: 0 errors.

WORKFLOW CHANGE, stated rather than buried: this adds one step to ci.yml. §11.1
cannot exist without a caller, and guard_tree.sh runs check_*.sh BARE — which would
run only the self-test, fifteen green rows judging no PR body, the exact failure the
neighbouring step's comment documents.

ont-delta: resolves scripts/check_pr_ont_delta.sh — §11.1 was a prose claim; this
turns it into a checkable one (form 4).

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…are fail-fast and one red guard skipped 48 of 59

Measured on run 34875945193 (PR #3268), job `guard-tree`:

    total steps                                    59
    ran                                            10
    skipped after the step-8 failure               48

    step  8  failure  Every cargo-free guard runs, and every failure is reported
    step 55  skipped  A PR body must close every issue it cites (§6 R-2)
    step 56  skipped  A sweep PR closes with an ontology delta (§11.1)

GitHub Actions steps are fail-fast: one red step darkens every step after it.

Why this is worse than a missed run. check_pr_closes_issue.sh exists because the
0.67.0 T-5 reconcile found 48 merged PRs since the previous tag of which only NINE
closed anything. Its own wiring comment, four lines above this change, records that
running it bare executes only its self-test — "Nine green rows about a regex, on
every PR, judging NO PR body" — and that a real caller was the remedy.

It got a real caller. The caller is masked. On any PR where one cargo-free guard is
red the guard is dark exactly as it was before it was wired, and step 8 is currently
red on EVERY PR (the pin/advisory deadlock, #3277), so §6 R-2 has been dark
fleet-wide for the duration.

`!cancelled()` rather than a bare event check: a step whose `if:` contains no status
function is still skipped on a prior failure. These two read
`github.event.pull_request.body` and nothing else, so no guard result can be their
precondition — which is what makes this the narrow, defensible half of the fix.

The other 46 skipped steps are mostly CASE TABLES — the mutation-verification proving
the neighbouring guards can still go red. A case table that does not run is the
theater this repo keeps deleting. They are NOT swept here: some (`target-watch:`
markers) plausibly do depend on ordering, and a blanket always() over 48 steps would
be its own kind of wrong. #3282 carries the classification.

Stated rather than buried: unmasking means these steps now report on PRs that are
already red for another reason, so the first sweep will surface findings that have
been invisible for as long as the masking has.

Same class as nextest --fail-fast hiding four dark failures across seven rounds; that
lesson said "sweep the CI selection" and nothing had swept the STEP surface.

ont-delta: none — a CI wiring fix; this PR's delta is already recorded against
scripts/check_pr_ont_delta.sh.

Pmat-Ticket: PMAT-1098
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@noahgift

Copy link
Copy Markdown
Contributor Author

The §6 R-2 gate has been dark on every PR

Found while checking whether this PR's new §11.1 step actually ran. It didn't — and neither did its neighbour.

guard-tree, run 34875945193
  total steps                       59
  ran                               10
  skipped after the step-8 failure  48

  step  8  failure  Every cargo-free guard runs, and every failure is reported
  step 55  skipped  A PR body must close every issue it cites (§6 R-2)
  step 56  skipped  A sweep PR closes with an ontology delta (§11.1)

Actions steps are fail-fast. check_pr_closes_issue.sh exists because the 0.67.0 reconcile found 48 merged PRs of which only 9 closed anything, and its own wiring comment says running it bare judges no PR body at all. It got a real caller — and the caller is masked by an unrelated red. Step 8 is currently red on every PR (#3277's deadlock), so §6 R-2 has been dark fleet-wide.

Fixed here for the two PR-body steps only, with !cancelled(): they read github.event.pull_request.body and nothing else, so no guard result can be their precondition.

The other 46 are mostly case tables — the mutation-verification proving neighbouring guards can still go red. Not swept here: some (target-watch: markers) plausibly depend on ordering, and a blanket always() over 48 steps would be its own kind of wrong. #3282 carries that classification.

Worth expecting: unmasking means these steps now report on PRs already red for another reason, so the first sweep surfaces findings that have been invisible for as long as the masking has.

🤖 Generated with Claude Code

@noahgift
noahgift enabled auto-merge September 14, 2026 18:38
@noahgift
noahgift added this pull request to the merge queue Sep 14, 2026
@noahgift
noahgift removed this pull request from the merge queue due to a manual request Sep 14, 2026
@noahgift
noahgift added this pull request to the merge queue Sep 15, 2026
Merged via the queue into main with commit e6e13ad Sep 15, 2026
32 of 35 checks passed
@noahgift
noahgift deleted the PMAT-1098-spec-amend branch September 15, 2026 05:53
noahgift added a commit that referenced this pull request Sep 17, 2026
… of over it

The operator's revision was cut from a working copy that predates #3268 and #3455;
landing it verbatim deleted §4.1-4.3, §5.1, §6.1-6.4, §10-§12 (596 lines, incl. the
§11.1 ont-delta rule the PR-body guard cites). This keeps main as the base and adds
the revision: header notes, selector row 1a, capacity-source rule, §1.5/§1.6, the
§2 rows + measurement hygiene, rule 4 group size, rule 7 (publish_strict, history
kept), rules 9-15, T-0/T-2/T-3 clauses appended to main's rows, T-4 replaced, the
P0 Frag/Runners/Pins/Fan-out/Unwedge rows, the milestone bullet, six §7 lines, the
§8 stops, and §9 with the 0.68.1 measurements. vs main: +229 / -14, every removed
line is a row that was extended or superseded by a later ruling.

Pmat-Ticket: PMAT-3468
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant