claude-memory/session-flow/docs-hygiene: memory_dir/contract_dir config-value parsing is hand-rolled and copy-pasted across ≥4 files, not a shared helper

[kyle-sexton]

Lane

babysit (safe tier, /loop 15m /source-control:babysit-prs)

Triggering example

PR #469 (fix/420-retro-resolve-memory-dir): worker fixed a Codex P2 in plugins/session-flow/skills/retro/context/session.md — a hand-rolled sed-extract-then-strip-whitespace snippet for reading memory_dir out of .claude/topic-docs.yaml was collapsing interior whitespace in quoted values (".agent work" → .agentwork), not just trimming. Fixed with a trailing-only trim.

The fix immediately re-triggered a Codex re-review that found a second, same-class bug in the identical snippet: a # inside a quoted value is also mishandled (the hand-rolled parser has no comment-vs-value disambiguation). The worker correctly declined to patch this in place — because the exact same hand-rolled sed/bash parsing shape is copy-pasted, not shared, across at minimum:

• plugins/session-flow/skills/retro/context/session.md (this PR)
• plugins/claude-memory/skills/audit/scripts/orphan-rule-check.sh (sibling PR fix(claude-memory): resolve memory_dir from topic-docs seam in orphan-rule-check #470)
• plugins/docs-hygiene/skills/audit-noise/scripts/lib/noise-shapes.sh (cited in claude-memory: orphan-rule-check hardcodes .work/ exclusion instead of resolving memory_dir from topic-docs seam #419 as the "fleet precedent" others should copy)
• a session-flow handoff structure.md snippet

Fixing the whitespace bug in one copy does not fix it in the other three; each will independently surface the same class of Codex finding (whitespace-in-value, hash-in-value, and likely YAML escape sequences) on its own PR, one at a time.

Observed vs expected

• Observed: #419 and #420 (already filed, both open) treat this as "some consumers hardcode .work/ instead of resolving memory_dir" and point at noise-shapes.sh as the correct fleet precedent to copy. That framing undersells the actual gap: even the cited "correct" precedent is itself a hand-rolled, not-fully-robust scalar parser (doesn't yet handle #-in-value; likely doesn't handle YAML escapes either), and it is copy-pasted rather than shared, so any robustness fix made in response to one PR's Codex review never reaches the sibling copies.
• Expected: a single shared helper (bash function or small script) that resolves a .claude/topic-docs.yaml key robustly — handling quoted/unquoted values, interior whitespace, # inside quotes, and YAML escapes — sourced or invoked identically everywhere memory_dir/contract_dir is read, so a robustness fix lands once and propagates. #419/#420 are the right first step (stop hardcoding .work/); this issue is the follow-on it doesn't yet cover (stop copy-pasting the parser itself).

Category

improvement

Note

Related to but distinct from #419 and #420 — those are "hardcoded default vs resolved value" bugs; this is "the resolution snippet itself is duplicated and insufficiently robust." Not filing as a duplicate; commenting cross-reference isn't appropriate since neither existing issue's acceptance criteria would cover extracting a shared helper.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human (cross-plugin design). This is the SSOT-promotion trigger that the #419 plan explicitly deferred to ("if a third consumer needs the same resolution → promote a shared topic-docs memory_dir resolver"). It's genuinely distinct from #419/#420 (those are "hardcoded .work/ vs resolved value"; this is "the resolver snippet itself is duplicated and insufficiently robust").

The load-bearing design question is a cache-isolation constraint: each plugin is installed into its own isolated cache dir, so a plugin cannot simply source a sibling plugin's helper file — a "single shared helper sourced everywhere" across claude-memory / session-flow / docs-hygiene is not trivially feasible as stated. Options a human must weigh: (a) each plugin vendors an identical robust helper kept in sync via the marketplace sync path, (b) a tiny robust parser is inlined but generated from one source, (c) accept per-copy divergence. Plus the robustness scope (quoted/unquoted values, interior whitespace, #-in-value, YAML escape sequences — Codex is finding these one class at a time, PR by PR).

Note the interaction: the #419 plan currently inlines the sed-extract mirroring noise-shapes.sh — but this issue observes that precedent itself mishandles #-in-value. If the shared-helper direction is chosen, #419's inline approach should adopt the robust helper rather than copy the flawed precedent. Priority: medium (cross-cutting refactor; spans non-north-star plugins, though session-flow is affected).

[kyle-sexton]

Gap-hunt input (control tower 7/19): recommend WIDENING this issue rather than filing a sibling — signal mining found the seam-resolution duplication class extends beyond memory_dir/contract_dir parsing to tracker-seam resolution and fallback logic (#482 #470 #469 #432 #365 #369 share the root). One shared seam-resolver helper in lib/ with fixture tests covers the class; per-file parsing fixes leave the generator in place.

[kyle-sexton]

This was generated by AI (needs-human decision-brief pass).

Decision brief (2-minute read)

Problem. The memory_dir / contract_dir resolution snippet (sed-extract + strip of .claude/topic-docs.yaml) is hand-rolled and copy-pasted across ≥4 files rather than shared, so each robustness fix (interior-whitespace, #-in-quoted-value, YAML escapes) lands in one copy while the siblings keep surfacing the same class of Codex finding one PR at a time.

Today. The duplication is real and the design question is already half-answered. #482 (OPEN, status: ready, priority: high) ratifies extracting a single parse-concern-value helper for the two hot memory_dir sites (retro HANDOFF_DIR + audit orphan-rule-check), homed upstream in the shared-contract distribution and sync-materialized into each plugin binding — which directly answers this issue's cache-isolation constraint (plugins cannot source a sibling's helper; vendor-via-sync instead of hand-copy, per the point-don't-copy discipline). What #482 does not cover: the other consumers this issue names (docs-hygiene noise-shapes.sh, the session-flow handoff structure.md snippet), and the gap-hunt comment's proposed widening to the whole tracker-seam-resolution class (#470 #469 #432 #365 #369).

Options.

1. RECOMMENDED — Adopt claude-memory + session-flow: memory_dir seam parsing residuals — '#' truncation in quoted values, absent-config save-point fallback #482's upstream-helper-via-sync mechanism as the pattern, and scope this issue as the bounded umbrella that extends that one helper to the remaining memory_dir/contract_dir consumers. claude-memory + session-flow: memory_dir seam parsing residuals — '#' truncation in quoted values, absent-config save-point fallback #482 lands the helper for the two hot sites first; this issue tracks pointing docs-hygiene / session-flow-handoff at the same synced helper so no copy keeps its own strip. Bounded, additive, reversible; the mechanism is already ratified, so this is extension, not new design. Leaves the broad tracker-seam-resolution refactor explicitly out.
2. Full-class widen — one shared seam-resolver helper covering config-value parsing AND tracker-seam resolution/fallback (the gap-hunt comment's fix(claude-memory): resolve memory_dir from topic-docs seam in orphan-rule-check #470 fix(session-flow): derive retro HANDOFF_DIR from resolved memory_dir #469 session-flow: topic-docs placement contract resolved via hardcoded raw.githubusercontent URL instead of bundled copy #432 work-items: github adapter should resolve a consumer-local gh-bot.sh wrapper independent of adapter location #365 work-items: define how consumer-local / shadowed adapters resolve the shared seam lib/ #369). Highest leverage — kills the whole duplication class once — but a large cross-plugin refactor with real scope/verification cost, and harder to reverse once many sites are rewired to it. Best gated behind claude-memory + session-flow: memory_dir seam parsing residuals — '#' truncation in quoted values, absent-config save-point fallback #482 landing plus a fixture-test harness proving the helper against each class.
3. Close as subsumed by claude-memory + session-flow: memory_dir seam parsing residuals — '#' truncation in quoted values, absent-config save-point fallback #482. If the two hot sites are the only ones that matter in practice, claude-memory + session-flow: memory_dir seam parsing residuals — '#' truncation in quoted values, absent-config save-point fallback #482 already delivers the helper and this issue is redundant. Cheapest, but leaves the named docs-hygiene / session-flow copies free to re-fork the flaw.

Cross-links. #482 (ready — the first materialization of the shared helper; its mechanism answers this issue's cache-isolation constraint). #419 / #420 (source issues — hardcoded .work vs resolved value, the narrower predecessor).

Decision asked: Bounded-widen (extend #482's synced helper to the remaining memory_dir consumers), full-class-widen (one seam-resolver for the whole class), or close as subsumed by #482?

[kyle-sexton]

Operator decision (2026-07-19, decision-session final batch; relayed).

ACCEPTED — the brief's RECOMMENDED bounded widen: fold the remaining verified hand-rolled copies (docs-hygiene, session-flow) into #482's ratified parse-concern-value helper adoption; the wider tracker-seam parsing class stays a separate audit task (its five cited files were not independently re-verified — the audit verifies before it sweeps).

Re-intake: removing needs-human, adding priority: needs-triage for routing.

[kyle-sexton]

This was generated by AI during triage.

Routing status: ready per ratified decision. Operator ACCEPTED the bounded-widen: fold the remaining verified hand-rolled copies (docs-hygiene, session-flow handoff structure.md) into #482's already-ratified parse-concern-value helper adoption (upstream-owned, sync-materialized into each plugin binding). The broader tracker-seam-resolution class (#470 #469 #432 #365 #369) stays a separate, independently-verified audit task — not folded here.