Status: historical audit and completed documentation-refactor record. The current disposition and validation record below preserve the outcome. Earlier findings and proposed sequences are not a new work queue or authority over PLAN.md and the subsystem guides.
flowchart LR
A[Audit] --> O[Assign document owners]
O --> R[Reconcile decisions]
R --> V[Reader and diagram checks]
Reviewed November 5, 2026. The owner subsequently authorized the documentation refactor. The existing dirty documentation and prototype stash are preserved. This plan proposes document ownership and sequencing, not production interfaces, new crates, a selected backend or implemented capabilities.
At the pre-refactor audit, the documentation was partially aligned. ARCHITECTURE.md already separates provider compilation, planning/policy, provisioning, supervision, backends and results. D-012 ends provider callbacks at compilation; D-016 owns state/lifecycle; D-025 requires tool preflight; D-026 separates repository observability from shared resource measurements. These boundaries should be retained.
The latest owner direction is independent local execution with an offline-capable core, on-demand verified tools, shared immutable caches and deny-by-default enforcement. Optional GitHub communication and attestations follow execution. These refinements require formal decision updates before describing them as settled interfaces or security guarantees.
| Finding | Evidence | Refactor action |
|---|---|---|
| Provisioning lacks a subsystem owner | D-025 and docs/engine/README.md contain the contract; no runners/provisioning guide exists | Extract provisioning ownership and link engine responsibilities to it |
| Validation has several meanings | Provider diagnostics, planner admission, artifact verification and TESTING-PLAN coexist | Name each validation stage and its authority; keep development tests separate |
| Scheduler/dispatcher contract is open | PLAN decision queue item 16; engine guide combines broad responsibilities | Document ready/blocked jobs, device admission, dispatch and supervisor ownership separately |
| New concurrency proposal is absent | No saved max-jobs configuration contract | Formalize owner preference max-jobs=0, admission checks, queue reasons; leave exact schema and fairness open |
| Independent execution is underspecified | D-017 and docs/sync prioritize running inside GHA, then independent CI | Distinguish independent local engine from remote CI hosting; revise delivery language around offline-first core |
| Bootstrap/acquisition policy needs reconciliation | D-010 allows provider download during repository commands; D-025 requires missing tool acquisition | Define preparation versus offline execution, missing-object diagnostics and explicitly enabled acquisition |
| Evidence/signing lacks an owner | Architecture has results/evidence, but no attestation contract | Add evidence boundary; keep signing trust and optional publication separate |
| Cross-repository telemetry is documented, coordination is not | D-026 and observability diagrams anticipate a coordinator | Specify emitted lifecycle/resource events without assuming daemon implementation |
| Profiles and repository metadata remain conversational proposals | Configuration schema remains open in D-023 | Track runner/tool catalogs, custom profiles, lockfile and .wsr layout as proposals |
| DX guides and worker contract can drift | Simulated Java/Python/Node guides; Java worker still prioritizes Docker native reference | Reconcile scenarios and future worker instructions after the architectural decisions are recorded |
Paths marked new are planned destinations, not existing specifications.
| Document | Owns | Boundary |
|---|---|---|
| PLAN.md | Decisions, unresolved questions, dependency order | Links to detailed subsystem contracts |
| ARCHITECTURE.md | Whole-system map, authority boundaries, lifecycle | Overview rather than duplicated schemas |
| docs/provider/README.md and crate GHA docs | Source syntax, expression lowering, provenance and compatibility | No workload execution or global scheduling |
| docs/planning/README.md (new) | Canonical validation, input binding, graph/matrix evaluation and requirements | Dynamic expressions evaluated at the appropriate lifecycle phase |
| docs/provisioning/README.md (new) | Runner profiles, package resolution, dependency closure, acquisition and environment assembly | Consumes authorized acquisition policy; no repository fairness decisions |
| docs/cache/README.md (new) | Immutable content identities, trust states, atomic publication, leases and retention | Separate secrets and mutable run state |
| docs/policy/README.md (new) | Trusted grants and admission rules | Repositories request authority; backends enforce granted access |
| docs/engine/README.md | Scheduling, device admission, dispatch, supervisor state and job outcomes | Separate scheduler/dispatcher sections before considering more files |
| docs/sandbox/README.md | Backend capabilities, platform matching, isolation and lifecycle enforcement | Docker/VM/Wasm selection remains a separate decision |
| docs/evidence/README.md (new) | Result identity, artifact digests, provenance and proposed attestations | Signing claims requires explicit trust/verification policy |
| docs/observability/README.md | Event correlation, logs, attributed resources, visibility and retention | Metrics are observations, not automatically evidence of truthful workload results |
| docs/sync/README.md | Optional GitHub/other connectors, publication queue and retries | Core execution cannot depend on external reporting availability |
| docs/config/README.md | Repo config, trusted global config, pinning and metadata ownership | Define precedence and separate requests from grants |
| docs/TESTING-PLAN.md and TEST-COVERAGE.md | Test strategy and observed evidence respectively | Planned tests remain distinct from passing coverage |
These are conceptual responsibilities. Their exact APIs and persisted schemas require later design. Static parsing cannot enumerate arbitrary dynamic commands; D-025 discovery limits must survive refactoring. Existing setup actions must retain their timing, requested versions and effects.
The architecture overview should show source/input compilation, planning/admission, provisioned requirements, ready-job scheduling, dispatch, supervised execution, result collection and optional publication. Policy and observability cross these stages. Cached offline inputs must suffice for execution; external-service calls explicitly requested by a workload remain external dependencies.
Define conceptual handoffs before coding: compiled model plus diagnostics; requirements and pins; prepared environment identity and capabilities; eligible job and resource budget; supervisor state/events; immutable result/evidence bundle. Do not freeze these as Rust structs in this refactor.
For provisioning versus scheduling, choose whether downloads occur before resource reservation or use separate bounded preparation capacity. Avoid reserving scarce execution resources during long downloads without an explicit rule. Dispatch must handle preparation failure and cancellation.
For background operation, decide foreground ownership versus optional shared coordinator, local client authentication, persistence/reconnect, fairness and crash reconciliation. The owner’s global job-count preference is 0 for no count cap; hardware capacity and policy admission remain effective.
Each responsibility has one owning specification; overview/index docs link to it. Every handoff has inputs, outputs, failure/cancellation behavior and an authority boundary. Known contradictions are resolved or explicitly recorded. Offline acquisition rules, cache isolation, runner identity, GHA setup semantics and dynamic state are consistently described. Scheduling and provisioning can be designed independently against the agreed handoff. Existing source remains scaffold until behavioral implementation/tests justify a status change.
Implemented the documentation ownership map with planning, provisioning, cache, policy and evidence guides. Rewrote engine/config/integrations and the architecture/index. Refined D-017 and added D-027–D-030 to distinguish cached local execution, scheduling count policy, metadata proposals and optional attestations. D-025/D-026 and prior security/provider decisions remain traceable.
Reconciled roadmap/checklist, CLI, security, provider/backend guides, GHA contracts and walkthrough scope. Added small Mermaid diagrams across the active design guides. Historical reference results remain historical. No product runtime, scheduler, catalog schema, attestation format, or new CLI command was implemented. The daemon, fairness, state persistence and provisioning APIs remain open.
The saved automation prompt is outside this documentation refactor. Review it separately before resuming implementation because it retains earlier native-reference priorities. Organization summaries are synchronized only for product-direction wording, with profile/template agreement.
Validation results are recorded in the final handoff. Runtime behavioral claims require their own TDD evidence. This record is completion of document separation, not completion of open designs.
| Original finding | Disposition after PR #17 |
|---|---|
| Provisioning ownership | Resolved by the provisioning guide |
| Validation meanings | Separated by the planning guide |
| Scheduler/dispatcher | Responsibilities separated; mechanisms remain open |
| Concurrency preference | Recorded in D-028; schema/fairness remain open |
| Independent execution | Refined in D-017/D-027 and integration guide |
| Acquisition rules | Recorded in D-027 and cache/provisioning guides |
| Evidence ownership | Added evidence guide and D-030; formats/trust remain open |
| Telemetry coordination | Cross-subsystem ownership documented; daemon remains open |
| Profiles and metadata | D-029/configuration preserve schema proposals explicitly |
| DX/worker drift | Follow-up audit corrects platform/preflight examples and current handoff |
The follow-up cleanup is a documentation correction. It supplies no runtime implementation. Companion organization-summary publication has a separate repository/PR lifecycle; local synchronization alone does not establish that GitHub’s organization profile was updated.
Offline cargo xtask ci passed after the documentation refactor. All 38 Mermaid diagrams parsed and rendered with Mermaid in headless Chrome; representative overview, provisioning, engine and evidence diagrams were visually inspected. Local relative links/anchors passed across 37 Markdown files. git diff –check passed in WSR and the companion organization-summary checkout. A fresh reader review resolved preflight/output-dependent requirements and optional unsigned publication. Ignored validation artifacts are under target/wsr-tests/design-refactor-20261105.