S10 R-WP16 — ast-dataflow-tooling → production-readiness merge dry-run

S10 R-WP16 — ast-dataflow-tooling → production-readiness merge dry-run

Wave: Wave 0-D (research, read-only + one writable output) Branch: ast-dataflow-tooling Worktree: /Users/liamj/Documents/development/knowledge-hub-ast-dataflow Date: 2026-05-18 (S10) Status: DRY-RUN COMPLETE — no merge committed; throwaway test branch deleted.

This investigation answers: if we merge ast-dataflow-tooling into production-readiness next session, what happens? R-WP16 is reframed for S10 from “dev-workflow integration of ast-dataflow” to “merge ast-dataflow-tooling into the wider production-readiness track before main-track absorption.”

---

§1 Branch divergence stats

Merge base: 186a05bc (“Merge branch ‘production-readiness’ into content-items-investigation”). Both branches diverged from this commit.

Direction	Commits	Files	Insertions	Deletions
ast-dataflow-tooling ahead of production-readiness	167	168 (116 A, 1 D, 51 M)	27,334	1,693
production-readiness ahead of ast-dataflow-tooling	52	77	20,468	902

ast-dataflow-tooling is the larger of the two. The bulk of its 116 added files are ast-dataflow primitives, fixtures, tests, and skill+spec docs. production-readiness’s 77-file delta is concentrated on workflow agent + curator skill refactors and §3 roadmap restructure.

---

§2 File-overlap matrix

33 files have been touched in BOTH branches since 186a05bc. Of these:

• 12 produce real merge conflicts (see §3).
• 21 auto-merge cleanly because the two branches edited disjoint regions.

Overlap files grouped by category:

A. Workflow agents (.claude/agents/)

File	ast-dataflow change	production-readiness change	Conflict?
workflow-checker.md	Prettier reformat / minor edits	Reframed terminology + body rewrite (WP6.S4 git mv to task-checker)	NO (auto-merge — branches added at compatible offsets)
workflow-curator.md	Prettier reformat + skill references	”workpackage” → “task ID-N” terminology + ID-N references	YES (semantic terminology conflict — large diff: ~302 lines)
workflow-executor.md	Prettier reformat	Reframed body (WP6.S3 git mv to task-executor)	NO
workflow-orchestrator.md	Prettier reformat + new skill list	Updated dispatching language + agent-name refs	YES (~350-line diff; same content reflowed differently)

B. Session-driver-cmux skills (.claude/skills/session-driver-cmux/)

File	ast-dataflow change	production-readiness change	Conflict?
SKILL.md	Prettier reformat	S48-S49 minimal-mode drop + safety gate notes	YES (~208 lines)
scripts/launch-worker.sh	Light edits	S48 minimal-mode removal + S46 empirical fixes	YES (~139 lines)
scripts/converse.sh, emit-event.sh, approve-tool.sh, send-prompt.sh, stop-worker.sh, wait-for-fleet.sh, hooks/hooks.json	Light edits	Various fixes	NO (auto-merge)

C. Curator skills (.claude/skills/)

File	ast-dataflow change	production-readiness change	Conflict?
start-session/SKILL.md	Prettier reformat	Body edits	YES (whitespace-only conflict — ~120 lines marker pollution)
triage-finding/SKILL.md	Prettier reformat	Body edits	NO
update-roadmap-backlog/SKILL.md	Prettier reformat	Body edits	NO

D. Root configuration

File	ast-dataflow change	production-readiness change	Conflict?
.gitignore	Added !.claude/skills/ast-dataflow/ lines + cmux-events comment block	Added !.claude/skills/implement-specs/ + !.claude/skills/spec-driven-implementation/	YES (trivial — both branches added entries in same region)

E. Phase-0 investigation docs (docs/plans/phase-0-investigation/)

