# Architectural Plan Review (2026-03-31)

This note records durable review findings for the current architectural parity epic and story set.

Reason for storing here:

- the configured MCP resource list is empty in this session
- no local memory artifact was exposed on disk
- this file is therefore the durable fallback memory seed for the findings below

Source set reviewed:

- `agents/outputs/architectural_parity_epic.md`
- `agents/outputs/architectural_parity_report.md`
- `agents/outputs/architectural_parity_story_*.md`

## Verdict

The plan is close, but it is not yet safe to treat as a fully executable path to end-state architectural parity without correction.

The main blockers are not implementation-detail nits. They are ownership and sequencing holes:

1. the remaining public-folder runtime parity gap has no closing implementation story
2. the query/index row promises DB-backed parity, but Story 8 intentionally stops at an in-memory substrate plus hooks
3. Story 12 and Story 12B are described as continuous governance tracks, but the epic still orders them as if they happen at the very end

## Blocking Gaps

### 1. Public-folder runtime parity is still unowned beyond Story 1

Evidence:

- the epic still tracks `Public-folder runtime separation` as `Partial`, owned only by Story 1
- Story 3 explicitly keeps public-link persistence out of scope
- Story 4B explicitly keeps public-link contexts on disabled/no-op persistence even though the upstream SDK persists folder-link caches
- Story 6 explicitly excludes public-link runtime events
- Story 12 expects parity scenarios for folder-link restart and public-folder fetch-nodes flows

Why this matters:

- Story 1 is documentation-only
- the row is still partial
- there is no later implementation story that closes the remaining folder-link cache/auth/runtime gap

Consequence:

- if the current plan is executed as written, the epic can finish while folder-link runtime parity is still materially thinner than upstream

Required correction:

- add a dedicated follow-on story for public-folder runtime parity, or
- explicitly narrow the epic so folder-link cache/auth/runtime parity is out of scope and no longer counted as an architecture row

### 2. Query/index parity has no owner for the DB-backed part of the row

Evidence:

- the epic row says the target is `DB-backed node query/search substrate`
- Story 8 explicitly says physical on-disk search indexes remain deferred
- Story 8 acceptance only requires one in-memory evaluator plus persistent-index hooks for later work
- the Story 8 relationship section mentions later public search work, but no later story owns node-backend query acceleration or on-disk index realization

Why this matters:

- Story 8 is a valid substrate story
- it is not the full DB-backed parity target that the epic row currently names

Consequence:

- the plan can land Story 8 successfully and still leave the epic’s query/index row only partially closed

Required correction:

- either add a follow-on story for backend-owned query/index realization
- or rename/narrow the epic row so it matches the actual Story 8 endpoint

## Sequencing Contradictions

### 3. Story 12 and Story 12B are ordered too late for the role their own specs give them

Evidence:

- the numbered execution order places Story 12 and Story 12B in the final validation phase
- the epic also says Story 12 should start after Story 2 and expand continuously
- the epic says Story 12B starts immediately and remains active until epic completion
- Story 12 says later stories should add scenarios as they land
- Story 12B says later stories should update the ledger as they land

Why this matters:

- if a team follows the numbered order literally, the audit and validation tracks arrive after the foundation decisions they are supposed to police

Required correction:

- move Story 12 and Story 12B out of the terminal execution order and treat them as continuous cross-cutting tracks

### 4. Story 6’s parallel-start rule is weaker than Story 6’s own durable-boundary requirements

Evidence:

- the epic says Stories 5 and 6 can run in parallel once Stories 2, 3, 4B, and 4B.5 are stable
- Story 6 says node events should come from successful refresh and successful action-packet batches that changed durable tree/share state

Why this matters:

- Story 6’s node-event semantics are defined in terms of committed tree/share boundaries
- those boundaries are created by Story 4 and hardened by Story 4C

Consequence:

- the current parallelism note permits starting Story 6 before the tree/event boundary it wants to observe is fully stabilized

Required correction:

- require Story 4 at minimum before Story 6 node-event work begins
- if Story 6 is expected to claim production-backed committed-node semantics, require Story 4C too

## Integration Gaps To Clarify

### 5. Story 8B hands raw `*~jscd` ownership to later sync/backup stories, but Story 9 and Story 10 do not consume that seam explicitly

Evidence:

- Story 8B says later sync/backup stories should consume cached raw `*~jscd` through the secondary-state runtime
- Story 9 constraints do not mention Story 8B
- Story 10A depends on Story 9, not Story 8B

Why this matters:

- without an explicit handoff, sync/backup can either ignore server-side desired-state inputs or create a second cache path

Required correction:

- add an explicit Story 8B -> Story 9/10 consumption rule
- or explicitly state that `*~jscd` consumption is deferred beyond the current sync/backup MVPs

### 6. The old Story 10 umbrella doc is safe as a compatibility note, but risky as an execution artifact

Evidence:

- `architectural_parity_story_10_scheduled_backup.md` is still present as a compatibility entrypoint
- it says new work should use Story 10A and Story 10B directly

Why this matters:

- this is low severity, but it creates one extra “story” file that is not itself executable work

Required correction:

- keep it only if older cross-links still need it
- otherwise archive or clearly label it as non-executable historical scaffolding

## Recommended Plan Corrections

1. Add a public-folder parity follow-on story, or remove that row from the architecture-closure target with an explicit out-of-scope rationale.
2. Add a query-index follow-on story for backend-owned index/search realization, or narrow the epic row to the in-memory-plus-hooks endpoint.
3. Recast Story 12 and Story 12B as continuous tracks in the execution order instead of terminal steps.
4. Tighten Story 6 prerequisites so node-event work does not outrun durable tree-boundary work.
5. Add an explicit 8B-to-9/10 handoff for raw cached sync/backup attribute state.
6. Keep the Story 10 umbrella file clearly non-executable or remove it once no references need it.

## Bottom Line

After those corrections, the plan is executable as a coherent parity program.

Without those corrections, the most likely failure mode is not “implementation gets messy.” It is “the project finishes the named stories and still cannot honestly claim architectural parity for folder-link runtime coverage and DB-backed query/index depth.”

## Update (2026-04-01)

The primary plan-continuity corrections above have now been applied in the story set:

1. Story 6 now depends on Story 4 for committed node-event continuity.
2. Story 4D now owns the missing public-folder runtime parity slice.
3. Story 8C now owns the missing backend-backed query/index parity slice.
4. Story 12 and Story 12B are now treated as continuous governance tracks in the epic execution order.

This note should therefore be read as the review that prompted those corrections, not as the current uncorrected plan state.
