Freshness Check

/freshness-check — Pipeline Freshness Check

Checks whether audit skills, checklists, supplements, and references are up to date. Ideally runs before every audit — the orchestrator recommends it automatically.

Problem

The pipeline contains versioned knowledge bases:

• Framework checklists (Beta + Stable)
• Tool references and documentation
• OWASP, WCAG, GDPR phases
• Stack supplements (Tailwind, Docker, etc.)

These go stale silently. Without regular checks, you audit against outdated standards.

Solution: Automated Freshness Scan

Flow

1. Check all sources in parallel (npm, WebSearch, context7)
2. Compare against documented state (as-of date in each file)
3. Create delta report (what is outdated, what is current)
4. Auto-update where possible (changelogs, versions)
5. Manual review where needed (new laws, breaking changes)

Modes

Source Catalog

Tier 1 — Frameworks & Tools (npm view, automatic)

Tier 2 — Security & Standards (WebSearch, semi-automatic)

CWE Top 25 2026: Out-of-bounds Write #1, XSS #2, SQL Injection #3. Four of top 5 are memory safety issues.

Tier 3 — Laws & Regulations (WebSearch, manual review)

Tier 1b — CLI Plugins (gh api + installed_plugins.json, automatic)

How to update plugins: Run /reload in Claude Code to pull the latest version from the marketplace. No manual install needed.

Check logic:

1. Read ~/.claude/plugins/installed_plugins.json → list all installed plugins
2. Per plugin: extract version and git info
3. Check latest release via gh api repos/{owner}/{repo}/releases/latest
4. Compare installed vs. latest → delta report entry

Tier 4 — Ecosystem (WebSearch/gh, situational)

Tier 5 — Community & Inspiration (gh api, full only)

Reference: community-sources.md — Full list with owner/repo, category, adoption history.

Flow:

1. Read community-sources.md (repos + as-of dates)
2. Per repo: gh api repos/{owner}/{repo}/commits?per_page=1 -> last commit timestamp
3. Compare with as-of date: New commits? -> Calculate delta
4. If delta > 14 days: Spot-check README or relevant files via gh api
5. Delta report with recommendation: "Worth checking" vs. "No action needed"

Tier 6 — Opportunity Analysis (full mode only)

Checks whether updates from Tiers 1-5 enable concrete improvements for the pipeline. Core question: "Could this update improve any of our skills, hooks, agents, or workflows?"

Pipeline inventory (matched against updates):

Flow:

1. Identify sources with updates — All entries from Tiers 1-5 with status != "ok"
2. Read changelogs/release notes:
   • npm: gh api repos/{owner}/{repo}/releases/latest or WebSearch "{tool} changelog {version}"
   • Community: gh api repos/{owner}/{repo}/commits?per_page=5 -> analyze commit messages
   • Standards: Evaluate WebSearch results from Tiers 2-3
3. Match new features against pipeline inventory:
   • New hook event in Claude Code? -> Check if new hook makes sense
   • New Astro feature? -> Check if astro-audit checklist needs expanding
   • New community pattern? -> Check if pipeline patterns need updating
   • New security requirement? -> Check if security-reviewer needs expanding
4. Rate opportunities:
   • HIGH: Direct improvement possible, concrete implementation proposal
   • MED: Potentially useful, worth a closer look
   • LOW: Nice-to-have, no urgent action needed
5. Create opportunity report (part of the delta report)

Rules:

• ONLY rate when there is a concrete connection to the pipeline — not everything is relevant
• Community repos: Only check new CLAUDE.md, skills, hooks, agents pattern files
• No speculation — only when a feature clearly matches a component
• Save opportunities in .freshness-state.json under "opportunities" array

Output format (in delta report):

OPPORTUNITIES (Tier 6 — Pipeline Improvements):
  [HIGH] {Source} v{Version}: {Feature}
         -> Affects: {Skill/Hook/Agent}
         -> Proposal: {concrete improvement proposal}
  [MED]  {Source}: {Feature/Pattern}
         -> Check if relevant for: {Area}
  [LOW]  {Source}: {Update}
         -> Nice-to-have: {Description}

Delta Report Format

Freshness Check — {Date}

OUTDATED (Action Required):
  [HIGH] Astro Beta: Documented beta.14, current beta.16
         -> Update changelog.md + checklist.md
  [HIGH] Claude Code: Reference v2.1.47, installed v2.2.0
         -> Update docs/claude-code-reference.md
  [MED]  Tailwind CSS: Supplement as-of 2026-01-15, current v4.1.0
         -> Review stacks/css/tailwind-v4.md

CURRENT:
  [OK] Node.js: v22 (LTS current)
  [OK] OWASP Top 10: 2025 (current)
  [OK] WCAG: 2.2 (current, 3.0 still draft)
  [OK] Vite: v7 (documented)

NOT CHECKABLE (no internet access or tool missing):
  [SKIP] Docker Engine: WebSearch not available

