Pre-implementation readiness report
Executive assessment
Current assessment: documentation integrity is healthy, but implementation readiness still requires a substantive review of the normative specifications and docs/roadmap.md.
The evidence collected so far confirms that:
- The project documentation correctly references docs/roadmap.md.
- The HTTPS documentation endpoint is accessible when the self-signed certificate is accepted.
- Canonical table verification passes.
- Markdown linting passes.
- All 101 checked documentation links pass.
- Generated Markdown content matches the canonical YAML tables.
These results establish structural consistency. They do not, by themselves, prove that the normative design is sufficiently complete and unambiguous for implementation.
The implementation-readiness decision should be based principally on:
- ARCHITECTURE.md
- docs/control-plane.md
- docs/work-graph.md
- docs/integration-and-conflicts.md
- docs/budgets.md
- docs/executors.md
- docs/validation.md
- docs/experiment.md
- docs/roadmap.md
- docs/glossary.md
- docs/event-catalogue.md
- The canonical definitions under docs/tables/
Confirmed readiness findings
Documentation references are correct
The earlier request for root-level ROADMAP.md resulted from an incorrect path supplied during the review. It is not a repository defect.
The project correctly identifies the roadmap as:
docs/roadmap.md
No corrective action is required for roadmap references.
Documentation checks pass
The canonical documentation check completed successfully:
- Table formatting was checked.
- Generated-table verification passed.
- Markdown linting passed.
- Documentation-link validation checked 101 links, including 56 unique links, with no errors.
This means there is no currently observed blocker from broken links, Markdown-policy violations, or drift between generated tables and their YAML sources.
Canonical table ownership is explicit
The project clearly establishes docs/tables/*.yaml as the source of truth for:
- State machines
- Policy-completeness rows
- Run outcomes
- Experiment limits
Generated sections in docs/control-plane.md and docs/experiment.md must not be edited manually. Changes must be made in the relevant YAML files and regenerated with:
.venv/bin/python scripts/tables.py --write
The full validation command is:
scripts/check-docs
Correction to the earlier review command
The earlier review attempted:
.venv/bin/python scripts/tables.py --check
The script does not support --check. Verification is performed by running it without --write, or through the canonical documentation check:
.venv/bin/python scripts/tables.py
scripts/check-docs
This was an error in the review procedure. There is no evidence that the repository documentation or CI instructs contributors to use the unsupported option.
MUST be resolved or verified before implementation
The following are implementation gates. Based on the evidence retrieved so far, they should be treated as matters requiring verification against the normative corpus, not as confirmed defects.
1. Roadmap milestones must have objective acceptance criteria
Every MVP milestone in docs/roadmap.md must identify:
- The normative requirements it implements
- Observable completion criteria
- Required tests or conformance cases
- Dependencies on earlier milestones
- Explicit exclusions and deferred functionality
- The artefacts expected from the milestone
Broad statements such as “implement the reducer”, “support crash recovery”, or “add executor integration” are not sufficient unless they reference precise behaviours, transitions, events, invariants, and evidence.
Required outcome: every implementation milestone can be judged complete without relying on subjective interpretation.
2. The deterministic control-plane boundary must be unambiguous
Before implementing the reducer, docs/control-plane.md must define:
- The reducer input
- The reducer output
- How commands or effects are represented
- Handling of invalid events
- Handling of duplicate events
- Behaviour in terminal states
- Ordering assumptions
- Wildcard-transition precedence
- Whether time, randomness, provider state, or environment state can influence reduction
The reducer should not directly execute external side effects. It should produce explicit commands or effects whose execution and acknowledgement are represented in durable state.
Required outcome: replaying the same ordered events from the same initial state always produces the same state and effects.
3. Event coverage must be complete
Every event used in a transition must have a complete entry in docs/event-catalogue.md, including:
- Emitter
- Affected state machine
- Payload schema
- Required identifiers
- Correlation and causation information
- Replay behaviour
- Deduplication identity
- Compatibility or versioning expectations
Every event must also have:
- A transition-table entry
- A positive conformance case
- Invalid-state coverage where relevant
- Invalid-payload coverage where relevant
Required outcome: no state change depends on an undocumented, ambiguous, or unreplayable event.
4. State-machine completeness must be demonstrated
The canonical YAML definitions must explicitly identify:
- Initial states
- Terminal states
- Legal transitions
- Wildcard transitions
- Cancellation paths
- Failure paths
- Retry paths
- Recovery paths
- Unsupported-event behaviour
Automated checks should detect:
- Undefined states or events
- Unreachable states
- Non-terminal states with no valid exit
- Inappropriate transitions from terminal states
- Events with no valid consumer
- Ambiguity between explicit and wildcard transitions
Required outcome: every machine is mechanically verifiable as internally consistent and behaviourally complete for the MVP.
5. Persistence and replay semantics must be settled
The normative design must specify:
- Event append atomicity
- Event ordering scope
- Optimistic concurrency or equivalent state ownership
- Deduplication rules
- Idempotency requirements
- Snapshot creation and invalidation
- Snapshot relationship to the event log
- Recovery from partially processed work
- Behaviour when an event is stored but its external effect is interrupted
- Behaviour when an external effect succeeds but its acknowledgement is not stored
Required outcome: process interruption at any persistence or dispatch boundary has a deterministic recovery path.
6. Side-effect delivery semantics must be explicit
Every executor-facing operation must declare whether delivery is:
- At most once
- At least once
- Effectively once through idempotency
Executor contracts must define:
- Invocation identity
- Input and output schemas
- Timeout semantics
- Cancellation semantics
- Retry classification
- Evidence requirements
- Artefact ownership
- Log handling
- Secret handling
Required outcome: retries cannot silently duplicate repository changes, deployments, model calls, or other external actions.
7. Concurrent ownership and fencing must be defined
Because the project supports parallel execution, it must establish:
- Who owns a runnable node
- How ownership is acquired
- How ownership expires
- Whether leases are used
- Whether fencing tokens are required
- How duplicate workers are prevented from committing results
- How graph updates are serialised
- How concurrent budget reservations are handled
Required outcome: two workers cannot both believe they have authority to complete or mutate the same logical work.
8. Work-graph mutation rules must be closed
docs/work-graph.md must define:
- Node identity
- Node mutability
- Dependency-cycle prevention
- Readiness calculation
- Graph-version semantics
- Decomposition ownership
- Replanning effects on queued work
- Replanning effects on active work
- Cancellation propagation
- Replacement and supersession relationships
- Acceptance-criteria inheritance
- Treatment of completed work after replanning
Required outcome: graph decomposition and replanning produce deterministic results without invalidating active work unpredictably.
9. Budget accounting must be safe under concurrency and replay
docs/budgets.md must settle:
- Reservation versus actual consumption
- Hierarchical budget propagation
- Concurrent reservation conflicts
- Reservation release and refund rules
- Failed-attempt accounting
- Retry accounting
- Delayed or unknown provider costs
- Mid-operation exhaustion
- Replay of ledger operations
Required outcome: budget limits remain enforceable under retries, concurrent workers, delayed cost reporting, and process recovery.
10. Repository integration must have an authoritative owner
docs/integration-and-conflicts.md must define:
- Integration ownership
- Workspace or worktree isolation
- Base revision pinning
- Merge or rebase policy
- Conflict classification
- Validation after integration
- Treatment of unrelated concurrent changes
- Commit and branch ownership
- Recovery after partial integration failure
Required outcome: parallel agents cannot independently integrate overlapping work into shared repository state.
11. Validation evidence must be binding and reproducible
docs/validation.md must define:
- Evidence schema
- Evidence provenance
- Binding to source revision
- Binding to produced artefacts
- Binding to the executor attempt
- Validation freshness
- Independent-evaluator requirements
- Acceptance thresholds
- Missing or invalid evidence behaviour
- Cached-evidence reuse
- Representation of nondeterministic tests
Required outcome: acceptance decisions can be reproduced and are demonstrably based on the exact implementation being accepted.
12. Trust boundaries and sandbox guarantees must be implementable
Before executor implementation, the specification must identify:
- Untrusted inputs
- Filesystem boundaries
- Network policy
- Process limits
- Resource limits
- Secret-exposure policy
- Command-approval policy
- Path-traversal protections
- Symbolic-link handling
- Artefact-extraction safety
- Log and error redaction
- Cleanup after cancellation or worker termination
Required outcome: executor isolation is a concrete enforceable contract, not only an architectural intention.
13. Run termination must have one authoritative outcome
The control-plane and glossary definitions must establish:
- Which component decides the final run outcome
- Whether terminal node states imply a run outcome
- Precedence among cancellation, policy rejection, budget exhaustion, validation failure, and infrastructure failure
- Whether a terminated run can resume
- Treatment of late executor responses
- Treatment of late validation or integration results
Required outcome: the system cannot expose conflicting final outcomes for the same run.
14. Schema evolution must be defined before persistent formats stabilise
At minimum, the baseline must include:
- Schema-version fields
- Unknown-event handling
- Unknown-enum handling
- Migration ownership
- Upgrade compatibility expectations
- Replay compatibility across versions
- Policy for changes to historical semantics
Required outcome: the initial implementation does not accidentally make persistent formats impossible to evolve safely.
15. Policy decisions must be replayable
If policy decisions affect scheduling, executor selection, approval, cancellation, or acceptance, the design must state:
- Whether the decision or only its result is persisted
- Which policy version produced it
- Which inputs were evaluated
- Whether replay re-evaluates or reuses the historical decision
- How policy changes affect active runs
Required outcome: replay cannot produce a different run history merely because the current policy differs from the policy used originally.
SHOULD be resolved before implementation
These items are not necessarily hard blockers, but resolving them before implementation would substantially reduce design drift and rework.
1. Add stable requirement identifiers
Each normative requirement should have a durable identifier that maps to:
- A roadmap milestone
- An architectural invariant
- A state-machine transition
- An event definition
- A conformance test
- An implementation module
This would make omissions, changes, and compliance decisions easier to audit.
2. Create a roadmap traceability matrix
A traceability matrix should connect each MVP deliverable to:
- Normative requirements
- Events
- State transitions
- Policy decisions
- Persistence requirements
- Tests
- Deferred scope
This is particularly valuable for a documentation-first system whose implementation must conform to multiple normative files.
3. Start with a narrow end-to-end vertical slice
The first implementation milestone should demonstrate one complete path:
1. Create a run.
2. Persist the initial event.
3. Add one simple work node.
4. Reserve a budget.
5. Select one deterministic executor.
6. Execute the node.
7. Record the result and evidence.
8. Validate the result.
9. Integrate the result.
10. Terminate the run.
11. Replay the event history to the same final state.
12. Repeat with interruption at critical boundaries.
This provides stronger architectural validation than implementing every subsystem horizontally.
4. Add executable examples for every state machine
Examples should cover:
- Successful execution
- Validation rejection
- Retryable failure
- Permanent failure
- User cancellation
- Budget exhaustion
- Worker termination
- Duplicate delivery
- Late result
- Replanning during active execution
Examples should use identifiers defined in docs/glossary.md and events defined in docs/event-catalogue.md.
5. Define observability fields early
Events, logs, traces, and metrics should consistently carry appropriate identifiers, including:
- Run ID
- Graph version
- Node ID
- Attempt ID
- Event ID
- Correlation ID
- Causation ID
- Executor ID
- Policy-decision ID
- Evidence ID
Adding these after persistence and executor interfaces stabilise would be costly.
6. Make MVP non-goals explicit
The roadmap should clearly identify deferred capabilities, potentially including:
- Multi-region operation
- Live worker migration
- Arbitrary third-party executor plug-ins
- Cross-repository transactions
- Automatic resolution of every semantic conflict
- Strong exactly-once external execution
- Dynamic policy-language extensibility
Explicit non-goals protect the MVP boundary and prevent informative examples from being interpreted as normative commitments.
7. Define operator intervention points
The design should state when a run:
- Continues automatically
- Pauses for approval
- Requires conflict resolution
- Requires credential renewal
- Requires policy override
- Must terminate
Operator actions should be represented by auditable events rather than out-of-band state mutation.
8. Add fault-injection coverage to the harness
The conformance harness should test interruption:
- Before event append
- After event append
- Before effect dispatch
- After effect dispatch
- After effect success
- Before acknowledgement persistence
- During validation
- During integration
- During budget settlement
- During snapshot creation
These tests directly exercise the project’s replay and recovery claims.
9. Define reference implementations for clocks and identifiers
The specification should recommend or define:
- Monotonic versus wall-clock usage
- Timestamp precision
- Identifier generation
- Ordering when timestamps are equal
- Test-clock injection
- Treatment of clock skew
This would help keep the reducer deterministic and tests reproducible.
10. Define error classification centrally
A shared error taxonomy should distinguish:
- User or specification errors
- Policy rejection
- Retryable infrastructure failure
- Permanent executor failure
- Validation failure
- Integration conflict
- Budget failure
- Internal invariant violation
The taxonomy should map directly to retry, cancellation, replanning, and run-outcome behaviour.
Recommended implementation gate
Implementation should begin only when the following conditions are satisfied:
- scripts/check-docs passes.
- .venv/bin/python scripts/tables.py passes.
- Every MVP milestone in docs/roadmap.md has measurable acceptance criteria.
- Every roadmap milestone traces to normative requirements.
- Every transition references catalogued states and events.
- Every event defines its payload, emitter, replay behaviour, ordering assumptions, and deduplication identity.
- Reducer behaviour is deterministic.
- Unsupported-event and duplicate-event behaviour is specified.
- Persistence crash boundaries are defined.
- External-effect delivery and recovery semantics are defined.
- Executor cancellation, timeout, retry, and idempotency rules are defined.
- Concurrent ownership and fencing rules are unambiguous.
- Work-graph mutation and replanning semantics are closed.
- Budget accounting remains correct under concurrency and replay.
- Validation evidence is bound to source, artefacts, and executor attempts.
- Run-outcome precedence is authoritative.
- Persistent schemas have an evolution strategy.
- At least one end-to-end scenario, including interruption and replay, can be expressed as a conformance test.
Overall conclusion
The project’s documentation mechanics are in good condition. There is no observed generated-table drift, Markdown failure, broken documentation link, or incorrect roadmap reference.
The previous roadmap-path finding should be discarded entirely. The unsupported --check invocation should likewise be recorded only as a correction to the earlier review method, not as a repository issue.
The project should not yet be declared implementation-ready solely from the successful structural checks. Readiness depends on confirming that the normative documents resolve the MUST items above, particularly:
- Reducer determinism
- Persistence and replay
- Side-effect idempotency
- Concurrent ownership
- Work-graph mutation
- Budget atomicity
- Validation evidence binding
- Run-outcome precedence
- Schema evolution
- Roadmap acceptance criteria
If those matters are already fully and consistently specified in the normative corpus, implementation can proceed according to docs/roadmap.md. If any remain ambiguous, they should be resolved before implementation because later changes would affect persistent data, externally visible behaviour, or core control-plane semantics.