portable-agent-layer 0.47.0 → 0.49.0

package/README.md

@@ -86,6 +86,7 @@ pal cli status        # check your setup
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
+| `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 
 ### Target flags
 

package/assets/STATUSLINE.md

@@ -0,0 +1,102 @@
+# PAL Status Line
+
+A customizable status line for Claude Code that displays context usage, active model, session cost, current directory, and git branch.
+
+## What It Shows
+
+**Line 1:** Model name, current directory, git branch, hook health, open ISCs, signal trend  
+**Line 2:** Context usage progress bar, percentage used, session cost, remaining context, rate limits  
+**Line 3:** Update notice (only when a new PAL version is available)
+
+Example output (macOS/Linux):
+```
+[Opus] 📁 portable-agent-layer  🌿 main  📋 21 open ISCs  sig: 3.0/10 ↓
+████████░░░░░░░░░░░░ 45% │ $0.12 │ 55% free
+```
+
+Example output (Windows):
+```
+[Opus] folder: portable-agent-layer  (git: main)  21 open ISCs  sig: 3.0/10 v
+########------------ 45% - $0.12 - 55% free
+```
+
+Colors adapt based on context usage:
+- 🟢 Green: 0-60% used
+- 🟡 Yellow: 60-80% used  
+- 🔴 Red: >80% used
+
+## Setup
+
+### On macOS / Linux
+
+1. Make the script executable:
+```bash
+chmod +x ~/.claude/statusline.sh
+```
+
+2. Add to `~/.claude/settings.json`:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.sh",
+    "padding": 2
+  }
+}
+```
+
+The statusline script is at: `portable-agent-layer/assets/statusline.sh`
+
+### On Windows
+
+1. Add to `~/.claude/settings.json`:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "powershell -NoProfile -Command \"Get-Content -Raw | & 'C:\\path\\to\\statusline.ps1'\"",
+    "padding": 2
+  }
+}
+```
+
+Or copy `statusline.ps1` to `~/.claude/statusline.ps1` and reference it from settings.
+
+The statusline script is at: `portable-agent-layer/assets/statusline.ps1`
+
+## Data Displayed
+
+- **Model:** Active Claude model (Opus, Sonnet, Haiku, etc.)
+- **Directory:** Repository name (if in a git repo) or folder name
+- **Git Branch:** Current branch, fetched from git worktree or `git` command
+- **Hook Health:** Count of ERROR lines in `~/.pal/memory/state/debug.log` from last 24h (hidden when 0)
+- **Open ISCs:** Count of unchecked ISCs for the current project (hidden when 0)
+- **Signal Trend:** Session quality score from `~/.pal/memory/state/signal-cache.json` with trend arrow
+- **Context Bar:** Visual progress bar showing token usage
+- **Context %:** Percentage of context window used
+- **Cost:** Estimated session cost in USD (shows "free" if <$0.01 on macOS/Linux, `$0.00` on Windows)
+- **Remaining %:** Percentage of context window remaining
+- **Rate Limits:** 5h and 7d usage percentages (Pro/Max plans only — hidden on other plans)
+- **Update Notice:** Shown on line 3 when `~/.pal/memory/state/update-available.json` flags a new version
+
+## Dependencies
+
+- **macOS/Linux:** `bash`, `jq`, `git` (for branch detection)
+- **Windows:** PowerShell 7+, `git` (for branch detection)
+
+## Customization
+
+Both scripts use `jq` to parse the JSON data Claude Code sends. You can modify them to:
+- Add or remove fields
+- Change colors (ANSI escape codes)
+- Adjust progress bar width
+- Show additional data like effort level, rate limits, or PR status
+
+Available fields are documented in the Claude Code statusline reference:
+https://code.claude.com/docs/en/statusline#available-data
+
+## Updates
+
+The status line runs after each assistant message, after `/compact`, and when vim mode toggles. It does not consume API tokens.
+
+Changes to the script appear on your next interaction with Claude Code.

package/assets/skills/create-skill/SKILL.md

@@ -57,7 +57,12 @@ The `description` should state **both what the skill does and when to invoke it*
    pal cli skill link <name>
    ```
    This creates the per-skill discovery symlink in each installed agent's skills directory (Claude Code, Cursor, Copilot, Codex); opencode discovers it automatically via `~/.pal/skills/`.
