docs(knowledge): fix youtube-digest contact-sheet retention wording + --target resolution gap

[kyle-sexton]

Summary

Two deferred codex-P2 follow-ups from the 2026-07-21 babysit verifier session on merged PR #854, both confined to plugins/knowledge/skills/youtube-digest/. Documentation / behavior-contract fixes; no open design fork.

Fix

Site 1 — contact-sheet retention wording (SKILL.md, intro paragraph).
The line called the key-frames/contact-sheets/ snapshot "temp-only handling," which contradicts the Output contract's characterization of the same directory (key-frames/contact-sheets/*.jpg → "local DR snapshot, gitignored"). Reworded That temp-only handling is otherwise a fixed… → That never-committed handling is a fixed…. The snapshot now reads as a durable-on-disk-but-gitignored instance of never-committed handling, not an exception to a temp-only rule — consistent with the same paragraph's own "durable on disk (it survives tempSession cleanup)" and with the Output contract.

Site 2 — --target local-checkout resolution gap (SKILL.md, "Synthesis target resolution").
--target <repo> resolved to a target name only, but templates/synthesis-item.md's Target touchpoints field is grep-backed and needs a real tree. A watch --target <repo> from a separate corpus session (where the named repo isn't checked out) had no tree to grep and could fall through to CLAUDE_PROJECT_DIR/CWD or invent paths. Fixed by:

• Requiring the target to resolve to a local working tree on disk, not merely a name.
• Adding a loud-fail rung on the explicit---target case: no local checkout → halt and ask for the local checkout path, never fall through to CLAUDE_PROJECT_DIR, grep CWD, or invent touchpoint paths. (Auto-clone is left to the future /knowledge:apply design, which is unbuilt; "resolve-or-halt" fully satisfies the acceptance without new clone infra.)
• Recording both the target name and its resolved local tree path in README.md's **Target:** line (templates/readme-journey.md updated to match) so resume re-greps the same tree instead of re-inferring it — closing the resume-durability side of the finding.

Knowledge plugin 0.9.2 → 0.9.3 + top-inserted CHANGELOG.md entry.

Verification

Site 1 — the umbrella term now matches the Output contract; the file no longer buckets the snapshot as temp-only:

