ast-dataflow — handover from ast-dataflow-tooling to production-readiness

ast-dataflow — handover from ast-dataflow-tooling to production-readiness

Status: Cross-track merge landed on production-readiness at commit 5d28cd08 (S11 R-WP-S11-D). The ast-dataflow-tooling worktree is closed; ast-dataflow follow-on work now lives on this track.

Purpose: orient the next production-readiness session on (a) what ast-dataflow shipped, (b) what landed in the merge, (c) what is queued, and (d) where to look when picking work up.

1. TL;DR

• 11 ast-dataflow queries + 2 ESLint rules + structured error contract + CLI shipped over 9 sessions (kh-ast-S1 → S11).
• Cross-track merge resolved 11 conflicts and brought 135 ast-dataflow-exclusive files + 21 auto-merged overlap files + OPS-T1 codemod specs (no impl) + post-merge runbook onto production-readiness. Smoke green: 12822/12822 vitest pass, lint clean, knip + format warnings all pre-existing.
• Six backlog items now sit on production-readiness for follow-on work (§5). Sequencing is gated on main-track Phase 1 canonical-pipeline migration timing.

2. What landed in the merge (kh-ast-S11 R-WP-S11-D, commit 5d28cd08)

The merge brought in 167 commits of ast-dataflow work from ast-dataflow-tooling @ ffc46cf7. Categories:

Category	Files	Notes
lib/ast-dataflow/* (library)	13	index.ts, resolve.ts, types.ts, 12 queries
eslint-rules/*	4	no-supabase-record-cast, no-unvalidated-route-input + tests
Tests + fixtures	~95	__tests__/lib/ast-dataflow/** + fixture corpora 01-09+
Skills + specs	~17	.claude/skills/ast-dataflow/ family + docs/specs/id-16-ast-dataflow-tool/**
OPS-T1 codemod specs (S11 R-WP-S11-A)	3	docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/{PRODUCT,TECH}.md + route-shape-inventory.md (1159 lines total — see §4)
Post-merge runbook	1	docs/runbooks/ast-dataflow-merge-S11.md

Conflict resolutions are documented in docs/runbooks/ast-dataflow-merge-S11.md (mechanical recipe). The two non-mechanical decisions worth flagging:

1. Terminology unification: ast-dataflow used “workpackage” / “WP-A”; production-readiness’s S48-S50 work ratified “task ID-N”. The merge took production-readiness’s vocabulary for workflow-orchestrator/-curator agents and session-driver-cmux skills. ast-dataflow’s spec/handoff/roadmap docs retained “WP” / “workpackage” as historical vocabulary — these are reading-only; not load-bearing for future workflow dispatch.
2. Product backlog forward-discipline: S11 R-WP-S11-C initially marked AST-S9-O1/O2 as status: "shipped" (closure-with-metadata). The Wave 1 verifier-gate caught this — shipped is in FORBIDDEN_STATUS_TOKENS per __tests__/docs/backlog-no-closed-rows.test.ts. Fix landed in commit ffc46cf7: shipped items REMOVED from product-backlog.json and ARCHIVED to product-backlog-completed.md under a new ”### kh-ast-S10 Progress (ast-dataflow track)” section. Pattern for future ast-dataflow closures: archive, don’t retain.

3. The nine-session arc (kh-ast-S1 → kh-ast-S11)

Session	Theme	Output	Tip SHA
S1-S3	Bootstrap + first four queries	callers, importers, references, column-reads + structured error contract + barrel walker	da75d281→03d61fbe
S4	Canonical-pipeline rename probe pair	column-writes + column-reads wildcard tier + test philosophy audit (23 tightenings)	within S3-S7 range
S5	Cross-project leverage trio	dead-exports, reexport-chain, type-evolution	within S3-S7 range
S6	KH-specific surfaces	string-literal-uses, enum-uses + flow-trace TECH sub-spec	within S3-S7 range
S7	Flow-trace + investigation briefs	flow-trace shipped (R-WP6, three-WP sequence); R-WP10/11/12 briefs authored	03d61fbe
S8	Wave 4: portability + verifier skill + type-safety triad	R-WP10a framework-portability; R-WP11a rename-sweep skill; R-WP12 type-safety pipeline spec triple	c2e0bc61→e7991b6a
S9	Wave 5: type-safety pipeline shipping	R-WP17 type-drift detector + KH baseline (37 fetcher-only); R-WP18 12-site cast sweep + no-supabase-record-cast rule; R-WP19 opaque-Json RPC inventory; R-WP20 MCP outputSchema scaffold on 5 tools; R-WP21 decision note	3b8dacf6→fedbfe1d
S10	Wave 6 + Wave 0 ratifications	Wave 6: skill packaging + CI gate (R-WP17 type-drift-parity in ci.yml); R-WP7 ast-dataflow skill family + call-chain-pin + efficacy eval (25/25 trigger phrases). Wave 0: 4 investigations binding S11 scope. R-WP21 RATIFIED-(c)-S10 (CI gate only; OPS-T1 deferred to codemod-led rollout)	4f7b5c32→20404054
S11	Final session: OPS-T1 codemod specs + cross-track merge	R-WP-S11-A specs (PRODUCT 265 / TECH 566 / inventory 328 = 1159 lines); R-WP-S11-B pre-flight (12 → 4 original conflicts); R-WP-S11-C housekeeping; R-WP-S11-D merge to production-readiness	366f5a0e→ffc46cf7 (ast-dataflow tip) / 5d28cd08 (merge on production-readiness)

4. The OPS-T1 codemod specs (R-WP-S11-A) — the headline deliverable

Authored at docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/. Specs only — no implementation code landed. Implementation is queued as 25 in the backlog.

File	Lines	What it contains
route-shape-inventory.md	328	Empirical inventory of 193 app/api/**/route.ts routes bucketed by shape variant: AUTH_PLAIN 40, PARAM_BODY 40, BODY_VALIDATED 31, PARAM 26, MULTI_PARAM_BODY 19, MULTI_BODY 17, CRON 9, NAKED_NO_AUTH 6, MULTI_PARAM 4, MCP 1 = 193. Mechanisability: 137 (71%) MECHANISABLE, 40 (21%) NEEDS-REVIEW, 16 (8%) MANUAL.
PRODUCT.md	265	User-facing behaviour for scripts/codemods/wrap-define-route.ts: dry-run vs apply modes, idempotency contract, diff preview format, failure modes per shape, acceptance criteria. §7 carries the verifier sub-section pointing at lib/ast-dataflow/queries/type-drift-detect.ts.
TECH.md	566	ts-morph implementation strategy. ResponseSchema inference ranks Source A (type-drift-baseline.json, 37 routes) highest, Source B (existing return-type annotation) second, Source C (return-statement walk) deferred. Test fixture set covers each shape variant. withRequestContext composition order specified (outermost wrapper). §7 carries the verifier sub-section.

