sequant 2.8.0 → 2.9.0

package/templates/scripts/cleanup-worktree.sh

@@ -1,8 +1,20 @@
 #!/bin/bash
 
 # Clean up a worktree after PR is merged
-# Usage: ./scripts/cleanup-worktree.sh <branch-name>
+# Usage: ./scripts/cleanup-worktree.sh [flags] <branch-name>
 # Example: ./scripts/cleanup-worktree.sh feature/123-add-user-dashboard
+#
+# The remote branch is deleted ONLY when the branch's PR is MERGED (the
+# documented post-merge contract) or when an explicit override flag is passed.
+# Local teardown (worktree + local branch) always runs so the branch lock is
+# freed for a subsequent `gh pr merge --delete-branch`.
+#
+# Flags:
+#   -y, --yes         Skip the confirmation prompt (non-interactive confirm).
+#                     Does NOT override the merge gate on remote deletion.
+#   --delete-remote   Override the merge gate and delete the remote branch even
+#                     when the PR is not merged (still honors the TTY confirm).
+#   --force           Implies both --yes and --delete-remote.
 
 set -e
 
@@ -13,7 +25,65 @@ YELLOW='\033[1;33m'
 RED='\033[0;31m'
 NC='\033[0m'
 
-BRANCH_NAME=$1
+# Print CLI usage/help (kept in sync with the header comment above).
+print_usage() {
+    cat <<'USAGE'
+Usage: ./scripts/cleanup-worktree.sh [flags] <branch-name>
+
+Clean up a feature worktree. The remote branch is deleted ONLY when the
+branch's PR is MERGED (the documented post-merge contract) or when an
+explicit override flag is passed. Local teardown (worktree + local branch)
+always runs so the branch lock is freed for a subsequent
+`gh pr merge --delete-branch`.
+
+Flags:
+  -y, --yes         Skip the confirmation prompt (non-interactive confirm).
+                    Does NOT override the merge gate on remote deletion.
+  --delete-remote   Override the merge gate and delete the remote branch even
+                    when the PR is not merged (still honors the confirm gate).
+  --force           Implies both --yes and --delete-remote.
+  -h, --help        Show this help and exit.
+
+Example:
+  ./scripts/cleanup-worktree.sh feature/123-add-user-dashboard
+USAGE
+}
+
+# Parse flags. ASSUME_YES bypasses the confirmation prompt; DELETE_REMOTE
+# overrides the merge gate on remote deletion. The first non-flag argument is
+# the branch name. --force is the combined opt-in (both behaviors).
+BRANCH_NAME=""
+ASSUME_YES=false
+DELETE_REMOTE=false
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -y|--yes)
+            ASSUME_YES=true
+            ;;
+        --delete-remote)
+            DELETE_REMOTE=true
+            ;;
+        --force)
+            ASSUME_YES=true
+            DELETE_REMOTE=true
+            ;;
+        -h|--help)
+            print_usage
+            exit 0
+            ;;
+        -*)
+            echo -e "${RED}❌ Error: Unknown flag: $1${NC}" >&2
+            print_usage >&2
+            exit 1
+            ;;
+        *)
+            if [ -z "$BRANCH_NAME" ]; then
+                BRANCH_NAME="$1"
+            fi
+            ;;
+    esac
+    shift
+done
 
 # Resolve main worktree (first entry in porcelain output) so subsequent git
 # commands run from a stable cwd even if the caller invoked us from inside the
