<!-- informative -->

# Research Analysis and Implementation Readiness Report

## Scope

This report reviews:

- `README.md` and every document directly linked from its document map and reading order;
- all files in `docs/research/`;
- the canonical definitions in `docs/tables/*.yaml`;
- the documentation and regression tooling used by the repository.

The README identifies the normative corpus as `ARCHITECTURE.md`, the control plane, work graph, integration and conflicts, budgets, executors, validation, experiment procedure, roadmap, deferred design, glossary, event catalogue, and canonical tables (`README.md:17-33`). The research corpus consists of:

- `docs/research/pre-implementation.txt`;
- `docs/research/alternatives.txt`;
- `docs/research/user-workflow.md`.

Validation performed for this review:

- `scripts/check-docs` passed, including generated-table verification, Markdown linting, and 101 documentation links with no errors;
- `scripts/tables.py` passed;
- `pytest -q` passed all 14 repository tests.

The repository contains documentation, table-generation tooling, documentation checks, and regression tests, but no production controller, executor, or persistence implementation was found.

## Executive conclusion

**Do not start implementation yet.** The documentation is structurally healthy, but it is not yet an implementation-ready specification. The strongest foundation is the deterministic control-plane model, independent state machines, event-backed mutations, versioned evidence, hierarchical budgets, and isolated repository integration. The main blockers are not broken links or table drift; they are missing or incomplete semantic contracts around the reducer, events, persistence and recovery, schema evolution, run-outcome precedence, user interaction, and conformance testing.

The roadmap also needs to change before coding starts. Its 32 steps are a useful sequence, but they are not independently testable milestones: they do not consistently provide observable acceptance criteria, normative traceability, dependencies, required tests, or explicit exclusions (`docs/roadmap.md:85-123`).

## Findings from the research documents

### 1. `docs/research/pre-implementation.txt`

This is the principal readiness assessment. Its central conclusion is that documentation mechanics are healthy but do not prove normative completeness (`docs/research/pre-implementation.txt:1-24`). It identifies 15 MUST items and 10 SHOULD items, then gives a recommended implementation gate (`docs/research/pre-implementation.txt:55-249`, `250-363`, `364-398`).

The most important findings are:

- Roadmap milestones need objective acceptance criteria and traceability.
- The reducer must have an explicit input, output, effect, ordering, duplicate-event, terminal-state, and wildcard-transition contract.
- Every event needs a complete payload, authority, replay, deduplication, and compatibility definition.
- State-machine completeness must be demonstrated beyond the current structural checks.
- Persistence, snapshots, partial writes, external-effect acknowledgement, and recovery boundaries must be deterministic.
- Executor delivery semantics, concurrent ownership, fencing, graph mutation, budget atomicity, evidence binding, run-outcome precedence, schema evolution, and replayable policy decisions must be settled.
- A narrow end-to-end vertical slice is preferable to implementing every subsystem horizontally (`docs/research/pre-implementation.txt:271-285`).

The report also correctly records that `scripts/tables.py --check` is not a supported command; the canonical checks are `scripts/tables.py` and `scripts/check-docs` (`docs/research/pre-implementation.txt:48-54`). This review confirmed that the repository itself uses the supported commands.

### 2. `docs/research/alternatives.txt`

This document recommends continuing the project as a deterministic governance and integration control plane rather than building another agent framework or workflow engine. It proposes retaining the project-specific reducer, event semantics, work graph, budgets, validation, integration, conflicts, and conformance harness while sourcing mature commodity subsystems (`docs/research/alternatives.txt:1-10`, `108-140`, `287-298`).

Its preferred direction is:

- PostgreSQL as the authoritative event, graph, attempt, and evidence ledger;
- a deterministic control-plane service;
- Temporal only as a candidate durable activity-dispatch layer;
- OpenHands, Aider, or SWE-agent behind the executor protocol;
- Podman or Kubernetes with stronger isolation where required;
- OPA for policy evaluation;
- OpenTelemetry for observability;
- Git worktrees for repository isolation.

