@tyroneross/build-loop 0.30.3

package/skills/authentication/references/supabase-auth.md

@@ -0,0 +1,172 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Supabase Auth
+
+## When to use
+
+- **Legacy projects** already on Supabase — keep them there unless there's a compelling reason to migrate
+- **Single-project apps** where Supabase's bundled Postgres + Storage + Realtime + Auth justify the lock-in
+- **Edge-function-heavy** workloads where Supabase Auth's JWT verification at the edge is convenient
+
+For new Next.js projects, the documented stack default is **Neon + Better Auth + Drizzle** instead — see `better-auth-setup.md`. Supabase Auth across multiple projects gets expensive (per-project pricing) and the SSR cookie story has been brittle (see breaking change below).
+
+For runtime API doc lookups, use `mcp__plugin_context7_context7__query-docs` with library `/supabase/supabase`.
+
+## When Supabase Auth vs Better Auth — decision
+
+| Need | Pick |
+|---|---|
+| Brand-new project, Next.js, single repo | **Better Auth + Neon + Drizzle** (Example Web App migrated TO this) |
+| Existing project on Supabase, working fine | **Stay on Supabase** — migration cost > benefit |
+| Multi-project portfolio (3+ apps) | **Better Auth** — per-project Supabase cost adds up |
+| Edge functions doing JWT verification on every request | **Supabase** — built-in JWT verification at the edge |
+| Need Postgres RLS policies as the auth boundary | **Supabase** (or Better Auth + manual `dbForUser` IDOR guard — see `better-auth-setup.md`) |
+| Complex social provider config (Apple iOS native, etc.) | **Better Auth** — more flexible plugin surface |
+| Mobile native app with offline session persistence | Either — Supabase has the JWT story; Better Auth has the Bearer plugin |
+
+## ⚠️ SSR ≥0.3 breaking change — `getAll` / `setAll`
+
+The single biggest gotcha. `@supabase/ssr` versions before 0.3 used per-cookie `get`/`set`/`remove`; 0.3+ requires a unified `getAll`/`setAll` interface. Code that worked in dev with an old version will fail in prod with the new version — **and the failure mode is a silent session loss**, not a thrown error.
+
+### Old (broken on ≥0.3)
+
+```ts
+// ❌ DO NOT use on @supabase/ssr ≥0.3
+const supabase = createServerClient(url, key, {
+  cookies: {
+    get(name) { return cookieStore.get(name)?.value },
+    set(name, value, options) { cookieStore.set({ name, value, ...options }) },
+    remove(name, options) { cookieStore.set({ name, value: '', ...options }) },
+  },
+})
+```
+
+### New (correct)
+
+```ts
+// ✅ @supabase/ssr ≥0.3
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+
+export async function createClient() {
+  const cookieStore = await cookies()
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll()
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            )
+          } catch {
+            // Called from a Server Component — middleware will refresh sessions instead.
+          }
+        },
+      },
+    }
+  )
+}
+```
+
+If you see "session not persisting after sign-in", "logged out after refresh", or RSC-only auth working but route handlers losing the session — check this first.
+
+## Browser client
+
+```ts
+// lib/supabase-browser.ts
+import { createBrowserClient } from '@supabase/ssr'
+
+export function createBrowserSupabase() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  )
+}
+```
+
+## Env-var validation — warn, don't fail (example-app pattern)
+
+Useful when Supabase is optional infrastructure and you want CI / preview envs without a real backend. From `example-app/lib/supabase.ts`:
+
+```ts
+const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL || 'https://placeholder.supabase.co'
+const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || 'placeholder_key'
+
+const validateSupabaseConfig = () => {
+  const hasValidUrl =
+    process.env.NEXT_PUBLIC_SUPABASE_URL &&
+    process.env.NEXT_PUBLIC_SUPABASE_URL !== 'your_supabase_project_url' &&
+    process.env.NEXT_PUBLIC_SUPABASE_URL !== 'https://placeholder.supabase.co'
+  const hasValidKey =
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY &&
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY !== 'your_supabase_anon_key'
+
+  if (!hasValidUrl || !hasValidKey) {
+    console.warn('Supabase configuration not properly set up. Database features will not work.')
+    return false
+  }
+  return true
+}
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+
+// Then in every operation:
+async function getThing() {
+  if (!validateSupabaseConfig()) return [] // graceful no-op, not a crash
+  // ... real query ...
+}
+```
+
+Trade-off: this hides config errors that should be surfaced. Prefer this only for genuinely-optional features (e.g., user-saved data when the app is also useful unauthenticated). For required auth, fail at boot — silent fallback is worse than a clear error.
+
+## RLS as the auth boundary
+
+Supabase's pitch is "let RLS do the auth check, pass the user JWT to Postgres, never write `dbForUser` wrappers." When it works, it's elegant:
+
+```sql
+-- Example RLS policy
+create policy "users_own_camps" on camps
+  for all
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+```
+
+Footguns:
+1. **Service-role queries bypass RLS by design.** Easy to accidentally use the service-role key in a route handler thinking you're being efficient — that's an IDOR.
+2. **`anon` role policies are public.** A misconfigured `select` policy on `anon` makes the table world-readable.
+3. **RLS errors look like "row not found".** `select * where id = X` returns `[]` if RLS denies, not a permission error. Confusing.
+4. **Migration ordering matters.** Add RLS policies BEFORE inserting prod data; enabling RLS on a populated table without policies locks it.
+
+If you adopt RLS, run a periodic audit: log every distinct combination of (table, role, command) the app actually uses, then assert each is policy-covered.
+
+## Migrating away from Supabase Auth
+
+Example Web App migrated `@supabase/ssr` → Better Auth. Pattern:
+
+1. Stand up Better Auth in parallel (keeps Supabase running)
+2. Migrate user records via a one-time script (account, session, verification tables)
+3. Switch the route handler from Supabase callbacks to `app/api/auth/[...all]/route.ts`
+4. Delete Supabase-specific cookie code
+5. Replace RLS-based auth with `dbForUser(userId)` IDOR wrapper (see `better-auth-setup.md`)
+
+The biggest risk is in step 2 — schema mismatch. Better Auth's user/account/session tables don't map 1:1 to Supabase auth schema. Test on a copy of prod first.
+
+## Verification
+
+1. Sign up with email/password (or magic-link / social, depending on config)
+2. Hard refresh the page — confirm session persists (this is the SSR cookie test)
+3. Open in a new tab — confirm session persists across tabs
+4. Sign out — confirm cookies cleared and protected pages redirect
+5. Confirm `auth.uid()` works inside SQL via the SQL editor (`select auth.uid()`)
+6. If using RLS: pick one protected table and confirm with `anon` role that it returns `[]`, with authenticated role that it returns owned rows only
+
+## Cross-references
+
+- Universal footgun #11 (cookie config) in `../SKILL.md`
+- `better-auth-setup.md` — the recommended alternative for new projects
+- For the Example Web App migration narrative, see `lessons-example-web-app-better-auth.md`

