feat(ci): promote the certain-exempt docs core to merge-queue trust

[PerishCode]

Why

#6029 landed the confidence-tiered scope rule structure as a deliberate degenerate case: all rules medium, the certain set empty, the merge queue running everything. This PR is the promised cold start — the first certain-tier promotion — chosen and sized by measurement rather than intuition.

The pain: merge-queue runs are all-or-nothing. Replaying the last 398 first-parent merges through the evaluator shows 14.1% touched only the exempt surface (docs, landing-page, editor configs), and 12.3% stay pure under a narrowed, guardable core — yet every one of those merges ran the full lane set (~51 runner-minutes of skippable lanes per run, measured across recent successful queue runs; UI P0 alone is ~31 of them). Docs and translation PRs pay a ~10-minute merge latency for browser suites that cannot observe them.

The promotion is statable in three sentences: promote the docs//apps/landing-page//editor-config exempt core to certain, guarded by a new floor-lane check asserting no skippable-lane source consumes those paths; a pure-core queue group now drops to the two unconditional floor lanes; measured tonnage is 12.3% of queue traffic (queue groups are effectively single-PR: 429 merges vs 440 successful queue runs this month, so the per-merge replay transfers directly).

The second deliverable is the methodology this decision was made with: specs/current/ci.md records the medium/certain iteration loops, the three-sentence promotion discipline, guard strength levels and floor placement rules, and the replay recipes — so the next promotion is a rule-table diff plus evidence, not a re-derivation.

What users will see

No product-facing change. For contributors and maintainers:

• A merge-queue group confined to docs/, apps/landing-page/, .vscode/, .idea/, .github/ISSUE_TEMPLATE/, LICENSE, .github/CODEOWNERS now runs only preflight + workspace unit tests (~4 min wall-clock instead of ~10). Any other file in the group escalates and keeps the full plan, exactly as before. Root markdown (README.md etc.) deliberately stays medium-tier.
• pnpm guard gains a "certain-exempt surface consumption" check: a repo-relative docs/... (or other certain-exempt) reference in gate-lane source now fails guard with a rationale and an exit path. Dot-relative references are flagged everywhere; bare literals only outside test fixtures (Vitest cwds make bare fixture paths unable to reach repository docs).
• scripts/guard.ts --list-checks prints the check-name registry; the rule-table invariant test resolves every certain rule's guard field against it, so a certain rule can never silently outlive its guard.
• specs/current/ci.md is the new required reading before changing confidence or guard fields (indexed from AGENTS.md and .github/AGENTS.md).

Surface area

