feat(preflight): SessionEnd queue-drain integration + Flow 4b (#156 PR B)

[Knapp-Kevin]

Summary

• Closes the cross-flow correction-capture path opened by [P1] SessionEnd capture-corrections hook is silently broken — design pivot to next-session surfacing #156 PR A. Capture-corrections in-session mode (invoked by preflight Step 3.5) now drains <repo>/.bicameral/pending-transcripts/ before scanning recent in-session turns.
• Drained ask-corrections share the existing preflight ≤4-question cap; remaining pending files stay queued for the next preflight to pick up. Multi-session backlog clears across multiple preflights, not in one.
• New e2e Flow 4b validates the full SessionEnd-write → next-preflight-drain → ingest pipeline end-to-end via three filesystem + ledger assertions.
• New --flow PATTERN argparse filter on tests/e2e/run_e2e_flows.py:main() enables targeted CI invocations: --flow "Flow 4" runs Flow 4 + Flow 4b together (cross-flow validation), --flow "Flow 4b" runs Flow 4b only (dev-velocity workflow).

Closes #156 fully (PR A shipped the queue-write; PR B closes the read/drain side).

Linked issues

Closes #156

Refs PR A: #198 (now merged on dev)

Phases

Phase 1 — capture-corrections + preflight SKILL.md updates

• skills/bicameral-capture-corrections/SKILL.md: in-session mode "## Steps" gains Step 0 (queue drain with ≤4-cap and partial-archive rules). Telemetry section gains g11_queue_drained / g11_queue_remaining / g11_queue_cap_hit diagnostic counters.
• skills/bicameral-preflight/SKILL.md: Step 3.5 description gains a forwarding paragraph. Canonical drain rubric stays in capture-corrections (single source of truth).

Phase 2 — Flow 4b cross-flow assertion + --flow filter

• tests/e2e/prompts/flow-4b-queue-drain.md: new prompt (trivial docstring add; no mention of bicameral / queue / corrections — the drain happens automatically via the preflight hook).
• tests/e2e/run_e2e_flows.py:
  • assert_flow_4b: three assertions (pending-transcripts/ empty, processed-transcripts/ contains archived file, ledger has source=agent_session decision).
  • _filter_flow_plan(plan, pattern): pure substring filter helper.
  • --flow PATTERN argparse argument on main(). Exit 2 on no-match typo with available-flows hint.
  • FlowSpec for Flow 4b inheriting session_group="dev_session".
  • Flow 4 advisory updated to point at Flow 4b instead of "deferred to PR B".
• tests/test_run_e2e_flows_filter.py: 3 functionality tests for _filter_flow_plan (no-pattern path, multi-match substring, exact match). Follows tests/test_e2e_asserters.py:30-42 shutil.which stub precedent.

Test plan

• pytest tests/test_run_e2e_flows_filter.py -v — 3/3 filter tests pass
• pytest tests/test_session_end_queue_writer.py tests/test_session_end_hook_drift.py tests/test_setup_wizard.py tests/test_e2e_asserters.py -v — 31/31 dependent tests still pass (PR A primitives, drift tests, e2e asserter unit tests)
• ruff check . && ruff format --check . — clean
• mypy tests/e2e/run_e2e_flows.py — clean
• argparse smoke-check: --flow "Flow 99 nonexistent" → exit 2 with Available: [..., 'Flow 4b', ...] hint
• CI runs the full test suite + e2e flow assertions on Linux
• python tests/e2e/run_e2e_flows.py --flow "Flow 4" validates the Flow 4 + Flow 4b cross-flow path end-to-end (deferred to CI environment with DESKTOP_REPO_PATH set)

Notes for review

• Branch is based on current upstream/dev (post-feat(hooks): SessionEnd queue-write pivot per #156 #198, post-feat(#114): CI grounding lint — plan paths + PR-body refs #121).
• The asserter follows the existing _validate_flow4_via_ledger pattern — uses _snapshot_ledger() + _count_agent_session_decisions() already in the file.
• Substring filter design rationale: "Flow 4" matches both Flow 4 and Flow 4b naturally, which is exactly the shape the cross-flow CI command needs (Flow 4b requires Flow 4 to populate the queue first via its SessionEnd hook). Narrow exact-match filtering uses --flow "Flow 4b".
• Plan-grounding lint (CI lint for unstructured references in plan files and PR bodies #114, just merged) ran on this PR's plan file at audit-prep time — see audit history for the F1 finding it caught (the original --flow "Flow 4b" CI command referenced an argument that didn't exist; F1 was resolved by adding the argparse arg as part of Phase 2).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 71b5a7f2-01e9-459f-a0f5-db0987b95f70

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 156b-preflight-queue-drain

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}