knowledge/youtube-digest: centralize .work/<epic>/<slug> sub-path shape + binary-retention landing — deferred from #558

[kyle-sexton]

Context

Deferred scope from #558 ("youtube-digest: externalize hardcoded assumptions + reconcile corpus durability"), split out in #854. #854 shipped the doc/prose surface of #558 (synthesis-target --target argument, ephemeral/target-bound reframe, named-not-silent gap callouts). This issue tracks the two remaining items from #558 that require actual code changes, not documentation:

A. Landing sub-path shape

library_dir (existing userConfig seam) relocates the .work/<watch-epic>/<video-slug>/ work root, but the sub-path's shape is a literal hardcoded across roughly ten extraction scripts — run-watch.js, watch-state.js, queue-claim.js, run-transcript.js, derive-video-slug.js, preflight-metadata.js, and others under plugins/knowledge/skills/youtube-digest/extraction/. A corpus consumer whose own convention is sources/<type>/<slug>/ (see the melodic-software/knowledge-corpus README) cannot get that shape today; the shape is not represented as a single value anywhere, so there's no single seam to make configurable without first centralizing the path construction.

Open design call before implementation: what seam represents the shape (a new userConfig template string with {epic}/{slug} placeholders? a tracked-convention file the skill reads per the plugin philosophy's four config seams?), and whether centralizing the ~10 call sites is a pure refactor or needs test updates per site.

B. Binary retention (raw video / bulk frames / contact sheets)

Raw video, bulk frames, and contact sheets are OS-temp-only by design (never land in the repo) — the video-digest slice convention's rationale is reproducibility over storage cost. A corpus consumer wants these retained as a durable, re-runnable synthesis substrate (the corpus README makes source video the durable substrate). This needs:

• A retention trigger/policy (opt-in via a new seam, presumably userConfig or the same shape-convention file from item A).
• LFS-aware landing: where binaries land, and how the pipeline behaves when the consumer's .gitattributes LFS-tracks them vs. plain git.
• Reconciling .work/'s "never-committed scratch" framing (per the topic-docs convention) against a committable sources/youtube/<slug>/ location for these specific binaries, without breaking the existing slice's other durable-but-plain-git artifacts.

Open design call before implementation: retention is presumably opt-in (default stays temp-only, preserving today's zero-config behavior per the plugin philosophy's "non-conflicting good-practice defaults" lane), but the trigger mechanism and LFS-detection logic are unspecified.

Out of scope (tracked elsewhere)

Section D of #558 (corpus .gitattributes LFS gaps, pre-LFS epub blobs) belongs to melodic-software/knowledge-corpus, not this repo.

Acceptance sketch

• Sub-path shape is a single documented seam, not ~10 hardcoded literals; library_dir and the new seam compose without a split-root bug (see docs(knowledge): youtube-digest synthesis target + named agnosticism gaps #854's "share the same root" discipline for library_dir as the pattern to extend, not duplicate).
• Retention is opt-in, default-off (zero-config behavior preserved), documented, and LFS-aware where the consumer's .gitattributes requires it.
• SKILL.md's two "tracked follow-up, not yet built" callouts (added in docs(knowledge): youtube-digest synthesis target + named agnosticism gaps #854) are resolved or narrowed once this lands.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human (genuinely open design). Deferred CODE scope from #558 (parent, open); the doc/prose surface shipped via #854. Two parts, each carrying an explicit open design call the reporter flagged:

• A. Sub-path shape seam — the .work/<epic>/<slug>/ shape is a hardcoded literal across ~10 youtube-digest extraction scripts (run-watch, watch-state, queue-claim, run-transcript, derive-video-slug, preflight-metadata, …); library_dir relocates the work root but not the shape, so a corpus consumer wanting sources/<type>/<slug>/ can't get it. Open decision: what seam represents the shape — a userConfig template string with {epic}/{slug} placeholders, or a tracked-convention file per the plugin philosophy's four config seams — and whether centralizing the ~10 call sites is a pure refactor or needs per-site test updates.
• B. Binary retention (raw video / bulk frames / contact sheets) — OS-temp-only by design today; a corpus consumer wants durable, re-runnable, LFS-aware retention. Open decision (unspecified): the retention trigger/policy (opt-in seam), the LFS-detection logic, and reconciling .work/'s "never-committed scratch" framing against a committable sources/youtube/<slug>/ location without breaking the slice's other plain-git durable artifacts.

Why human-gated, not decision-defaulted: hits all three needs-human reserves — open design space (seam architecture), product intent (retention default / zero-config preservation), and cross-repo policy (the melodic-software/knowledge-corpus convention + .gitattributes/LFS). B's mechanism is unspecified (not a single vetoable fork), and A's seam choice shapes the plugin's public config surface. Acceptance sketch preserved on the issue (shape = single documented seam composing with library_dir without a split-root bug; retention opt-in/default-off/LFS-aware; #854's two "not yet built" SKILL.md callouts resolved/narrowed once this lands).

Priority medium (knowledge plugin is outside the week's priority set → lower within-tier ordering; reporter severity: n/a). Type Feature. wayfind: design applied. automated provenance label retained.

[kyle-sexton]

This was generated by AI (decide lane — decision-brief pass).

Problem

A — sub-path shape seam. library_dir relocates the work root, but the .work/<epic>/<slug>/ sub-path shape is fixed in code and agent-prose, so a corpus consumer whose convention is sources/<type>/<slug>/ cannot get it. B — binary retention. Raw video / bulk frames / contact sheets are OS-temp-only by design, with no opt-in, LFS-aware path to retain them as a durable, re-runnable substrate. The two are coupled: B's landing path is whatever shape A resolves — you cannot durably land binaries until you can express where the slice lives.

Today (verified against main @ a37cf60)

• Root is already a seam; shape is not. resolveWorkRoot() reads YOUTUBE_WORK_ROOT → CLAUDE_PROJECT_DIR → cwd() — extraction/lib/work-root.js:18-19. library_dir is a userConfig directory (default ".") — .claude-plugin/plugin.json:30-35 — wired via run.mjs --work-root → YOUTUBE_WORK_ROOT env (skills/youtube-digest/SKILL.md:40-52).
• Shape is mostly centralized, not "~10 scattered literals." The choke point is resolveWorkSliceDir(repoRoot, slug) = path.join(repoRoot, ".work", YOUTUBE_WATCH_EPIC_DIR, slug) — extraction/transcript/derive-video-slug.js:44-46; epic constant "youtube-watch" at :7. The real surface to centralize is small: (1) one bypasser — resolveEpicDir() re-joins the .work literal itself instead of calling the helper (extraction/watch/queue-claim.js:30-31); (2) agent-prose embeddings of .work/<watch-epic>/<slug>/ in watch-state.js:162,182, SKILL.md:52, and context/.
• Layout is test-asserted. derive-video-slug.test.js:33-34 asserts the exact path.join("/repo",".work",epic,"talk-abc") output — changing the helper's shape breaks this test, so centralizing is not a pure refactor (see A's sub-question).
• B today. Video / bulk frames / contact sheets = "OS temp only / never in repo" (SKILL.md:18,370-371). .work/ slice text artifacts are durable + committed (plain git) — the "never-committed scratch" framing is already formally carved out for this skill (SKILL.md:36). But snapshot-bootstrap.js writes a per-dir .gitignore (*.jpg) into key-frames/contact-sheets/ — that self-ignore would fight any frame-retention path and must be reconciled.
• docs(knowledge): youtube-digest synthesis target + named agnosticism gaps #854 is an open draft PR (branch docs/558-youtube-digest-corpus-durability), not merged — the two named-limitation callouts ("Templating the sub-path shape is a tracked follow-up, not yet built"; "a documented, LFS-aware retention path is a tracked follow-up, not yet built") live on that branch, not on main.

Governing constraint

The config-ownership table in docs/PLUGIN-PHILOSOPHY.md:162-173 picks the owner: personal/admin scalar → userConfig; tracked repository convention or rich team policy → a documented consumer-project file; invocation-specific choice → explicit argument. Critically, userConfig is not repository configuration — Claude Code reads pluginConfigs only from user/managed settings, never project settings (:175-178). The discriminating question for A: is the sub-path shape a personal preference or shared repo/team config?

Decision A — what seam represents the sub-path shape

A corpus's sources/<type>/<slug>/ layout is committed to the corpus, identical across every consumer and CI run — i.e. shared repo/team config, not a personal scalar. Reinforced by: (a) a {epic}/{slug} template cannot express sources/<type>/<slug> — the <type> taxonomy/category dimension is team policy, not a slug; (b) library_dir's own description already encodes hybrid precedence ("a convention declared in your project's CLAUDE.md or rules takes precedence"). So the governing constraint points away from a pure userConfig string.

• A1 — Tracked-convention file, primary; userConfig as personal override (hybrid). ✅ RECOMMENDED. The shape template (with {epic}/{slug} and a {type}/category placeholder) is declared in a documented consumer-project file — the philosophy's home for a tracked team convention — read at the same precedence tier library_dir already documents; a personal userConfig string overrides for the solo case. Composes with the existing library_dir root seam (root × shape are orthogonal). Zero-config default .work/{epic}/{slug} preserves today's behavior exactly. Reversibility: high — additive, default-preserving; removing it restores the literal. Cost: two resolution sources + precedence docs.
• A2 — userConfig template string only (e.g. work_subpath, default .work/{epic}/{slug}). Simplest; one channel; composes with library_dir (also userConfig). But conflicts with the governing constraint (shared layout ≠ personal scalar; unreadable from project settings) and the {type} taxonomy doesn't fit a placeholder-only string. Reversibility: high. Reasonable only if the team decides the shape is genuinely a personal scalar.
• A3 — Tracked-convention file only (no personal override). Cleanest philosophy fit for pure team/enterprise use; drops the solo-override convenience library_dir set precedent for. Reversibility: high.

Sub-question (refactor vs. test updates): not a pure refactor. It needs (1) a code consolidation — route resolveEpicDir (queue-claim.js:30-31) through the one shape helper and parametrize the helper by the resolved template — which requires updating the layout-asserting tests (derive-video-slug.test.js:33-34, and the lane-layout contract in check-watch-outcomes-layout.test.js); and (2) prose threading — the shape variable must flow into SKILL.md + context/ agent instructions the same way --work-root already does (SKILL.md:40-52), since those literals are agent-followed, not just code. Small surface, but two-layered.

Decision B — retention trigger + landing + LFS

Preserve zero-config default-off. B's landing path = A's resolved shape (decide A first).

• B1 — Opt-in userConfig boolean retain_binaries (default false) + detection-first LFS gate. ✅ RECOMMENDED. Retained binaries land in the A-resolved slice dir (…/media/); LFS by detection, never assumption — inspect the consumer's .gitattributes for a glob covering the extension (mkv/mp4/jpg/webp/pptx) and stage only if covered, else leave on disk + warn (never silently commit a large blob to plain git — the philosophy's presence-gated posture). Must reconcile the *.jpg self-ignore (snapshot-bootstrap.js) so retained frames aren't re-excluded. Reversibility: high — default-off means zero-config users see no change; retire by dropping the flag.
• B2 — Tracked-convention retention policy (which artifact classes retain, where) in the same consumer-project file as A1. Richer, team-level, pairs naturally with A1 for enterprise corpus use; heavier. Reversibility: high.
• B3 — Per-invocation --retain argument (invocation-specific tier). Simplest, most reversible, no persistent config — but not durable across resume unless recorded in README.md (the --target line precedent). Reversibility: highest.