Key design decision to honour at implementation time: the codemod is a sibling utility at scripts/codemods/, not a part of ast-dataflow. ast-dataflow’s PRODUCT.md explicitly scopes the tool as “not an autofix tool”. The codemod writes; ast-dataflow’s type-drift-detect verifies.

5. Backlog queued on production-readiness (AST-prefixed rows)

ID	Description	Priority	Effort	Gating
23	ast-dataflow-type-evolution-check skill — Pattern 6 catalogue → full skill	medium	2-3h	concrete type-rename use case
24	ast-dataflow-enum-member-audit skill — Pattern 8 catalogue → full skill	medium	2-3h	enum audit / as const false positive
25	OPS-T1 codemod implementation (scripts/codemods/wrap-define-route.ts) — specs ratified-ready	medium	16-24h	main-track Phase 1 canonical-pipeline migration kickoff
26	R-WP22 MCP outputSchema full rollout — promote scaffold pattern across remaining tools	low	29h	no hard gate

OQ-R9 (opaque-Json RPC migration, 5-RPC Tier 1+2 sprint, ~7h) is not yet a numbered backlog item — referenced in docs/specs/id-16-ast-dataflow-tool/ROADMAP.md “Carried forward to production-readiness” section. Promote when scheduling.

6. Out-of-scope finding from S11 R-WP-S11-A worth triaging

WP-A’s route-shape inventory flagged two routes in NAKED_NO_AUTH that are not in proxy.ts publicRoutes allowlist:

• app/api/feeds/[workspaceId]/rss/route.ts
• app/api/feeds/[workspaceId]/rss/filtered/route.ts

They appear to be intentionally unauthenticated (exempt from proxy redirect via the isApiRoute check in proxy.ts), but the proxy contract gotcha in CLAUDE.md says “New public endpoints must be added to publicRoutes in proxy.ts (project root) or they silently redirect to /login.” Worth a quick confirmation pass — either backlog or close as confirmed-intent.

7. Carried-forward Liam ratifications

• R-WP21 OPS-T1 path: option (c) only (Liam ratified at kh-ast-S10 close). CI gate type-drift-parity ships in ci.yml (commit c99f5953). Wave-A per-route annotations DROPPED. Wave-A’ full migration DEFERRED to codemod-led path (25). Doc: docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/decision-OPS-T1.md.
• Terminology: “task ID-N” wins for workflow-orchestrator dispatching vocabulary (S11 session-start ratification). ast-dataflow spec/roadmap “WP-A” / “workpackage” usage retained as historical.
• Test-path convention (S10 synthesis §3.4): until ast-dataflow extracts to its own package, tests stay at __tests__/lib/ast-dataflow/ (flat). Future package extraction: sibling-of-source (lib/ast-dataflow/queries/<name>.ts + <name>.test.ts). No migration ahead of extraction.
• Forward-discipline backlog rule (kh-ast-S11 Wave 1 verifier-fix learning): shipped items REMOVED from product-backlog.json, ARCHIVED to product-backlog-completed.md. Do NOT retain with status: "shipped" field — fails __tests__/docs/backlog-no-closed-rows.test.ts.

