S10 Wave 0 synthesis — scope, mechanisation, merge plan

Status: RATIFIED-S10 (kh-ast-S10 — synthesises 4 Wave 0 research outputs into roadmap-binding decisions). Inputs: S10-route-retirement-inventory.md, S10-intelligence-cluster-fate.md, S10-programmatic-migration-feasibility.md, S10-r-wp16-merge-dry-run.md.

1. Why this doc exists

S10 opened with a question: do the main-track canonical-pipeline retirements shrink the scope of R-WP21 (OPS-T1 defineRoute() 193-route rollout) enough to flip the orchestrator’s hybrid-(b)+(c) recommendation toward (a)? Four parallel research agents ran read-only investigations against the authoritative main-track sources (docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md, docs/reference/project-plan.md, docs/plans/phase-0-investigation/architecture/07-collapse-list.md, docs/plans/phase-0-investigation/0.9-decision-graph.md) plus the current ast-dataflow + gitnexus + cocoindex-code toolchain. This doc consolidates the four reports into roadmap-binding decisions and the S11 work plan.

2. Wave 0 findings

2.1 Route survival (Wave 0-A)

Of 193 app/api/**/route.ts files, 186 (96.4%) survive Phase 1 path-unchanged, 4 (2.1%) rename (the digest cluster → /api/change-reports/** per 0.9-decision-graph.md §11.3 component 7), 1 (source-documents/[id]/diff/route.ts) is [DEFERRED-v1.1] per S240 Liam ratification but persists in v1, and 0 retire outright. The bid-cluster rename (lib/bid/* → lib/procurement/*, BID_STATES → PROCUREMENT_WORKFLOW_STATES) is explicitly scoped to the backend per 07-collapse-list.md §6 — the 29 public /api/bids/** routes survive path-unchanged absent a separate ratification. OPS-T1 scope reduction available: none. The 16-24h Wave-A’ estimate stands.

2.2 Intelligence cluster fate (Wave 0-B)

All 20 app/api/intelligence/**/route.ts files survive: 16 unchanged, 4 body-rewrite-only (URL preserved, return shape unchanged). intelligence_workspaces is a v1 reserved seat per docs/specs/reserved-workspace-seats/PRODUCT.md S-1 ([RATIFIED-S240]); intelligence is one of six core baseline application_types per architecture/04-workspace-types.md §3. The feed-system schema (feed_sources, feed_articles, feed_prompts, feed_flags, company_profiles) is NOT in any retire or rename list. MCP intelligence tools are [REFINE] not [RETIRE] per 06-mcp-tooling.md §6. Wave-A annotation work would be safe-and-permanent if Liam had selected hybrid (b)+(c).

2.3 Programmatic migration feasibility (Wave 0-C)

Mechanisation rate across six canonical-pipeline workstreams:

Workstream	Mechanisation	Driver
OPS-T1 `defineRoute()` rollout	~10-20%	No AST-rewrite primitive in any tool. Needs sibling codemod.
`project_id` → `workspace_id` (44 files)	70-85%	rename-sweep skill (gitnexus_rename + ast-dataflow verifier)
`templates` table family rename	70-85%	rename-sweep skill
`bid_workspaces` → `procurement_workspaces` + `lib/bid/` → `lib/procurement/`	70-85%	rename-sweep skill
`/api/digest/` → `/api/change-reports/` + `digests` table	70-80%	rename-sweep skill (paths + symbols + SQL)
`content_citations` → `citations`	75-85%	rename-sweep skill

Total Phase 1 saving: ~17-25h on a ~36-52h baseline (excluding the codemod authoring itself). OPS-T1 drags the average down — it is a code transformation, not a rename, and ast-dataflow’s PRODUCT.md explicitly scopes the tool as “not an autofix tool”. The recommendation is a new sibling utility at scripts/codemods/wrap-define-route.ts using ts-morph for the rewrite, with ast-dataflow remaining the verifier.

2.4 Cross-track merge dry-run (Wave 0-D)

ast-dataflow-tooling → production-readiness merge produces 12 conflicts of 363 paths staged. The merge brings in 167 ast-dataflow commits (27.3K insertions, 1.7K deletions, 168 files). Of the 33 files touched by both branches since the common ancestor 186a05bc, 21 auto-merge cleanly; the 12 conflicts split into three buckets:

Trivial whitespace / Prettier reformat conflicts (.gitignore, start-session/SKILL.md, main_session_output.md)
Workflow-agent terminology drift (workflow-curator.md, workflow-orchestrator.md, session-driver-cmux/* — production-readiness’s S48-S50 “workpackage → task ID-N” rewrites vs ast-dataflow’s prettier-reformat)
One substantive: docs/reference/product-roadmap.md from production-readiness’s WP4 JSON-driven re-render not matching ast-dataflow’s ad-hoc §8/§9 renumbering

None of the ast-dataflow primitives conflict. All 135 files (lib/ast-dataflow/*, eslint-rules/*, ~95 test fixtures, ~16 spec docs) merge verbatim. CI workflow files have no overlap.

Merge difficulty: moderate. 8 of 12 conflicts resolve in <30 min each. The roadmap.md conflict needs a non-line-by-line resolution (regenerate from canonical JSON). Total effort: 4-6 hours, split across pre-flight (1.5-2.5h), merge itself (2-3h), post-merge verification (30-60min).

3. Ratified decisions (S10 close)

3.1 R-WP21 — OPS-T1 path

Liam ratification: option (c) only. Wave-A (b) per-route annotations on the intelligence cluster is DROPPED. Full OPS-T1 (a) defineRoute() migration is DEFERRED to a future session aligned with main-track Phase 1 timing.

Rationale:

Wave-A annotations are tactical and would be partially obsoleted (~70% line-churn, 30% schema-knowledge reuse) once OPS-T1 ships. With OPS-T1 not yet mechanisable (Wave 0-C finding) but a codemod-assist achievable in S11, Wave-A’s 4-6h is the wrong place to spend hours.
CI gate (option c) is orthogonal to (a) and (b) — it ratchets whatever baseline exists and is the cheapest regression-prevention lever per the decision-OPS-T1 doc. Ships in S10 as Wave 1 WP1.
OPS-T1 stays manual under current toolchain (Wave 0-C). A sibling scripts/codemods/wrap-define-route.ts ts-morph utility would cut the 16-24h estimate substantially. Authoring the codemod (+ its PRODUCT.md + TECH.md) is reserved as the headline WP for S11.

3.2 R-WP19 — Opaque-Json RPC migration appetite (OQ-R9)

Carried forward — no S10 binding. The 5-RPC Tier 1+2 sprint (~7h) is queued for after Phase 1 canonical-pipeline migration settles. Re-evaluation at S11 close as part of the cross-track handover.

3.3 R-WP16 — Cross-track merge (re-framing)

Original framing (“dev-workflow integration”) is REPLACED by the actual mechanical task: merge ast-dataflow-tooling → production-readiness to consolidate 167 commits of ast-dataflow work into the wider project before main-track absorption. Per 0-D findings:

S10: no merge action — Wave 1 work-package commits land here on ast-dataflow-tooling. Splitting Wave 1 across branches would create a second divergence.
S11 pre-flight: terminology decision (workpackage vs task ID-N) + scratch-file cleanup + roadmap JSON canonicalisation. 1.5-2.5h.
S11 merge wave: the 12-conflict resolution on production-readiness with the buckets documented in S10-r-wp16-merge-dry-run.md §3-§6. 2-3h.
S11 verification: knip + full test suite + smoke. 30-60min.
Out of scope for S11: production-readiness → main merge. Defer to a separate orchestrator-led session.

3.4 Test-path convention (S9 deferred item)

Two-axis question carried forward: (a) AST-dataflow tool is also intended for use on other codebases; (b) KH test-path convention places tests at __tests__/lib/ast-dataflow/ (flat) not at queries/<name>.test.ts (TECH.md proposed). Resolution path: when ast-dataflow extracts to its own package (post-merge to production-readiness, in a follow-on session), adopt a sibling-of-source layout (lib/ast-dataflow/queries/<name>.ts

lib/ast-dataflow/queries/<name>.test.ts) for portability. Until then, TECH.md updates to reflect the actual KH convention; the test files do NOT migrate now. Closure noted in handoff for S11 housekeeping.

4. S11 work plan (binding)

S11 is the last session on the ast-dataflow-tooling worktree. Scope is bounded by what fits in one session plus housekeeping. Three parallelisable WPs plus a sequential merge:

4.1 S11-WP-A: OPS-T1 codemod investigation + spec authoring (~4-6h)

Inputs: R-WP21 decision (3.1 above); Wave 0-C feasibility report; type-safety-pipeline/PRODUCT.md D-19; decision-OPS-T1.md.

What:

Investigation phase (~1h): catalog the 193 routes by handler shape variants — naked export async function GET(req), parameterised [id], request-body-validated, multi-method (GET+POST in same file), etc. Output route-shape inventory feeding the codemod design.
write-product-spec for scripts/codemods/wrap-define-route.ts: user-facing behaviour, dry-run + apply modes, idempotency contract, diff preview format, failure modes (route shapes the codemod can’t handle → reports for manual migration). ~1.5-2h.
write-tech-spec: ts-morph implementation strategy, ResponseSchema inference (from existing return-type annotations / type-drift baseline / handler return-statement walk), test fixture set, integration with the existing ast-dataflow verifier suite. ~1.5-2h.

Files (NEW): docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/PRODUCT.md + docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/TECH.md. No implementation in S11 — the spec lands; implementation happens in a future session after main-track Phase 1 canonical-pipeline migration begins.

Acceptance: Both specs reviewed + ratified by Liam at S11 close. Specs explicitly carry a “verifier” sub-section pointing at ast-dataflow’s existing type-drift-detect as the post-migration regression gate.

4.2 S11-WP-B: Pre-flight for cross-track merge (~1.5-2.5h)

Inputs: Wave 0-D dry-run report §5.

What:

Terminology consolidation decision (workpackage vs task ID-N) — flag to Liam at session start; one-line ratification + propagate the change to ast-dataflow’s skill docs + workflow-orchestrator references.
Scratch-file cleanup: identify and remove any ast-dataflow files that are not load-bearing for the merge (the dry-run report names them).
Roadmap canonicalisation: regenerate docs/reference/product-roadmap.md from the production-readiness canonical JSON so the merge auto-resolves the §8/§9 renumbering. Add §3 collapse-list and §11 new-features rows for the 4 Wave 0 investigations + Wave 1 deliverables.

Files (EDIT): various — list per dry-run §5.

Acceptance: Dry-run of the same merge command on a fresh test branch shows ≤6 conflicts (down from 12). The remaining 6 are documented and queued for the merge wave.

4.3 S11-WP-C: Housekeeping (~1h)

What:

Move R-WP22 (MCP outputSchema full rollout, ~29h) row to the production-readiness backlog with provenance trail.
Audit docs/reference/product-backlog.json (this worktree) — close AST-S9-O1 + AST-S9-O2 (shipped S10), add any S10-surfaced candidates (Pattern 6 skill, Pattern 8 skill, OPS-T1 codemod sibling-utility verification).
ROADMAP edit: mark R-WP21 RATIFIED-(c)-S10; mark Wave 6 R-WP7 + R-WP16 SHIPPED with commit refs; add a new “Wave 7” section reserving the OPS-T1 codemod spec authoring as the entry-point work.
Update docs/specs/id-16-ast-dataflow-tool/TECH.md §Test-path convention note per 3.4 above.

Files (EDIT): ROADMAP.md, product-backlog.json, TECH.md.

Acceptance: All S10 deliverables traceable in the roadmap. S11 close hands over a clean “what’s done / what’s deferred / what’s now in production-readiness scope” matrix.

4.4 S11-WP-D: Cross-track merge execution (~2-3h)

Inputs: S11-WP-B pre-flight outputs. Wave 0-D §3 conflict list.

What: Execute the merge on production-readiness worktree following the resolution recipe in S10-r-wp16-merge-dry-run.md §3. Verify with post-merge smoke (knip + full vitest + lint + format:check). Push.

Files (TOUCHED): the 12 conflict files + 168 ast-dataflow files landing on production-readiness.

Acceptance: production-readiness branch contains all ast-dataflow work. CI green. Conflict-resolution decisions documented in a sibling docs/runbooks/ast-dataflow-merge-S11.md post-mortem for cross-track audit trail.

4.5 S11 dispatch order

1
Wave 1 (parallel):    WP-A (codemod specs)
2
                      WP-B (merge pre-flight)
3
                      WP-C (housekeeping)
4
Wave 1 verifier gate
5
Wave 2:               WP-D (merge execution) — sequential, on production-readiness
6
Wave 2 verifier gate
7
Close-out:            handoff to first session on production-readiness
8
                      that picks up ast-dataflow work

5. Wave 1 deliverables (S10)

The four Wave 1 work packages from the S10 brief shipped at the following commits on ast-dataflow-tooling:

WP	Commit	Scope
WP4 (AST-S9-O2)	`e07edfc5`	`SearchBodySchema.layer` removed; client confirmed never passes the field. 12,729 tests pass.
WP1 (R-WP17 CI gate)	`c99f5953`	`type-drift-parity` job in `.github/workflows/ci.yml`. Synthetic test passes (probe → exit 1; revert → exit 0). `docs/runbooks/ci.md` updated.
WP2 (R-WP7 skills)	`61413dd3`	Catalogue + call-chain-pin skills + efficacy eval (25/25 trigger phrases). CLAUDE.md section added.
WP3 (AST-S9-O1)	`b2339cee`	Shape F extension to `no-supabase-record-cast` rule; 3 casts removed from `lib/topic-inference.ts`. 25 rule tests (was 20).
Wave 2 cleanup	`a39ab16f`	Verifier-finding fixes: `enum-member-uses` → `enum-uses` + query count 11 → 12; intelligence-cluster lint suppression (cast deferred to OPS-T1 codemod).

Out-of-scope observations from Wave 1 surfaced two backlog candidates: Pattern 6 (type-evolution agreement check) and Pattern 8 (enum-member-uses Knip confirmation) skill files — currently catalogue entries only. S11 WP-C housekeeping records them.

6. Sequencing summary

1
S10 (this session):
2
  Wave 0 (research) → Wave 1 (4 parallel WPs) → Wave 2 (verifier + fixes) → Wave 3 (this synthesis)
3

4
S11 (final session on ast-dataflow-tooling):
5
  Wave 1 (parallel: WP-A codemod specs / WP-B pre-flight / WP-C housekeeping) →
6
  verifier gate →
7
  Wave 2 (WP-D merge execution on production-readiness) →
8
  verifier gate → close-out
9

10
Post-S11 (production-readiness-led):
11
  ast-dataflow work consumed by production-readiness. OPS-T1 codemod
12
  implementation scheduled aligned with main-track Phase 1 canonical-
13
  pipeline migration.

7. Files

S10-route-retirement-inventory.md — 0-A output
S10-intelligence-cluster-fate.md — 0-B output
S10-programmatic-migration-feasibility.md — 0-C output
S10-r-wp16-merge-dry-run.md — 0-D output
S10-wave-0-synthesis.md — this doc (the binding ratification)

End of synthesis.