docs: consolidate the design-contract pull request queue

[tt-a1i]

Problem

The open pull request queue contains 30 documentation PRs. Twenty-five overlapping design-contract PRs (#243-#268, excluding #258) were opened from one stale base in a short batch. They all update the same design index and cover overlapping Session, context, lifecycle, delivery, resource, and future-capability vocabulary.

Merging them independently would turn candidate designs into repository contracts before the decisions converge, create repeated index conflicts, and impose a review burden that is much larger than the runtime value.

Closing a PR under this plan is not a finding that its research is wrong. The PR remains the preserved source record and must be linked from any successor that reuses it.

Evidence boundary

Repository documentation may preserve:

• current implementation facts tied to a revision;
• accepted Decisions and their alternatives;
• completed Benchmark results with frozen identities and evidence;
• protocols for an active, explicitly approved experiment.

A complete-looking candidate design is not automatically an accepted contract. Future capabilities without an implementation decision or completed experiment remain Issue-level research.

Keep as independent work

• docs: establish knowledge and evidence contract #199 — documentation and evidence governance. Repair or split it so governance, Benchmark protocol, and one Benchmark run are not coupled accidentally.
• docs(workflows): clarify acceptance requiredEvidence type, limits, and usage (#207) #223 and docs(workflows): clarify evidence-free acceptance criteria #229 — focused Workflow acceptance behavior documentation.
• docs(benchmark): 落地 OpenPI 54-cell ARM64 诊断报告 #271 and docs(benchmark): 落地 DeepSeek 24-cell 诊断报告 #272 — completed Benchmark reports; review each against the source Issue evidence.

Consolidate into at most three successor records

Execution lifecycle

Source PRs: #244, #246, #247, #250, #254, #255, #257, #260.

Cover only settled facts and unresolved decisions across Session, Goal, Tasks, background execution, completion delivery, pause, checkpoint/rewind, and structured child results.

Context and model invocation

Source PRs: #245, #248, #249, #253, #256.

Cover provider/model routing, model-visible context, cache ownership, compaction, and diagnostics. Keep observed facts separate from recommendations and unknown provider behavior.

Capability, authority, and resources

Source PRs: #243, #251, #252, #265.

Cover provider boundaries, role/tool-schema disclosure, owner-scoped resource references, and shared admission. Do not introduce a second registry, router, scheduler, or authority plane.

Defer until there is an active implementation or experiment

• docs(capabilities): define on-demand lsp contract #259 — on-demand LSP
• docs(pi): record AgentHarness compatibility baseline #261 — AgentHarness compatibility baseline
• docs(research): define advisor reviewer benchmark #262 — continuous Advisor benchmark
• docs(collaboration): define local observer contract #263 — local Observer
• docs(debugging): define dap failure benchmark #264 — DAP benchmark
• docs(editing): define structural query edit boundary #266 — structural query/edit
• docs(memory): define durable learning boundary #267 — durable learning
• docs(compute): define persistent eval benchmark #268 — persistent Eval/Tool Bridge

These PRs remain available as research input. Reopen the work through the linked source Issue when its decision frontier, owner, fixed implementation point or experiment, and acceptance evidence are ready.

Success criteria

• Keep docs: establish knowledge and evidence contract #199, docs(workflows): clarify acceptance requiredEvidence type, limits, and usage (#207) #223, docs(workflows): clarify evidence-free acceptance criteria #229, docs(benchmark): 落地 OpenPI 54-cell ARM64 诊断报告 #271, and docs(benchmark): 落地 DeepSeek 24-cell 诊断报告 #272 open and process them independently.
• Close docs(capabilities): define external provider contract #243-docs(compute): define persistent eval benchmark #268 except fix(subagents): surface worktree cleanup failures #258 with a link to this tracker and an explicit disposition.
• Do not ask the contributor to rebase all 25 branches.
• Any successor cites every source PR it incorporates.
• Successor records distinguish facts, decisions, recommendations, unknowns, protocols, and validated results.
• Successor records use the canonical openpi-dev/openpi identity and current category policy.
• No runtime feature is claimed implemented or accepted by documentation alone.

Proposed order

1. Settle the documentation governance boundary in docs: establish knowledge and evidence contract #199.
2. Process the two focused Workflow docs.
3. Verify the two Benchmark reports against their source evidence.
4. Draft the three consolidation records only where settled content remains.
5. Leave future capability research in Issues until activated.