cleargate 0.1.0-alpha.1 → 0.2.1

package/templates/cleargate-planning/.claude/hooks/stamp-and-gate.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -u
+REPO_ROOT="${CLAUDE_PROJECT_DIR}"
+LOG="${REPO_ROOT}/.cleargate/hook-log/gate-check.log"
+mkdir -p "$(dirname "$LOG")"
+FILE=$(jq -r '.tool_input.file_path' 2>/dev/null || echo "")
+[ -z "$FILE" ] && exit 0
+case "$FILE" in *.cleargate/delivery/*) : ;; *) exit 0 ;; esac
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+# Ordered chain — stamp MUST precede gate (gate may read draft_tokens)
+node "${REPO_ROOT}/cleargate-cli/dist/cli.js" stamp-tokens "$FILE" >>"$LOG" 2>&1
+SR1=$?
+node "${REPO_ROOT}/cleargate-cli/dist/cli.js" gate check "$FILE" >>"$LOG" 2>&1
+SR2=$?
+node "${REPO_ROOT}/cleargate-cli/dist/cli.js" wiki ingest "$FILE" >>"$LOG" 2>&1
+SR3=$?
+echo "[$TS] stamp=$SR1 gate=$SR2 ingest=$SR3 file=$FILE" >>"$LOG"
+exit 0   # ALWAYS 0 — severity enforcement is at wiki lint, not hook

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# SubagentStop hook: append one JSONL row per subagent completion to the active sprint's token ledger.
+#
+# Input: JSON on stdin from Claude Code with fields session_id, transcript_path, cwd, hook_event_name.
+# Output: appends to .cleargate/sprint-runs/<sprint-id>/token-ledger.jsonl
+# Cost computation is deferred to the Reporter agent (prices change; keep raw).
+#
+# Active sprint detection (FIXED 2026-04-19):
+#   Primary  : .cleargate/sprint-runs/.active sentinel file (one line: "SPRINT-NN")
+#              Orchestrator writes this at sprint kickoff, removes/updates at close.
+#   Fallback : .cleargate/sprint-runs/_off-sprint/token-ledger.jsonl
+#              When no .active sentinel exists, writes still get captured but
+#              tagged off-sprint instead of misrouting to a stale sprint dir.
+#   (Removed): the old `ls -td sprint-runs/*/ | head -1` mtime heuristic — it
+#              misrouted SPRINT-04 firings to SPRINT-03 because ledger appends
+#              themselves bumped SPRINT-03's mtime. See REPORT.md SPRINT-04.
+#
+# Work-item ID detection (GENERALIZED 2026-04-19 STORY-008-04):
+#   Primary  : first user message in the transcript — that's the orchestrator's
+#              dispatch prompt, which by agent convention starts with
+#              `STORY=NNN-NN`, `PROPOSAL-NNN`, `EPIC-NNN`, `CR-NNN`, or `BUG-NNN`.
+#   Pattern  : (STORY|PROPOSAL|EPIC|CR|BUG)[-=]?[0-9]+(-[0-9]+)?
+#   Fallback : grep first match anywhere in the transcript.
+#   story_id : populated only when the match is a STORY-* (backward compat).
+#   work_item_id: always populated when detection succeeds; equals story_id for STORY items.
+#   (Removed): grep-first-anywhere as PRIMARY — it picked up SPRINT-05 mentions
+#              from architect plans being read by the subagent and mistagged
+#              every SPRINT-04 firing as STORY-006-01.
+#
+# Robustness: never exits non-zero on parse failure (never block a subagent stop). Errors go to a
+# sibling hook.log so you can diagnose without fighting the runtime.
+
+set -u
+
+REPO_ROOT="/Users/ssuladze/Documents/Dev/ClearGate"
+LOG_DIR="${REPO_ROOT}/.cleargate/hook-log"
+mkdir -p "${LOG_DIR}"
+HOOK_LOG="${LOG_DIR}/token-ledger.log"
+ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
+
+{
+  INPUT="$(cat)"
+
+  # --- parse hook payload ---
+  TRANSCRIPT_PATH="$(printf '%s' "${INPUT}" | jq -r '.transcript_path // empty')"
+  SESSION_ID="$(printf '%s' "${INPUT}" | jq -r '.session_id // empty')"
+
+  if [[ -z "${TRANSCRIPT_PATH}" || ! -f "${TRANSCRIPT_PATH}" ]]; then
+    printf '[%s] no transcript_path (session=%s)\n' "$(date -u +%FT%TZ)" "${SESSION_ID}" >> "${HOOK_LOG}"
+    exit 0
+  fi
+
+  # --- determine active sprint via sentinel ---
+  SPRINT_ID=""
+  if [[ -f "${ACTIVE_SENTINEL}" ]]; then
+    SPRINT_ID="$(tr -d '[:space:]' < "${ACTIVE_SENTINEL}")"
+  fi
+
+  if [[ -n "${SPRINT_ID}" ]]; then
+    SPRINT_DIR="${REPO_ROOT}/.cleargate/sprint-runs/${SPRINT_ID}"
+    mkdir -p "${SPRINT_DIR}"
+    printf '[%s] routing to sprint=%s (sentinel)\n' "$(date -u +%FT%TZ)" "${SPRINT_ID}" >> "${HOOK_LOG}"
+  else
+    # No active sprint: capture the row in an off-sprint ledger so we don't lose data.
+    SPRINT_ID="_off-sprint"
+    SPRINT_DIR="${REPO_ROOT}/.cleargate/sprint-runs/_off-sprint"
+    mkdir -p "${SPRINT_DIR}"
+    printf '[%s] no .active sentinel — bucketing as _off-sprint\n' "$(date -u +%FT%TZ)" >> "${HOOK_LOG}"
+  fi
+  LEDGER="${SPRINT_DIR}/token-ledger.jsonl"
+
+  # --- walk transcript, sum usage across all assistant turns in this subagent run ---
+  USAGE_JSON="$(jq -cs '
+    map(select(.type == "assistant" and .message.usage))
+    | (map(.message.usage.input_tokens // 0)                     | add) as $in
+    | (map(.message.usage.output_tokens // 0)                    | add) as $out
+    | (map(.message.usage.cache_creation_input_tokens // 0)      | add) as $cc
+    | (map(.message.usage.cache_read_input_tokens // 0)          | add) as $cr
+    | (map(.message.model) | unique | map(select(. != null)) | join(","))     as $models
+    | (length)                                                   as $turns
+    | {input: $in, output: $out, cache_creation: $cc, cache_read: $cr, model: $models, turns: $turns}
+  ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+
+  if [[ -z "${USAGE_JSON}" || "${USAGE_JSON}" == "null" ]]; then
+    printf '[%s] could not parse usage from %s\n' "$(date -u +%FT%TZ)" "${TRANSCRIPT_PATH}" >> "${HOOK_LOG}"
+    exit 0
+  fi
+
+  # --- detect agent_type ---
+  # Subagent transcripts contain `subagent_type` in the parent's tool invocation.
+  # Best-effort extraction; falls back to grepping role markers in the transcript body.
+  AGENT_TYPE="$(jq -rs '
+    [.[] | select(.type == "user") | .message.content]
+    | tostring
+    | capture("subagent_type[\"\\s:=]+(?<t>[a-zA-Z0-9_-]+)"; "g")?.t
+    // "unknown"
+  ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+  [[ -z "${AGENT_TYPE}" || "${AGENT_TYPE}" == "null" ]] && AGENT_TYPE="unknown"
+
+  if [[ "${AGENT_TYPE}" == "unknown" ]]; then
+    for role in architect developer qa reporter; do
+      if grep -qiE "\\b${role}\\b agent|role: ${role}|you are the ${role}" "${TRANSCRIPT_PATH}" 2>/dev/null; then
+        AGENT_TYPE="${role}"
+        break
+      fi
+    done
+  fi
+
+  # --- detect work_item_id (PRIMARY: first user message; FALLBACK: anywhere-grep) ---
+  # Orchestrator convention (.claude/agents/developer.md): the first line of the
+  # dispatch prompt is `STORY=NNN-NN`. The first user message in the transcript
+  # is that prompt. Look there first to avoid picking up work-item mentions inside
+  # the subagent's later reads of plans, sprint files, etc.
+  #
+  # Pattern covers: STORY-NNN-NN, PROPOSAL-NNN, EPIC-NNN, CR-NNN, BUG-NNN
+  # (and = separator variants like STORY=008-04)
+  WORK_ITEM_RAW="$(jq -rs '
+    [.[] | select(.type == "user")] | .[0].message.content
+    | if type == "array" then map(.text? // "") | join(" ") else (. // "") end
+    | tostring
+    | scan("(STORY|PROPOSAL|EPIC|CR|BUG)[-=]?([0-9]+(-[0-9]+)?)") | .[0:2] | join("-")
+  ' "${TRANSCRIPT_PATH}" 2>/dev/null | head -1)"
+
+  if [[ -n "${WORK_ITEM_RAW}" && "${WORK_ITEM_RAW}" != "null" && "${WORK_ITEM_RAW}" != "-" ]]; then
+    # Normalize: replace any = separator with - in the result
+    WORK_ITEM_ID="$(printf '%s' "${WORK_ITEM_RAW}" | sed 's/=/-/g')"
+  else
+    # Fallback: grep anywhere in the transcript
+    WORK_ITEM_ID="$(grep -oE '(STORY|PROPOSAL|EPIC|CR|BUG)[-=]?[0-9]+(-[0-9]+)?' "${TRANSCRIPT_PATH}" 2>/dev/null \
+      | head -1 \
+      | sed 's/=/-/g')"
+    if [[ -n "${WORK_ITEM_ID}" ]]; then
+      printf '[%s] work_item_id fallback grep: %s\n' "$(date -u +%FT%TZ)" "${WORK_ITEM_ID}" >> "${HOOK_LOG}"
+    fi
+  fi
+  [[ -z "${WORK_ITEM_ID}" ]] && WORK_ITEM_ID=""
+
+  # story_id is populated only when the work item is a STORY-* (backward compat)
+  STORY_ID=""
+  if [[ "${WORK_ITEM_ID}" == STORY-* ]]; then
+    STORY_ID="${WORK_ITEM_ID}"
+  fi
+
+  # Legacy fallback: if no work_item_id found at all, fall back to old grep for story_id only
+  if [[ -z "${WORK_ITEM_ID}" ]]; then
+    STORY_ID="$(grep -oE 'STORY[-=]?[0-9]{3}-[0-9]{2}' "${TRANSCRIPT_PATH}" 2>/dev/null \
+      | head -1 \
+      | sed -E 's/STORY[-=]?([0-9]{3}-[0-9]{2})/STORY-\1/')"
+    [[ -z "${STORY_ID}" ]] && STORY_ID="none"
+    WORK_ITEM_ID="${STORY_ID}"
+  fi
+
+  # --- assemble ledger row ---
+  TS="$(date -u +%FT%TZ)"
+  ROW="$(jq -cn \
+    --arg ts "${TS}" \
+    --arg agent "${AGENT_TYPE}" \
+    --arg story "${STORY_ID}" \
+    --arg work_item "${WORK_ITEM_ID}" \
+    --arg session "${SESSION_ID}" \
+    --arg transcript "${TRANSCRIPT_PATH}" \
+    --arg sprint "${SPRINT_ID}" \
+    --argjson usage "${USAGE_JSON}" \
+    '{ts: $ts, sprint_id: $sprint, agent_type: $agent, story_id: $story, work_item_id: $work_item, session_id: $session, transcript: $transcript} + $usage')"
+
+  printf '%s\n' "${ROW}" >> "${LEDGER}"
+  printf '[%s] wrote row: sprint=%s agent=%s work_item=%s story=%s tokens=in:%s/out:%s\n' \
+    "${TS}" "${SPRINT_ID}" "${AGENT_TYPE}" "${WORK_ITEM_ID}" "${STORY_ID}" \
+    "$(printf '%s' "${USAGE_JSON}" | jq -r '.input')" \
+    "$(printf '%s' "${USAGE_JSON}" | jq -r '.output')" \
+    >> "${HOOK_LOG}"
+} 2>> "${HOOK_LOG}"
+
+exit 0

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

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/token-ledger.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/stamp-and-gate.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,92 @@
+---
+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 (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.
+
+## Modes
+
+### `check` — read before work
+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.
+
+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>
+```
+
+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)
+- `#schema` — Drizzle / migration / Postgres table shape gotcha
+- `#auth` — JWT / refresh / bcrypt / token handling
+- `#keychain` — macOS Keychain / libsecret / `@napi-rs/keyring` / `keytar`
+- `#redis` — Redis key shape, TTL, persistence
+- `#test-harness` — local docker compose, Postgres 18, Redis 8, flaky tests
+- `#ci` — pipeline / GitHub Actions / pre-commit hooks
+- `#mcp` — MCP SDK / Streamable HTTP / session protocol
+- `#cli` — Commander / tsup / bin entry / npm publish
+- `#admin-api` — Admin API contract / OpenAPI snapshot / zod
+- `#ui` — SvelteKit / Tailwind / DaisyUI
+- `#reporting` — sprint report generation
+- `#qa` — recurring QA kickback patterns
+- `#ambiguity` — story-spec ambiguities that bit us
+
+## Rules
+
+1. **Grep before append.** `grep -iF "<key phrase>" .cleargate/FLASHCARD.md` — if a matching card exists, skip or edit the existing line with a date suffix (e.g. `… (reconfirmed 2026-05-10)`). Never duplicate.
+2. **One line per card.** Hard cap 120 characters for the lesson body. If it needs more, you are writing docs, not a flashcard — put docs elsewhere.
+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, 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`, 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
+
+`.cleargate/FLASHCARD.md` layout:
+
+```markdown
+# ClearGate Flashcards
+
+One-liner gotcha log. Newest first. Grep by tag (e.g. `grep '#schema'`).
+Active cards have no marker; `[S]` = stale, `[R]` = resolved (see SKILL.md Rule 7).
+Format: `YYYY-MM-DD · #tags · [marker]? 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/templates/cleargate-planning/.cleargate/FLASHCARD.md

@@ -0,0 +1,7 @@
+# ClearGate Flashcards
+
+One-liner gotcha log. Newest first. Grep by tag (e.g. `grep '#schema'`).
+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`
+
+---