stack-check

# /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:

```markdown
# 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:

   ```markdown
   ## 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 misclassifying ambiguous
   parenthetical text as a date.

6. **Sanity-check AGENTS.md** (if present in cwd or repo root):
   - File size, two tiers (report the size either way):
     - **warn over 8 KiB** — lean target exceeded; an always-loaded file
       this large dilutes attention. Suggest extracting topic depth to
       `docs/` behind a when-to-read link.
     - **flag over 32 KiB** — Codex caps the assembled project doc at
       `project_doc.max_bytes` (default 32768) and silently drops the rest,
       so content past that byte is invisible to Codex agents.
     Both tiers are advisory here and do not stop the timestamp reset (step
     9). `/repo-doctor` escalates the 32 KiB tier to a hard ❌ — that split
     is intentional (see ADR 0009): `/stack-check` informs, `/repo-doctor`
     gates.
   - Broken `@<path>` imports: grep for `^@` lines, verify each
     referenced file