File	ast-dataflow change	production-readiness change	Conflict?
0.9-collapse-candidates.md	DELETED (archived to .planning/.archive/.specs/)	Modified in place	YES (modify/delete)
0.9-decision-graph.md	Prettier reformat	S234/S235 ratifications added (substantive new content)	YES (~49 lines marker pollution but substance is one-sided)
kh-workflow-orchestration.md	Added “Superseded by:” header	Added agent names / skill refs	YES (~88-line diff — orthogonal edits but in close proximity)
kh-workflow-orchestration-assessment.md	Added supersession header	Added agent updates	YES (~74 lines)
10-feedback-investigation-findings/ (8 files)	Prettier reformat	Body edits	NO (all auto-merge)
dw-subagent-outputs/02-dw11-ast-data-flow-gitnexus-eval.md	Prettier reformat	Content edits	NO
dw-subagent-outputs/01-dw10-gitbook-warp-skills-port.md, 03-dw14-bulletproof-react-supabase-typegen.md, prompts.md	Prettier	Edits	NO
dw11-ast-data-flow-route.md	Prettier reformat	S46 (e2c909f4) edits	NO

F. Roadmap rendered Markdown

File	ast-dataflow change	production-readiness change	Conflict?
docs/reference/product-roadmap.md	Prettier reformat + WP renumbering (“Pass 2 improvements …”, §8 telemetry, §9.1.1 templates)	WP4.S4 re-render from migrated JSON with different §3.5.x / §3.7.x numbering scheme	YES (~200-line diff — numbering scheme divergence)

G. Other root files

File	ast-dataflow change	production-readiness change	Conflict?
main_session_output.md	ast-dataflow session log dump	production-readiness session log dump	YES (~932-line diff — both branches dumped different session content into the same scratch file)

---

§3 Dry-run merge result

Procedure:

1. Created throwaway branch ast-dataflow-merge-dryrun-tmp from production-readiness HEAD (9df51c67).
2. Ran git merge ast-dataflow-tooling --no-commit --no-ff.
3. Captured conflict list.
4. Ran git merge --abort.
5. Deleted ast-dataflow-merge-dryrun-tmp (verified gone).

Conflicts: 12 files. (363 paths in conflicted index total; 12 unresolved.)

AA .claude/agents/workflow-curator.md
AA .claude/agents/workflow-orchestrator.md
AA .claude/skills/session-driver-cmux/SKILL.md
AA .claude/skills/session-driver-cmux/scripts/launch-worker.sh
UU .claude/skills/start-session/SKILL.md
UU .gitignore
UD docs/plans/phase-0-investigation/0.9-collapse-candidates.md
UU docs/plans/phase-0-investigation/0.9-decision-graph.md
AA docs/plans/phase-0-investigation/kh-workflow-orchestration-assessment.md
AA docs/plans/phase-0-investigation/kh-workflow-orchestration.md
UU docs/reference/product-roadmap.md
UU main_session_output.md

Status codes: AA = both-added (each branch added the file independently with different content), UU = both-modified, UD = modified-in-ours, deleted-in-theirs.

Difficulty classification (per conflict):

Conflict	Resolution effort	Notes
.gitignore	Trivial (2 min)	Both branches added rules at the same offset; union the two new lines.
start-session/SKILL.md	Trivial (5 min)	Whitespace-only conflict from Prettier wrap differences; pick the production-readiness body, re-run Prettier.
main_session_output.md	Trivial (1 min)	Scratch file — delete or pick one side outright. Should arguably be .gitignored.
kh-workflow-orchestration.md	Easy (10 min)	Orthogonal edits; manually keep the “Superseded by:” header (ast-dataflow) and the agent-name / skill refs (production-readiness).
kh-workflow-orchestration-assessment.md	Easy (10 min)	Same pattern as above.
0.9-decision-graph.md	Easy (5 min)	production-readiness side has the new substantive S234/S235 content. Take production-readiness wholesale; ast-dataflow side was Prettier reformat only.
0.9-collapse-candidates.md	Easy (5 min)	ast-dataflow archived this file; production-readiness modified it. Resolution: honour the archive (delete + ensure .planning/.archive/.specs/0.9-collapse-candidates.md is staged).
workflow-curator.md	Moderate (30 min)	Genuine terminology divergence (workpackage / task ID-N). production-readiness body is the newer authoritative version; merge in any prettier-only formatting from ast-dataflow.
workflow-orchestrator.md	Moderate (30 min)	Same pattern as workflow-curator.
session-driver-cmux/SKILL.md	Moderate (20 min)	production-readiness has S48-S49 minimal-mode drop notes; ast-dataflow is reformat. Take production-readiness body.
session-driver-cmux/scripts/launch-worker.sh	Moderate (20 min)	production-readiness has substantive script changes (S48 cleanup); take production-readiness.
docs/reference/product-roadmap.md	Hard (60-90 min)	Substantive numbering-scheme divergence. production-readiness renumbered §3.x via WP4 JSON-driven rewrite (S26-S0 stack); ast-dataflow renumbered §8 / §9.1.1 ad-hoc. Resolution requires consulting product-roadmap.json on production-readiness as canonical and re-rendering product-roadmap.md. Do NOT hand-merge the table rows.

