claudetools/.claude/commands/wiki-lint.md

Health-check the wiki for missing articles, stale content, broken backlinks, and cross-reference gaps.

Run this after any session where new session logs were created, or when starting a new session and the wiki may be out of date. Also run before any `/wiki-compile all` pass.

---

## Step 1 — Missing Articles (Primary Check)

Scan for clients and projects that have session logs but no wiki article.

```bash
# List all client slugs that have session-logs but no wiki article
# Repo root is machine-specific (C:/ on some, D:/ on others) — never hardcode it.
cd "$(git rev-parse --show-toplevel)"
for dir in clients/*/session-logs; do
  slug=$(echo "$dir" | sed 's|clients/||;s|/session-logs||')
  wiki="wiki/clients/$slug.md"
  if [ ! -f "$wiki" ]; then
    count=$(ls "$dir"/*.md 2>/dev/null | wc -l)
    echo "MISSING: $wiki  ($count session logs)"
  fi
done
```

```bash
# List all project slugs that have session-logs but no wiki article
for dir in projects/*/session-logs; do
  slug=$(echo "$dir" | sed 's|projects/||;s|/session-logs||')
  wiki="wiki/projects/$slug.md"
  if [ ! -f "$wiki" ]; then
    count=$(ls "$dir"/*.md 2>/dev/null | wc -l)
    echo "MISSING: $wiki  ($count session logs)"
  fi
done
```

Report each missing article as:
```
[MISSING] wiki/clients/<slug>.md — <N> session logs, oldest: <YYYY-MM-DD>
```

Suggest: `Run /wiki-compile client:<slug> to seed.`

---

## Step 2 — Stale Articles

Check `last_compiled` date in all wiki article frontmatter. Flag any article where:
- `last_compiled` is more than 90 days ago AND there are session logs newer than `last_compiled`
- Report as `[STALE]` with days since compile and count of new logs

Use `grep -r "last_compiled:" wiki/` to collect dates, then compare against session log mtimes.

---

## Step 3 — Broken Backlinks

Scan all `[[link]]` references in wiki articles. For each `[[slug]]`, check:
- Does `wiki/clients/<slug>.md` exist? Or `wiki/projects/<slug>.md`? Or `wiki/systems/<slug>.md`?
- If none match → flag as `[BROKEN_LINK]`

```bash
grep -rh '\[\[' wiki/ | grep -o '\[\[[^]]*\]\]' | sed 's/\[\[//;s/\]\]//' | sort -u
```

For each slug found, normalize before checking:
1. Strip leading `wiki/` prefix if present → flag as `[BAD_FORMAT]` (seeding agents sometimes write wrong format)
2. Strip trailing `.md` extension if present → also flag as `[BAD_FORMAT]`
3. Check existence: `wiki/<slug>.md`, `wiki/clients/<slug>.md`, `wiki/projects/<slug>.md`, `wiki/systems/<slug>.md`, `wiki/patterns/<slug>.md`
4. If no file found after normalization → flag as `[BROKEN_LINK]`

Note: `[[systems/neptune]]` will always show as broken until neptune is seeded — that's expected.

---

## Step 4 — Index Gaps

Read `wiki/index.md`. For every `.md` file in `wiki/clients/`, `wiki/projects/`, `wiki/systems/`:
- Is it listed in `wiki/index.md`? If not → flag as `[NOT_INDEXED]`

Conversely, for every row in `wiki/index.md`:
- Does the linked file actually exist? If not → flag as `[DEAD_INDEX_ENTRY]`

---

## Step 5 — Compilation Queue Cleanup

Read the `## Compilation Queue` section in `wiki/index.md`. For each entry:
- Does the corresponding `wiki/<type>/<slug>.md` file now exist? If yes → flag the queue entry as stale, suggest removing it.

---

## Step 6 — Syncro Live-Check (Client Articles, Auto-Fix)

For every client wiki article that contains a `Syncro customer ID` line, pull live billing data from Syncro and auto-fix stale values in place. This step runs silently — no user confirmation needed. Fixes are committed at the end.

### Setup

```bash
# Resolves CLAUDETOOLS_ROOT + VAULT_ROOT from identity.json and reads the caller's
# per-user Syncro key from the SOPS vault. Never hardcode a repo path or an API key.
source "$(git rev-parse --show-toplevel)/.claude/scripts/syncro-env.sh" || true

BASE="$SYNCRO_BASE"
API_KEY="$SYNCRO_API_KEY"

if [ -z "$API_KEY" ]; then
  echo "[SYNCRO] No API key for user '${SYNCRO_USER:-unknown}' — skipping Step 6"
  exit 0
fi
```

### For Each Client Article