$ grep -n "temp-only" plugins/knowledge/skills/youtube-digest/SKILL.md
(no matches)
$ grep -n "never-committed handling" SKILL.md
19: ... but gitignored, so it is never committed (see the Output contract). That never-committed handling is a fixed, non-configurable part of this contract ...
$ grep -n "local DR snapshot" SKILL.md
369: | key-frames/contact-sheets/*.jpg | ... | never in git | METADATA | script (snapshot-bootstrap.js; local DR snapshot, gitignored) |

Site 2 — resolution now names a local tree and a loud-fail path; synthesis-item.md's grep-backed field has a tree to grep, and the recorded Target line carries the path for resume:

$ grep -n "local working tree on disk" SKILL.md
289: ... the target must resolve to a **local working tree on disk**, not merely a name ...
$ grep -n "does \*\*not\*\* resolve — stop and ask" SKILL.md
289: ... has no local checkout ... does **not** resolve — stop and ask for its local checkout path rather than falling through to CLAUDE_PROJECT_DIR, grepping the current directory, or inventing touchpoint paths ...
$ grep -n "Target touchpoints" plugins/knowledge/skills/youtube-digest/templates/synthesis-item.md
6: - **Target touchpoints:** {paths/headings in the resolved target — grep-backed}
$ grep -n "Target:" plugins/knowledge/skills/youtube-digest/templates/readme-journey.md
9: **Target:** {resolved synthesis target — name + local tree path; SKILL.md "Synthesis target resolution"}

• markdownlint-cli2 on all three changed markdown files → 0 errors.
• Commit is SSH-signed (verified G) per the org ruleset.

Closes #1015

Related

• knowledge/youtube-digest: SKILL.md contact-sheet retention wording + --target local-checkout resolution gap (PR #854 follow-ups) #1015 — this issue (batched from the lane sweep: triage — week of 7/20 (rolling paper-cut batch) #657 triage sweep).
• docs(knowledge): youtube-digest synthesis target + named agnosticism gaps #854 — originating PR whose review deferred both findings as codex-P2 follow-ups.
• lane sweep: triage — week of 7/20 (rolling paper-cut batch) #657 — triage-sweep source (T8h batch conversion) that folded the finding lines into knowledge/youtube-digest: SKILL.md contact-sheet retention wording + --target local-checkout resolution gap (PR #854 follow-ups) #1015.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mu8bLN896ia5AeWmGPqAUv

Work-class: C3 (bug-fix-shaped) — attended triage 2026-07-23, operator-ratified. 🤖

[claude]

Claude finished @kyle-sexton's task in 1m 34s —— View job

---

PR Review

• Gather context and understand request
• Read PR diff and changed files
• Review correctness and consistency
• Review CLAUDE.md / design-rule alignment
• Post findings

---

Summary

Two well-scoped doc/behavior-contract fixes in plugins/knowledge/skills/youtube-digest/. No code changes; version bump (0.9.2 → 0.9.3) is correctly sized (patch). Both fixes are internally consistent and address real problems.

---

Site 1 — Contact-sheet retention wording

SKILL.md line 19

The swap of temp-only handling → never-committed handling is correct. The same sentence already states the snapshot is "durable on disk (it survives tempSession cleanup)", and the Output contract table at line 369 labels the same path **never in git** / "local DR snapshot, gitignored". Calling it "temp-only" contradicted both of those within the same paragraph. The new umbrella term matches the Output contract's never in git language exactly. No issues.

---

Site 2 — --target resolution gap

SKILL.md line 289

The three-rung cascade is now:

1. --target <repo> → must resolve to a local checkout (not just a name)
2. CLAUDE_PROJECT_DIR when watch runs directly inside a repo
3. ask

With an explicit loud-fail: if --target is given but no local checkout exists, halt and ask — never fall through to CLAUDE_PROJECT_DIR or invent paths.

This directly fixes the gap in templates/synthesis-item.md's grep-backed **Target touchpoints:** field, which requires a real tree on disk to populate.

One observation worth tracking (not a blocker): the resolved local tree path recorded in README.md's **Target:** line is an absolute path at write time. If the corpus repo is later moved or re-cloned on a different machine, a resume session will find a stale path and have to ask again anyway. The PR correctly scopes this as a pragmatic improvement over the prior state (where no path was recorded at all), and notes that full portability is deferred to the /knowledge:apply auto-clone design. That framing is sound — just worth a comment in the README.md template placeholder so future consumers know the path may need updating on machine change.

templates/readme-journey.md line 9

The template placeholder update (name + local tree path) correctly aligns with the SKILL.md change.

---

CHANGELOG

CHANGELOG.md lines 7–22

Accurate, complete summary of both fixes. No issues.

---

CLAUDE.md / design-rule alignment

• Repo-agnostic: no hardcoded paths introduced. The --target resolution explicitly prohibits grepping CWD as a fallback, which is the right call.
• No PII or secrets.
• Version bump is explicit semver in plugin.json. ✓
• No plugin-form isolation concerns (doc-only change).

---

Verdict

LGTM. Both fixes are correct and internally consistent. The single observation above (absolute-path staleness on machine change) is a known limitation scoped to a future /knowledge:apply design — no action required here.

[claude]

Claude finished @kyle-sexton's task in 1m 8s —— View job

---

Security Review — PR #1027

• Gather context and understand request
• Examine PR diff
• Read changed files
• Analyze for security issues
• Post findings

---

No security issues found.

All four changed files are documentation / plain-text artifacts:

File	Change
plugin.json	Version bump 0.9.2 → 0.9.3
CHANGELOG.md	Plain-text changelog entry
SKILL.md	Two wording edits (lines 19, 289)
templates/readme-journey.md	Template placeholder expansion

SKILL.md line 289 (--target resolution) is the only change with any behaviour-bearing instructions, and it moves in the right direction from a security standpoint: it removes an implicit fallthrough to CLAUDE_PROJECT_DIR / CWD when a named target has no local checkout, replacing it with a hard-stop ("halt and ask"). Implicit fallthrough to an unintended directory is the kind of path-confusion bug that can cause the agent to grep unrelated trees or record wrong touchpoints; the new loud-fail rung closes that.

The template update (readme-journey.md) records a local tree path in the **Target:** field. That path is stored inside the .work/<epic>/<slug>/README.md slice directory, which the skill marks as gitignored; there is no new egress surface or committed-path-exposure risk introduced by this change.

Scope checked: no GitHub Actions changes, no new shell commands, no dependency changes, no credential/secret handling, no external service calls.

---

[kyle-sexton]

🔒 merge-drive lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, worker tier). Will fix clear branch-owned CI/bot findings, defer non-DEFER-FORBIDDEN items with reply+resolve, push, then re-check the merge gate.