/stack-check

name: stack-check
description: >
  USE WHEN the `stack-freshness` SessionStart hook nudges
  ("stack last checked 42d ago"), or when user asks to check dep
  versions. Verifies Claude Code + Codex + plugin + CLI deps vs
  `stack.toml` (per-OS update commands), flags stale
  AIDEV-TODO/QUESTION anchors (deadline-aware), and sanity-checks
  AGENTS.md size + imports. Read-only. Resets the freshness timestamp.
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - Bash(claude --version)
  - Bash(codex --version)
  - Bash(git --version)
  - Bash(rg --version)
  - Bash(jq --version)
  - Bash(python --version)
  - Bash(python3 --version)
  - Bash(mmdc --version)
  - Bash(node --version)
  - Bash(shellcheck --version)
  - Bash(npm view:*)
  - Bash(touch:*)
  - Bash(date:*)
  - Bash(test:*)
  - Bash(mkdir:*)
  - Bash(git rev-parse:*)
  - Bash(wc:*)
  - Bash(stat:*)
  - WebFetch

/stack-check

What it does

Walks `stack.toml`, queries each declared dependency's installed version, optionally fetches the latest available version, and reports a Markdown table:

# Stack check — <YYYY-MM-DD>

| Tool | Installed | Required | Status | Update |
|------|-----------|----------|--------|--------|
| claude (Claude Code) | 2.1.89 | ≥2.1.0 | ok | — |
| codex (Codex CLI) | 0.39.0 | ≥0.40.0 | **outdated** | npm i -g @openai/codex |
| claude-leverage (this plugin) | 1.0.0 | latest 1.0.1 | **outdated** | /plugin update claude-leverage |
| git | 2.45.0 | ≥2.40.0 | ok | — |
| rg | 14.0.3 | ≥13.0.0 | ok | — |
| jq | (not found) | ≥1.6 (optional) | missing | brew install jq |
| python | 3.12.1 | ≥3.10 | ok | — |
| mmdc | (not found) | ≥10.0.0 (optional) | missing | npm i -g @mermaid-js/mermaid-cli |
| node | 20.10.0 | ≥20.0.0 | ok | — |
| shellcheck | (not found) | ≥0.8.0 (optional) | missing | brew install shellcheck |

On successful completion (no errors thrown), updates `~/.local/state/claude-leverage/.last-stack-check` (or `~/.claude/claude-leverage/.last-stack-check` if XDG state dir is unavailable) with the current epoch time so the SessionStart hook stays quiet for the next N days.

Workflow

1. **Load `stack.toml`.** From the plugin install dir (`$CLAUDE_PLUGIN_ROOT/stack.toml`) or, if running standalone, from the repo root. If neither exists, STOP and report.

2. **For each `[[host.tool]]` and `[[deps.tool]]`:**

• Run `check_cmd`. Capture stdout+stderr.
• Parse the version with a simple regex (`(\d+\.\d+(\.\d+)?)` —

accept "X.Y" and "X.Y.Z" both). If parse fails or command not found, mark "missing" (and "outdated" if `optional = false`).

• Compare against `min_version` using a tuple compare (split on `.`).
• Mark: `ok` | `outdated` | `missing` | `unknown (parse failed)`.
• **Resolve update hint** per-OS: detect platform via `uname -s` (or

PowerShell `$env:OS` / `$IsWindows`). Prefer `update_hint_macos` / `update_hint_linux` / `update_hint_windows` when present and the platform matches; otherwise fall back to the generic `update_hint` field. This is what stack.toml `manifest_version = 2` introduced.

3. **For the plugin itself:**

• Read `version` from the installed `.claude-plugin/plugin.json`.
• WebFetch

`https://raw.githubusercontent.com/Filip-Podstavec/claude-leverage/main/.claude-plugin/plugin.json` and compare to the installed version. Cache the network result for 24h in `~/.claude/claude-leverage/.stack-check-cache.json` to avoid hammering GitHub if the user runs the skill repeatedly.

4. **For Claude Code itself:**

• `claude --version` is the installed version.
• We do NOT fetch the latest Claude Code version from the network —

Anthropic doesn't expose a stable scrapable endpoint. Instead, the `min_version` in stack.toml is hand-maintained: bump it when this plugin starts depending on a feature only present in a newer CC.

5. **Walk the current repo for AIDEV anchor health** (if cwd is inside a git repo). Grep `git rev-parse --show-toplevel` for `AIDEV-(TODO|QUESTION)` matches and parse each line.

Two flavors of anchor:

• **Deadline-bearing**: `AIDEV-TODO(by: 2026-08-01):` or

`AIDEV-QUESTION(by: YYYY-MM-DD):`. Extract the ISO-8601 date and compare against today.

• `due-soon` (deadline in the next 14 days)
• `overdue` (deadline already passed)
• **Age-based** (no deadline): use `git log -1 --format=%cI -- <file>`

for the file's last-modified timestamp.

• `fresh` (≤30 days)
• `aging` (30–90 days)
• `stale` (>90 days)

Cap walk at 5000 files; skip the bench archive, vendor dirs, node_modules, __pycache__, .git.

Reported after the version table:

   ## AIDEV anchors (current repo: <name>)

   - 14 AIDEV-TODO total: 3 fresh, 8 aging, 2 stale (>90d), **1 overdue (by deadline)**
   - 5 AIDEV-QUESTION total: 1 fresh, 2 aging, 1 stale, 1 due-soon

   **Overdue (deadline passed):**
   - `src/billing/charge.py:47` — AIDEV-TODO due 2026-04-01 (44 days overdue)
     "replace the polling loop with webhooks"

   **Due soon (next 14 days):**
   - `src/auth/middleware.py:89` — AIDEV-QUESTION due 2026-06-05 (in 12 days)

   **Stale (no deadline, last touched >90 days ago):**
   - `src/legacy/handlers.py:120` — AIDEV-TODO (last touched 2025-12-03)
     "migrate to v2 API"

If not in a git repo, skip this section silently.

Deadline parsing tolerates a few formats. The distinguishing rule for implementors: the parenthesized content matches one of these regexes (anchored, case-insensitive on the keyword):

• `^by:\s*(\d{4}-\d{2}-\d{2})$` — `(by: 2026-08-01)`
• `^(\d{4}-\d{2}-\d{2})$` — `(2026-08-01)` (bare ISO date)
• `^deadline:\s*(\d{4}-\d{2}-\d{2})$` — `(deadline: 2026-08-01)`

Anything else in the parens (free-form notes like `(Q3 2026)` or `(after the migration)`) is NOT a deadline; that anchor falls under age-based stale tracking. This prevents misclas