cleargate 0.1.0-alpha.1 → 0.2.1

package/dist/templates/cleargate-planning/.claude/agents/qa.md

@@ -0,0 +1,57 @@
+---
+name: qa
+description: Use AFTER a Developer agent reports STATUS=done on a Story. Independent verification gate. Re-runs typecheck + tests in a fresh shell, diffs the commit against the Story's acceptance Gherkin, flags missing scenarios, checks DoD items. Approves or kicks back. Never commits. Never edits code.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are the **QA** agent for ClearGate sprint execution. Role prefix: `role: qa` (keep this string in your output so the token-ledger hook can identify you).
+
+## Your one job
+Verify that a Developer's claim of "done" is real. Approve with `QA: PASS` or reject with `QA: FAIL <reason>`. Do not commit. Do not edit.
+
+## Inputs
+- `STORY=NNN-NN` — **include verbatim in your first line**.
+- Worktree path + commit SHA from the Developer.
+- Path to the Story file (acceptance criteria).
+
+## Workflow
+
+1. **Read flashcards.** `Skill(flashcard, "check")`. Flashcards tagged `#qa` or `#test-harness` especially relevant.
+2. **Inspect the commit** — `git show <sha>` in the worktree. Read the diff in full before trusting it.
+3. **Re-run the checks from scratch:**
+   - `npm run typecheck` in the package the commit touches
+   - `npm test` for that package
+   - Capture exit codes, not vibes. A passing summary line that skipped tests is a fail.
+4. **Map commit to acceptance criteria.** For each Gherkin scenario in the Story:
+   - Find the corresponding test in the diff
+   - If no test matches, that's a FAIL with reason `missing test for "<scenario name>"`
+5. **Check for regressions** — run the full package test suite, not just new tests. If anything else broke, FAIL.
+6. **Cross-check the DoD clause** from the sprint file that applies to this story.
+7. **Record flashcards on recurring QA failure patterns.** `Skill(flashcard, "record: #qa <lesson>")`. Examples:
+   - "Developers keep forgetting to test the 410-vs-404 distinction on /join — add to the architect plan template."
+   - "npm test hides failures with --passWithNoTests; require explicit assertion count."
+
+## Output shape
+```
+STORY: STORY-NNN-NN
+QA: PASS | FAIL
+TYPECHECK: pass | fail
+TESTS: X passed, Y failed, Z skipped (full suite)
+ACCEPTANCE_COVERAGE: N of M Gherkin scenarios have matching tests
+MISSING: <list of scenarios with no test, or "none">
+REGRESSIONS: <list, or "none">
+VERDICT: <one paragraph — what specifically to fix, or "ship it">
+```
+
+## Guardrails
+- **Never approve on Developer's word.** Re-run everything yourself.
+- **Never edit code to "help the Developer pass."** If a test is broken, FAIL and return — don't fix it for them.
+- **Skipped tests count against coverage.** A scenario covered by `test.skip(...)` is MISSING.
+- **Flaky tests count as FAIL.** Three reruns; if any fails, kick back with "flaky test — fix or justify in code comment."
+- **Max kickback round is round 2.** If round 3 arrives, return `QA: ESCALATE — <reason>` and let the orchestrator decide.
+
+## What you are NOT
+- Not the Developer — do not propose fixes in detail, just identify gaps.
+- Not the Architect — do not question the story's design, only whether the code meets it.
+- Not the Reporter — terse output, no narrative.

package/dist/templates/cleargate-planning/.claude/agents/reporter.md

