Start with the project context guide for reading order and authority. AGENTS.md remains the agent entry point. The checkout is a CLI/types scaffold. The following documents specify planned behavior, open contracts and verification requirements. Start with the architecture, then follow one subsystem.
flowchart LR
A[Architecture overview] --> P[Compile and validate]
P --> R[Provision environments]
R --> E[Schedule and execute]
E --> O[Observe and record]
O --> C[Optional report]
| Guide | Owns |
|---|---|
| Decisions | Accepted direction and open decisions |
| Architecture | Whole-system responsibilities and handoffs |
| Providers | Syntax/semantic lowering and provider plugin boundary |
| GHA provider | GHA action/state/compatibility contracts |
| Planning and validation | Structural validation, binding and admission phases |
| Runner provisioning | Profiles, tools, dependency closure and environment readiness |
| Content cache | Verified immutable reuse, acquisition, deletion and retention |
| Trusted policy | Requests, grants and admission authority |
| Engine | Scheduler, dispatcher, supervisor and job lifecycle |
| Execution backends | Platform and enforced isolation mechanisms |
| Observability | Scoped logs/metrics, device pressure and contention |
| Evidence | Results, artifact identity and optional attestations |
| Integrations | Optional publication/hosted reuse and external dependencies |
| Configuration | Repo/global settings, pins and metadata proposals |
| Security model | Threat model, invariants and residual risks |
| CLI | Actual scaffold behavior and open interface |
| Roadmap | Delivery gates |
| Checklist | Implemented behavior with evidence |
| Testing context | Reading routes for strategy, evidence and current commands |
| Testing plan | Development and compatibility test strategy |
| Coverage index | Observed evidence and pending tests |
| Testing WSR | Exact current commands and fixture conventions |
| Template migration | Tooling provenance and recovery rules |
| Crates | Source inventory, maintenance dispositions and publication constraints |
Completed records are grouped in the archive; paused worker contracts and checkpoints remain under implementation for saved external prompts. They are not active specifications or permission to execute historical next-action commands.
| Record | Status and authority |
|---|---|
| CLI skeleton plan | Completed implementation record; the CLI guide owns current behavior. |
| Design refactor record | Historical audit and completed documentation separation; current contracts live in the ownership map above. |
| Java worker | Paused worker contract; explicit resumption is required before implementation. |
| Java progress | Dated preparation evidence; its current checkpoint supersedes historical next actions. Machine-local artifacts are not clean-clone inputs. |
Java, Python and Node show simulated target experiences. Their adjacent YAML files remain reference inputs outside .github/workflows. Their A/B choices require decisions before implementation. Shared contracts above override illustrative logs/paths.
Maintain one owner for each contract. PLAN records authority and status; detailed guides own the explanation. Preserve historical test/prototype evidence instead of relabelling it as implementation. When a decision changes, reconcile overview, subsystem, security, tests and affected walkthroughs. Organization summaries should link to this design without introducing separate runtime commitments.
For cleanup, classify content as active, planned, historical, superseded or an archive candidate. Age or lack of implementation alone does not invalidate an accepted design. Preserve decisions, licenses, release history, native-reference evidence, migration backups and the prototype stash. Label historical records and remove them from active guidance before considering relocation; any later move must repair incoming links and preserve provenance. Do not duplicate subsystem contracts in a new cleanup roadmap. Package dispositions live in the crate inventory.
Layout and consolidation plan records canonical locations, compatibility entry points, preserved local guides and the old-to-new mapping.