```bash
for ARTICLE in wiki/clients/*.md; do
  SLUG=$(basename "$ARTICLE" .md)

  # Extract Syncro customer ID — skip if not documented
  CUST_ID=$(grep -oP '(?<=\*\*Syncro customer ID:\*\* )\d+' "$ARTICLE" 2>/dev/null)
  [ -z "$CUST_ID" ] && continue

  # Pull live customer data
  CUST=$(curl -s "$BASE/customers/${CUST_ID}?api_key=$API_KEY" | jq '.customer')
  [ -z "$CUST" ] && echo "[SYNCRO][WARNING] $SLUG — API returned empty for customer $CUST_ID" && continue

  LIVE_HOURS=$(echo "$CUST" | jq -r '.prepay_hours // "0"')
  TODAY=$(date +%Y-%m-%d)

  # --- Fix 1: Hours remaining ---
  # Extract current wiki value (match pattern: "X.X hrs as of")
  WIKI_HOURS=$(grep -oP '[\d.]+ hrs as of' "$ARTICLE" | grep -oP '[\d.]+' | head -1)

  if [ -n "$WIKI_HOURS" ] && [ "$WIKI_HOURS" != "$LIVE_HOURS" ]; then
    # Replace the Hours remaining line with live value
    sed -i "s/\*\*Hours remaining[^:]*:\*\*[^\n]*/\*\*Hours remaining (if prepaid):\*\* ${LIVE_HOURS} hrs as of ${TODAY} (Syncro live)/" "$ARTICLE"
    echo "[SYNCRO][FIXED] $SLUG — hours: wiki=${WIKI_HOURS} → Syncro=${LIVE_HOURS}"
    SYNCRO_FIXES+=("$SLUG: hours ${WIKI_HOURS} → ${LIVE_HOURS}")
  fi

  # --- Check 2: Open ticket count (flag only, no auto-fix) ---
  OPEN_COUNT=$(curl -s "$BASE/tickets?customer_id=${CUST_ID}&status=New,In+Progress,Scheduled,Waiting+on+Customer&per_page=1&api_key=$API_KEY" | jq '.meta.total_count // (.tickets | length)')
  # Flag if article was compiled > 7 days ago and open ticket count changed
  COMPILED=$(grep -oP '(?<=last_compiled: )[\d-]+' "$ARTICLE")
  COMPILED_AGE=$(( ( $(date +%s) - $(date -d "$COMPILED" +%s 2>/dev/null || echo 0) ) / 86400 ))
  if [ "$COMPILED_AGE" -gt 7 ] && [ "$OPEN_COUNT" -gt 0 ]; then
    SYNCRO_TICKET_FLAGS+=("[TICKETS_CHECK] $SLUG — $OPEN_COUNT open ticket(s) in Syncro; article compiled ${COMPILED_AGE}d ago")
  fi
done
```

### Commit Fixes (if any)

```bash
if [ ${#SYNCRO_FIXES[@]} -gt 0 ]; then
  cd "$CLAUDETOOLS_ROOT"
  git add wiki/clients/*.md
  git commit -m "wiki-lint: Syncro live-check auto-fix (${#SYNCRO_FIXES[@]} article(s))"
  git push origin main
fi
```

### Add to Lint Report

Append to the report output:

```
### Syncro Live-Check (N auto-fixed, M flagged)
[SYNCRO][FIXED] cascades-tucson — hours: 37.5 → 31.0 (Syncro live as of YYYY-MM-DD)
[TICKETS_CHECK] valleywide — 2 open ticket(s) in Syncro; article compiled 14d ago
```

If API key is missing or Syncro is unreachable, emit `[SYNCRO] Skipped (API unavailable)` and continue.

---

## Output Format

Emit a clean lint report:

```
## Wiki Lint Report — YYYY-MM-DD

### Missing Articles (N)
[MISSING] wiki/clients/evs.md — 1 session log (2026-04-17)
...

### Stale Articles (N)
[STALE] wiki/clients/cascades-tucson.md — compiled 2026-05-24, 3 new logs since
...

### Broken Backlinks (N)
[BROKEN_LINK] wiki/clients/kittle.md → [[gururmm]] (no file found)
...

### Index Gaps (N)
[NOT_INDEXED] wiki/clients/new-client.md — not listed in index.md
...

### Compilation Queue — Stale Entries (N)
[QUEUE_STALE] client:birthbiologic — wiki/clients/birth-biologic.md exists; remove from queue
...

### Syncro Live-Check (N auto-fixed, M flagged)
[SYNCRO][FIXED] cascades-tucson — hours: 37.5 → 31.0 (Syncro live)
[TICKETS_CHECK] valleywide — 2 open ticket(s); article compiled 14d ago
...

### Summary
- N missing articles → run /wiki-compile for each
- N stale articles → run /wiki-compile to refresh
- N broken links → fix manually or after recompile
- N index gaps → update wiki/index.md
- N Syncro hours auto-fixed, M ticket flags for review
```

After the report, ask: "Run /wiki-compile for any of the missing articles now?"