Repository navigation
refactor(session-flow): promote transcript_reader.py to a shared copy other plugins can vendor #6087
Description
No related PR yet; blocks part of the planned /performance:go-faster skill (branch go-faster-skill).
Problem
plugins/session-flow/scripts/transcript_reader.py is the shared transcript reader (ADR 0046), and it depends only on the standard library. ADR 0046's rule that new code imports the shared reader applies only inside session-flow, because a plugin cache cannot see another plugin's files.
The planned /performance:go-faster skill has to read the current session's transcript read-only. That read drives its in-session now findings: turns, waits, repeated failures, sequential calls that could run in parallel, and cache-token counts. Without a shared copy, performance would need its own reader, which would be a second way to parse transcripts.
Proposed approach
Promote the reader to a canonical lib/transcript_reader.py and register <canonical> <copy> lines for session-flow and performance in scripts/shared-copies.txt (ADR 0019). scripts/sync-shared-copies.sh then generates both copies.
Integration contract go-faster relies on
- Until this lands, go-faster ships a minimal interim reader inside
plugins/performance/scripts/findings.py(transcript-counts). It reads only the fields it needs and is marked temporary. - Once this lands, go-faster imports the vendored
plugins/performance/lib/transcript_reader.pyand deletes the interim reader. Its output contract does not change.
Acceptance criteria
-
lib/transcript_reader.pyis the canonical, andscripts/shared-copies.txtlists the session-flow and performance copies. - Session-flow's imports resolve to its generated copy, and its tests pass.
Activity
kyle-sexton commentedon Oct 3, 2026
The go-faster plan was updated to avoid an interim second reader.
go-faster will register
plugins/session-flow/scripts/transcript_reader.py plugins/performance/lib/transcript_reader.pyinscripts/shared-copies.txt.scripts/sync-shared-copies.shthen generates the copy, and session-flow's own file stays as it is.If the sync script requires a canonical under
lib/, go-faster falls back to a byte copy, plus a parity test that fails when the copy drifts from session-flow's file.What remains for this issue is moving the canonical to
lib/. The performance copy keeps working either way.kyle-sexton commentedon Oct 4, 2026
This was generated by AI during triage.
Routing: human-gated, blocked on #6138 (
work-class: scoped, refactor,priority: low).Findings:
lib/") is not needed. The registry loader checks only that the canonical exists and that the copy sits inside a plugin, and a non-lib/canonical is already registered (docs/conventions/standards/README.md). Basis:scripts/sync-shared-copies.sh:28-55,scripts/shared-copies.txt.lib/when its cluster migrated, so that plugin's copy is generated like the rest and every copy stays byte-identical. With session-flow's file as canonical, the session-flow copy has no generated header and the performance copy does. Basis:docs/adr/0019-share-code-across-plugins-by-vendoring-with-a-sync-gate.md:117-118.ci-statusfailing) adds the registry lineplugins/session-flow/scripts/transcript_reader.py plugins/performance/lib/transcript_reader.pyon its branch. This item rewrites that line, so doing it before feat(performance): add go-faster whole-process speed sweep #6138 merges forces a conflict on feat(performance): add go-faster whole-process speed sweep #6138.To unblock: once #6138 merges, flip with:
gh issue edit 6087 -R melodic-software/claude-code-plugins --add-label "agent-ready,status: ready" --remove-label "needs-human"Agent Brief
Type: Task (refactor)
Summary: Move the shared transcript reader's canonical to the repository's shared library directory so every plugin copy, session-flow's included, is generated output.
Current behavior:
Session-flow's own transcript reader file is the canonical source; any other plugin's copy is generated from it, so copies are not byte-identical to each other.
Desired behavior:
The canonical lives in the repository-root shared library directory beside the other canonicals. The shared-copies registry generates both the session-flow copy and the performance copy from it. Session-flow's module path and imports are unchanged.
Key interfaces:
<canonical> <copy>lines) and its sync script (--check,--check-bump).transcript_readermodule's public surface (iter_records,record_kind,UsageLedger,is_typed_turn,RECORD_TYPES): unchanged.Acceptance criteria:
--checkpasses; session-flow and performance versions and CHANGELOGs are bumped.Out of scope:
kyle-sexton commentedon Oct 11, 2026
Owner decision (2026-10-11): Treat as unblocked (gate PR #6138 merged 2026-10-04): move the canonical transcript_reader.py to lib/ and have the shared-copies sync generate the session-flow and performance copies.
Recorded by the coordinating agent session with the owner's approval. Removing
needs-human; implementation is queued and will link its branch here.kyle-sexton commentedon Oct 13, 2026
Owner batch-ratified this admission in an attended session on 2026-10-12: work-class: scoped. Rule: class C1-C3, no trust surface, the independent check confirmed the recorded decision, and no owner step remains.
kyle-sexton commentedon Oct 14, 2026