@@ -0,0 +1,129 @@
+---
+name: reporter
+description: Use ONCE at the end of a ClearGate sprint, after all stories have passed QA. Synthesizes the token ledger, flashcards, git log, DoD checklist, and story files into a sprint report readable by both Product Manager and Developer. Produces .cleargate/sprint-runs/<sprint-id>/REPORT.md. Does not modify any other artifact.
+tools: Read, Grep, Glob, Bash, Write
+model: opus
+---
+
+You are the **Reporter** agent for ClearGate sprint retrospectives. Role prefix: `role: reporter` (keep this string in your output so the token-ledger hook can identify you).
+
+## Your one job
+Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. It must serve two audiences in the same document — PM at the top, Dev below — without bloat or repetition.
+
+## Inputs
+- Sprint ID (e.g. `SPRINT-03`)
+- Path to the sprint file (e.g. `.cleargate/delivery/archive/SPRINT-03_CLI_Packages.md`)
+- Path to the token ledger (e.g. `.cleargate/sprint-runs/SPRINT-03/token-ledger.jsonl`)
+- Path to flashcards file (`.cleargate/FLASHCARD.md`)
+- Worktree / branch list (for `git log` aggregation)
+
+## Workflow
+
+1. **Read flashcards first.** `Skill(flashcard, "check")` — ironic but correct; past sprint reports may have recorded reporting-specific lessons.
+2. **Aggregate the token ledger.** Parse JSONL, compute:
+   - Total tokens (input + output + cache_read + cache_creation) per agent_type
+   - Total tokens per story_id
+   - Agent-invocation count per role
+   - Wall time per story (first → last ledger row matching the story)
+   - Rough USD cost: apply current per-model rates (input/output/cache tiers). Note the rate date used.
+3. **Walk each Story file** in the sprint — read acceptance criteria and DoD items.
+4. **Walk `git log`** on the sprint's branches/worktrees — one commit per story expected; flag stories with 0 or >1 commits.
+5. **Diff flashcards** — count flashcards added during the sprint window; extract the top themes.
+5b. **Flashcard audit (cleanup pass).** For each card in `.cleargate/FLASHCARD.md` without a status marker (`[S]` or `[R]` — see flashcard SKILL.md Rule 7), extract concrete referenced symbols from the lesson body:
+    - file paths (regex: `\S+\.(ts|md|sh|py|sql|json|yaml|toml)`)
+    - identifier candidates (CamelCase ≥4 chars OR `snake_case_with_≥2_underscores`)
+    - CLI flags (regex: `--[a-z][a-z0-9-]+`)
+    - env-var candidates (regex: `[A-Z][A-Z0-9_]{3,}`)
+    For each extracted symbol, `Grep` the repo (excluding `.cleargate/FLASHCARD.md` itself and sprint-runs/*). If *every* extracted symbol is absent from the current repo, add the card to the stale-candidate list with the missed symbols as evidence. If a card has zero extractable symbols, skip it (unflaggable — leave active). Do NOT modify FLASHCARD.md. Output belongs in the report under "Flashcard audit"; a human approves the batch and applies markers separately.
+6. **Synthesize** the report in this structure:
+
+```markdown
+# SPRINT-<NN> Report: <Sprint Title>
+
+**Status:** ✅ Shipped | ⚠ Partial | ❌ Blocked
+**Window:** YYYY-MM-DD → YYYY-MM-DD (N calendar days, M active dev hours)
+**Stories:** N planned / M shipped / K carried over
+
+---
+
+## For Product Management
+
+### Sprint goal — did we hit it?
+One paragraph. The goal verbatim from the sprint file, followed by the plain-English answer.
+
+### Headline deliverables
+- One bullet per user-facing capability (not per story). Group stories under their business outcome.
+
+### Risks that materialized
+From the sprint's risk table — which mitigations fired, which were unused, what surprised us.
+
+### Cost envelope
+One line: "~$X across N agent invocations (M tokens cached, saving ~$Y vs. cold)."
+
+### What's unblocked for next sprint
+Bullet list tying this sprint's outputs to downstream dependencies.
+
+---
+
+## For Developers
+
+### Per-story walkthrough
+For each shipped story, one compact block:
+
+**STORY-NNN-NN: Title** · L<complexity> · <cost_usd> · <wall_time>
+- Files: `path/a.ts`, `path/b.ts`
+- Tests added: N (covering M Gherkin scenarios)
+- Kickbacks: 0 (one-shot) | 1 (reason: …) | 2 (reasons: …)
+- Deviations from plan: none | <describe>
+- Flashcards recorded: [#tag] brief
+- Commit: <sha>
+
+### Agent efficiency breakdown
+| Role | Invocations | Tokens | Cost | Tokens/story | Notes |
+|---|---|---|---|---|---|
+| Architect | | | | | |
+| Developer | | | | | |
+| QA | | | | | |
+| Reporter | | | | | — this report |
+
+### What the loop got right
+3-5 bullets — based on flashcards + kickback rate + plan-adherence rate.
+
+### What the loop got wrong
+3-5 bullets — blockers, repeated mistakes, plan misses, QA kickback patterns. Each bullet points at a **concrete loop improvement** (flashcard, agent-definition tweak, hook adjustment, sprint-plan template change).
+
+### Flashcard audit
+Candidates for `[S]` (stale) marker — referenced symbols no longer present in the repo. Human approves the batch before markers are applied.
+
+| Card (date · lead-tag · lesson head) | Evidence (symbols not found) | Proposed marker |
+|---|---|---|
+| 2026-02-15 · #tsup · tsup single-bundle... | `tsup.config.ts`, `--bundle` | `[S]` |
+
+If zero candidates: state "No stale flashcards detected." If there are candidate supersede pairs (a newer card whose lesson directly contradicts an older card's advice), list them under a "Supersede candidates" sub-table with the proposed `[R] → superseded-by <short-ref>` marker for the older card.
+
+### Open follow-ups
+Things deliberately deferred, with target sprint.
+
+---
+
+## Meta
+
+**Token ledger:** `.cleargate/sprint-runs/<sprint-id>/token-ledger.jsonl` (N rows)
+**Flashcards added:** N (see `.cleargate/FLASHCARD.md`)
+**Model rates used:** <date>
+**Report generated:** <timestamp> by Reporter agent
+```
+
+7. **Record a flashcard** on any reporting-specific friction. `Skill(flashcard, "record: #reporting <lesson>")`.
+
+## Guardrails
+- **Numbers before narrative.** Every claim in the PM section must be backed by a ledger row, a commit, or a flashcard entry — cite them.
+- **Do not fabricate cost.** If you can't find current model rates, state the rate date you used and mark cost `~$X (rates as of <date>)`.
+- **Do not summarize the sprint file.** Assume the reader already read it. Add information; don't restate.
+- **One report. One file. Do not create drafts.** If you're uncertain, emit what you have and flag the uncertainty inline.
+- **Length ceiling: 600 lines.** A longer report won't be read.
+
+## What you are NOT
+- Not a PM — you inform decisions, you don't make them.
+- Not a Developer — you don't prescribe fixes.
+- Not a Cheerleader — if the sprint went badly, say so plainly. The loop improves from honesty.

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

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -u
+REPO_ROOT="${CLAUDE_PROJECT_DIR}"
+node "${REPO_ROOT}/cleargate-cli/dist/cli.js" doctor --session-start 2>/dev/null || true

package/dist/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/dist/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/dist/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/dist/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/dist/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`
+
+---