knowledge: library_dir seam accepts only literal paths — machine-specific config collides with hardcoded-path guardrail

[kyle-sexton]

Problem

The knowledge plugin's library_dir userConfig option only resolves literal paths. resolveWorkRoot() (skills/youtube-digest/extraction/lib/work-root.js) is:

return process.env.YOUTUBE_WORK_ROOT || process.env.CLAUDE_PROJECT_DIR || process.cwd();

No ~, env-var, or placeholder expansion anywhere in the chain — the skill contract prefixes relative values with the home directory, and absolute values pass through verbatim.

Consequence: pointing library_dir at a repo outside the home directory (the intended knowledge-corpus consolidation flow, e.g. D:/repos/github.com/melodic-software/knowledge-corpus) requires a literal machine-specific path in user-level settings.json. The guardrails plugin's hardcoded-path-check hook (correctly) blocks writing that value. The two plugins are in direct conflict for the primary supported use case.

Observed 2026-07-21 during a live digest session: config write blocked by the hook; session fell back to per-run --work-root flags.

Candidate solutions (decision open)

1. Env-var indirection — allow library_dir values like ${KNOWLEDGE_CORPUS_DIR}; expand in resolveWorkRoot()/launcher. Machine variance lives in OS user env vars, settings.json stays portable.
2. Tilde expansion — support ~/... values; helps only when the corpus lives under home (does not cover the drive-split layout).
3. ghq-derived scheme — support ghq:owner/repo; resolve via ghq root + layout at runtime. Portable across machines that keep the ghq convention; matches the org's existing repo-layout doc.

Options 1 and 3 both solve the drive-split case; 3 is zero-config per machine but couples the seam to ghq presence. Evaluate against the plugin's portability posture before picking.

Acceptance sketch

• A non-home corpus root configurable without a machine-specific literal in settings.json
• hardcoded-path-check passes on the resulting config
• Existing literal-path values keep working (back-compat)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y4RMR3G1rHAdNjxTqenVJL

[kyle-sexton]

This was generated by AI during triage.

Umbrella-fold → member of #531 (portability coupling). This is a machine-specific-path coupling instance: the library_dir seam requires a literal machine-specific path (e.g. a non-home corpus root), which collides with the hardcoded-path-check guardrail — the same declared-agnosticism coupling class #531 tracks. The 3-option resolution fork (env-var indirection / tilde / ghq-derived scheme) is a portability-posture decision, which #531 owns.

Routed per the blocked-by-carrier pattern: blocked by #531 decision — not routed as standalone work. When #531's portability posture settles the resolution-scheme approach, this seam's fix follows from it. Acceptance sketch preserved on the issue (non-home root configurable without a machine-specific literal; hardcoded-path-check passes; existing literal-path values keep working).