cleargate 0.2.0 → 0.2.1

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

@@ -29,6 +29,12 @@ Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. It must serve
 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
@@ -86,6 +92,15 @@ For each shipped story, one compact block:
 ### 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.
 

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/templates/story.md

@@ -15,6 +15,16 @@ L2: Standard — 2-3 files, known pattern, ~2-4hr (default)
 L3: Complex — Cross-cutting, spike may be needed, ~1-2 days
 L4: Uncertain — Requires probing/spiking, >2 days
 
+Granularity Rubric (run this check BEFORE emitting a story during epic-decomposition):
+A candidate story is too big — emit two stories instead, with consecutive IDs (e.g. STORY-007-03 and STORY-007-04, never 03a/03b) — if ANY signal trips:
+  • §1.2 Detailed Requirements joins unrelated user goals with "and also" / "additionally".
+  • §2.1 Gherkin would need >5 scenarios covering unrelated behaviors.
+  • §3.1 Files-to-touch span unrelated subsystems (e.g. API + UI + migration in one story).
+  • Complexity would land at L4 (>2 days). L4 is a planning smell — split, or carve out a spike as its own story.
+Also split the inverse: two candidate stories that each touch the same 1-2 files with overlapping scenarios should merge into one L1/L2.
+At epic-decomposition time there are no remote IDs yet — splits and merges are free. Prefer two focused L1/L2 stories over one L3. Prefer L3 over L4.
+When the rubric is ambiguous, surface the decision to the human as a one-liner ("candidate covers A+B — split into X and Y?") rather than guessing.
+
 Do NOT output these instructions.
 </instructions>
 

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

@@ -24,6 +24,7 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 - Use the templates in `.cleargate/templates/` (`proposal.md`, `epic.md`, `story.md`, `CR.md`, `Bug.md`, `Sprint Plan Template.md`, `initiative.md`).
 - Save drafts to `.cleargate/delivery/pending-sync/{TYPE}-{ID}-{Name}.md`.
 - After `cleargate_push_item` returns a Remote ID, update the frontmatter AND move the file to `.cleargate/delivery/archive/` — these two happen atomically, never one without the other.
+- **Story granularity.** When decomposing an epic into stories, run the Granularity Rubric at the top of `story.md`. If a candidate story trips any signal (unrelated goals joined, >5 Gherkin scenarios, subsystems span, L4 complexity), emit two stories with consecutive IDs instead. Splits and merges are free at decomposition time — no remote IDs exist yet.
 
 **Four-agent loop (roles in `.claude/agents/`):**
 - `architect.md` — one plan per milestone; no production code.

package/dist/templates/cleargate-planning/MANIFEST.json