• UI — new page / dialog / panel / menu item / setting / empty state in apps/web or apps/desktop (including Electron menu bar)
• Keyboard shortcut — new or changed
• CLI / env var — new od subcommand or flag, new tools-dev / tools-pack / tools-pr flag, or new OD_* env var
• API / contract — new /api/* endpoint, new SSE event, or changed shape in packages/contracts
• Extension point — new entry under skills/, design-systems/, design-templates/, or craft/, or change to the skills protocol
• i18n keys — added new translation keys (see TRANSLATIONS.md for the locale workflow)
• New top-level dependency — adding any new entry to the root package.json
• Default behavior change — changes what existing users experience without opting in
• None — internal refactor, docs, tests, or translation update only

What's in here (by commit)

1. feat(ci): the promotion + guard. exempt-surface splits into certain-exempt-surface (the promotable core, confidence: "certain", guard named) and the medium residue (global *.md regex, trusted-workflow exacts, nix/); the residue carries excludeWhen over the core so min-confidence co-matching cannot neutralize the promotion for docs/**.md. New guard check scripts/check-certain-exempt-consumption.ts scans gate-lane sources (root scripts/ excluded — floor-owned code runs on every plan and legitimately reads docs, e.g. product neutrality) with a two-level precision rule tuned against the real false-positive corpus (24 project-fixture hits at the naive level, 1 true consumer at the final level: tools/release reading docs/CHANGELOG, which executes in no ci.yml lane — allowlisted with rationale). Goldens: one new case pins the divergence (pure-core queue group → floor lanes), the adjacent case pins containment (a group with README.md still runs everything), and new invariants pin no-co-match and guard resolution.
2. docs(ci): the methodology. specs/current/ci.md + index lines. Owns confidence-tier evolution; topology stays with .github/AGENTS.md.

Expected effect (measured)

• ~2.2 pure-core merges/day at current velocity → ~3,400 skippable runner-minutes/month removed from the queue (±25%; five-run duration sample), including Windows runner minutes.
• Pure-docs merge latency: ~10 min → ~4 min (longest skipped lane was the UI P0 workspace-restoration shard).
• UI P0 shard capacity freed for other queue runs at peak.

Bug fix verification

Not a bug fix. Behavior-change containment is pinned the same way #6029 pinned behavior preservation: the golden that changes is the proof of the promotion; the goldens that do not change (root-markdown group, mixed group, resolution-failure fail-open, 300-file ceiling) are the proof of its limits.

Validation

• pnpm guard (including the new check; it caught its own test's fixture snippets during development — allowlisted with rationale)
• pnpm typecheck surfaces touched: pnpm exec tsc -p scripts/tsconfig.json --noEmit + @open-design/e2e typecheck
• pnpm --filter @open-design/e2e test tests/scripts/scopes.test.ts — 36 passing (19 goldens including the new divergence case, queue failure paths, rule-table invariants, consumption-guard precision semantics)
• pnpm --filter @open-design/e2e test tests/packaged-smoke-workflow.test.ts — 52 passing (no topology entanglement)
• Offline: scripts/scopes.ts plan --context merge-queue --files docs/architecture.md apps/landing-page/src/index.astro LICENSE → zero escalations, floor lanes only

Adjacent issues

• e2e/tests/** arms no e2e Vitest lane on PR runs; consequently edits to the trusted atom workflows (comment.atom.yml etc.) run the workflow-topology tests only in the merge queue, nowhere on the PR itself. Pre-existing; deserves its own medium-tier rule PR.
• mocks/** is fallback-classified into Playwright lanes instead of the daemon tests that consume it (~1% tonnage; worked-example candidate for the medium loop).
• Floor conditionalization (pure-core groups still pay ~6 min of floors) is the natural second certain-tier proposal; it must first confront guard coverage for non-markdown files inside exempt prefixes.
• The dispatch-hot workspace-validation asymmetry remains pinned in the goldens, unchanged.

🤖 Generated with Claude Code

[mrcfps]

@PerishCode Thanks for the careful measurement, containment goldens, and documented promotion methodology. The scope behavior and focused validation look solid; I found one merge-safe guard-coverage gap where the blanket test-fixture exemption can hide genuine repository-root reads. Tightening that boundary would make the new certain-tier invariant more durable.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[PerishCode]

Looper fixer round complete — b56bc20

• ✅ Review comment on scripts/check-certain-exempt-consumption.ts (@mrcfps) — thread
  • Replaced the blanket test-path exemption with known sandbox-writer detection and explicit rationale-backed file exceptions in scripts/check-certain-exempt-consumption.ts. Added a matrix proving writeProjectFile is tolerated while readRepoFile is reported.

_{🔁 Powered by Looper · runner=fixer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[mrcfps]

@PerishCode Thank you for the careful follow-up on the earlier fixture exemption and for the strong scope goldens and methodology write-up. The current tree and focused validation look sound; I found one merge-safe static-analysis gap worth tightening so the new certain-tier boundary remains dependable as path construction evolves.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[PerishCode]

Follow-up on the fixer round, from the author side:

@mrcfps's finding is confirmed and was a real hole. The original fixture-tolerance rule assumed bare docs/... literals in tests could not reach repository docs (Vitest cwd argument); readRepoFile in trae-cli.test.ts is exactly the repo-root-resolving helper that argument missed. The fixer's polarity change — flag by default, tolerate known sandbox writers, rationale-backed file exceptions — is the right fail-closed shape for a certain-tier guard, and I'm keeping it.

One hardening on top (723faea): the trae-cli exception was justified by a wiring fact ("not selected by any ci.yml daemon-test lane") stated as prose. That fact is true today — the daemon lane runs only tests/project-watchers.test.ts — but prose rationales rot silently when remote wiring changes. The exception is now conditional on that exact ci.yml needle: if the daemon lane widens, the exemption disappears and the guard reports the docs/agent-adapters.md read, forcing reclassification (a docs → daemon scope rule, or relocating the consistency assertion to e2e/tests/) instead of trusting a stale comment. Verified both paths locally.

On the red Web workspace tests job: App.connectors.test.tsx > keeps telemetry and content sharing enabled when the first-run banner share choice is clicked failed with a zero-call mock assertion. The fixer commit touches only scripts/ and e2e/tests/scripts/ — neither is in that suite's dependency surface — and the same job passed on the parent commit an hour earlier. Treating it as an unrelated flake; the push above re-runs the lane. If it reds again on an untouched suite, it deserves its own issue rather than burying it in this PR.

[mrcfps]

@PerishCode Thank you for the careful follow-up: the test-fixture handling is now much narrower, the real docs consumer is tied to current lane wiring, and the confidence methodology is substantially clearer. I verified all changed ranges and reran the 36-case scope suite, scripts TypeScript check, and full repository guard successfully. I found one additional merge-safe gap in how that lane-wiring precondition is enforced; the existing unresolved static path-composition thread also still applies, so I have not duplicated it here.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[PerishCode]

Looper fixer round complete — 3682778

• ✅ Review comment on scripts/check-certain-exempt-consumption.ts (@mrcfps) — thread
  • Updated scripts/check-certain-exempt-consumption.ts to fold static path.join/path.resolve expressions and detect template literals entering exempt roots while preserving sandbox-writer exclusions. Expanded e2e/tests/scripts/scopes.test.ts with direct, relative, split-path, interpolated-prefix, and sandbox cases.
• • Review comment on scripts/check-certain-exempt-consumption.ts:272 (@mrcfps) — thread
  • Agent did not provide a decision for this thread

_{🔁 Powered by Looper · runner=fixer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[PerishCode]

Looper fixer round complete — 6849e86

• ✅ Review comment on scripts/check-certain-exempt-consumption.ts (@mrcfps) — thread
  • Updated scripts/check-certain-exempt-consumption.ts to inventory daemon test invocations and permit the conditional consumer only when exactly the narrow project-watchers command exists. Added narrow-only and narrow-plus-broader fixtures in e2e/tests/scripts/scopes.test.ts.

_{🔁 Powered by Looper · runner=fixer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[mrcfps]

@PerishCode Thank you for the quick, careful follow-up on the earlier guard feedback. The certain-tier scope behavior, current workflow wiring, and focused validation are sound; I found one remaining merge-safe command-normalization gap in the new exclusivity check that is worth closing so the conditional exception stays fail-closed as CI syntax evolves.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[PerishCode]

Looper fixer round complete — 7852a1e

• ✅ Review comment on scripts/check-certain-exempt-consumption.ts (@mrcfps) — thread
  • Updated scripts/check-certain-exempt-consumption.ts to normalize -F, --filter=, --dir, and -C daemon selectors, and expanded e2e/tests/scripts/scopes.test.ts to verify each broader command disables the conditional exception.

_{🔁 Powered by Looper · runner=fixer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[mrcfps]

@PerishCode Thank you for the careful follow-up and the added selector-form coverage. The certain-tier scope behavior, guard, documentation, and focused validation are otherwise coherent; I found one remaining merge-safe parsing gap in the conditional daemon-test exception that is worth making fail-closed.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[PerishCode]

Looper fixer round complete — 5935905

• ✅ Review comment on scripts/check-certain-exempt-consumption.ts (@mrcfps) — thread
  • Updated scripts/check-certain-exempt-consumption.ts to extract and tokenize YAML run bodies before inventorying daemon test commands regardless of pnpm option placement. Expanded e2e/tests/scripts/scopes.test.ts with run test, --silent, and -r forms.

_{🔁 Powered by Looper · runner=fixer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[mrcfps]

@PerishCode I reviewed all changed ranges on the current head, including the certain-tier rule split, fail-closed scope behavior, guard registration, consumption scanner and daemon-command inventory, methodology documentation, and the expanded scope fixture matrix. I also verified this exact checkout with the 37-case focused scope suite, the full repository guard, the scripts TypeScript check, and the full workspace typecheck; all passed. The latest tokenization follow-up closes the prior command-order gap cleanly. Thank you for the careful measurement, strong containment tests, and patient hardening across the review rounds—this is thoughtful CI work. 🙌

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}