COMMUNITY & INSPIRATION (Tier 5):
  | Repo                | As-of      | Last Commit    | Delta    | Severity |
  |---------------------|------------|----------------|----------|----------|
  | get-shit-done       | 2026-02-20 | 2026-02-25     | 5 days   | OK       |
  | awesome-claude-code | 2026-02-20 | 2026-03-05     | 13 days  | LOW      |
  | obsidian-skills     | 2026-02-20 | 2026-03-15     | 23 days  | MEDIUM   |

  Recommendation: obsidian-skills has new activity — check if new patterns are relevant.

OPPORTUNITIES (Tier 6 — Pipeline Improvements):
  [HIGH] Claude Code v2.2.0: New hook event "PreModelResponse"
         -> Affects: token-warning.sh
         -> Proposal: Context warning before model response instead of after — more precise control
  [MED]  GSD: New "parallel-agent" coordination pattern
         -> Check if relevant for: audit-orchestrator, team workflows
  [LOW]  Astro beta.17: middlewareMode config
         -> Nice-to-have: Deployment could benefit from this

Severity in Delta Report

Auto-Update Logic

When mode is update or full:

What Gets Auto-Updated

1. Astro Changelog (versions/v{x}-beta/changelog.md):

   • New betas via GitHub Releases or npm
   • Summarize release notes
   • Update as-of date

2. Astro Checklist (versions/v{x}-beta/checklist.md):

   • Adjust counters if new checks needed
   • Update as-of date
   • Add new breaking changes as checks

3. Astro Reference Links (versions/v{x}-beta/reference-links.md):

   • Add new PRs
   • Update as-of date

4. Claude Code Reference (docs/claude-code-reference.md):

   • Update version header
   • Document new features/flags (WebSearch)

What Gets Marked as Note Only (Manual Review)

• Legal changes (GDPR, accessibility laws, DSA, EU AI Act)
• Security standards (OWASP, CWE, ASVS)
• WCAG version jump (2.2 -> 3.0)
• Major framework migrations (Tailwind v4 -> v5)

Rule: NEVER auto-write legal and security-relevant changes into phase files — always enforce manual review.

As-of Date Convention

Every file containing versioned knowledge MUST have an as-of date at the end:

As of: YYYY-MM-DD (updated for {version/reason})

The freshness check parses this date and compares it with the current state.

Files with as-of dates:

• versions/*/changelog.md
• versions/*/checklist.md
• versions/*/reference-links.md
• docs/claude-code-reference.md
• docs/beta-flags.md
• All phase files with year references (OWASP 2025, WCAG 2.2, etc.)

Integration with Orchestrator

The orchestrator recommends /freshness-check automatically:

IF last freshness check > 7 days ago OR no check documented:
  -> "Recommendation: /freshness-check before audit start (last check: {date})"
IF last check < 7 days:
  -> No hint, proceed directly to audit plan

Freshness state is saved in .freshness-state.json:

{
  "lastCheck": "YYYY-MM-DD",
  "mode": "check|update|full",
  "results": {
    "astro-beta": { "status": "ok|outdated|skip", "documented": "beta.14", "current": "beta.16" },
    "astro-stable": { "status": "ok", "documented": "5.17.2", "current": "5.17.2" },
    "tailwind": { "status": "ok", "documented": "4.0.x", "current": "4.0.x" },
    "claude-code": { "status": "outdated", "documented": "2.1.47", "current": "2.2.0" },
    "node": { "status": "ok", "documented": "22", "current": "22.12.0" },
    "owasp": { "status": "ok", "documented": "2025", "current": "2025" },
    "wcag": { "status": "ok", "documented": "2.2", "current": "2.2" },
    "community": {
      "get-shit-done": { "status": "ok", "asOf": "2026-02-20", "latestCommit": "2026-02-19" },
      "obsidian-skills": { "status": "medium", "asOf": "2026-02-20", "latestCommit": "2026-03-15", "note": "23 new commits" }
    }
  },
  "opportunities": [
    { "severity": "high", "source": "claude-code", "feature": "PreModelResponse hook event", "target": "token-warning.sh", "suggestion": "More precise context warning control" },
    { "severity": "med", "source": "get-shit-done", "feature": "Parallel-agent pattern", "target": "audit-orchestrator", "suggestion": "Check if orchestrator logic can be improved" }
  ],
  "summary": {
    "total": 12,
    "ok": 9,
    "outdated": 2,
    "skip": 1,
    "opportunities": 2
  }
}

Context Protection

• Tier 1 (npm): Fast, low context usage — always check
• Tier 2+3 (WebSearch): More context — only in full mode
• Tier 4 (Ecosystem): Optional — only if relevant for the current project
• Tier 5 (Community): gh api + optional WebSearch — full only
• Tier 6 (Opportunities): Analyzes changelogs of updates — full only, after Tiers 1-5
• Write state immediately after each source
• When context is low: Finish Tier 1, mark rest as "SKIP"

Rules

• No blind auto-update of laws/standards — always manual review
• npm view ALWAYS live — never from memory
• Update as-of date in every updated file
• Show delta report to user before auto-updates are applied
• Freshness check is optional — audits work without it, but with potentially outdated data
• Meaningful max once per week — daily would be overkill (unless a known release is expected)