Total estimated conflict-resolution effort: 3-4 hours, assuming the product-roadmap.md resolution can use the JSON-driven re-render path rather than line-by-line table merge.

---

§4 Files ast-dataflow-tooling exclusively owns (clean-merge candidates)

These 135 files exist only in ast-dataflow-tooling’s delta and will land cleanly. They are the core ast-dataflow primitives + harness.

Library code (16 files):

• lib/ast-dataflow/index.ts
• lib/ast-dataflow/resolve.ts
• lib/ast-dataflow/types.ts
• lib/ast-dataflow/queries/{callers,column-reads,column-writes,dead-exports,enum-uses,flow-trace,importers,reexport-chain,references,string-literal-uses,type-drift-detect,type-evolution}.ts
• scripts/ast-dataflow-cli.ts

ESLint rules (4 files):

• eslint-rules/index.js
• eslint-rules/no-supabase-record-cast.js
• eslint-rules/no-unvalidated-route-input.js
• eslint-rules/tests/no-supabase-record-cast.test.ts

Tests + fixtures (~95 files):

• __tests__/lib/ast-dataflow/*.test.ts (callers, column-reads, column-writes, dead-exports, enum-uses, errors, etc.)
• __tests__/lib/ast-dataflow/fixtures/{01-callers,04-anonymous-enclosings,05-importers,06-references,07-column-reads,08-column-writes,09-dead-exports,…}/*

Skills + specs (~15 files):

• .claude/skills/ast-dataflow/ast-dataflow-rename-sweep/SKILL.md
• docs/specs/id-16-ast-dataflow-tool/{PRODUCT,TECH,ROADMAP}.md
• docs/specs/id-16-ast-dataflow-tool/investigations/R-WP10-… through R-WP12-…
• docs/specs/id-16-ast-dataflow-tool/type-safety-pipeline/{PRODUCT.md,TECH.md,allowlist.json,decision-OPS-T1.md}

Total: ~135 files that the production-readiness merge will accept verbatim. Combined with the 21 auto-merging overlap files = ~156 files land with zero touch.

---

§5 Pre-flight steps required before next session’s actual merge

Before attempting the real merge:

1. Reach agreement on terminology. The workflow agent docs (workflow-curator.md, workflow-orchestrator.md) diverge on “task ID-N” vs “workpackage” framing. Decide which is canonical and apply ahead of merge so the resolution is deterministic, not improvised at merge time. Recommendation: keep production-readiness’s terminology (it’s the more recent S49/S50 work and the docs were renamed via git mv already).

2. Re-render product-roadmap.md post-merge from JSON. Do not hand-merge §3.x table rows. Resolution path:

   • Accept production-readiness’s docs/reference/product-roadmap.json as canonical (it has the WP4 §3 restructure).
   • Cherry-pick any ast-dataflow roadmap additions (§8 AI Telemetry, §9.1.1) into the JSON.
   • Re-run the WP4.S4 render script (docs/reference/product-roadmap.md is a generated artefact in production-readiness).

3. Resolve the archive vs in-place decision for 0.9-collapse-candidates.md. ast-dataflow archived it (per S232 Wave 1 closure); production-readiness kept editing it. The archive direction is correct architecturally — confirm with Liam, then resolve by completing the archive.

4. Decide whether main_session_output.md should be tracked at all. Both branches use it as a scratch file. Either (a) .gitignore it and remove from both branches, or (b) accept one branch’s content arbitrarily.

5. Run bun run knip on ast-dataflow-tooling before merge — confirms no dead exports introduced by recent waves that would unnecessarily inflate the production-readiness diff.

6. Stash production-readiness untracked files. Production-readiness worktree currently has 4 untracked .bak.json / .bak.md / skills-lock.json files. Either commit or remove them before merge to keep the merge commit clean.

7. Optional: rebase ast-dataflow-tooling on production-readiness first. A rebase would surface conflicts one commit at a time, making them easier to attribute. However, with 167 commits to replay it’s higher-effort than a single merge with manual resolution. Recommend: single merge with the resolutions above.

---

§6 Recommended sequencing

Direct merge ast-dataflow-tooling → production-readiness in S11, with pre-flight steps from §5 completed first. Do not run S10 Wave 1 work on production-readiness before the merge.

Reasoning:

• Wave 1 WPs (R-WP17 CI gate, etc.) should land on ast-dataflow-tooling first, then merge as a unit. Splitting Wave 1 work between branches creates a second divergence to reconcile. The ast-dataflow track has been operating in isolation precisely so primitives can stabilise before they touch the wider project.
• No need to “run ast-dataflow against production-readiness branch first to detect drift.” The 12 conflicts are all in .claude/, docs/plans/phase-0-investigation/, and a roadmap rendering — none touch the ast-dataflow primitives or fixtures. Drift detection on the primitives themselves would only matter post-merge.
• Production-readiness is the right intermediate destination. Per the user’s framing, ast-dataflow → production-readiness consolidates 9 sessions of tooling work into the wider track before any main-branch promotion. Skipping production-readiness and going direct to main would conflict with the same 12 files anyway, plus a wider surface from production-readiness’s 52 commits to main.

Order of operations for S11:

1. (S11 Wave 0) Apply pre-flight items §5.1-§5.6 on ast-dataflow-tooling directly (or via a short-lived prep branch). Commit. Push.
2. (S11 Wave 1) Switch to production-readiness worktree. git pull. Attempt merge. Apply remaining manual resolutions (mostly §5.2 roadmap re-render). Resolve, commit, push.
3. (S11 Wave 2 or S12) After verification, plan production-readiness → main merge separately.

---

§7 Estimated merge effort

Phase	Effort
Pre-flight (§5 items 1, 3, 4, 6 — terminology + scratch files)	1-1.5h
Pre-flight §5.2 (JSON roadmap canonicalisation prep)	30-60 min
Actual merge + 12 conflict resolutions	2-3h
Post-merge sanity (bun run knip, full test run, manual smoke)	30-60 min
Total	4-6 hours

A single S11 wave (2h max per CLAUDE.md agent budget) cannot complete the merge; it should be split: pre-flight in one wave, the merge itself in a second wave, post-merge verification in a third. Or, since the bulk of the work is non-agent (Liam-judgement calls on terminology + roadmap canonicalisation), the merge wave can be longer if Liam drives it interactively.

Confidence: Medium-high. The conflict count is small (12) and most are mechanical. The unknowns are (a) which branch wins for workflow-agent terminology and (b) whether the roadmap JSON can be cleanly canonicalised. Both are decisions, not implementation risks.

---

Appendix: throwaway test branch cleanup verification

cd /Users/liamj/Documents/development/knowledge-hub-production-readiness
git status                  # On branch production-readiness (clean working tree, only untracked .bak files)
git branch -a | grep dryrun # (no output — branch deleted)

Test branch ast-dataflow-merge-dryrun-tmp deleted post-investigation. No merge commit landed on production-readiness. No push.

Note on branch tip used: the dry-run was performed against ast-dataflow-tooling at tip 44003a8a (pulled at start of session). Sibling S10 Wave 0 agents subsequently committed two new investigation docs (Wave 0-A 1e0f5dfa and Wave 0-B 8eda3718) adding docs/specs/id-16-ast-dataflow-tool/investigations/S10-route-retirement-inventory.md + S10-intelligence-cluster-fate.md. Both files are new and do not exist in production-readiness, so they merge cleanly and do not change the §3 conflict count.