Cross-links & flags

• youtube-digest: externalize hardcoded assumptions + reconcile corpus durability (agnosticism + retention + synthesis split) #558 — parent (open); this is its deferred code scope (§A landing-shape, §B durability).
• docs(knowledge): youtube-digest synthesis target + named agnosticism gaps #854 — doc surface; open draft PR, not yet merged (docs/558-youtube-digest-corpus-durability). Its two "tracked follow-up, not yet built" SKILL.md callouts are the prose placeholders this issue resolves once built. Comment-only here — not touching that PR.
• docs/PLUGIN-PHILOSOPHY.md:162-178 — the config-seam ownership table + "userConfig is not repository configuration" is the governing constraint on A's seam choice.
• ⚠️ Cross-repo policy — needs human/product judgment. The melodic-software/knowledge-corpus sources/<type>/<slug>/ convention and its .gitattributes/LFS globs (per youtube-digest: externalize hardcoded assumptions + reconcile corpus durability (agnosticism + retention + synthesis split) #558 §D: missing mkv/pptx/key/webp; pre-LFS epub blobs needing git lfs migrate) are owned by that repo, not this one. Whether sources/<type>/<slug>/ is a stable public target this skill should encode, and how LFS coverage is guaranteed on the corpus side, are product/cross-repo calls outside this decision — flag before implementing B's LFS gate against an assumed layout.

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as not planned.

Deferred from #558. Centralizing .work// sub-path shape has no fired trigger and no second consumer pattern yet.

Re-open trigger: When a second youtube-digest consumer or binary-retention incident requires centralization.