This is the single entry point for the agent-first clean cutover. Active documents below are mutually controlling: each owns one implementation area, and none of the archived documents may override them.
CK-07A's evidence
records 80 / 80 variants after CK-07B/C/D/E and CK-03–07 replay. The
CK-08 gap
is preserved/superseded; CK-04 runs 3/4 remain waived and five-run success
unclaimed. Historical CK-08 covers 21 plans/42 variants, but shared truth,
post-materialization paging, mixed timing and unproved scale cannot admit
projections; corrective-gates-v1
keeps CK-09 blocked.
CK-08R2 is complete on merge: two supported direct plans now use bounded
physical keyset SQL; 19 plans retain explicit gaps without projection.
Retained CK-08R3 a28e9cdbff8e48d334712a449fdcee111c725673 then stopped
before scale on first/deep EvidenceService EXPLAIN. CK-08R3A owns that separate
fix; CK-08R3 awaits its accepted merge/exact-main verification. Independent
truth now consumes answer-semantics.v1;
The linked CK-08R3A schema/publication requalification authority
binds only the resulting 57-index schema digest, synthetic publication fixture
manifests, and compatible tiny-accounting EXPLAIN expectation; R3A remains
Conditional Ready and implementation remains unaccepted. The exact
final-shared authority
keeps predecessor handling rejection-only and binds exact
zero-based nonnegative turn-rank equality, including valid rank 0 and
preserved rank >0, across manifestation, observation, persisted turn, and
EvidenceService evidence. Its exact atomic seven-production/nine-support
cohort and fixture/DDL identities, including the session-leading lifecycle
index, are permitted, not accepted.
The linked CK-08R3A bounded-session portability authority
supersedes only the prior marker-free EXPLAIN wording: SQLite 3.45.1 may emit
at most one structurally proven USE TEMP B-TREE FOR ORDER BY for the deep
timeline/allowance session branch, whose merge input is at most one row. The
lifecycle branch, every first page, every other deep shape, all result/cursor
truth, and all generic forbidden-plan checks remain bounded and fail closed;
the authority changes no production, DDL, or schema identity.
The linked CK-08R3A portable-plan branch-ownership authority
supersedes only the support proof: full EXPLAIN row ids, parents, direct
siblings, and leftmost ancestry must bind the sole marker to the unique
session-event branch. A marker under calls, tools, lifecycle, or an ambiguous
lookup chain is rejected; the corrected support test remains preflight-only
and the implementation remains unaccepted.
R1C is accepted at exact main fb0c57886097a6b985d2f321b2de858cbdfc0a97;
R1B remains held on shared query/evidence/grading integration before final R1
requalification.
CK-QG1A0 gated the selected R2 PageExecutor successor; QG1A removed its two
C/B/B findings and is accepted at exact main 30983d4b5005e7e2a507757c76a3c05ab56281e6;
existing QG1 PR #392 is Ready to resume from corrected main. CK-07R1A separately corrected
PR #394's exact hosted lifecycle-tail failure without a budget waiver.
CK-07R1A0 path authority remains accepted at exact main
519b503aa3b23019033b6481687c08b23fc6c31e; its linked source-digest
authority
and run-invocation authority
keep CK-07R1 blocked_hold
(docs/decisions/evidence/ck07r1a0/lifecycle-run-invocation-authority.json).
The shared-preparation transition is exactly two-state: live exact-main
preparation 408d18e4… before R3A, and the current session-bounded preparation
6689d61f… only inside the complete R3A cohort after its acceptance. Prior
candidate e204e0da… and historical candidate d192c858… are retained
read-only, revoked for the new base, and forbidden for direct use. CK-07 must
later reapply its retained lifecycle diff onto the accepted R3A base to derive
a new exact preparation digest before any run. PR #394 remains a stale failed
read-only witness; it is not updated, rerun, or merged. The old argv-guard attempt remains the historical
pre_child_argv_guard_failure: exit 2 after 0.075241709 seconds, with no
child, PID, handshake, token, output, ledger, stdout, stderr, receipt, or
runtime evidence. The corrected guard is
(sys.argv[0], *sys.argv[1:]) == LAUNCH_COMMAND[1:]. The run authority freezes
the exact launch, fixture, revoked malformed dispatch value, 720-second wrapper
timeout, four-path non-overwriting preflight, evidence, token, and no-retry
contract while preserving the 5000/120000/100/500/500 ms budgets. No worker
resumes from this authority task, no run token is consumed, no launch/output is
authorized, no other successor is advanced, and the one-run gate remains
unspent. Reclassification and maintainability remain open. The central authority is
REMAINING_EXECUTION_PLAN.md.
The finite source/runtime state machine is currently authority_main: the live
predecessor may remain on authority main, while only the exact selected
successor may enter worker prequalification. post_single_run is unavailable
without a complete planner-valid receipt bound to its exact dynamic receipt and
evidence identity, and final_accepted additionally requires the worker PR to
be squash-merged and exact-main verified. No state transition claims runtime
qualification in this authority.
| Order | Document | Controls |
|---|---|---|
| 1 | docs/decisions/PRODUCT_DIRECTION.md |
Product definition, responsibility boundary, non-goals, locked decisions, and success measures. |
| 2 | docs/product/SUPPORTED_QUESTION_CONTRACTS.md |
Supported intents, answer grades, evidence, performance classes, named presets, and unsupported conclusions. |
| 3 | docs/architecture/LOGICAL_KERNEL_CONTRACT.md |
Physical-design-independent entities, fields, identities, time, missingness, provenance, and publication semantics. |
| 4 | docs/architecture/FORMULA_AND_SELECTOR_CONTRACT.md |
Executable formula semantics, answer-field bindings, selector ownership, provenance, and exact comparison. |
| 5 | docs/architecture/PLAN_OPERAND_AND_FACT_CONTRACT.md |
Executable plan-to-operand/direct-fact bindings, pure compiler boundary, valuation relation, and missing canonical facts. |
| 6 | docs/architecture/PHYSICAL_ARCHITECTURE_BAKEOFF.md |
Candidate A/C/D experiment, fixtures, workloads, measurements, and selection decision. |
| 7 | docs/architecture/TARGET_ARCHITECTURE.md |
Package ownership and runtime boundaries after the bake-off. |
| 8 | docs/architecture/ADAPTER_CONTRACT.md |
Codex source ingestion, normalization, capabilities, cursors, replacement, duplicates, and the future-agent seam. |
| 9 | docs/architecture/PUBLICATION_REFRESH_RECOVERY.md |
Refresh state machine, dirty keys, small tails, large artifacts, crashes, promotion, and rollback. |
| 10 | docs/architecture/QUERY_EVIDENCE_PROJECTION_CONTRACTS.md |
Named plans, bounded composition, evidence, pagination, projections, valuation, and result envelopes. |
| 11 | docs/product/AGENT_SETUP_AND_MCP_EXPERIENCE.md |
First use, history selection, host waiting, reopen, refresh/expansion, call budgets, and skill behavior. |
| 12 | docs/quality/QUALIFICATION_PLAN.md |
Synthetic truth, production-shape profiling, benchmarks, installed-agent trials, crash tests, and ratchets. |
| 13 | docs/roadmap/AGENT_FIRST_CLEAN_CUTOVER.md |
The only authoritative implementation roadmap, dependencies, gates, cutover, and release. |
| 14 | docs/roadmap/REMAINING_EXECUTION_PLAN.md |
Remaining task graph, readiness, role routing, ownership locks, and allowed/forbidden parallelism. |
| 15 | docs/roadmap/TASK_PACKETS.md and docs/roadmap/tasks/ |
Completion accounting and one agent-executable contract file per delegated task. |
| 16 | docs/roadmap/LINEAR_BACKLOG.md |
Historical Linear-ready mapping; no Linear change is authorized by the decomposition. |
| Question | Authority |
|---|---|
| What product are we building? | PRODUCT_DIRECTION.md |
| Can the product answer this question, and how? | SUPPORTED_QUESTION_CONTRACTS.md |
| What does a session, turn, call, tool, resource, observation, or publication mean? | LOGICAL_KERNEL_CONTRACT.md |
| What exactly does a formula compute, and how must selector evidence resolve? | FORMULA_AND_SELECTOR_CONTRACT.md |
| How do named plans derive formula operands and direct facts, and which missing fact representations are authoritative? | PLAN_OPERAND_AND_FACT_CONTRACT.md |
| Which physical schema is allowed? | The completed decision artifact required by PHYSICAL_ARCHITECTURE_BAKEOFF.md |
| Which package owns a behavior? | TARGET_ARCHITECTURE.md |
| How does Codex JSONL become canonical facts? | ADAPTER_CONTRACT.md |
| May this refresh rebuild or block readers? | PUBLICATION_REFRESH_RECOVERY.md |
| May this query, selector, or projection exist? | QUERY_EVIDENCE_PROJECTION_CONTRACTS.md |
| How should an installed agent set up and call the kernel? | AGENT_SETUP_AND_MCP_EXPERIENCE.md |
| What proves the implementation? | QUALIFICATION_PLAN.md |
| What happens next, and what may run in parallel? | REMAINING_EXECUTION_PLAN.md, constrained by AGENT_FIRST_CLEAN_CUTOVER.md |
| Where does work get tracked? | LINEAR_BACKLOG.md; Linear is intended after maintainer issue creation. |
- Open the Ready child task from
REMAINING_EXECUTION_PLAN.md, confirm its exact dependencies and ownership lock, then read its controlling documents. - Read the relevant question IDs and logical entities.
- Read the publication/query/adapter contract that owns the touched boundary.
- Read the qualification cases and budgets before writing code.
- Consult archived spike evidence only for the exact oracle or lesson named by the packet.
- For every upstream artifact consumed as truth, run the packet's executable seam check against the actual consumer path and independent reference evaluator; a digest or prior completion status is not sufficient.
- Amend
PRODUCT_DIRECTION.mdif responsibility or non-goals change. - Amend affected question contracts and logical semantics.
- Update architecture, qualification, roadmap, packet, and backlog mappings in the same change.
- Add or change an executable contract before production implementation.
Read the roadmap, publication/recovery protocol, qualification plan, cutover packets, and release packet. The roadmap's active runtime-retirement gate controls deletion. Consult the spike disposition only for the historical inventory and named oracles; it cannot add or waive a cutover condition.
Everything under docs/archive/ is non-authoritative. The useful archive is:
docs/archive/SPIKE_DISPOSITION.mddocs/archive/SPIKE_PERFORMANCE_EVIDENCE.mddocs/archive/spike/KERNEL_STABLE_CONTRACT_0_28.mddocs/archive/spike/ALLOWANCE_EFFICIENCY_FINDINGS.mddocs/archive/spike/OVERLAY_ADAPTER_CONTRACT_0_28.md
Git history contains prior roadmaps, review reports, UI plans, and superseded proposals. They are intentionally absent from the active tree.
The 0.28 implementation, tests, fixtures, and release tooling remain executable oracles until the retirement gate. Their current behavior is not product authority unless an active document explicitly adopts it.
If two active documents appear inconsistent:
- product responsibility and non-goals win over implementation convenience;
- question and logical contracts win over a physical candidate;
- safety and publication invariants win over latency;
- the qualification plan decides whether a claim is proven;
- stop the affected packet and record a decision amendment rather than silently choosing the spike behavior.
If an already completed packet's artifact fails in a downstream consumer, preserve the historical completion record, add a corrective packet to the dependency graph, and require linked requalification evidence for every affected downstream seam before dependent work resumes.
Archived documents, old branch names, current spike schemas, and historical release notes never resolve an active-contract conflict.