@@ -1,6 +1,6 @@
 {
-  "cleargate_version": "0.2.0",
-  "generated_at": "2026-04-19T16:46:17.751Z",
+  "cleargate_version": "0.2.1",
+  "generated_at": "2026-04-19T18:33:06.178Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
@@ -46,7 +46,7 @@
     },
     {
       "path": ".claude/agents/reporter.md",
-      "sha256": "a83497454969e81015e7d0415e86a3bcf48cafb13741ed7f18b603f9e54cfb80",
+      "sha256": "a9b7e248fd1baaef7fb0c23d4ba92bc94bcd46e9261a6dabbd183477fab96359",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -81,7 +81,7 @@
     },
     {
       "path": ".claude/skills/flashcard/SKILL.md",
-      "sha256": "56d6bf3797516ac26ada15876ef2f4cf43842b3af7300abef502a75bd177639e",
+      "sha256": "4c0fe5bb74697e1eb1f37203ff44b8e6a800f024a2f8c3fc8542aa206cd2c777",
       "tier": "skill",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -151,7 +151,7 @@
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "3e722c51f706177f08c16b56ef984090c7841102f70384bb47d5442846991fe8",
+      "sha256": "6c32fcabc9332cb928ac3b8fbfe618751b0a4cb05cd0f16463c3c4e22f8a67f1",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleargate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "Planning framework for Claude Code agents — sprint/epic/story protocol, four-agent loop (architect/developer/qa/reporter), Karpathy-style awareness wiki.",

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

@@ -29,6 +29,12 @@ Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. It must serve
 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
@@ -86,6 +92,15 @@ For each shipped story, one compact block:
 ### 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.
 

package/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/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/templates/cleargate-planning/.cleargate/templates/story.md

@@ -15,6 +15,16 @@ L2: Standard — 2-3 files, known pattern, ~2-4hr (default)
 L3: Complex — Cross-cutting, spike may be needed, ~1-2 days
 L4: Uncertain — Requires probing/spiking, >2 days
 
+Granularity Rubric (run this check BEFORE emitting a story during epic-decomposition):
+A candidate story is too big — emit two stories instead, with consecutive IDs (e.g. STORY-007-03 and STORY-007-04, never 03a/03b) — if ANY signal trips:
+  • §1.2 Detailed Requirements joins unrelated user goals with "and also" / "additionally".
+  • §2.1 Gherkin would need >5 scenarios covering unrelated behaviors.
+  • §3.1 Files-to-touch span unrelated subsystems (e.g. API + UI + migration in one story).
+  • Complexity would land at L4 (>2 days). L4 is a planning smell — split, or carve out a spike as its own story.
+Also split the inverse: two candidate stories that each touch the same 1-2 files with overlapping scenarios should merge into one L1/L2.
+At epic-decomposition time there are no remote IDs yet — splits and merges are free. Prefer two focused L1/L2 stories over one L3. Prefer L3 over L4.
+When the rubric is ambiguous, surface the decision to the human as a one-liner ("candidate covers A+B — split into X and Y?") rather than guessing.
+
 Do NOT output these instructions.
 </instructions>
 

package/templates/cleargate-planning/CLAUDE.md

@@ -24,6 +24,7 @@ This repository uses **ClearGate** — a standalone planning framework for AI co
 - Use the templates in `.cleargate/templates/` (`proposal.md`, `epic.md`, `story.md`, `CR.md`, `Bug.md`, `Sprint Plan Template.md`, `initiative.md`).
 - Save drafts to `.cleargate/delivery/pending-sync/{TYPE}-{ID}-{Name}.md`.
 - After `cleargate_push_item` returns a Remote ID, update the frontmatter AND move the file to `.cleargate/delivery/archive/` — these two happen atomically, never one without the other.
+- **Story granularity.** When decomposing an epic into stories, run the Granularity Rubric at the top of `story.md`. If a candidate story trips any signal (unrelated goals joined, >5 Gherkin scenarios, subsystems span, L4 complexity), emit two stories with consecutive IDs instead. Splits and merges are free at decomposition time — no remote IDs exist yet.
 
 **Four-agent loop (roles in `.claude/agents/`):**
 - `architect.md` — one plan per milestone; no production code.

package/templates/cleargate-planning/MANIFEST.json

@@ -1,6 +1,6 @@
 {
-  "cleargate_version": "0.2.0",
-  "generated_at": "2026-04-19T16:46:17.751Z",
+  "cleargate_version": "0.2.1",
+  "generated_at": "2026-04-19T18:33:06.178Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
@@ -46,7 +46,7 @@
     },
     {
       "path": ".claude/agents/reporter.md",
-      "sha256": "a83497454969e81015e7d0415e86a3bcf48cafb13741ed7f18b603f9e54cfb80",
+      "sha256": "a9b7e248fd1baaef7fb0c23d4ba92bc94bcd46e9261a6dabbd183477fab96359",
       "tier": "agent",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -81,7 +81,7 @@
     },
     {
       "path": ".claude/skills/flashcard/SKILL.md",
-      "sha256": "56d6bf3797516ac26ada15876ef2f4cf43842b3af7300abef502a75bd177639e",
+      "sha256": "4c0fe5bb74697e1eb1f37203ff44b8e6a800f024a2f8c3fc8542aa206cd2c777",
       "tier": "skill",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -151,7 +151,7 @@
     },
     {
       "path": ".cleargate/templates/story.md",
-      "sha256": "3e722c51f706177f08c16b56ef984090c7841102f70384bb47d5442846991fe8",
+      "sha256": "6c32fcabc9332cb928ac3b8fbfe618751b0a4cb05cd0f16463c3c4e22f8a67f1",
       "tier": "template",
       "overwrite_policy": "merge-3way",
       "preserve_on_uninstall": false