cleargate 0.2.0 → 0.3.0

package/dist/templates/cleargate-planning/.claude/hooks/pre-commit-test-ratchet.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# pre-commit-test-ratchet.sh — STORY-014-04: Pre-existing Test-Failure Ratchet
+#
+# Invoked by .claude/hooks/pre-commit.sh dispatcher (STORY-014-01).
+# Runs test_ratchet.mjs in 'check' mode and blocks commit on regression.
+#
+# Bypass (discouraged): SKIP_TEST_RATCHET=1
+# Timeout: 120s (enough for current cleargate-cli suite ~45s)
+#
+# macOS compatibility: 'timeout' is GNU coreutils; on macOS use 'gtimeout' (brew coreutils).
+# Fallback: if neither is available, run without timeout and print a warning.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="${CLEARGATE_REPO_ROOT:-$(cd "${SCRIPT_DIR}/../.." && pwd)}"
+
+# ---------------------------------------------------------------------------
+# Bypass
+# ---------------------------------------------------------------------------
+if [[ "${SKIP_TEST_RATCHET:-0}" == "1" ]]; then
+  echo "test-ratchet: SKIP_TEST_RATCHET=1 — bypassing test ratchet check (discouraged)" >&2
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve timeout binary (GNU on Linux; gtimeout on macOS via brew)
+# ---------------------------------------------------------------------------
+TIMEOUT_CMD=""
+if command -v timeout &>/dev/null; then
+  TIMEOUT_CMD="timeout 120"
+elif command -v gtimeout &>/dev/null; then
+  TIMEOUT_CMD="gtimeout 120"
+else
+  echo "test-ratchet: WARNING — 'timeout' not found; running without 120s guard" >&2
+fi
+
+# ---------------------------------------------------------------------------
+# Run ratchet
+# ---------------------------------------------------------------------------
+RATCHET_SCRIPT="${REPO_ROOT}/.cleargate/scripts/test_ratchet.mjs"
+
+if [[ ! -f "${RATCHET_SCRIPT}" ]]; then
+  echo "test-ratchet: ERROR — ratchet script not found at ${RATCHET_SCRIPT}" >&2
+  exit 1
+fi
+
+export CLEARGATE_REPO_ROOT="${REPO_ROOT}"
+
+${TIMEOUT_CMD} node "${RATCHET_SCRIPT}" check
+STATUS=$?
+
+if [[ ${STATUS} -eq 124 ]]; then
+  echo "test-ratchet: ERROR — ratchet timed out after 120s; commit blocked" >&2
+  exit 1
+fi
+
+exit ${STATUS}

package/dist/templates/cleargate-planning/.claude/hooks/pre-commit.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# pre-commit.sh — Dispatcher: chains all pre-commit-*.sh hooks in lexical order.
+#
+# Install: ln -sf ../../.claude/hooks/pre-commit.sh .git/hooks/pre-commit
+#
+# Each pre-commit-*.sh is expected to exit 0 on success or non-zero to block.
+# The dispatcher exits on the first non-zero exit code.
+
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+for hook in "${HOOK_DIR}"/pre-commit-*.sh; do
+  [[ -f "${hook}" ]] || continue
+  [[ -x "${hook}" ]] || continue
+  bash "${hook}" || exit $?
+done
+
+exit 0

package/dist/templates/cleargate-planning/.claude/hooks/session-start.sh

@@ -2,3 +2,54 @@
 set -u
 REPO_ROOT="${CLAUDE_PROJECT_DIR}"
 node "${REPO_ROOT}/cleargate-cli/dist/cli.js" doctor --session-start 2>/dev/null || true