8. Critical gotchas surfaced in S11 (add to your working memory)

1. isolation: "worktree" sub-agents can still drift to the parent worktree. S11 R-WP-S11-C dispatched as a worktree-isolated agent but committed directly to ast-dataflow-tooling (commits 6dbf9da2 + af9fe05c). Work was intact, so no merge action needed — but mitigation for next time: every sub-agent must prefix cd $(git rev-parse --show-toplevel) && after any Read and verify pwd matches the worktree path before git commit.
2. Reference-doc freshness guard fails on merge commits. __tests__/docs/reference-doc-edit-coupled-freshness.test.ts uses git show --format= <sha> -- <file> which returns combined-diff format for merge commits — + regex won’t register single-parent additions to last_updated. Workaround: a follow-up single-parent commit that bumps last_updated (commit 744d9ef1 is the S11 example). Or include [skip-doc-freshness-guard] in the merge commit message body if the bump is intentional.
3. Concurrent dev on production-readiness during a cross-track merge is non-fatal but adds reconciliation rounds. S11 saw three concurrent commits (b6f7d55f, 80944a09, 831d9e74) land while the merge was in flight. Pattern that worked: fresh worktree off production-readiness, merge ast-dataflow into it, then pull-and-merge production-readiness into the merge worktree to reconcile, fast-forward production-readiness, push. See docs/runbooks/ast-dataflow-merge-S11.md for the full sequence.

9. When picking up 25 (OPS-T1 codemod implementation)

Read first (in order):

1. This doc (orientation).
2. docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/PRODUCT.md (behaviour spec).
3. docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/TECH.md (implementation strategy).
4. docs/specs/id-16-ast-dataflow-tool/ops-t1-codemod/route-shape-inventory.md (empirical route categorisation).
5. docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/decision-OPS-T1.md (S10 ratification context).
6. lib/ast-dataflow/queries/type-drift-detect.ts (post-migration verifier integration target).
7. scripts/codemods/ (currently empty — confirm none exist before authoring).
8. proxy.ts (note the gotcha from §6 — confirm RSS routes before bulk-wrapping the NAKED_NO_AUTH set).

Sequencing assumption: 25 is gated on main-track Phase 1 canonical-pipeline migration kickoff. Check docs/reference/state-of-the-product.md and the main-track continuation prompts before scheduling.

10. Quick smoke commands

# AST tests (expect 215 pass / 0 skip / 0 fail)
bun run test __tests__/lib/ast-dataflow/

# Type-drift detector probe (S10 baseline: 37 fetcher-only routes)
bun scripts/ast-dataflow-cli.ts type-drift-detect

# Specific query smoke (e.g. callers on sb())
bun scripts/ast-dataflow-cli.ts callers --symbol sb

# Full vitest (expect ≥12822 pass; 24 skip; 0 fail)
bun run test

# Knip (warnings include ast-dataflow library API exports — expected, not regressions)
bun run knip

11. References

• docs/runbooks/ast-dataflow-merge-S11.md — mechanical conflict-resolution log for the merge.
• docs/specs/id-16-ast-dataflow-tool/ROADMAP.md — track-local roadmap with full Wave 1-7 SHIPPED stamps and “Carried forward to production-readiness” section.
• docs/specs/id-16-ast-dataflow-tool/PRODUCT.md — behaviour spec (12 query surfaces, 30 invariants).
• docs/specs/id-16-ast-dataflow-tool/TECH.md — data model, library layout, validation, follow-ups.
• docs/specs/id-16-ast-dataflow-tool/investigations/S10-wave-0-synthesis.md — binding ratification doc for the S11 plan.
• docs/specs/id-16-ast-dataflow-tool/investigations/S10-r-wp16-merge-dry-run.md — original 12-conflict projection and resolution recipes.
• docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/{PRODUCT,TECH}.md — type-safety pipeline triad authored S8.
• docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/decision-OPS-T1.md — R-WP21 decision note.
• docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/allowlist.json — type-drift baseline (37 fetcher-only routes).
• .claude/skills/ast-dataflow/SKILL.md — catalogue skill (orient-to-query mapping for 12 queries + 9 cross-tool patterns).
• .claude/skills/ast-dataflow/ast-dataflow-rename-sweep/SKILL.md — verifier skill for post-gitnexus_rename audits.
• .claude/skills/ast-dataflow/ast-dataflow-call-chain-pin/SKILL.md — diagnostic skill for wrong-argument-value bugs.
• CLAUDE.md — project root project guidance including the “ast-dataflow — TypeScript Symbol Analysis” section.

12. Branch reference

• ast-dataflow-tooling tip: ffc46cf7 (preserved on origin — do NOT delete per S11 close-out brief).
• production-readiness post-handover tip: fb7831fa.
• Merge commit on production-readiness: 5d28cd08.
• Reconciliation merge (for concurrent S51 work): 5d28cd08 is the actual reconciliation; the bare ast-dataflow merge is 03392948.
• Freshness-guard bump: 744d9ef1.
• Backlog promotion close-out: fb7831fa.

---

End of handover.