@@ -23,11 +93,11 @@ MAIN_WORKTREE=$(git worktree list --porcelain | sed -n 's/^worktree //p' | head
 
 # Check if branch name provided
 if [ -z "$BRANCH_NAME" ]; then
-    echo -e "${RED}❌ Error: Branch name required${NC}"
-    echo "Usage: ./scripts/cleanup-worktree.sh <branch-name>"
-    echo ""
-    echo "Active worktrees:"
-    git worktree list
+    echo -e "${RED}❌ Error: Branch name required${NC}" >&2
+    print_usage >&2
+    echo "" >&2
+    echo "Active worktrees:" >&2
+    git worktree list >&2
     exit 1
 fi
 
@@ -58,12 +128,24 @@ echo ""
 # Check if PR is merged
 PR_STATUS=$(gh pr list --head "$BRANCH_NAME" --state merged --json number,state --jq '.[0].state' 2>/dev/null || echo "")
 
+# Confirmation gate — only reached when the PR is NOT merged. When MERGED we
+# short-circuit past this entirely (no prompt, no TTY check) so the documented
+# post-merge happy path is unchanged.
 if [ "$PR_STATUS" != "MERGED" ]; then
     echo -e "${YELLOW}⚠️  Warning: PR for this branch is not merged${NC}"
-    read -p "Are you sure you want to delete this worktree? (y/n) " -n 1 -r
-    echo
-    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-        echo -e "${BLUE}Cancelled.${NC}"
+    if [ "$ASSUME_YES" = true ]; then
+        echo -e "${BLUE}Proceeding (--yes/--force).${NC}"
+    elif [ -t 0 ]; then
+        read -p "Are you sure you want to delete this worktree? (y/n) " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo -e "${BLUE}Cancelled.${NC}"
+            exit 0
+        fi
+    else
+        # Non-interactive (no TTY) and no confirm flag: exit safely instead of
+        # stalling on `read`. Pass --yes/--force to proceed without a prompt.
+        echo -e "${BLUE}Non-interactive context and PR not merged — pass --yes or --force to proceed. Exiting without changes.${NC}"
         exit 0
     fi
 fi
@@ -101,9 +183,16 @@ git worktree remove "$WORKTREE_PATH" --force
 echo -e "${BLUE}🌿 Deleting local branch...${NC}"
 git branch -D "$BRANCH_NAME" 2>/dev/null || true
 
-# Delete remote branch
-echo -e "${BLUE}☁️  Deleting remote branch...${NC}"
-git push origin --delete "$BRANCH_NAME" 2>/dev/null || true
+# Delete remote branch — hard-gated on merge state. Only delete when the PR is
+# MERGED or an explicit override flag (--delete-remote/--force) was passed.
+# Otherwise leave the remote branch (and any open PR) intact: deleting an open
+# PR's head branch makes GitHub close the PR unmerged, stranding the work.
+if [ "$PR_STATUS" = "MERGED" ] || [ "$DELETE_REMOTE" = true ]; then
+    echo -e "${BLUE}☁️  Deleting remote branch...${NC}"
+    git push origin --delete "$BRANCH_NAME" 2>/dev/null || true
+else
+    echo -e "${YELLOW}⏭️  Skipped remote-branch delete (PR not merged; pass --delete-remote or --force to override).${NC}"
+fi
 
 # Update main
 echo -e "${BLUE}📥 Updating main branch...${NC}"

package/templates/skills/assess/SKILL.md

@@ -196,11 +196,10 @@ Triggers (any one):
 - Issue body or comments mention `"depends on #N"`, `"blocked by #N"`, or `"after #N"`
 - One issue's described output is another issue's input (e.g., A changes a function signature that B consumes)
 
-Format: `Chain: <CMD_PREFIX> run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
+Format: `Chain: <CMD_PREFIX> run <N1> <N2> --chain -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 Flag references:
 - `--chain` chains issues (each branches from previous; implies `--sequential`)
-- `--qa-gate` pauses chain on QA failure (requires `--chain`)
 - `--base <branch>` — issue references a feature branch
 
 ### Step 5: Conflict Detection
@@ -255,7 +254,7 @@ Order: <N> → <N> (<dependency reason>)
 ⚠ #<N>  <warning>
 ⚠ #<N>  <warning>
 
-Chain: <CMD_PREFIX> run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <reason>
+Chain: <CMD_PREFIX> run <N1> <N2> --chain -Q <phases>   # alternative — <reason>
 
 Flags:
   <flag>                <one-line reason>
@@ -318,7 +317,7 @@ Emit annotations in this order between the separators that follow `Commands:`:
   - `⚠ #412  bug + auth labels — domain label (auth) takes priority over bug`
 
 - **`Chain:`** — Only when 2+ PROCEED issues have a detected dependency (see "Chain detection" in Step 4). Suggests an alternative execution topology. Does not replace the default per-issue commands. Format:
-  `Chain: <CMD_PREFIX> run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
+  `Chain: <CMD_PREFIX> run <N1> <N2> --chain -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 - **`Flags:`** — Only when non-default flags appear in the commands and the reason isn't obvious. One line per **distinct** flag used across all commands. Omit entire section when `-Q` is the only non-default flag AND its reason is obvious (e.g., all issues are enhancements). Format:
   ```
@@ -402,7 +401,7 @@ Order: 185 → 186 (185 changes fetchApi error format that 186 consumes)
 ⚠ #185  Domain errors already exist in repository layer — scope may be smaller than expected
 ⚠ #186  @tanstack/react-query not installed; large scope (9 hooks + optimistic updates)
 
-Chain: npx sequant run 185 186 --chain --qa-gate -Q --testgen
+Chain: npx sequant run 185 186 --chain -Q --testgen
        # alternative — use if 186 should branch from 185's work
 
 Flags:
@@ -669,16 +668,97 @@ Every separator and section is conditional. If there are no warnings, no chain,
 
 After displaying output, prompt the user to save using `AskUserQuestion` with options "Yes (Recommended)" and "No".
 
-If confirmed, post a structured comment to each issue via `gh issue comment`. Each posted comment should include:
-- **Supersession header** (when priors exist): If `findAllAssessComments` returned ≥1 prior, prepend `buildSupersessionHeader(priors)` immediately above the `→ ACTION — reason` line. When `detectChurn(...).isChurn === true`, also emit a `⚠ Re-assessed N times since <firstDate> without execution — possible blocker or low priority` warning in the dashboard. When `shouldPromptOnConflict(prior, new) === true`, confirm with the user via `AskUserQuestion` before posting. See "Prior Assessment Detection" in Step 1 for full protocol.
-- The action headline (`→ ACTION — reason`)
-- The workflow (for PROCEED/REWRITE)
-- Standard HTML markers on separate lines:
-  ```
-  <!-- assess:action=PROCEED -->
-  <!-- assess:phases=spec,exec,qa -->
-  <!-- assess:quality-loop=true -->
-  ```
+If confirmed, post a structured comment to each issue via `gh issue comment`. **Each posted comment is rendered with the single-mode template that matches that issue's verdict** — the same `#### PROCEED / CLOSE / CLARIFY / PARK / MERGE / REWRITE` templates defined under [Single Mode (1 issue)](#single-mode-1-issue) above. There is no separate, thinner shape for posted comments: the batch **dashboard** in chat and the **posted comment** on each issue are the only two formats, and the posted comment always reuses the single-mode template for its verdict. (Note: this is *not* a reversal of #453 — the single-mode templates are themselves the streamlined, scan-friendly format.)
+
+Render each comment as follows:
+
+1. **Pick the template by verdict.** For issue `#N`'s action, use the matching single-mode template (`#### PROCEED`, `#### REWRITE`, etc.) and fill it exactly as single mode would, including — where that template defines them:
+   - the `#<N> — <Title>` / `<State> · <labels>` header,
+   - the section separators the template defines,
+   - the `Commands:` block with the **resolved `CMD_PREFIX`** (Step-1 probe — `sequant` when a global is on PATH, else `npx sequant`) and the **real current flags** for that issue. When the dashboard batched several issues onto one `run` line (e.g. `run 461 460 458 443 -Q`), restate just `#N`'s own single-issue invocation (`run 458 -Q`): the shared flags that applied to `#N`, plus any per-issue flags the dashboard listed separately for it (e.g. `#412`'s `--security-review`, `#411`'s `--phases exec,qa`),
+   - the `<phases> · <N> ACs` line,
+   - for **CLOSE**, the `Cleanup:` block populated with just `#N`'s cleanup commands, de-aggregated from the dashboard's combined `Cleanup:` block.
+
+   Reference these templates rather than re-copying their bodies here — they are the single source of truth (avoids drift). Verdicts whose template omits a field (CLOSE / CLARIFY / PARK / MERGE have no `Commands:` or `<phases> · <N> ACs` line) simply omit it, exactly as the template shows.
+
+2. **Carry per-issue warnings.** Any `⚠` line from the batch dashboard that concerns `#N` (collision/conflict, churn, staleness, dual-concern, partial-AC) is carried into that issue's comment, with the leading `#N` dropped (the comment is already scoped to that issue). Placement depends on whether the verdict's template defines a warning slot:
+   - **PROCEED / REWRITE** — the template already defines a `⚠ ...` region between its two trailing separators; place the warning there.
+   - **CLOSE / CLARIFY / PARK / MERGE** — these templates have no `⚠` region (just a single trailing separator before the markers). Add the warning as its own separator-delimited block immediately above the marker block, so the tail reads: `<trailing separator>` → `⚠ ...` → `<separator>` → `<!-- assess:action=... -->`. This is the sole case where a posted comment extends a slot-less template; every other field still follows Step 1's "omit what the template omits." When an issue has no `⚠`, the template is emitted unchanged.
+
+3. **Supersession header** (when priors exist): If `findAllAssessComments` returned ≥1 prior, prepend `buildSupersessionHeader(priors)` immediately above the `→ ACTION — reason` line. When `detectChurn(...).isChurn === true`, also emit the `⚠ Re-assessed N times since <firstDate> without execution — possible blocker or low priority` warning in the warning slot (per step 2). When `shouldPromptOnConflict(prior, new) === true`, confirm with the user via `AskUserQuestion` before posting. See "Prior Assessment Detection" in Step 1 for full protocol.
+
+4. **Machine markers.** The posted comment keeps the single-mode **3-line** marker block — one directive per line, and only those directives the verdict defines:
+   ```
+   <!-- assess:action=PROCEED -->
+   <!-- assess:phases=spec,exec,qa -->
+   <!-- assess:quality-loop=true -->
+   ```
+   Do **not** use the batch dashboard's compact one-line marker (`<!-- #N assess:action=… assess:phases=… -->`) in a posted comment — that form is for the chat dashboard only.
+
+The chat batch dashboard is unchanged — this step governs only what lands on each issue.
+
+### Batch: dashboard vs posted comment
+
+A batch run shows one scannable dashboard in chat, then posts one single-mode comment per issue. The two are distinct by design: the dashboard is a triage table across all issues; each comment is the full single-mode assessment for that one issue.
+
+Dashboard (chat) — excerpt for #458:
+
+```
+ #    Action     Reason                              Run
+ 458  PROCEED    Parallel UX + race condition          spec → exec → qa
+────────────────────────────────────────────────────────────────
+Commands:
+  npx sequant run 458 -Q
+────────────────────────────────────────────────────────────────
+⚠ #458  Dual concern (UX + race) across 4 files
+
+Flags:
+  -Q     dual concern across 4 files
+────────────────────────────────────────────────────────────────
+
+<!-- #458 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+```
+
+Posted comment on issue #458 (single-mode PROCEED template — `#N` dropped from the warning, 3-line markers):
+
+```
+#458 — Parallel run UX freeze + reconcileState race condition
+Open · bug, enhancement, cli
+────────────────────────────────────────────────────────────────
+
+→ PROCEED — Both root causes confirmed in codebase
+
+Commands:
+  npx sequant run 458 -Q
+
+spec → exec → qa · 8 ACs
+
+Flags:
+  -Q     dual concern across 4 files
+────────────────────────────────────────────────────────────────
+⚠ Dual concern (UX + race) across 4 files
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=PROCEED -->
+<!-- assess:phases=spec,exec,qa -->
+<!-- assess:quality-loop=true -->
+```
+
+For a verdict whose template has no `⚠` slot, the carried warning becomes its own separator-delimited block above the markers (Step 2). Posted comment on a **PARK** issue the churn detector flagged:
+
+```
+#530 — Measure real-world assess latency across 20 repos
+Open · task, needs-data
+────────────────────────────────────────────────────────────────
+
+→ PARK — Blocked on manual measurement not yet scheduled
+  Resume after: latency sampling run completes
+────────────────────────────────────────────────────────────────
+⚠ Re-assessed 3 times since 2026-06-30 without execution — possible blocker or low priority
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=PARK -->
+```
 
 ## Notes
 
@@ -709,4 +789,5 @@ If confirmed, post a structured comment to each issue via `gh issue comment`. Ea
 - [ ] Supersession header prepended when prior assess comments exist (`buildSupersessionHeader`)
 - [ ] Churn warning included in dashboard when `detectChurn(...).isChurn === true`
 - [ ] Batch mode: table is the primary output, no per-issue detail sections
+- [ ] Persist step: each posted comment uses the single-mode verdict template (not the dashboard shape or a thinner form), with per-issue `⚠` carried into the warning slot and the 3-line marker block
 - [ ] Single mode: focused summary with separators between sections

package/templates/skills/assess/references/predicted-collision-detection.md

@@ -15,9 +15,12 @@ The detector runs automatically during Step 5 whenever ≥2 PROCEED issues are p
 
 For each issue body, paths are extracted in this order:
 
-### 1. Strip code blocks and HTML comments
+### 1. Strip code blocks, HTML comments, and background sections
 
-Fenced code blocks (```` ``` … ``` ````) and HTML comments (`<!-- … -->`) are removed before any path matching. This is the **AC-5 false-positive guard**: paths quoted as code in prose count, paths inside a code block don't.
+Two pre-extraction strips run before any path matching:
+
+- **Code blocks and HTML comments.** Fenced code blocks (```` ``` … ``` ````) and HTML comments (`<!-- … -->`) are removed. This is the **AC-5 false-positive guard**: paths quoted as code in prose count, paths inside a code block don't.
+- **Background/citation sections (#769).** Content under any H1/H2 heading whose text prefix-matches `BACKGROUND_SECTIONS` — `References`, `Context`, `Motivation`, `Additional context`, `See also` (case-insensitive) — is removed, up to the next H1/H2 heading. A path named *only* under such a section is a citation of existing code, not a file the issue will modify, so it no longer contributes to the path set. A path named in an AC bullet (or any other foreground section) survives even when it is *also* cited under `## References`.
 
 ### 2. Backtick-quoted source paths (PATH_REGEX)
 
@@ -85,9 +88,9 @@ These paths are stripped from every issue's path set before pairwise intersectio
 
 `EXCLUDED_PATHS` in `src/lib/assess-collision-detect.ts` is the canonical list. To add or remove an entry, edit that constant; this document and the skill prose pick up the change automatically.
 
-### Code block / HTML comment stripping
+### Code block / HTML comment / background-section stripping
 
-Step 1 of the extraction (above) removes all fenced code blocks and HTML comments before path matching. A path mentioned **only** inside one of those will not contribute to the issue's path set.
+Step 1 of the extraction (above) removes all fenced code blocks, HTML comments, and background/citation sections (`## References`, `## Context`, `## Motivation`, `## Additional context`, `## See also`) before path matching. A path mentioned **only** inside one of those will not contribute to the issue's path set. This is what stops sibling issues that all cite the same background doc under `## References` from being reported as a phantom collision (#769).
 
 ### Path-shape constraints
 
@@ -95,7 +98,7 @@ The PATH_REGEX requires a directory prefix (one of the six tracked roots) and a
 
 ## Tuning notes
 
-- **Proximity weighting** is not implemented. The original feature design proposed weighting paths inside `- [ ] **AC-N:**` bullets higher than paths in "Motivation" or "Additional context". Adding it is a follow-up if the false-positive rate becomes a problem in practice; leave it out until evidence demands it.
+- **Background-section exclusion is implemented (#769); proximity *scoring* is not.** The original design (#556) proposed weighting paths by proximity to `- [ ] **AC-N:**` bullets. #769 shipped the cheap version of that mitigation instead — strip whole background sections (`BACKGROUND_SECTIONS`: `References`, `Context`, `Motivation`, `Additional context`, `See also`) before extraction, so a path cited *only* as background drops out while AC-bullet paths survive. The fuller per-path scoring model remains a follow-up if wholesale section exclusion proves too blunt (e.g. a real target named only under `## Context` becomes a false negative); leave it out until evidence demands it.
 - **Cost.** For 13 issues (the realistic batch ceiling), pairwise comparison is 78 pairs — cheap, no real performance concern. Don't optimize prematurely.
 
 ## Output rules
@@ -104,6 +107,6 @@ The detector returns `CollisionResult[]` from `detectFileCollisions`. The format
 
 - `Order: A → B (path)` per pair (or `Order: A → B → C (path)` for 3+ on the same file). `path` is the canonical bare form (e.g. `qa/SKILL.md`).
 - `⚠ #N  Modifies <path> (overlaps #M); land sequentially` per affected issue.
-- `Chain: npx sequant run A B C --chain --qa-gate -Q   # alternative — N issues modify <path> (chain length≥3 historically 1/6 = 17%; see docs/reference/chain-mode-analysis-2026-05.md)` only when ≥3 issues collide on the same file (suggest-only). The historical-rate annotation comes from the #604 forensic write-up; users see the suggestion alongside the parallel default and can weigh the trade-off.
+- `Chain: npx sequant run A B C --chain -Q   # alternative — N issues modify <path> (chain length≥3 historically 1/6 = 17%, predates the #748/#749 fixes; see docs/reference/chain-mode-analysis-2026-05.md)` only when ≥3 issues collide on the same file (suggest-only). The historical-rate annotation comes from the #604 forensic write-up; users see the suggestion alongside the parallel default and can weigh the trade-off.
 
 The bare-filename `Order:` exception (defined in the skill's "Annotation Rules") applies here — predicted collisions are file-collision reasons by definition, so the filename in parentheses is the reason verbatim.

package/templates/skills/fullsolve/SKILL.md

@@ -855,7 +855,7 @@ export CLAUDE_HOOKS_SMART_TESTS=true
 When enabled, smart tests will:
 - Auto-run related tests after each file edit during Phase 2 (EXEC)
 - Catch regressions immediately instead of waiting for explicit `npm test`
-- Log results to `/tmp/claude-tests.log` for debugging
+- Log results to `claude-tests.log` for debugging (`/logs/`, else `/.sequant/logs/`)
 
 **Benefits:**
 - Faster feedback loop during implementation

package/templates/skills/reflect/SKILL.md

@@ -120,21 +120,35 @@ For each proposal, specify:
 
 ### **Documentation Health Check**
 
-Review CLAUDE.md size and relevance:
-- Current line count (target: 700-800)
-- Sections that feel bloated
-- Sections that are missing
-- Redundancy check
-- Extract candidates (sections >50 lines)
-- Recommendation: [Prune | Expand | Restructure | Extract | Good as-is]
+**CLAUDE.md is an index, not a knowledge store.** Durable knowledge belongs in
+auto-memory, `docs/`, or the relevant skill; CLAUDE.md holds only what must be
+loaded into *every* session (commit rules, hook gotchas, skill-invocation
+rules). A short CLAUDE.md is a sign the other tiers are doing their job — do
+**not** recommend padding it toward some line count. There is no target length.
+
+Review CLAUDE.md relevance:
+- Does every line still apply, and is it still accurate?
+- Anything that only matters in one workflow → move to that skill or `docs/`
+- Anything that is durable session-to-session context → auto-memory
+- Redundancy check (same rule stated here and in a skill)
+- Extract candidates (sections >50 lines — CLAUDE.md should rarely have any)
+- Recommendation: [Prune | Restructure | Extract | Good as-is]
+
+Also check the **memory** tier, which carries most of this repo's knowledge:
+- Entries citing script flags, CLI behavior, or `file:line` **rot silently** —
+  spot-check any entry you relied on this session against current code and fix
+  it. A wrong memory is worse than a missing one.
+- Index (`MEMORY.md`) one-liners still accurate?
 
 ### **Action Items**
 
-Generate a checklist:
-- [ ] Add section to CLAUDE.md: [topic]
-- [ ] Update slash command: [command name]
-- [ ] Move to docs/archive/: [file name]
-- [ ] Create new command: [command name]
+Generate a checklist. Prefer concrete targets — a file, a memory entry, a
+command — over intentions:
+- [ ] Correct/remove a stale memory entry: [name] (verify against current code first)
+- [ ] Add a memory entry for: [durable lesson]
+- [ ] Update skill: [name] — remember all three skill dirs
+- [ ] Update docs: [path] (check main README + marketplace README + docs/)
+- [ ] Add a pointer to CLAUDE.md: [one line + link] — only if needed most sessions
 - [ ] Remove outdated content: [location]
 
 ## Workflow Analytics
@@ -172,7 +186,7 @@ At the end of reflection, ask:
 - [ ] **Session Summary** - What was accomplished, what went well, friction points
 - [ ] **Effectiveness Analysis** - Token efficiency, context gathering, pattern reuse
 - [ ] **Proposed Changes** - Specific changes with target files and rationale
-- [ ] **Documentation Health** - Line count, bloat assessment, recommendations
+- [ ] **Documentation Health** - CLAUDE.md relevance/accuracy (not length) + memory-tier rot check
 - [ ] **Action Items** - Checklist of concrete next steps
 
 **DO NOT respond until all items are verified.**

package/templates/skills/reflect/references/documentation-tiers.md

@@ -1,70 +1,82 @@
 # Documentation Tiers
 
-Organize information by access frequency:
-
-## Tier 1: Hot Path (CLAUDE.md)
-
-- Used in 50%+ of sessions
-- Core architecture decisions
-- Most common commands and patterns
-- **Target: 700-800 lines** (check with `wc -l CLAUDE.md`)
-- Quick summaries with links to detailed docs
-- Review monthly
-
-**Keep in CLAUDE.md:**
-- ✅ Core architecture patterns (database, routing, components)
-- ✅ Most common commands (development, discovery, enrichment)
-- ✅ Critical patterns (validation, audit logging, state management)
-- ✅ Quick reference information needed in 50%+ of sessions
-
-## Tier 2: Reference (docs/ folder)
-
-- Used in 10-50% of sessions
-- Detailed specs, schemas, guides
-- Can be 1000+ lines per doc
-- Review quarterly
-
-**Current specialized docs:**
-- `ARCHITECTURE.md` - System architecture overview
-- `DATA_PIPELINE.md` - Data processing workflows
-- `TESTING.md` - Testing patterns and strategies
-- `ADMIN_CMS_ARCHITECTURE.md` - Full CMS architecture
-
-## Tier 3: Archive (docs/archive/)
-
-- Used in <10% of sessions
-- Historical context, deprecated patterns
-- Move here after 6 months of non-use
-- Keep for searchability, not active use
-
-## Tier 4: Code Comments
-
-- Implementation-specific details
-- Edge case handling
-- Why certain approaches were chosen
-- Lives with the code, not in docs
-
-## When to Extract to Separate Docs
-
-Move from CLAUDE.md to docs/ when:
-- ✅ Section exceeds 50 lines
-- ✅ Contains detailed workflow steps (>3 steps)
-- ✅ Has extensive examples or command variations
-- ✅ Used occasionally but not in every session
-- ✅ Could evolve independently
-
-## Documentation Health Metrics
-
-**CLAUDE.md Health Check:**
-- Current line count vs target (700-800)
-- Lines added in last month
-- Sections that feel bloated
-- Sections that are missing
-- Redundancy between CLAUDE.md and docs/
-
-**Recommendations:**
-- **Prune:** >900 lines, multiple bloated sections
-- **Expand:** <600 lines, missing critical patterns
-- **Restructure:** Hard to find information
-- **Extract:** Multiple sections >50 lines
-- **Good as-is:** 700-800 lines, balanced content
+Where knowledge lives in this repo, by how often it's needed and how long it stays true.
+
+**There are no line-count targets.** Judge a tier by whether the right reader
+finds the right thing, not by size. A short CLAUDE.md means the other tiers are
+working, not that it needs filling.
+
+## Tier 1: CLAUDE.md — the always-loaded index
+
+Loaded into **every** session, so everything here is a tax on every session.
+
+**Keep only:**
+- ✅ Rules with no natural home in a skill or doc (commit conventions, hook gotchas)
+- ✅ Pointers — a one-line "here's the trap, here's the link"
+- ✅ Things that are wrong to learn late (e.g. skill-invocation namespacing)
+
+**Move out:**
+- ❌ Anything that matters in one workflow → that skill
+- ❌ Anything explanatory or >~10 lines → `docs/` and link to it
+- ❌ Session-to-session context about *this developer's* work → auto-memory
+
+## Tier 2: Auto-memory — the main knowledge store
+
+`~/.claude/projects/<project>/memory/`, indexed by `MEMORY.md`. This is where
+most of this repo's hard-won knowledge actually lives (100+ entries): pitfalls,
+feedback, architecture decisions, roadmap state.
+
+- One fact per file; `MEMORY.md` carries a one-line pointer.
+- Best tier for "I learned this the hard way and would re-learn it otherwise".
+
+**Its failure mode is rot, not bloat.** Entries citing script flags, CLI
+behavior, or `file:line` go stale silently, and a *wrong* memory is worse than a
+missing one — it gets trusted. Verify before asserting; fix on sight.
+
+## Tier 3: docs/ — reference for humans
+
+Real structure: `concepts/`, `features/`, `guides/`, `reference/`,
+`getting-started/`, `examples/`, `internal/`, `incidents/`, `investigations/`.
+
+- Detailed specs, architecture, runbooks. Length is fine here.
+- User-facing behavior changes must land here, and often in **more than one
+  place** — check the main README, the marketplace README, and `docs/`.
+- Review when the behavior it describes changes, not on a calendar.
+
+## Tier 4: Skills — workflow instructions
+
+`skills/`, `templates/skills/`, `.claude/skills/` — **three real copies**;
+fix all three or `sequant init`/`update` regenerates the bug (CI enforces this
+via `npm run lint:skill-sync`).
+
+- Procedure a skill must follow belongs in its `SKILL.md`.
+- Detail a skill needs only sometimes → its `references/`, linked from `SKILL.md`.
+- **When editing a SKILL.md, grep its `references/` for the same claim.** Prose
+  specs of a rule drift out of sync with the rule itself.
+
+## Tier 5: Code comments
+
+Constraints the code can't show — why this approach, what breaks otherwise.
+Not what the next line does, and not where it came from.
+
+## When to extract from CLAUDE.md
+
+- ✅ It's explanatory rather than a pointer
+- ✅ It only applies to one workflow or one command
+- ✅ It has examples, steps, or rationale
+- ✅ It could evolve independently of the rest
+
+## Health check
+
+**CLAUDE.md:** is every line still true, still needed in *most* sessions, and
+not duplicated in a skill? Recommend `Prune | Restructure | Extract | Good as-is`
+— never "Expand".
+
+**Memory:** spot-check entries relied on this session against current code.
+Are `MEMORY.md` one-liners still accurate? Any entry superseded by shipped work?
+
+**docs/:** does anything contradict what shipped? Behavior changes are the usual
+source of drift.
+
+**Skills:** are the three copies in sync, and does each `SKILL.md` agree with its
+own `references/`?