+
+# ── §14.9 SessionStart sync nudge (STORY-010-08) ─────────────────────────────
+# Daily-throttled: probe remote for updates at most once per 24h.
+# Never auto-pulls or auto-pushes. Exits 0 regardless of outcome.
+MARKER="${REPO_ROOT}/.cleargate/.sync-marker.json"
+NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+NOW_EPOCH=$(date +%s)
+
+if [ ! -f "${MARKER}" ]; then
+  # First run — write marker with current timestamp and skip MCP call (24h grace).
+  mkdir -p "$(dirname "${MARKER}")"
+  printf '{"last_check":"%s"}' "${NOW_ISO}" > "${MARKER}"
+else
+  # Parse last_check epoch from marker using node (portable, avoids jq dep)
+  LAST_CHECK_ISO=$(node -e "try{const m=JSON.parse(require('fs').readFileSync('${MARKER}','utf8'));process.stdout.write(m.last_check||'1970-01-01T00:00:00Z')}catch{process.stdout.write('1970-01-01T00:00:00Z')}" 2>/dev/null || echo "1970-01-01T00:00:00Z")
+  LAST_EPOCH=$(node -e "process.stdout.write(String(Math.floor(new Date('${LAST_CHECK_ISO}').getTime()/1000)))" 2>/dev/null || echo "0")
+  ELAPSED=$(( NOW_EPOCH - LAST_EPOCH ))
+
+  if [ "${ELAPSED}" -ge 86400 ]; then
+    # ≥24h since last check — run probe (3s timeout, R7 mitigation)
+    RESULT_FILE=$(mktemp)
+    # Cross-platform 3-second timeout: prefer `timeout` (Linux); fall back to
+    # background-process kill (macOS where GNU coreutils may be absent).
+    if command -v timeout > /dev/null 2>&1; then
+      timeout 3 node "${REPO_ROOT}/cleargate-cli/dist/cli.js" sync --check > "${RESULT_FILE}" 2>/dev/null || true
+    else
+      node "${REPO_ROOT}/cleargate-cli/dist/cli.js" sync --check > "${RESULT_FILE}" 2>/dev/null &
+      _PROBE_PID=$!
+      (sleep 3 && kill "${_PROBE_PID}" 2>/dev/null) &
+      _KILL_PID=$!
+      wait "${_PROBE_PID}" 2>/dev/null || true
+      kill "${_KILL_PID}" 2>/dev/null || true
+      wait "${_KILL_PID}" 2>/dev/null || true
+    fi
+    UPDATES=$(node -e "
+try {
+  var data = require('fs').readFileSync(process.argv[1], 'utf8').trim();
+  var obj = JSON.parse(data);
+  process.stdout.write(String(obj.updates || 0));
+} catch(e) {
+  process.stdout.write('0');
+}
+" "${RESULT_FILE}" 2>/dev/null || echo "0")
+    rm -f "${RESULT_FILE}"
+    if [ "${UPDATES}" -gt 0 ] 2>/dev/null; then
+      printf '📡 ClearGate: %s remote updates since yesterday — run `cleargate sync` to reconcile.\n' "${UPDATES}"
+    fi
+    # Marker is updated by sync --check itself; no re-write needed here.
+  fi
+fi
+exit 0

package/dist/templates/cleargate-planning/.claude/hooks/token-ledger.sh

@@ -32,7 +32,7 @@
 
 set -u
 
-REPO_ROOT="/Users/ssuladze/Documents/Dev/ClearGate"
+REPO_ROOT="${ORCHESTRATOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR}}"
 LOG_DIR="${REPO_ROOT}/.cleargate/hook-log"
 mkdir -p "${LOG_DIR}"
 HOOK_LOG="${LOG_DIR}/token-ledger.log"

package/dist/templates/cleargate-planning/.claude/settings.json

@@ -10,6 +10,17 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pending-task-sentinel.sh"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write",

package/dist/templates/cleargate-planning/.claude/skills/flashcard/SKILL.md

@@ -1,27 +1,37 @@
 ---
 name: flashcard
-description: Append-only project lesson log at .cleargate/FLASHCARD.md. Use BEFORE starting non-trivial work to read past gotchas ("check" mode). Use WHEN you hit a surprise, wasted time, or a non-obvious gotcha to record it for future agents ("record: <one-liner>" mode). One-liners only; tag with #schema/#auth/#test-harness/etc. Also triggers on phrases like "turns out", "unexpected", "gotcha", "wasted time on", "starting work on", "before implementing".
+description: Append-only project lesson log at .cleargate/FLASHCARD.md. Use BEFORE starting non-trivial work to read past gotchas ("check" mode). Use WHEN you (a) hit a surprise, (b) found the winning path after a non-trivial task succeeded, or (c) were corrected by the user — record a one-liner for future agents ("record: <text>" mode). One-liners only; tag with #schema/#auth/#test-harness/etc. Also triggers on phrases: "turns out", "unexpected", "gotcha", "wasted time on", "starting work on", "before implementing", "user pushed back", "prefer X over Y", "winning path", "after several attempts", "the recipe that worked".
 ---
 
 # Flashcard — Project Lesson Log
 
 Append-only one-liner log of non-obvious gotchas that future agents in this project should know. Lives at `.cleargate/FLASHCARD.md` in the project root. Not a general wiki — only things that surprised us and would surprise someone else.
 
-## Two modes
+## Modes
 
 ### `check` — read before work
-Read `.cleargate/FLASHCARD.md`. Scan for tags relevant to your current task (grep by `#schema`, `#auth`, etc.). If a card applies, follow its guidance. If unsure whether a card applies, err on applying it — reading 20 one-liners is cheap.
+Read `.cleargate/FLASHCARD.md`. Apply the Rule 8 filter: skip cards marked `[S]` (stale) or `[R]` (resolved) unless your current task directly matches a tag in a superseded card. Scan active cards for tags relevant to your task (grep by `#schema`, `#auth`, etc.). If unsure whether a card applies, err on applying it — reading 20 one-liners is cheap.
 
-### `record: <one-liner>` — write after surprise
-Append a single line to `.cleargate/FLASHCARD.md`. Format:
+Use `check-all` instead when investigating history or debugging a recurring issue — it includes `[S]` and `[R]` cards.
+
+### `record: <text>` — three trigger classes, same format
+Append a single line to `.cleargate/FLASHCARD.md`. Same 120-char cap regardless of trigger:
+
+1. **Surprise** — something bit us. Lead with the surprise, not the context.
+2. **Recipe** — the winning path after a non-trivial task succeeded (roughly 5+ tool calls, or one clear dead-end recovery). Lead with the *action that worked*, not the failures traversed. Tag `#recipe` alongside the domain tag.
+3. **Correction** — the user pushed back on an approach. Capture the rule, not the exchange. Prefer the shape "prefer X over Y because Z". Tag `#correction` alongside the domain tag.
+
+Format (unchanged):
 
 ```
 YYYY-MM-DD · #tag1 #tag2 · <lesson ≤ 120 chars>
 ```
 
-Example:
+Examples:
 ```
 2026-04-18 · #redis #auth · Invite tokens in Redis-only vanish on eviction — use Postgres invites table as source of truth.
+2026-04-19 · #recipe #wiki · For wiki drift detection, git SHA beats content hash — drops the metadata-lifecycle dependency.
+2026-04-19 · #correction #planning · Prefer two L1/L2 stories over one L3 at epic-decomposition (user: splits are free pre-push).
 ```
 
 ### Tag vocabulary (append new tags freely, but prefer these)
@@ -46,14 +56,21 @@ Example:
 3. **Lead with the surprise, not the context.** Good: "Drizzle 0.45 silently drops `DEFAULT gen_random_uuid()` — use `sql` template." Bad: "When working on schema migrations yesterday we found that sometimes…"
 4. **Lessons, not events.** "Shipped STORY-004-07 today" is NOT a flashcard. "Postgres 18 needs `pgcrypto` extension for gen_random_uuid — not enabled by default in official docker image" IS.
 5. **Ordered newest-first after the header** — new entries go at the TOP of the log section, not bottom. Readers scan the top; old stuff drifts down.
-6. **Never delete.** Edit to add reconfirmations or deprecation notes; keep the original text. History is the point.
+6. **Never delete.** Edit to add reconfirmations, supersede pointers, or status markers (Rule 7); keep the original text. History is the point.
+7. **Status markers for cleanup.** A card may carry a status marker placed *immediately after the second `·`* and before the lesson body:
+   - no marker → active (default; the vast majority of cards).
+   - `[S]` → stale. The symbol the card references no longer exists in the repo.
+   - `[R] → superseded-by <short-ref>` → resolved or replaced by a later card / shipped fix. `<short-ref>` is a date+tag (e.g. `2026-04-19/#hooks-sentinel`) or a STORY/CR ID.
+   Markers are additive — the original lesson text is preserved. The reporter agent flags candidates at sprint end; a human approves the batch before markers are applied (see `.claude/agents/reporter.md` → "Flashcard audit").
+8. **Check-mode filter.** `check` reads active cards only (no marker). Include `[S]` / `[R]` cards only when: (a) their tags directly match the current task area, or (b) the invocation is `check-all` (explicit history read). This keeps `check` signal-dense without losing the historical record.
 
 ## Invocation contract
 
 When an agent invokes this skill:
 
-- **`Skill(flashcard, "check")`** — open `.cleargate/FLASHCARD.md`, summarize any cards with tags relevant to the current task context in one line per card. If none apply, respond "no relevant flashcards" and proceed.
-- **`Skill(flashcard, "record: <text>")`** — parse the text for date + tags + body. If date missing, insert today's UTC date. If tags missing, refuse with "add at least one tag." Grep for duplicates; if dup, reconfirm the existing line instead of appending. Append to the top of the log section in the file.
+- **`Skill(flashcard, "check")`** — open `.cleargate/FLASHCARD.md`, apply the Rule 8 filter, summarize matching active cards in one line per card. If none apply, respond "no relevant flashcards" and proceed.
+- **`Skill(flashcard, "check-all")`** — same as `check` but includes `[S]` / `[R]` cards. Use when investigating history, debugging a recurring issue, or tracing a supersede chain.
+- **`Skill(flashcard, "record: <text>")`** — parse the text for date + tags + body. If date missing, insert today's UTC date. If tags missing, refuse with "add at least one tag." For recipe-class entries include `#recipe`; for correction-class entries include `#correction`. Grep for duplicates; if dup, reconfirm the existing line instead of appending. Append to the top of the log section in the file.
 
 ## File shape
 
@@ -63,11 +80,13 @@ When an agent invokes this skill:
 # ClearGate Flashcards
 
 One-liner gotcha log. Newest first. Grep by tag (e.g. `grep '#schema'`).
-Format: `YYYY-MM-DD · #tags · lesson`
+Active cards have no marker; `[S]` = stale, `[R]` = resolved (see SKILL.md Rule 7).
+Format: `YYYY-MM-DD · #tags · [marker]? lesson`
 
 ---
 
-2026-04-18 · #redis #auth · <newest lesson>
-2026-04-17 · #schema · <older lesson>
+2026-04-19 · #redis #auth · <newest active lesson>
+2026-04-17 · #schema · [S] drizzle-kit v0.42 silently drops indexes — fixed in v0.45 upgrade.
+2026-04-15 · #hooks · [R] → superseded-by 2026-04-19/#hooks-sentinel · SubagentStop fires on orchestrator not subagents.
 ...
 ```

package/dist/templates/cleargate-planning/.cleargate/FLASHCARD.md

@@ -1,6 +1,7 @@
 # ClearGate Flashcards
 
 One-liner gotcha log. Newest first. Grep by tag (e.g. `grep '#schema'`).
-Format: `YYYY-MM-DD · #tags · lesson`
+Active cards have no marker; `[S]` = stale, `[R]` = resolved (see `.claude/skills/flashcard/SKILL.md` Rules 7–8).
+Format: `YYYY-MM-DD · #tags · [marker]? lesson`
 
 ---

package/dist/templates/cleargate-planning/.cleargate/config.example.yml

@@ -0,0 +1,37 @@
+# ClearGate per-repo configuration.
+# Copy to .cleargate/config.yml and edit. All keys optional.
+
+# wiki:
+#   index_token_ceiling: 8000   # chars budget for wiki/index.md (STORY-015-03)
+
+# gates:
+#   precommit: "<command run before every commit — typecheck + tests>"
+#   test: "<command to run the test suite>"
+#   typecheck: "<command to run the type checker>"
+#   lint: "<command to run the linter>"
+
+# Node example:
+# gates:
+#   precommit: "npm run typecheck && npm test"
+#   test: "npm test"
+#   typecheck: "npm run typecheck"
+#   lint: "npm run lint"
+
+# Go example:
+# gates:
+#   precommit: "go vet ./... && go test ./..."
+#   test: "go test ./..."
+#   typecheck: "go build ./..."
+
+# Python example:
+# gates:
+#   precommit: "mypy . && pytest"
+#   test: "pytest"
+#   typecheck: "mypy ."
+
+# Rust example:
+# gates:
+#   precommit: "cargo check && cargo test"
+#   test: "cargo test"
+#   typecheck: "cargo check"
+#   lint: "cargo clippy"