The key architectural warning is sound: Temporal must not become a second normative state authority. The orchestrator should emit commands, Temporal should execute or schedule those commands, and the orchestrator reducer should admit immutable results and determine normative state (`docs/research/alternatives.txt:61-79`, `190-213`). The document appropriately requires a focused Temporal compatibility spike before committing to it, including worker termination, duplicate delivery, cancellation races, controller restart, late superseded results, schema upgrades, and ledger reconciliation (`docs/research/alternatives.txt:255-272`). If that boundary proves awkward, the documented fallback is a PostgreSQL transactional outbox with leased workers.

The alternatives memo is not a procurement decision. It explicitly says its licence and capability information was not live-verified and must be rechecked (`docs/research/alternatives.txt:11`). It is also truncated at the end (`docs/research/alternatives.txt:299`). Its stack recommendations should therefore be treated as hypotheses until the compatibility, licensing, security, and operational gates are completed.

### 3. `docs/research/user-workflow.md`

This document identifies a real product-contract gap: the normative corpus explains internal mechanics but not how a user starts, monitors, intervenes in, or consumes a run (`docs/research/user-workflow.md:15-30`). It recommends writing `docs/user-workflows.md` before implementation and evolving it alongside the system (`docs/research/user-workflow.md:3-12`, `85-122`).

The proposed workflows are:

1. Starting from scratch: provide a project kernel, define the root contract and budgets, start the run, observe progress, intervene where policy requires, and retrieve accepted artefacts and evidence.
2. Working on an existing project: identify the repository and base revision, define the change and acceptance criteria, declare scopes and integration dependencies, handle conflicts or replanning, and retrieve the integrated result.

The document also identifies missing user-facing schemas for the project kernel, run configuration, progress stream, result artefacts, intervention, and failure diagnosis. These gaps affect implementation because they determine API and event contracts before persistent formats stabilize.

Correction added during review: an earlier version of this report claimed that `docs/research/user-workflow.md:52` refers to `docs/research/pre-implementation.md`. No such reference exists; line 52 is a policy-configuration table row.

## Cross-document assessment

### Confirmed strengths

The normative corpus has several strong properties:

- The control plane is explicitly the sole authority for admission, ordering, graph mutation, scheduling, budgets, evidence policy, acceptance, publication, replay, and recovery (`ARCHITECTURE.md:68-101`, `docs/control-plane.md:10-30`).
- Mutations are event-backed, globally sequenced, transactionally persisted, and replayed without invoking external systems (`docs/control-plane.md:32-103`, `115-140`).
- Node, attempt, artefact, accounting, and freshness dimensions are separate, with canonical YAML definitions and generated Markdown (`docs/control-plane.md:142-148`, `docs/tables/`).
- Executor outputs are untrusted observations; self-reported success is never acceptance evidence (`docs/executors.md:64-91`, `131-164`, `docs/validation.md:40-52`).
- Budget reservations, commitments, actual consumption, reclamation, and ancestor accounting have a no-overcommitment invariant (`docs/budgets.md:18-47`, `71-139`).
- Repository work is isolated in disposable worktrees, checked against owned scopes, integrated by an owner, validated, and published as immutable versions (`docs/integration-and-conflicts.md:45-136`, `docs/executors.md:170-200`).
- Acceptance is bound to contract, input, artefact, validator, policy, environment, and authority versions (`docs/validation.md:54-99`).
- The experiment procedure defines a meaningful four-arm comparison and prohibits measured trials until deterministic conformance suites pass (`docs/experiment.md:5-56`, `205-229`).

### Blocking or incomplete areas

