claude-memory + session-flow: memory_dir seam parsing residuals — '#' truncation in quoted values, absent-config save-point fallback

[kyle-sexton]

Category: bug (edge-case residuals) · Source: pre-merge digest of PRs #469/#470 — author-dispositioned VALID(defer) review findings that were deferred without a tracked follow-up (the gap the v4 lane rules now close).

Residuals

1. seam="${seam%%#*}" truncates a quoted memory_dir value containing # — same naive-string-op class as the whitespace bug both PRs DID fix. Present in both the orphan-rule-check (fix(claude-memory): resolve memory_dir from topic-docs seam in orphan-rule-check #470) and retro HANDOFF_DIR (fix(session-flow): derive retro HANDOFF_DIR from resolved memory_dir #469) resolution snippets.
2. fix(session-flow): derive retro HANDOFF_DIR from resolved memory_dir #469: when topic-docs.yaml is absent, the snippet defaults to .work without consulting a CLAUDE.md / .claude/rules-declared save-point location.

Ask

Harden the shared parsing shape once (both sites use the same sed/strip pattern — candidate for one shared helper per #474) and add the fallback lookup. Regression cases for #-in-quoted-value and absent-config.

Related

#419 #420 (source issues) · #474 (shared config-value parsing helper) · PRs #469 #470

[kyle-sexton]

This was generated by AI during triage. · Category: bug (edge-case residuals) · Priority: priority: high (session-flow is in the north-star set; pipeline correctness). Self-labeled severity: edge-case — noted for implementer sub-sort within high. Routed status: ready.

#482 — harden the shared memory_dir seam parse (quote-aware #, real fallback chain)

Two residuals were deferred from the #469/#470 review without a tracked follow-up. Both live in the concern-file memory_dir seam parse that #469 and #470 introduced independently but identically — the retro HANDOFF_DIR resolution and the audit orphan-rule-check both open-code the same four-line strip. This is the same naive-string-op class as the trailing-whitespace bug those PRs already fixed; it just wasn't finished.

(Pre-implementation gate: confirm both sites still open-code the identical strip in the target versions before extracting — the strip shape is attributed to #469/#470, not independently re-verified against a moving main.)

Residual 1 — # inside a quoted value is truncated

The comment-strip (%%#*, keep everything before the first #) runs before the quote-strip. So a value that legitimately contains # inside quotes — memory_dir: "a#b", or memory_dir: ".work/#topic" — is cut at the first # down to "a, and only then are the quotes peeled, yielding a. The # and everything after it are lost.

Correct parse rule (quote-respecting). Per YAML scalar/comment semantics, a # introduces a comment only when it is outside quotes and at line-start or preceded by whitespace. So:

• Quoted value ("…" / '…'): the scalar is the content between the matching quotes — every # inside is data and MUST be preserved. Only text after the closing quote is a trailing comment and is discarded.
• Unquoted value: strip a trailing comment only at a # that is preceded by whitespace ( #…); a # adjacent to a non-space character (a#b) is part of the scalar, not a comment.
• Then peel the matched surrounding quote pair, trim surrounding whitespace, normalize a trailing slash — the order must be quote-resolution first, comment-strip made quote-aware, never a blind %%#* at the front.

The current %%#*-first ordering violates this for every quoted-value case; that's the whole bug.

Residual 2 — absent config jumps straight to .work

Both sites seed memory_dir=".work" and override it only when .claude/topic-docs.yaml yields a value. When that file is absent (or lacks the key), resolution defaults to .work without consulting rung 2 of the contract's resolution order — a working-docs / save-point location declared in the consumer's CLAUDE.md or .claude/rules. A repo that declares its convention there but ships no concern file is silently sent to .work.

Fallback chain (must match the contract's rung order):

1. .claude/topic-docs.yaml memory_dir present → use it.
2. Absent/empty → a save-point / working-docs convention declared in CLAUDE.md / .claude/rules → use that.
3. Otherwise → documented default .work.

(The contract's interactive/inferred-layout rungs sit between 2 and 3; these are non-interactive scripts, so they degrade straight to the .work default and should note that inferred/interactive resolution is deferred to the caller rather than silently collapsing rung 2.)

Recommendation — one shared helper, not two inline fixes (#474)

There is no shared config-value parser today; each site duplicates the block verbatim, which is exactly why one review-deferred bug became two. Fixing both inline re-forks the duplication. Extract a single parse-concern-value helper — the "shared config-value parsing helper" #474 already calls for — with a behavioral contract:

• Input: concern-file path + key name (and the declared-convention lookup for the fallback).
• Output: the resolved value — quote-aware comment-stripped, quote-peeled, whitespace-trimmed, trailing-slash-normalized — or the fallback-chain result when the key is absent; empty only when nothing resolves.
• Consumers: the claude-memory audit orphan-rule-check memory_dir resolution and the session-flow retro HANDOFF_DIR resolution both call it; neither keeps its own strip.

Because both plugins implement the single topic-docs contract (which already centralizes the resolution order "identically for every implementer"), the helper's home is upstream in the shared/contract distribution and is sync-materialized into both plugin bindings — not hand-copied into each. Duplicating it per-plugin would recreate the exact drift this issue exists to close.

Acceptance criteria

• A single shared parse-concern-value helper exists upstream and is the only memory_dir seam parser; both consuming sites delegate to it (one code path).
• Regression — #-in-quoted-value preserved: memory_dir: "a#b" (and single-quoted, and .work/#topic) resolves to the full value including #, never truncated at the first #.
• Regression — absent-config consults the declared location before .work: with no topic-docs.yaml but a CLAUDE.md / .claude-declared save-point location, resolution returns that declared location, not .work.
• Existing behavior held (no regression): an unquoted trailing # comment is still stripped; surrounding whitespace trimmed; trailing slash normalized; empty/absent → .work.
• Helper unit-tested directly for the two regression cases plus the held-behavior cases; both consuming sites verified to route through it.

Relations: realizes #474 (the shared config-value parsing helper); residuals deferred from the #469/#470 review; seam resolution originally sourced from #419/#420.

Decision defaulted: harden the parse in ONE shared config-value helper (per #474) rather than duplicating the fix at both the claude-memory and session-flow sites — veto before merge