Skip to content

docs(review-checklist): rule 26 — a derived default must be one its consumer accepts - #1755

Merged
lilyshen0722 merged 1 commit into
mainfrom
kai/checklist-consumer-accepts
Sep 19, 2026
Merged

lilyshen0722 merged 1 commit into
mainfrom
kai/checklist-consumer-accepts

Conversation

@lilyshen0722

Copy link
Copy Markdown
Contributor

Adds one rule to the incident-derived reviewer checklist: a default you derive for a consumer must be one that consumer accepts, and the check is to run the derived value through the consumer's own guard rather than assert its shape.

Why this rule, and why this incident

Earned by #1754 / TASK-052, where four instances of one family surfaced in a single PR and every one of them was found by running the consumer rather than inspecting the serializer. The predicate that chose the sandbox half of a derived seat environment was ADAPTERS_WITH_DEFAULT_MCP — the set that consumes mcp[] — where the question was which adapters can enforce a sandbox.

Two of the four failed in the fatal-and-silent direction: a declaration the consumer must refuse. The daemon writes the record, the spawn throws, and the stored row looks correct the whole time — so every derived seat of that adapter is unspawnable while the board says it is installed:

  • cli/src/lib/adapters/pi.js:149 assertNoSandboxDeclared (called at :231, from fix(cli): pi seats — seat token out of the shell env; unenforceable sandbox fails closed #1727) refuses trust: 'public' — so every daemon-derived pi seat would have been written a record it cannot start on. Two fixtures were pinning that shape green.
  • codex's absent-mode throw would have stopped every derived codex seat.
  • claude's two consumers read one declaration independently and disagreed at runtime.
  • The doc comment this PR wrote beside the constant asserted the opposite mechanism ("a pi seat gets the block and is NOT confined by it"); pi in fact fails closed on it.

The assertion that closes the class is not expect(derived).not.toHaveProperty('sandbox') — that passes on exactly the state that breaks the seat — it is running the derived value through the consumer's own guard: the spec this adapter receives is one this adapter accepts. Reverting the guard reds exactly the two paired tests.

Facts in the rule are checked against the tree, not recalled: ADAPTERS_WITH_DEFAULT_MCP is at cli/src/lib/default-environment.js:25 (gating the mcp half at :41/:60) and assertNoSandboxDeclared is at cli/src/lib/adapters/pi.js:149. The quoted comment is in #1754's diff and is labelled as such in the text, so a reader grepping main is not sent hunting for it.

Placement

Appended, per the file's own norm: rule numbers ascend in document order and are cited by number elsewhere (ADR-028 rule 23, ADR-019 rule 9, REVIEW.md §7), so a rule added mid-file renumbers everything below it. New section at the end, first item numbered 26 ⇒ renders as 26. Nothing above this diff changed.

Verification

Gate: factual accuracy against the tree (Vera's standing rule for a doc/runbook PR).

…onsumer accepts

Adds a section + rule 26 at the end of the file, per the doc's numbering
norm (append to the tail; rule numbers ascend in document order and are
cited by number elsewhere, so nothing above is renumbered).

The rule is earned by #1754/TASK-052, where four instances of one family
all surfaced from running the consumer rather than inspecting the derived
shape: the predicate was ADAPTERS_WITH_DEFAULT_MCP ("consumes mcp[]"),
which is not the set that can enforce a sandbox. Two of the four were
fatal-and-silent — codex's throw and pi's assertNoSandboxDeclared would
each have made every daemon-derived seat of that adapter unspawnable
while the stored record looked correct.

No version bump: docs only.
@lilyshen0722
lilyshen0722 force-pushed the kai/checklist-consumer-accepts branch from 5c367a1 to ad3aa8d Compare September 19, 2026 15:09
@lilyshen0722
lilyshen0722 merged commit e938afc into main Sep 19, 2026
13 checks passed
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