| Area | Assessment | Required resolution |
|---|---|---|
| Roadmap readiness | The 32 steps lack consistent acceptance criteria, dependencies, tests, and traceability. | Add a milestone matrix and measurable completion gates before coding. |
| Reducer contract | The flow and replay promise are clear, but there is no formal reducer signature, explicit command/effect representation, or wildcard precedence rule. | Define `reducer(state, event) -> (state, effects)` and all unsupported/ambiguous-input behaviour. |
| Event catalogue | Events are listed, but per-event payload schemas, required identifiers, replay behaviour, deduplication identity, and compatibility rules are incomplete. | Expand the catalogue or link each event to a versioned schema and conformance case. |
| Persistence and recovery | Crash recovery is described, but snapshot creation/invalidation, partial persistence, and effect-success/acknowledgement gaps are not fully specified. | Define persistence boundaries and deterministic reconciliation for each gap. |
| Delivery and concurrency | Dispatch-before-send and attempt tokens are specified, but the delivery class and multi-worker ownership/fencing model are not explicit. | Declare effective-once/idempotency semantics and either specify the single-process MVP boundary or add leases and fencing. |
| Work graph and replanning | The mutation protocol and decomposition checks are comparatively detailed, but active-work invalidation and replanning examples are not executable yet. | Add normative examples and conformance cases for queued, reserved, running, and completed work. |
| Budgets | The accounting model is strong, but wall-clock accounting, delayed provider costs, and replay behaviour need concrete implementation tests. | Bind budget policies to ledger events and fault-injection cases. |
| Run outcomes | Terminal root states map to outcomes, but precedence among simultaneous cancellation, budget, validation, conflict, and infrastructure conditions is absent. | Add one authoritative outcome-resolution rule. |
| Schema and policy evolution | Version fields exist, but migration ownership, unknown events/enums, and replay compatibility are deferred without a baseline policy. | Resolve the minimum evolution contract before persistent formats stabilize. |
| User workflow | No user workflow document or project-kernel/run/result schema exists. | Write the workflow contract before defining public APIs or persistent input records. |
| Conformance | Existing tests cover table/regression behaviour, not the experiment's required end-to-end, recovery, isolation, and replay suites. | Implement the conformance harness before measured trials. |
| Third-party stack | Temporal and executor choices are recommendations, not validated decisions. | Run the Temporal spike or choose the outbox fallback, and complete licence/security checks. |

The most important distinction is that the current table verifier proves structural consistency, not behavioural completeness. It checks generated Markdown, event/state catalogue alignment, terminal-state reopening, and transition incidence rather than reachability from creation, but it does not prove that guards are implementable, that replay is deterministic for all crash boundaries, or that a user-visible workflow is complete.

## Recommendation before implementation

Implementation should remain blocked until the following gates are closed:

1. **Define the MVP user contract.** Write `docs/user-workflows.md`; define the project-kernel, run-configuration, progress, intervention, result, evidence, and failure-diagnosis schemas. Decide whether the first MVP is an operator/harness interface, a CLI, or both.
2. **Make the roadmap executable.** Add acceptance criteria, normative references, dependencies, required tests, artefacts, and exclusions to every roadmap step. Add a traceability matrix linking requirements to transitions, events, policies, persistence records, tests, and deferred scope.
3. **Formalize the reducer and effects.** Specify the reducer signature, deterministic input ordering, output/effect representation, unsupported-event handling, unknown-schema handling, wildcard precedence, and the rule that replay never re-executes side effects.
4. **Complete event semantics.** Give every event a versioned payload schema, required identifiers, authority, correlation/causation, idempotency key, replay behaviour, and compatibility rule. Apply the repository rule that a new event requires a catalogue entry, transition entry, and conformance case.
5. **Close persistence and recovery boundaries.** Define append atomicity, snapshot policy, optimistic concurrency ownership, partial-write recovery, effect dispatch/acknowledgement gaps, conservative cost settlement, and reconciliation between any durable dispatch system and PostgreSQL.
6. **Settle execution-substrate scope.** Either complete the Temporal compatibility spike or explicitly select the PostgreSQL transactional-outbox and leased-worker fallback for the MVP. Do not encode the normative state machine directly as a Temporal workflow.
7. **Declare concurrency semantics.** State that the first implementation is single-process with serialized admission if that is the intended boundary; otherwise specify leases, expiry, fencing tokens, duplicate-worker prevention, and graph-update serialization.
8. **Define run-outcome precedence.** Add a single deterministic rule for simultaneous terminal conditions and late results.
9. **Resolve minimum schema evolution.** Define schema-version fields, unknown-event and unknown-enum handling, migration ownership, replay compatibility, and how historical policy decisions remain reproducible.
10. **Build the conformance harness.** Start with one narrow vertical slice: create a run, persist the initial event, add one node, reserve a budget, dispatch one deterministic executor, record a result, validate it, integrate it, terminate the run, replay the event stream, and inject interruptions at persistence and dispatch boundaries.
11. **Complete security and licensing gates.** Add the repository licence, verify third-party licences and exact versions, and test the sandbox, credential, network, path, symlink, artefact-extraction, log-redaction, and cleanup contracts before allowing untrusted executors.

