docs(cli-orchestrator): reclassify SessionCache from Level 3 component to Level 4 implementation detail

[WesleyMFrederick]

Problem

SessionCache (src/cache/checkExtractCache.ts) is documented as a standalone Level 3 component in ARCHITECTURE-Citation-Manager.md (#### Citation Manager.SessionCache), but it does not meet the criteria for Level 3 classification under our C4 framework conventions. This misclassification creates confusion about component boundaries and architectural intent.

Reproduction Steps

1. Open /WesleyMFrederick/cc-workflows/blob/main/tools/citation-manager/design-docs/ARCHITECTURE-Citation-Manager.md
2. Find #### Citation Manager.SessionCache — listed as peer to CitationValidator, ContentExtractor, etc.
3. Compare against Level 3 criteria: DI via factory, multiple consumers, peer interactions
4. SessionCache fails all three: no DI, single consumer (CLI Orchestrator), no peer interactions
5. Open SessionCache Component Guide.md — links point to sibling implementation guides instead of architecture doc component anchors

Root Cause

SessionCache was implemented as a migration from bash to TypeScript (PR #98) and documented as its own Level 3 component without evaluating whether it met C4 component boundary criteria. The existing Level 4 precedent (LinkObjectFactory) was not applied.

6 pieces of evidence for demotion:

1. Single consumer — only CLI Orchestrator calls checkExtractCache() and writeExtractCache()
2. No peer interfaces — unlike ParsedFileCache (consumed by CitationValidator AND ContentExtractor), SessionCache has zero peer consumers
3. CLI-level concern — cache check wraps the extract links command action, not a domain operation
4. LinkObjectFactory precedent — already classified as Level 4 for identical reasons (single consumer, CLI helper)
5. No DI — uses node:fs and node:crypto directly; every Level 3 component uses DI via factory
6. Not in component factory — componentFactory.ts does not instantiate SessionCache

Expected Behavior

SessionCache should be classified as a Level 4 implementation detail of CLI Orchestrator, parallel to LinkObjectFactory:

• Listed under CLI Orchestrator's ##### Level 4 Implementation Details section
• src/cache/ directory documented in Level 4 file structure
• CLI Orchestrator interactions updated to reference SessionCache as internal helper (not cross-component)

Related

• PR feat(citation-manager): move session cache from bash hook to TypeScript tool #98 — SessionCache migration from bash to TypeScript
• /WesleyMFrederick/cc-workflows/blob/main/tools/citation-manager/design-docs/ARCHITECTURE-Citation-Manager.md — architecture doc needing update
• /WesleyMFrederick/cc-workflows/blob/main/tools/citation-manager/design-docs/component-guides/SessionCache%20Component%20Guide.md — guide needing updates

Note

Architecture Principles Evaluation (9 categories)

#	Principle Category	Conformance	Notes
1	Modular Design	PARTIAL	Single responsibility ✅. No DI for fs/crypto ❌. No interface defined ❌.
2	Data-First Design	PASS	Cache key strategy (sessionId_md5(content)) is clean.
3	Action-Based File Organization	PASS	checkExtractCache.ts follows verb-noun naming.
4	Format/Interface Design	PASS	Simple 3-parameter functions with boolean/void returns.
5	MVP Principles	PASS	Empty marker files = simplest possible cache.
6	Deterministic Offloading	PASS	Pure deterministic I/O in tool layer.
7	Self-Contained Naming	PASS	Function names clearly signal purpose.
8	Safety-First Design	PARTIAL	Auto-creates cache dir ✅. No error handling on fs ops ❌.
9	Anti-Patterns	PASS	No scattered checks, no over-engineering.

SessionCache Guide vs MarkdownParser Guide (Template Gaps)

Section	Gap
Overview.Problem links	Points to sibling implementation guides instead of ARCHITECTURE doc component anchors
Testing Strategy	MISSING — needs section following MarkdownParser template
Technical Debt	MISSING — promote "unbounded cache growth" from Whiteboard to formal tech debt with github-query block

File Location Decision

src/cache/ is the correct location — no move needed:

• src/core/ holds Level 3 components (ContentExtractor, MarkdownParser) — wrong level
• src/*.ts top-level holds Level 3 components — wrong level
• src/cache/ parallels src/factories/ as CLI Orchestrator internal subfolder
• Future: if CLI Orchestrator outgrows single file, consolidate into src/core/CLIOrchestrator/

---

Acceptance Criteria

• #### Citation Manager.SessionCache removed as standalone Level 3 component from ARCHITECTURE-Citation-Manager.md
• SessionCache added as Level 4 Implementation Detail under CLI Orchestrator section (parallel to LinkObjectFactory)
• CLI Orchestrator interactions updated: "delegates cache deduplication" becomes internal implementation note
• src/cache/checkExtractCache.ts added to Level 4 file structure tree
• SessionCache Component Guide: fix 4 broken links to point to ARCHITECTURE doc component anchors
• SessionCache Component Guide: add Testing Strategy section
• SessionCache Component Guide: add Technical Debt section with github-query block using component:CLIOrchestrator label
• SessionCache Component Guide: add header note clarifying Level 4 status
• CLI Orchestrator Implementation Guide: add Technical Debt section with github-query block matching MarkdownParser pattern

Definition of Done

• ARCHITECTURE-Citation-Manager.md updated with SessionCache as Level 4
• SessionCache Component Guide updated with all template gaps filled
• CLI Orchestrator Implementation Guide has Technical Debt section
• All citation links validate (citation-manager validate passes)
• No broken cross-references between guides and architecture doc
• Committed with conventional commit