-6. Validate before declaring done:
+6. Run the doctor and resolve every error it reports:
+   ```bash
+   pal cli skill doctor <name>
+   ```
+   It checks the mechanical rules (folder/file-name match, name length/charset, description length, point-of-view, body length, reference depth). Fix all `✗` errors; weigh each `⚠` warning. A name/folder mismatch or a misnamed file makes the skill silently fail to load, so never skip this.
+7. Validate the rest by hand — the doctor can't judge these:
    - **Trigger clarity** — could a model decide *not* to invoke this from the description alone? If so, tighten it.
    - **Step concreteness** — every step has a verb and an object.
    - **Output specification** — the caller knows what they get back.

package/assets/statusline.ps1

@@ -0,0 +1,142 @@
+# PAL Status Line - Windows PowerShell version
+# Reads JSON from stdin (Claude Code session data) and prints a formatted status line
+
+$data = $input | Out-String | ConvertFrom-Json
+
+# Extract data with fallbacks (PowerShell 5.1 compatible)
+$MODEL = if ($data.model.display_name) { $data.model.display_name } else { "Unknown" }
+$USED_RAW = $data.context_window.used_percentage
+$USED = if ($USED_RAW -ne $null) { [int]$USED_RAW } else { 0 }
+$REM_RAW = $data.context_window.remaining_percentage
+$REM = if ($REM_RAW -ne $null) { [int]$REM_RAW } else { 0 }
+$COST_RAW = $data.cost.total_cost_usd
+$COST = if ($COST_RAW -ne $null) { [double]$COST_RAW } else { 0 }
+$CWD = if ($data.workspace.current_dir) { $data.workspace.current_dir } else { "~" }
+$REPO = if ($data.workspace.repo.name) { $data.workspace.repo.name } else { "" }
+
+# Extract git branch
+$BRANCH = ""
+try { $BRANCH = & git -C $CWD rev-parse --abbrev-ref HEAD 2>$null } catch { $BRANCH = "" }
+
+# Format directory
+$DIR_DISPLAY = if ($REPO) { $REPO } else { Split-Path -Leaf $CWD }
+
+# Format git branch indicator
+$GIT_INDICATOR = if ($BRANCH) { "  (git: $BRANCH)" } else { "" }
+
+# Format cost
+$COST_STR = '$' + ([math]::Round($COST, 2)).ToString("0.00")
+
+# PAL: Hook health - count ERROR lines in debug.log from last 24h
+$HOOK_ERRORS = 0
+$debugLog = Join-Path $env:USERPROFILE ".pal\memory\state\debug.log"
+if (Test-Path $debugLog) {
+  $cutoff = (Get-Date).AddHours(-24)
+  try {
+    $HOOK_ERRORS = (Get-Content $debugLog -ErrorAction SilentlyContinue |
+      Where-Object { $_ -match '\] ERROR ' } |
+      Where-Object {
+        $m = [regex]::Match($_, '^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]')
+        if ($m.Success) { [datetime]$m.Groups[1].Value -gt $cutoff } else { $false }
+      }).Count
+  } catch { $HOOK_ERRORS = 0 }
+}
+
+# PAL: Open ISC count - find project matching current directory
+$OPEN_ISCS = 0
+$PROJECT_NAME = ""
+$projectsDir = Join-Path $env:USERPROFILE ".pal\memory\projects"
+if (Test-Path $projectsDir) {
+  try {
+    $CWD_NORM = $CWD.Replace('/', '\').TrimEnd('\')
+    foreach ($slug in Get-ChildItem $projectsDir -Directory | Select-Object -ExpandProperty Name) {
+      $isa = Join-Path $projectsDir "$slug\ISA.md"
+      if (-not (Test-Path $isa)) { continue }
+      $content = Get-Content $isa -Raw -ErrorAction SilentlyContinue
+      $pathMatch = [regex]::Match($content, 'path:\s*"?([^"\n\r]+)"?')
+      if ($pathMatch.Success) {
+        $projPath = $pathMatch.Groups[1].Value.Trim().Replace('/', '\').TrimEnd('\')
+        if ($projPath -eq $CWD_NORM -or $CWD_NORM.StartsWith($projPath)) {
+          $PROJECT_NAME = $slug
+          $OPEN_ISCS = ([regex]::Matches($content, '- \[ \] ISC-')).Count
+          break
+        }
+      }
+    }
+  } catch { $OPEN_ISCS = 0 }
+}
+
+# Rate limits (Pro/Max only - absent for other plans)
+$FIVE_H_RAW = $data.rate_limits.five_hour.used_percentage
+$SEVEN_D_RAW = $data.rate_limits.seven_day.used_percentage
+$RATE_PARTS = @()
+if ($FIVE_H_RAW -ne $null) { $RATE_PARTS += "5h: $([int]$FIVE_H_RAW)%" }
+if ($SEVEN_D_RAW -ne $null) { $RATE_PARTS += "7d: $([int]$SEVEN_D_RAW)%" }
+$RATE_STR = if ($RATE_PARTS.Count -gt 0) { " - " + ($RATE_PARTS -join " | ") } else { "" }
+
+# Create context progress bar - if both are 0, data not yet available (pre-first API call)
+$NO_DATA = ($USED_RAW -eq $null -and $REM_RAW -eq $null)
+if ($NO_DATA) { $USED = 0; $REM = 100 }
+$FILLED = [int]($USED / 5)
+$EMPTY = 20 - $FILLED
+$BAR = ("#" * $FILLED) + ("-" * $EMPTY)
+
+# ANSI color codes (PowerShell 5.1 compatible - use concatenation to avoid array-index expansion)
+$ESC = [char]27
+$CYAN   = $ESC + "[36m"
+$GREEN  = $ESC + "[32m"
+$YELLOW = $ESC + "[33m"
+$RED    = $ESC + "[31m"
+$DIM    = $ESC + "[90m"
+$RESET  = $ESC + "[0m"
+
+# Choose bar color based on context usage
+$BAR_COLOR = if ($USED -gt 80) { $RED } elseif ($USED -gt 60) { $YELLOW } else { $GREEN }
+
+# PAL: Signal trend (reads 10-min cache written by session intelligence)
+$SIGNAL_STR = ""
+$signalCache = Join-Path $env:USERPROFILE ".pal\memory\state\signal-cache.json"
+if (Test-Path $signalCache) {
+  try {
+    $sc = Get-Content $signalCache -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json
+    if ($sc.today -ne $null) {
+      $ARROW = switch ($sc.trend) {
+        "up"     { "^"; break }
+        "down"   { "v"; break }
+        "stable" { "-"; break }
+        default  { "?"; break }
+      }
+      $SIG_TODAY = ([math]::Round([double]$sc.today, 1)).ToString("0.0")
+      $SIG_COLOR = if ($sc.trend -eq "up") { $GREEN } elseif ($sc.trend -eq "down") { $RED } else { $DIM }
+      $SIGNAL_STR = "  " + $SIG_COLOR + "sig: $SIG_TODAY/10 $ARROW" + $RESET
+    }
+  } catch {}
+}
+
+# PAL: Update available check (reads cached result, no network call)
+# Emoji constructed at runtime to avoid PS5.1 UTF-8-without-BOM encoding issues
+$UPDATE_LINE = ""
+$updateCache = Join-Path $env:USERPROFILE ".pal\memory\state\update-available.json"
+if (Test-Path $updateCache) {
+  try {
+    $uc = Get-Content $updateCache -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json
+    if ($uc.available -eq $true) {
+      $versionStr = if ($uc.current -ne $uc.latest) { "$($uc.current) -> $($uc.latest)" } else { $uc.current + " (new commits)" }
+      $UPDATE_LINE = "[update] $versionStr  run: pal cli update"
+    }
+  } catch {}
+}
+
+# Build PAL indicators
+$HOOK_STR = if ($HOOK_ERRORS -gt 0) { "  " + $RED + "! $HOOK_ERRORS hook err" + $RESET } else { "" }
+$ISC_STR  = if ($OPEN_ISCS -gt 0)   { "  " + $DIM + "$OPEN_ISCS open ISCs" + $RESET }  else { "" }
+
+# Line 1: Model, Directory, Git Branch, Hook Health, Open ISCs
+Write-Host ($CYAN + "[$MODEL]" + $RESET + " folder: $DIR_DISPLAY" + $DIM + $GIT_INDICATOR + $RESET + $HOOK_STR + $ISC_STR + $SIGNAL_STR)
+
+# Line 2: Context bar with usage percentage, cost, and rate limits
+$CTX_STR = "$USED% - $COST_STR - ${REM}% free"
+Write-Host ($BAR_COLOR + $BAR + $RESET + " " + $CTX_STR + $DIM + $RATE_STR + $RESET)
+
+# Line 3: Update available (only when cache says available AND versions differ)
+if ($UPDATE_LINE) { Write-Host ($YELLOW + $UPDATE_LINE + $RESET) }

package/assets/statusline.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# PAL Status Line — macOS/Linux
+# Reads JSON from stdin (Claude Code session data) and prints a formatted status line
+
+input=$(cat)
+
+# Extract data with fallbacks
+MODEL=$(echo "$input" | jq -r '.model.display_name // "Unknown"')
+USED_RAW=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
+REM_RAW=$(echo "$input" | jq -r '.context_window.remaining_percentage // empty')
+USED=$( [ -n "$USED_RAW" ] && echo "${USED_RAW%.*}" || echo 0 )
+REMAINING=$( [ -n "$REM_RAW" ] && echo "${REM_RAW%.*}" || echo 0 )
+COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
+CWD=$(echo "$input" | jq -r '.workspace.current_dir // "~"')
+REPO=$(echo "$input" | jq -r '.workspace.repo.name // ""')
+
+# No data yet (pre-first API call)
+if [ -z "$USED_RAW" ] && [ -z "$REM_RAW" ]; then
+  USED=0; REMAINING=100
+fi
+
+# Extract git branch — try multiple sources for robustness
+BRANCH=$(echo "$input" | jq -r '.worktree.branch // ""')
+if [ -z "$BRANCH" ]; then
+  BRANCH=$(git -C "$CWD" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+fi
+
+# Format directory — show repo name if available, else just folder name
+if [ -n "$REPO" ]; then
+  DIR_DISPLAY="$REPO"
+else
+  DIR_DISPLAY="${CWD##*/}"
+fi
+
+# Format git branch with emoji indicator
+if [ -n "$BRANCH" ]; then
+  GIT_INDICATOR="  (🌿 ${BRANCH})"
+else
+  GIT_INDICATOR=""
+fi
+
+# Format cost — show as $X.XX or 'free' if < $0.01
+if (( $(echo "$COST < 0.01" | bc -l) )); then
+  COST_STR="free"
+else
+  COST_STR=$(printf '$%.2f' "$COST")
+fi
+
+# PAL: Hook health — count ERROR lines in debug.log from last 24h
+HOOK_ERRORS=0
+DEBUG_LOG="$HOME/.pal/memory/state/debug.log"
+if [ -f "$DEBUG_LOG" ]; then
+  # Cross-platform 24h cutoff: macOS uses date -v, GNU Linux uses date -d
+  CUTOFF=$(date -v-24H "+%Y-%m-%d %H:%M:%S" 2>/dev/null || date -d '24 hours ago' "+%Y-%m-%d %H:%M:%S" 2>/dev/null)
+  if [ -n "$CUTOFF" ]; then
+    # Log format: [YYYY-MM-DD HH:MM:SS] LEVEL ... — split on [ or ] to get $2 = timestamp
+    HOOK_ERRORS=$(grep '\] ERROR ' "$DEBUG_LOG" | awk -F'[][]]' '$2 > "'"$CUTOFF"'"' | wc -l | tr -d ' ')
+  else
+    HOOK_ERRORS=$(grep -c '\] ERROR ' "$DEBUG_LOG" 2>/dev/null || echo 0)
+  fi
+fi
+
+# PAL: Open ISC count — find project matching current directory
+OPEN_ISCS=0
+PROJECTS_DIR="$HOME/.pal/memory/projects"
+if [ -d "$PROJECTS_DIR" ]; then
+  CWD_NORM="${CWD%/}"
+  for ISA in "$PROJECTS_DIR"/*/ISA.md; do
+    [ -f "$ISA" ] || continue
+    PROJ_PATH=$(grep -m1 'path:' "$ISA" | sed 's/.*path:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+    PROJ_PATH="${PROJ_PATH%/}"
+    if [ "$PROJ_PATH" = "$CWD_NORM" ] || [[ "$CWD_NORM" == "${PROJ_PATH}/"* ]]; then
+      OPEN_ISCS=$(grep -c '- \[ \] ISC-' "$ISA" 2>/dev/null || echo 0)
+      break
+    fi
+  done
+fi
+
+# Rate limits (Pro/Max only — absent for other plans)
+FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
+SEVEN_D=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
+RATE_PARTS=()
+[ -n "$FIVE_H" ] && RATE_PARTS+=("5h: ${FIVE_H%.*}%")
+[ -n "$SEVEN_D" ] && RATE_PARTS+=("7d: ${SEVEN_D%.*}%")
+RATE_STR=""
+if [ ${#RATE_PARTS[@]} -gt 0 ]; then
+  RATE_STR=" │ $(IFS=" | "; echo "${RATE_PARTS[*]}")"
+fi
+
+# Create context progress bar (20 chars wide)
+FILLED=$((USED / 5))
+EMPTY=$((20 - FILLED))
+if [ "$FILLED" -le 0 ]; then
+  BAR="░░░░░░░░░░░░░░░░░░░░"
+elif [ "$FILLED" -ge 20 ]; then
+  BAR="████████████████████"
+else
+  BAR=$(printf '█%.0s' $(seq 1 $FILLED))$(printf '░%.0s' $(seq 1 $EMPTY))
+fi
+
+# Color codes (ANSI)
+CYAN='\033[36m'
+GREEN='\033[32m'
+YELLOW='\033[33m'
+RED='\033[31m'
+DIM='\033[90m'
+RESET='\033[0m'
+
+# Choose bar color based on context usage
+if [ "$USED" -gt 80 ]; then
+  CONTEXT_COLOR=$RED
+elif [ "$USED" -gt 60 ]; then
+  CONTEXT_COLOR=$YELLOW
+else
+  CONTEXT_COLOR=$GREEN
+fi
+
+# PAL: Signal trend (reads 10-min cache written by session intelligence)
+SIGNAL_STR=""
+SIGNAL_CACHE="$HOME/.pal/memory/state/signal-cache.json"
+if [ -f "$SIGNAL_CACHE" ]; then
+  SC_TODAY=$(jq -r '.today // empty' "$SIGNAL_CACHE" 2>/dev/null)
+  SC_TREND=$(jq -r '.trend // empty' "$SIGNAL_CACHE" 2>/dev/null)
+  if [ -n "$SC_TODAY" ]; then
+    case "$SC_TREND" in
+      up)     ARROW="↑"; SIG_COLOR=$GREEN ;;
+      down)   ARROW="↓"; SIG_COLOR=$RED ;;
+      stable) ARROW="→"; SIG_COLOR=$DIM ;;
+      *)      ARROW="?"; SIG_COLOR=$DIM ;;
+    esac
+    SIG_TODAY=$(printf "%.1f" "$SC_TODAY")
+    SIGNAL_STR="  ${SIG_COLOR}sig: ${SIG_TODAY}/10 ${ARROW}${RESET}"
+  fi
+fi
+
+# PAL: Update available check (reads cached result, no network call)
+UPDATE_LINE=""
+UPDATE_CACHE="$HOME/.pal/memory/state/update-available.json"
+if [ -f "$UPDATE_CACHE" ]; then
+  UC_AVAIL=$(jq -r '.available // false' "$UPDATE_CACHE" 2>/dev/null)
+  if [ "$UC_AVAIL" = "true" ]; then
+    UC_CURRENT=$(jq -r '.current // ""' "$UPDATE_CACHE" 2>/dev/null)
+    UC_LATEST=$(jq -r '.latest // ""' "$UPDATE_CACHE" 2>/dev/null)
+    if [ "$UC_CURRENT" != "$UC_LATEST" ]; then
+      VERSION_STR="$UC_CURRENT → $UC_LATEST"
+    else
+      VERSION_STR="$UC_CURRENT (new commits)"
+    fi
+    UPDATE_LINE="📦 update: $VERSION_STR  run: pal cli update"
+  fi
+fi
+
+# Build PAL indicators
+HOOK_STR=""
+[ "$HOOK_ERRORS" -gt 0 ] && HOOK_STR="  ${RED}⚠️  ${HOOK_ERRORS} hook err${RESET}"
+ISC_STR=""
+[ "$OPEN_ISCS" -gt 0 ] && ISC_STR="  ${DIM}📋 ${OPEN_ISCS} open ISCs${RESET}"
+
+# Line 1: Model, Directory, Git Branch, Hook Health, Open ISCs, Signal
+echo -e "${CYAN}[${MODEL}]${RESET} 📁 ${DIR_DISPLAY}${DIM}${GIT_INDICATOR}${RESET}${HOOK_STR}${ISC_STR}${SIGNAL_STR}"
+
+# Line 2: Context bar with usage percentage, cost, and rate limits
+echo -e "${CONTEXT_COLOR}${BAR}${RESET} ${USED}% │ ${COST_STR} │ ${REMAINING}% free${DIM}${RATE_STR}${RESET}"
+
+# Line 3: Update available (only when cache says available AND versions differ)
+[ -n "$UPDATE_LINE" ] && echo -e "${YELLOW}${UPDATE_LINE}${RESET}"
+exit 0

package/assets/templates/PAL/ALGORITHM.md

@@ -165,6 +165,18 @@ Refine criteria if the pressure test reveals gaps. Add criteria for uncovered fa
 - Decide execution order — what's serial, what can parallelize
 - **Extended+:** use EnterPlanMode for user alignment before executing
 
+**Grounding Gate — verify the premises before EXECUTE.**
+
+Don't just *list* what must be true — actively confirm the load-bearing facts the criteria rest on. For each premise (a reported behavior, a provider/API contract, an external tool's CLI, a file's contents, a claim about system state):
+- **Reproduce** the reported behavior before designing a fix — no fix on an unreproduced bug.
+- **Fetch the authoritative source** (live docs, the actual file, `gh api`) before asserting how something works.
+- **Probe the dependency/contract** (tool availability, MCP account, env var, DB connectivity, exact CLI) before building on it.
+- **Confirm one concrete artifact** (a commit, a shebang, a line of output) behind any external claim.
+
+No criterion may rest on an unverified premise. If a premise can't be verified now, mark it explicitly as an assumption and add a criterion to check it during EXECUTE. After 2 failed attempts at the same sub-problem, stop and re-ground — re-run OBSERVE rather than iterating on a bad premise.
+
+Output: `🧭 GROUNDING: [premises verified, or assumptions flagged]`
+
 ### ━━━ ⚡ EXECUTE ━━━ 3/5
 
 Do the work. Invoke selected capabilities via tool calls.
@@ -217,9 +229,11 @@ Focus: reasoning approach, problem decomposition, anticipation, blind spots.
 
 ```bash
 bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed N --failed N --sentiment 1-10 \
-  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection" --scope general
 ```
 
+Set `--scope task-specific` when the Q2 idea is bound to this one task (e.g. a criterion that only matters for the specific file, API, or dataset you were handling) and would not generalize to the algorithm; use `general` (the default) for reusable structural improvements. This keeps the algorithm-update synthesis focused on changes worth folding into ALGORITHM.md.
+
 **3. Relationship note** — write one Session entry capturing what was done this session:
 
 ```bash
@@ -316,6 +330,7 @@ Only write if the insight is **genuine and reusable** — not every session prod
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
 🧠 PREMORTEM: [failure modes]
+🧭 GROUNDING: [premises verified, or assumptions flagged]
 📐 APPROACH: [execution plan]
 
 ━━━ ⚡ EXECUTE ━━━ 3/5

package/assets/templates/settings.claude.json

@@ -25,6 +25,27 @@
       "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)"
     ]
   },
+  "skillOverrides": {
+    "claude-api": "off",
+    "update-config": "off",
+    "deep-research": "off",
+    "code-review": "off"
+  },
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "showClearContextOnPlanAccept": true,
+  "respectGitignore": true,
+  "spinnerTipsEnabled": true,
+  "spinnerTipsOverride": {
+    "tips": [
+      "Need something reusable? Use the /create-skill command.",
+      "PAL learns from your feedback and improves over time. Don't be shy to give feedback!",
+      "For simple PDFs use the /create-pdf skill. Need a styled one? Use /consulting-report instead.",
+      "Use the /research skill to run comprehensive web research with multiple parallel agents."
+    ]
+  },
   "hooks": {
     "SessionStart": [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -17,6 +17,7 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
+ *   skill doctor <name>               Evaluate a skill against the authoring best practices
  */
 
 import { spawnSync } from "node:child_process";
@@ -242,6 +243,7 @@ function showHelp() {
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
+    pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)

package/src/cli/skill.ts

@@ -1,15 +1,30 @@
 /**
  * pal cli skill — manage personal skills under ~/.pal/skills/.
  *
- *   pal cli skill link <name>   Link an existing ~/.pal/skills/<name>/ into
- *                               every installed agent so it is discoverable.
+ *   pal cli skill link <name>     Link an existing ~/.pal/skills/<name>/ into
+ *                                 every installed agent so it is discoverable.
+ *   pal cli skill doctor <name>   Evaluate ~/.pal/skills/<name>/ against the
+ *                                 skill-authoring best practices.
  */
 
+import { resolve } from "node:path";
+import { palHome } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
+import { formatReport, lintSkill } from "../tools/skill-doctor";
 
 export async function runSkill(args: string[]): Promise<number> {
   const [sub, name] = args;
 
+  if (sub === "doctor") {
+    if (!name) {
+      log.error("Usage: pal cli skill doctor <name>");
+      return 1;
+    }
+    const report = lintSkill(resolve(palHome(), "skills", name));
+    console.log(formatReport(report));
+    return report.errors > 0 ? 1 : 0;
+  }
+
   if (sub === "link") {
     if (!name) {
       log.error("Usage: pal cli skill link <name>");
@@ -35,6 +50,6 @@ export async function runSkill(args: string[]): Promise<number> {
     }
   }
 
-  log.error("Usage: pal cli skill link <name>");
+  log.error("Usage: pal cli skill <link|doctor> <name>");
   return 1;
 }

package/src/hooks/lib/algorithm-review.ts

@@ -0,0 +1,85 @@
+/**
+ * Algorithm-review cadence — decides when to nudge the MAINTAINER to run an
+ * `/algorithm-update` session (fold accumulated Q2 reflections into ALGORITHM.md).
+ *
+ * Maintainer-only by construction: the nudge fires solely in a PAL repo checkout,
+ * detected by the presence of the repo-only `.agents/skills/algorithm-update`
+ * skill. That path never ships to downstream installs — package.json `files`
+ * lists only `src/` and `assets/`, so `.agents/` is absent everywhere except a
+ * source checkout. Downstream users therefore never see this nudge.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { readReflections } from "./learning-store";
+import { palPkg, paths } from "./paths";
+
+const NUDGE_MIN_COUNT = 25;
+const NUDGE_MIN_DAYS = 7;
+const DAY_MS = 86_400_000;
+
+function markFile(): string {
+  return resolve(paths.state(), "algorithm-review.json");
+}
+
+export function readReviewMark(): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(markFile(), "utf-8"));
+    return typeof parsed.lastReviewedTs === "string" ? parsed.lastReviewedTs : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeReviewMark(ts: string): void {
+  writeFileSync(markFile(), `${JSON.stringify({ lastReviewedTs: ts }, null, 2)}\n`);
+}
+
+/** True only in a maintainer repo checkout — the repo-only update skill is present. */
+export function isMaintainerEnv(): boolean {
+  return existsSync(
+    resolve(palPkg(), ".agents", "skills", "algorithm-update", "SKILL.md")
+  );
+}
+
+/** Count reflections newer than the last review mark (all of them, if never reviewed). */
+export function countUnreviewed(mark: string | null = readReviewMark()): number {
+  const reflections = readReflections(paths.reflectionsFile());
+  if (!mark) return reflections.length;
+  const cutoff = new Date(mark).getTime();
+  return reflections.filter((r) => r.ts && new Date(r.ts).getTime() > cutoff).length;
+}
+
+export interface ReviewNudge {
+  count: number;
+  sinceDays: number;
+  since: string | null;
+}
+
+/**
+ * Nudge data when BOTH thresholds are met (≥25 new AND ≥7 days) in a maintainer
+ * env, else null. `now` is injected for testability.
+ */
+export function algorithmReviewNudge(now: Date): ReviewNudge | null {
+  if (!isMaintainerEnv()) return null;
+  const mark = readReviewMark();
+  const count = countUnreviewed(mark);
+  if (count < NUDGE_MIN_COUNT) return null;
+  const sinceDays = mark
+    ? Math.floor((now.getTime() - new Date(mark).getTime()) / DAY_MS)
+    : Number.POSITIVE_INFINITY;
+  if (sinceDays < NUDGE_MIN_DAYS) return null;
+  return { count, sinceDays, since: mark };
+}
+
+/** Formatted nudge section for the session reminder, or "" when it shouldn't fire. */
+export function loadAlgorithmReviewNudge(now: Date = new Date()): string {
+  const n = algorithmReviewNudge(now);
+  if (!n) return "";
+  const since = n.since ? new Date(n.since).toISOString().slice(0, 10) : "the start";
+  const age = Number.isFinite(n.sinceDays) ? `, ${n.sinceDays}d` : "";
+  return [
+    "## Algorithm Review Due",
+    `🔧 ${n.count} new algorithm reflections since ${since}${age} — run \`/algorithm-update\` to fold the recurring ones into ALGORITHM.md.`,
+  ].join("\n");
+}