## Roadmap changes required

The existing roadmap should be revised before step 01 is treated as implementation work:

- Add a phase for user-workflow and public schema definition before schema implementation.
- Add a phase for normative closure: reducer contract, event catalogue, persistence, outcome precedence, schema evolution, and concurrency scope.
- Add a phase for the Temporal-versus-outbox decision and its proof tests.
- Split the current horizontal steps into observable milestones with dependencies and exclusions.
- Add explicit conformance milestones for transition completeness, replay equivalence, crash injection, sandbox isolation, accounting settlement, and oracle calibration.
- Keep the existing pilot and four-arm experiment steps, but make manifest freeze and no-change-after-freeze an explicit gate.
- Add stable requirement identifiers or a traceability matrix so each milestone can be audited against the architecture, transitions, events, policies, tests, and deferred scope.

## Proposed implementation sequence after the gates pass

1. Implement versioned schemas and the append-only event store with deterministic ordering.
2. Implement the reducer and state machines before adding workers or external services.
3. Implement the ledger, timers, reservations, commitments, actuals, and reclamation atomically with events.
4. Implement the executor protocol, single-use attempt tokens, cancellation, timeout, and idempotent observation handling.
5. Implement the chosen dispatch substrate and recovery reconciliation.
6. Implement disposable worktrees, sandbox enforcement, diff-scope checks, and trusted integration.
7. Implement validation, evidence binding, freshness, conflict handling, and run-outcome resolution.
8. Implement replay and state/ledger equivalence tests before adding the reasoning-model adapter.
9. Add the narrow user-facing CLI or harness contract and the first end-to-end vertical slice.
10. Expand to decomposition, bounded fan-out, concurrent disjoint-scope execution, and the experiment arms only after the vertical slice is stable.

## Steps after implementation

Before any measured experiment:

- Run `scripts/check-docs`, `scripts/tables.py`, and the full test suite on every documentation or schema change.
- Pass transition-completeness, event/replay, attempt/accounting, recovery, isolation, and oracle-calibration suites.
- Verify that replay produces identical graph state, ledger state, artefacts, freshness, and terminal outcome without reinvoking executors or external services.
- Run crash injection before append, after append, before dispatch, after dispatch, after effect success, before acknowledgement, during validation, during integration, and during budget settlement.
- Run the unmeasured `DIRECT` and `FIXED_ONE_LEVEL` pilots, then the recursive and concurrent pilots.
- Calibrate the hidden oracle against known-good, unchanged, broken, timeout, and infrastructure-failure candidates.
- Freeze the experiment manifest, including target commit, kernel and contract hashes, environment digest, controller/reducer/policy/schema/tool/model versions, model parameters, budgets, hidden-suite hash, seed, and arm assignment.
- Run the four-arm measured comparison only after the manifest is frozen; report distributions, costs, false successes, unresolved runs, stale work, conflicts, and infrastructure errors.
- Reassess the roadmap and architecture using measured evidence, then decide whether to retain the outbox or adopt Temporal and additional executor/sandbox backends.

## Final recommendation

The project should continue, but the next work item is specification closure and conformance planning, not production implementation. The roadmap is a good skeleton, but it needs objective acceptance criteria and traceability; the alternatives research is a useful architectural hypothesis, not a committed stack; and the user-workflow research identifies a missing contract that should be resolved before persistent APIs are built. Once the gates above are closed, implementation should begin with the narrow replayable vertical slice rather than the full 32-step stack.