package/skills/auto-decision-capture/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: auto-decision-capture
+description: Project-scoped skill for proactive in-session decision capture. Provides Claude the signal taxonomy, confidence ladder, overwrite rules, and the three extraction prompts (SPO triplet / MADR-aligned / batch consolidation) so substantive decisions land in build-loop-memory without manual triggering. Use when the user makes a substantive choice, confirms a proposal, or implies a constraint with textual evidence.
+user-invocable: false
+when_to_use: |
+  - User issues a direct verbal marker ("let's go with X", "ship it", "use Y")
+  - Claude offered a choice menu and the user picked one
+  - User accepts a proposal Claude wrote (action-confirmation)
+  - Topic shifts past a proposal that stood without objection (continuation)
+  - User states a project-scoped constraint, preference, or convention
+  - Topic-coherent inference can be drawn with quotable evidence (tier 3)
+namespace: build-loop-memory/projects/<project>/decisions/
+companion_scripts:
+  - scripts/write_decision/__main__.py — atomic writer (file + INDEX + events.jsonl + DB)
+  - scripts/scan_transcript_for_decisions.py — Stop-hook batch sweep (tier 3)
+  - scripts/supersede_decision.py — explicit replacement
+  - scripts/revoke_decision.py — explicit withdrawal
+  - scripts/recall.py — "have we decided this before?" lookup
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# auto-decision-capture — proactive decision capture during sessions
+
+This skill makes Claude an active participant in maintaining the project's
+decision log. The user does not have to remember to write decisions, and
+does not have to invoke a slash command. When evidence is in the
+conversation, Claude writes; when evidence is weak, the end-of-session
+Stop hook batches inferences for review.
+
+## Core principle: signal-based, NOT turn-counted
+
+There is no "wait N turns" rule. The threshold is **"is there textual
+evidence?"**, not "have we waited long enough?". Every capture must
+trace to a quote, an action, or a topic transition. No speculation
+without a concrete signal.
+
+## Signal taxonomy and confidence ladder
+
+| Signal | Confidence | Write target | Write timing | Example |
+|---|---|---|---|---|
+| **Direct verbal marker (user)** | `explicit` | trusted (`build-loop-memory/projects/<project>/decisions/`) | immediately on user turn | "let's go with X" / "ship it" / "use Y" |
+| **Choice converter** | `explicit` | trusted | immediately | Claude offered A/B/C; user said "B" |
+| **Implementation declarative (agent)** | `explicit` | trusted | when stated in agent reasoning | "I'll use X for Y", "going with X over Y because Z", "implementing via X". For build-orchestrator subagents specifically — task-execution language IS a decision signal. |
+| **Tradeoff statement** | `explicit` | trusted | when "X over Y because Z" appears | "extend YAML parser instead of changing test expectations" / "use X (Apache-2.0) over Y (GPL-3) because licensing" |
+| **Threshold/parameter declaration with rationale** | `explicit` | trusted | when a numeric/named value is bound to reasoning | "cosine 0.85 because design ref §12 cites Mem0/Zep production consensus" / "default budget 25s leaves headroom on cold qwen3:8b" |
+| **Default-value selection** | `confirmed` | trusted | when a default is declared | "default: `claude-opus-4-7` (current top model)" / "fall back to ollama on MLX failure" |
+| **Action-confirmation (user)** | `confirmed` | trusted | after action accepted | Claude proposed → wrote code → user accepted without reverting |
+| **Continuation pattern** | `confirmed` | trusted | when topic shifts past decision | proposal stood while conversation moved on |
+| **Topic-coherent inference** | `inferred` | trusted, **overwriteable** | aggressive — written during session | Claude pattern-matched a position; user did not object but did not endorse |
+| **Pure pattern-match from prior conversation** | `assumed` | trusted, **overwriteable** | aggressive — written during session | inferred from past decisions or memory |
+
+**Note on agent-style language (build-orchestrator subagents, implementer subagents).** Task-execution language ("I'll add X", "extending Y", "default to Z") is just as much a decision signal as user-conversational language ("let's use Y"). Earlier versions of this skill under-captured agent decisions because the patterns were tuned only for user-Claude back-and-forth. The three middle rows above (Implementation declarative / Tradeoff / Threshold) are the explicit fix. **If you are reasoning as a subagent and you make any of those moves, capture it.**
+
+**Tier 1 + 2 (explicit + confirmed) live captures during the session.**
+Use `scripts/write_decision/__main__.py` directly with `--confidence explicit` or
+`--confidence confirmed`. Set `--source auto-explicit` or
+`--source auto-confirmed` so the capture is distinguishable from manual
+human entries.
+
+**Tier 3 + 4 (inferred + assumed) batch sweeps at session end** via the
+Stop hook. The hook runs `scripts/scan_transcript_for_decisions.py`,
+which calls a local LLM (`qwen3:8b-q4_K_M`) with Prompt C below. Tier 3
+results land in `build-loop-memory/projects/<project>/decisions/_review/` for user promotion,
+NOT in the trusted set.
+
+You can also write tier-3 captures aggressively in-session if a
+topic-coherent inference is strong. Old `inferred` of the same
+`primary_tag + entity` is overwritten by the next signal — see
+"Overwrite rules" below.
+
+## Overwrite rules
+
+Written into `write_decision.py`'s topic-identity supersession path
+(`primary_tag + entity` is the topic key):
+
+- Higher-confidence auto-supersedes lower (prior moves to `_history/<id>-vN.md`)
+- Equal-confidence requires `--supersedes <id>` flag (refuse otherwise)
+- Lower-confidence cannot displace higher (refused with exit 1)
+- `inferred` and `assumed` captures are overwriteable by any newer signal of
+  equal or higher confidence on the same topic
+
+This is the safety mechanism that lets you capture aggressively without
+poisoning the trusted set: a wrong inferred capture is corrected by the
+next contradicting signal.
+
+## What gets captured (positive evidence required)
+
+- Decisions: choice + rationale + alternatives that were on the table + provenance
+- Project-scoped constraints, preferences, conventions stated as durable
+- Tooling/library/architecture choices with rationale
+
+## What does NOT get captured
+
+- Brainstorming that did not converge
+- Questions the user asked Claude
+- One-off corrections to a single response (these are feedback, not decisions)
+- Anything Claude "thinks the user would want" without textual evidence
+- Sensitive or volatile content where the user has not signaled durability
+
+**No sensitivity-keyword filter.** Per project direction, capture any
+decision the user makes regardless of topic. The user can revoke any
+capture with `scripts/revoke_decision.py --id <id> --reason ...`.
+
+## Tag selection — controlled vocabulary
+
+Tags come from `write_decision.py`'s controlled vocabulary. New tags get the `proposed:`
+prefix (e.g. `proposed:streaming-llm`), surfaced for promotion in the
+next Phase 1 Assess. Do not invent tags outside this vocabulary —
+vocabulary mismatch is the dominant retrieval failure mode.
+
+## How to capture (live, during the session)
+
+```bash
+python3 scripts/write_decision/__main__.py \
+  --workdir "$PWD" \
+  --title "<one-line title>" \
+  --decision "<one-sentence decision>" \
+  --context "<1-3 sentences>" \
+  --alternatives "<options considered>" \
+  --consequences "<1-3 bullets>" \
+  --tags "tooling,testing" \
+  --primary-tag "testing" \
+  --entity "<scope: project name or module>" \
+  --confidence explicit \
+  --source auto-explicit \
+  --captured-turn-excerpt "<≤200 chars from the user's turn>" \
+  --tool claude-code \
+  --model claude-opus-4-7 \
+  --task-category bugfix \
+  --author auto
+```
+
+### v2 metadata fields (skill-driven captures)
+
+Frontmatter v2 (added 2026-05-04, design §15) attaches five required
+fields and four optional fields to every decision. The writer applies
+sensible defaults so legacy callers still work, but skill-driven
+captures should set these explicitly when the signal is clear:
+
+| Field | Skill default | Example | When to override |
+|---|---|---|---|
+| `--tool` | `claude-code` (Stop hook fires inside Claude Code) | `claude-code` | If the conversation references another tool authoring the decision (rare) |
+| `--model` | `claude-opus-4-7` (or `$CLAUDE_MODEL`) | `claude-sonnet-4-6` | When you know the active sub-agent's model |
+| `--author` | `auto` (skill-driven captures) | `auto` | Always `auto` for in-session skill writes |
+| `--project` | derived from entity prefix or `$CLAUDE_PROJECT_DIR` | `build-loop` | Almost never; the default is right |
+| `--task-category` | `unknown` if no signal | `bugfix`, `feature`, `refactor`, `research`, `docs`, `migration`, `experiment`, `config` | **Set explicitly** whenever the conversational signal is clear (user said "fix this bug" → `bugfix`; "add this feature" → `feature`; "investigate why X" → `research`) |
+| `--files-touched` | `[]` (or `--infer-files-touched` for git diff) | `src/auth/session.ts,src/auth/middleware.ts` | When the decision is bound to a specific file set |
+
+**Inferring `task_category` from the conversation** — pick the strongest
+signal:
+
+- "fix the bug where…" / "this error…" / "broken since…" → `bugfix`
+- "add the X feature" / "build a new…" / "implement…" → `feature`
+- "clean up…" / "extract…" / "rename…" without behavior change → `refactor`
+- "investigate / understand / what's the best way" → `research`
+- "update the docs" / "README" / "changelog" → `docs`
+- "migrate from X to Y" / "schema change" → `migration`
+- "try / spike / experiment" → `experiment`
+- env vars / settings / runtime config → `config`
+- everything else → `unknown` (let the user override later via `/knowledge:review`)
+
+### v3 metadata fields (skill-driven captures, design §16)
+
+Frontmatter v3 (added 2026-05-04) adds seven more fields. The writer fills
+sensible defaults, but skill-driven captures should set the three that
+benefit from conversational signal:
+
+| Field | Skill default | When to override |
+|---|---|---|
+| `--confidence-source` | `user_statement` if confidence=`explicit` AND a verbal marker / quote is captured; else `ai_inference` | Set explicitly whenever you can attribute the assertion. `user_statement` for direct quotes ("let's go with X"); `ai_inference` for topic-coherent inferences; `tool_extraction` if the value came from a deterministic tool output rather than the conversation |
+| `--domain` | `unknown` | **Set explicitly** when the conversational scope is clear: `ui` for visual / interaction work, `api` for endpoint contracts, `data` for storage layer, `search` for retrieval / recall / indexing, `auth` for identity / permissions, `build` for compilation / packaging / CI, `infra` for deploy / hosting / runtime, `tooling` for dev workflow / CLI / linters, `docs` for documentation, `test` for test-suite work, `meta` for cross-cutting / process / architecture |
+| `--goal` | `unknown` | **Set explicitly** when the user's framing makes intent clear: `user-value` for end-user-visible improvements, `reliability` for bug fixes / robustness, `performance` for speed / cost / efficiency, `security` for hardening, `dev-velocity` for developer-experience gains, `maintainability` for refactor / readability, `compliance` for regulated requirements, `learning` for spike / explore |
+| `--confirmation-count` | `0` | Almost never override at write time — the bumper hook (future) increments this on successful action |
+| `--valid-until` | `null` | Set when the decision is bound to a date — quarterly OKR, vendor contract end, model deprecation |
+| `--causal-parent-id` | `null` | Set when this decision is downstream of a specific prior decision (use the 4-digit id) |
+| `--embedding-model-version` | `$EMBED_MODEL` env or `mxbai-embed-large-v1` | Almost never override; the writer reads the active backend automatically |
+
+**Examples — `domain` and `goal` from conversational context:**
+
+| User said | `domain` | `goal` |
+|---|---|---|
+| "fix this bug in the search retrieval" | `search` | `reliability` |
+| "speed up the homepage loader" | `ui` | `performance` |
+| "rotate the API keys before Friday" | `auth` | `security` |
+| "rewrite the auth middleware to be testable" | `auth` | `maintainability` |
+| "add a CSV export to the dashboard" | `ui` | `user-value` |
+| "investigate which queue library to use" | `infra` | `learning` |
+| "update the CONTRIBUTING.md" | `docs` | `dev-velocity` |
+| "tighten the lint rules" | `tooling` | `maintainability` |
+
+When in doubt, leave them as `unknown` rather than guess — the user can
+backfill via `/knowledge:review`.
+
+**`confidence_source` — when to set what:**
+
+- Direct verbal marker (the user typed it) → `user_statement`
+- Choice converter (Claude offered A/B/C, user picked one) → `user_statement`
+- Action confirmation (user did the thing Claude proposed) → `user_statement`
+- Topic-coherent inference (no direct quote, but the topic stood) → `ai_inference`
+- Pulled from external memory / migration import / vector-DB sync → `external_import`
+- Deterministic tool output (e.g., `git log`, `grep`) → `tool_extraction`
+- Genuinely cannot tell → `unknown`
+
+Output is the new 4-digit decision ID on stdout (e.g. `0042`). Errors go
+to stderr.
+
+For supersession (a new decision replaces an old one):
+```bash
+python3 scripts/supersede_decision.py \
+  --old-id 0042 \
+  --new-decision "..." \
+  --new-title "..." \
+  --tags "..." --primary-tag "..." --entity "..." \
+  --confidence explicit \
+  --rationale "Why we changed our mind"
+```
+
+For revocation (the captured decision was wrong, no replacement):
+```bash
+python3 scripts/revoke_decision.py \
+  --id 0042 \
+  --reason "user clarified this was venting, not a decision"
+```
+
+For lookup before writing (avoid duplicates):
+```bash
+python3 scripts/recall.py --query "test framework"
+```
+
+## Extraction prompts (inline reference)
+
+These three prompts are the canonical extraction templates from
+`~/dev/research/topics/repo-episodic-memory-framework/repo-episodic-memory-framework.md` §12.
+Use them whenever you need to extract structured decisions from
+unstructured conversation. Keep temperature low (0.1–0.3).
+
+### Prompt A — Subject-Predicate-Object triplet extraction
+
+```
+Extract facts from the user's conversational decisions. Output JSON array.
+Each fact: subject (who/what), predicate (relationship), object (value).
+
+Example:
+  Input: "We'll use pytest for testing from now on."
+  Output: [{"subject":"this_project","predicate":"testing_framework",
+           "object":"pytest","confidence":"explicit",
+           "entity_type":"tool","tags":["tooling","testing"]}]
+
+Rules:
+- confidence: explicit | confirmed | inferred | assumed
+- entity_type: tool | process | library | constraint | preference | architecture
+- tags: from controlled vocabulary {{taxonomy_tags}}
+- Do NOT infer beyond textual evidence.
+```
+
+### Prompt B — Decision + rationale (MADR-aligned, single decision)
+
+```
+Extract a decision the user made or implied. Output JSON object.
+
+Schema: {decision_title, context, alternatives_considered[],
+         chosen, rationale, confidence, primary_tag}
+
+Rules:
+- rationale MUST have textual evidence; otherwise mark "inferred"
+- If user did not explicitly choose, confidence is "inferred" at best
+- primary_tag is singular; pick most relevant
+```
+
+### Prompt C — End-of-session batch consolidation (tier 3 sweep)
+
+```
+Scan the conversation transcript. Identify 2–4 decisions the user made
+implicitly. For each, output:
+
+[{decision, evidence (exact quote or turn range),
+  confidence: inferred|assumed,
+  may_be_superseded_by: null or prior decision ID}]
+
+Existing decisions: {{prior_decisions_summary}}
+
+Rules:
+- Only capture if there is textual signal. No speculation.
+- Flag supersessions for human review.
+```
+
+## Dedup thresholds (when comparing against prior captures)
+
+| Cosine similarity | Same (subject, predicate)? | Action |
+|---|---|---|
+| ≥ 0.90 | yes, near-identical object | IGNORE (already known) |
+| 0.85–0.90 | yes, slight phrasing variation | MERGE (use supersession) |
+| 0.75–0.85 | related but different predicates | INSERT (keep both) |
+| < 0.75 | unrelated | INSERT |
+
+`write_decision.py` handles the topic-identity match (primary_tag + entity);
+the cosine threshold matters for the end-of-session batch sweep
+(`scripts/scan_transcript_for_decisions.py` consults `semantic_facts`
+before writing).
+
+## End-of-session sweep — automatic via Stop hook
+
+The Stop hook in `hooks/hooks.json` invokes
+`scripts/scan_transcript_for_decisions.py` against
+`$CLAUDE_TRANSCRIPT_PATH`. The script:
+
+1. Reads the transcript JSONL
+2. Calls `qwen3:8b-q4_K_M` with Prompt C (above)
+3. For each candidate: dedups against `semantic_facts` (≥0.85 = SKIP)
+4. Tier 1+2 (explicit+confirmed) → `write_decision.py` → trusted
+5. Tier 3+4 (inferred+assumed) → `build-loop-memory/projects/<project>/decisions/_review/` quarantine
+
+If ollama is unreachable, the hook logs a no-op and exits 0 — never
+fails the session.
+
+### Per-session opt-out
+
+Create `.build-loop/.no-capture` to skip the auto-capture sweep for the
+current session. The script exits 0 immediately on startup with a log
+line. Remove the file when you want the sweep back on:
+
+```bash
+touch .build-loop/.no-capture     # disable for this session
+rm .build-loop/.no-capture        # re-enable
+```
+
+This is a per-repo flag; it does not affect other projects.
+
+### Hardening contract (Stop-hook safety)
+
+The script self-imposes guardrails so the Stop hook never disrupts a
+coding session:
+
+- **Wall-clock budget** — default 25s, override with env `SCAN_BUDGET_S`.
+  Checked before the LLM call and between writes. On overrun the script
+  logs `budget exceeded` and exits 0 with whatever was already written.
+  The hook timeout (60s) is a backstop; the budget should always fire
+  first.
+- **Single-flight lock** — `fcntl.flock` on `/tmp/build-loop-scan.lock`
+  (override with `--lock-file`). A second concurrent invocation exits 0
+  immediately with a log line. Prevents contention when sessions end
+  close together.
+- **Output suppression** — the hook command redirects stdout and stderr
+  to `/dev/null`. The durable record is the log file at
+  `${XDG_STATE_HOME}/build-loop/scan.log` (default
+  `~/.local/state/build-loop/scan.log`). Override with `--log-file`. The
+  log file auto-rotates when it exceeds 10 MB (last 1 MB kept).
+
+## Confidence floor at retrieval
+
+`write_decision.py`'s INDEX regenerator filters by `confidence >= confirmed`
+by default. Tier 3 entries written aggressively in-session do appear in
+the trusted directory but are filtered out of the default INDEX view.
+Phase 1 Assess loads only `explicit + confirmed` unless you explicitly
+search at lower confidence.
+
+## When in doubt
+
+1. If the user's turn contains a clear verbal marker → capture as `explicit`
+2. If the user accepted Claude's proposal and the topic moved on → capture as `confirmed`
+3. If you can quote evidence but the user did not endorse → capture as `inferred`
+4. If you can only pattern-match prior context → either skip, or capture as `assumed` knowing it will be overwritten
+
+When unsure between two confidence levels, pick the lower. The system
+self-heals as more signal arrives.
+
+## When the user runs `/knowledge:review`, surface…
+
+The review surface (loaded by `build-loop:knowledge-review`, backed by
+`scripts/knowledge_review.py`) shows four sections of decisions and
+procedures awaiting human attention:
+
+1. **Review queue** — tier-3 / inferred captures sitting in
+   `build-loop-memory/projects/<project>/decisions/_review/` (written there by either the Stop-hook
+   batch sweep or in-session aggressive `inferred` captures from this
+   skill). User promotes or dismisses each.
+2. **Decision rot** — accepted decisions where `last_validated` (or
+   `date` if absent) is older than 90 days. User marks-validated,
+   supersedes, or revokes. Long-running decisions accumulate rot until
+   touched.
+3. **Open conflicts** — `fact_conflicts` rows (resolved=FALSE) created
+   when `consolidate_memory.py` detected two semantic facts with the
+   same `(subject, predicate, confidence)` but different `object`. User
+   resolves by superseding one.
+4. **Stale procedures** — procedure files whose `depends_on` symbols
+   are no longer present in the codebase (run by
+   `procedural_governance.py --mode validate-symbols`).
+
+**Cross-reference**: when this skill writes aggressively at tier 3
+(`inferred`) and the same `primary_tag + entity` keeps getting
+overwritten, that's a signal the user's intent is unstable. The
+review queue surfaces it; the user takes the explicit decision and
+pins it. The overwrite path then stops firing.
+
+Consolidation (`scripts/consolidate_memory.py`) is the related batch
+script for promoting candidate JSONL entries into
+`semantic_facts`.
+
+## Corrections + lessons (companion stack)
+
+This skill captures **decisions** inline during a session. The companion
+correction-aware capture stack — `scripts/scan_corrections/` (tier-1
+deterministic Stop hook), `scripts/surface_pending_lessons.py` (tier-3
+host-agent surface), and `scripts/bridge_lesson_to_harness.py` (store
+mirror) — captures **corrections, preferences, and lessons** at session
+boundaries, with no Ollama dependency. Full design:
+`skills/build-loop/references/correction-aware-capture.md`.
+
+When the user corrects an action you just took ("revert that", "don't do
+X", "use Y instead of Z"), the tier-1 scanner writes a raw candidate to
+`.build-loop/pending-lessons/`. At the next SessionStart, the host coding
+agent — you — reads `surface_pending_lessons.py` output, classifies each
+candidate, and promotes via `scripts/memory_writer.py --type lesson|feedback`
+(global lane: `build-loop-memory/lessons/`; project lane:
+`build-loop-memory/projects/<slug>/lessons/`). The two paths are
+complementary: this skill catches what you can see during the turn; the
+companion catches what the deterministic scanner can find at the end of
+the session.