feat(metadata-agent): add in-memory session cache management for Reporting Agent v2

[Copilot]

Summary

Adds session-level in-memory cache subsystem for Reporting Agent v2 Phase 2.3 with configurable TTL/capacity, LRU eviction, deterministic invalidation, and observable metrics.

Changes Made

Added

• agents/metadata-agent/lib/cache/cache-config.js — Cache config defaults + validation
• agents/metadata-agent/lib/cache/cache-metrics.js — Hit/miss/eviction/expiry/invalidation counters and hit-rate snapshots
• agents/metadata-agent/lib/cache/session-cache.js — TTL-aware in-memory cache with LRU eviction and invalidation hooks
• 29 focused unit tests under agents/metadata-agent/__tests__/cache/

API Usage

const cache = new SessionCache({ ttlMs: 300000, maxEntries: 1000 });
cache.set("repo:lightspeedwp/.github:prs", payload);
const cached = cache.get("repo:lightspeedwp/.github:prs");
const metrics = cache.getMetrics();

Key Features

• TTL-based expiry — Configurable per-entry or global TTL (default 5min)
• LRU eviction — Refreshes recency on reads and overwrites
• Targeted invalidation — delete(), clear(), invalidateByPrefix(), invalidateByPredicate(), invalidateExpired()
• Observable metrics — Hit rate, eviction reasons, invalidation tracking
• Nullable values — Correctly handles null cached values in guard paths
• Strict validation — Enforces positive-integer config, rejects null/undefined prefixes

Testing

• 29 focused unit tests covering cache config, basic operations, TTL expiry, LRU semantics, invalidation, and metrics
• Tests verify correct handling of nullable cached values
• Prefix invalidation normalised for consistent matching

Linked Issue

Resolves #2033

---

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[github-actions]

🔍 Reviewer Summary for PR #2486

CI Status: ❌ pending
Files changed: 5

Recommendations

• CI checks not green

[github-actions]

🔍 Reviewer Summary for PR #2486

CI Status: ❌ pending
Files changed: 5

Recommendations

• CI checks not green

[github-actions]

⚠️ A merged PR reached develop without passing the template content guardrail.

Missing required section(s): Linked issues, Changelog, Global DoD checklist

This is a post-merge backstop for admin bypasses. Please review branch protection for develop.

[github-actions]

🚫 This PR description is missing required template content.

Missing required section(s): Linked issues, Changelog, Global DoD checklist

Please update the PR body using one of the repository PR templates:

• https://github.com/lightspeedwp/.github/blob/develop/.github/pull_request_template.md
• https://github.com/lightspeedwp/.github/tree/develop/.github/PULL_REQUEST_TEMPLATE

Empty placeholders, unchecked checklist boxes, and stub issue references do not count.

[github-actions]

🔍 Reviewer Summary for PR #2486

CI Status: ❌ pending
Files changed: 5

Recommendations

• CI checks not green

[github-actions]

⚠️ Branch Naming Issue

This PR's branch name copilot/reporting-agent-v2-phase-2-3-session-cache-managem doesn't follow the standard pattern.

Standard pattern: {type}/{scope}-{title} (e.g., feat/something, fix/bug-name)

Based on linked issue type: task

Correct template should be: pr_feature.md

No action required — this is informational. Future PRs should use the correct branch name.

See Branching Strategy for more info.

[github-actions]

❌ Branch Name Validation Failed

The branch name copilot/reporting-agent-v2-phase-2-3-session-cache-managem does not follow the LightSpeed branching strategy.

Required Format

{type}/{scope}-{short-title}

• type: one of the allowed prefixes (lowercase)
• scope: lowercase, hyphens only (no underscores or uppercase)
• title: lowercase, hyphens only (no underscores or uppercase)

Allowed Branch Types

feat, fix, hotfix, release, refactor, chore, docs, test, perf, ci, build, deps, security, revert, research, design, a11y, ux, i18n, ops, proto, ds, api, schema, telemetry, content, seo, config, migrate, qa, uat, audit, codex

Valid Examples

• ✓ feat/branch-naming-enforcement
• ✓ fix/validation-script-bug
• ✓ chore/update-dependencies
• ✓ docs/branching-strategy-guide
• ✓ hotfix/critical-security-patch

Invalid Examples

• ✗ claude/my-branch (type "claude" not allowed)
• ✗ Feature/MyBranch (uppercase not allowed)
• ✗ fix-bug (missing type prefix)
• ✗ feat/my_feature (underscores not allowed)
• ✗ feat/MyFeature (uppercase not allowed)

Solution

Rename your branch to follow the pattern and update the PR.

For more information, see docs/BRANCHING_STRATEGY.md.

[github-actions]

🔍 Reviewer Summary for PR #2486

CI Status: ❌ pending
Files changed: 5

Recommendations

• CI checks not green

[github-actions]

🔍 Reviewer Summary for PR #2486

CI Status: ❌ pending
Files changed: 5

Recommendations

• CI checks not green

[github-actions]

🔍 Reviewer Summary for PR #2486

CI Status: ❌ pending
Files changed: 5

Recommendations

• CI checks not green

[ashleyshaw]

Approved

[ashleyshaw]

Approved