@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/backend-realtime/references/patterns.md

@@ -0,0 +1,74 @@
+# Real-time Reference Patterns
+
+Longer, copy-ready implementations for `backend-realtime`. Examples assume a
+**Next.js App Router + Supabase** stack (`@/lib/supabase/client`, `'use client'`,
+a `Message` row type). Adapt import paths and types to the detected stack.
+
+---
+
+## Subscribe to Database Changes (`useRealtimeMessages`)
+
+Initial fetch + INSERT/DELETE subscription for a chat room, with cleanup on
+unmount.
+
+```tsx
+'use client'
+import { useEffect, useState } from 'react'
+import { createClient } from '@/lib/supabase/client'
+
+export function useRealtimeMessages(roomId: string) {
+ const [messages, setMessages] = useState<Message[]>([])
+ const supabase = createClient()
+
+ useEffect(() => {
+ // Initial fetch
+ const fetchMessages = async () => {
+ const { data } = await supabase
+ .from('messages')
+ .select('*')
+ .eq('room_id', roomId)
+ .order('created_at', { ascending: true })
+
+ if (data) setMessages(data)
+ }
+ fetchMessages()
+
+ // Subscribe to changes
+ const channel = supabase
+ .channel(`room:${roomId}`)
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'messages',
+ filter: `room_id=eq.${roomId}`,
+ },
+ (payload) => {
+ setMessages((prev) => [...prev, payload.new as Message])
+ }
+ )
+ .on(
+ 'postgres_changes',
+ {
+ event: 'DELETE',
+ schema: 'public',
+ table: 'messages',
+ filter: `room_id=eq.${roomId}`,
+ },
+ (payload) => {
+ setMessages((prev) =>
+ prev.filter((m) => m.id !== payload.old.id)
+ )
+ }
+ )
+ .subscribe()
+
+ return () => {
+ supabase.removeChannel(channel)
+ }
+ }, [roomId, supabase])
+
+ return messages
+}
+```

package/skills/burndown-full/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: burndown-full
+description: >
+  Drive a planned mechanical change to 100% repo coverage after a run stopped
+  early. Use when "finish the burndown", "it stopped halfway", "apply this
+  everywhere", or "half-migrated". One plan plus deferrals →
+  complete-everything.
+---
+
+# Burndown Full
+
+**Degree of freedom: MIXED.** Signature and batch sizing `[HIGH freedom]`;
+from-scratch re-search and the zero-hit gate `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — the old pattern's remaining hits from a fresh search
+2. **Interpret** — planned files vs the real blast radius (tests, barrels, stories)
+3. **Classify** — still-old / already-new / false-positive
+4. **Severity** — leftover production call sites outrank a comment in CHANGELOG
+
+## Worked example
+
+> **Observe:** plan listed 8 files; fresh `rg Button2` finds 14 (plus a story and a re-export).
+> **Interpret:** the plan was a hypothesis; barrels were missed.
+> **Classify:** 6 extra call sites still-old; CHANGELOG mention is false-positive.
+> **Done:** re-search → 0 real hits; typecheck/lint/tests green.
+
+## Self-critique before reporting
+
+- **Fresh search** — done is zero hits from scratch, not memory
+- **Plan is not the boundary** — extras were appended, not ignored
+- **No skip** — tests/stories/re-exports burned down too
+- **Right owner** — one approved plan + deferrals → `complete-everything`; inventory → `housekeep-backlog`
+
+## What problem this solves
+
+A coding agent is given a plan, generates it, starts executing, and then **stops before the change is actually complete across the codebase**. The user is left with a half-migrated repo. This is not a motivation problem — it is a well-documented set of failure modes in long-horizon LLM agents:
+
+- **Compaction.** Long runs get compacted; anything that lived only in the transcript — including "what's left to do" — is gone afterwards. The remaining work has to live in a file.
+- **Premature termination.** When tool outputs and history get pruned or summarized to save context, agents lose task-level awareness ("how many items remain, am I near done?") and declare completion early. The fix shown in the research is to keep a *condensed, persistent record of remaining work* visible at all times.
+- **Plan-as-boundary error.** A plan is a *hypothesis* about scope produced before the repo was fully explored. The real set of affected files is almost always larger than the plan's list (barrels, tests, stories, configs, re-exports, dynamic usages). Treating the plan's file list as the boundary guarantees an incomplete burndown.
+
+The countermeasures below are drawn from how robust coding agents (Claude Code's TodoWrite, etc.) actually achieve reliable completion: **enumerate before executing, externalize the worklist to a file so it survives context truncation, work in small focused batches, and define "done" by a fresh verification pass rather than by the agent's memory.**
+
+## The core principle
+
+> **The plan is a starting hypothesis about scope, never the limit of scope. Memory is not a source of truth — a fresh repo-wide search is. You are not done when the planned files are edited; you are done when a from-scratch search for the old pattern returns zero, and the whole project type-checks, lints, and tests clean.**
+
+Internalize this loop: **enumerate → batch-execute → persist progress → verify from scratch → if anything remains, loop.** Never exit the loop on a feeling of completion.
+
+Repo-wide parked-work inventory (every plan, TODO, skip, open finding) is
+`housekeep-backlog`. This skill burns down **one** mechanical change.
+
+---
+
+## Phase 0 — Recover and pin down the change
+
+Reconstruct, in one precise sentence, what the change actually is. Pull from:
+- the plan file or prior conversation (if arguments reference a plan/path, read it fully first);
+- what's already been applied: `git diff`, `git diff --staged`, `git log --oneline -15`, `git status`.
+
+Then convert the change into a **machine-checkable signature** — the concrete pattern(s) that distinguish "still needs changing" from "already changed." Define both explicitly:
+
+- **MATCH** = the pattern that marks code still needing the change (the *remaining-work* signal).
+- **DONE** = the pattern that marks code already migrated (so you never redo or thrash).
+
+Examples of (MATCH → DONE):
+- old import path → new import path
+- `TWEEN_*` constant names → `SPRING_PHYSICS_*`
+- deprecated `<OldButton>` / `useOldHook` → replacement
+- old API/prop signature → new signature
+- a lint/style rule violation → its corrected form
+
+**If the change cannot be expressed as a searchable pattern (grep / structural / AST), STOP and say so.** Ask the user to make the criterion concrete, or agree on a per-file judgment checklist instead. Proceeding on "vibes" is the exact thing that causes the early stop — verification by search is what makes a full burndown provable. Do not skip this.
+
+Also discover the project's **verification commands** up front (don't assume them):
+- Look in `package.json` scripts, `Makefile`, `justfile`, `README`, `AGENTS.md`/`CLAUDE.md`, CI config.
+- Identify: typecheck (e.g. `tsc --noEmit`), lint, test, build. Note the exact commands. If none exist, say so — verification will rely on search + build only.
+
+## Phase 1 — Enumerate the FULL worklist before editing anything
+
+Run an exhaustive, repo-wide search for MATCH. **Search the whole repo, not the plan's file list.** Cast wide with ripgrep; include every plausibly relevant extension and location:
+
+```bash
+rg -n --hidden \
+  -g '!node_modules' -g '!.git' -g '!dist' -g '!build' -g '!.next' -g '!coverage' -g '!*.lock' \
+  -e '<MATCH_PATTERN>'
+```
+
+Deliberately hunt the categories plans habitually miss:
+- barrel / index files and re-exports (`export * from`, `export { X } from`)
+- aliased and namespace imports (`import { X as Y }`, `import * as M`)
+- string-literal and dynamic usages, template strings, config keys
+- tests, snapshots, fixtures, mocks, stories (`*.stories.*`), e2e
+- type definitions (`*.d.ts`), generated types
+- config files (`*.config.*`, `.env*`, CI yaml), scripts, docs/README
+- comments and JSDoc, if the change semantically requires them
+
+If MATCH is multi-form (e.g. a symbol imported several ways), run a query per form and union the results. Don't trust a single grep to capture every flavor.
+
+**Write the result to a durable checklist file: `.cursor/burndown-state.md`.** This file is your working memory; it must survive context truncation. One line per (file + occurrence/role). Format:
+
+```md
+# Burndown: <one-sentence change definition>
+MATCH: <pattern>
+DONE:  <pattern>
+Verify: typecheck=`<cmd>` lint=`<cmd>` test=`<cmd>` build=`<cmd>`
+Total occurrences found: N across M files
+Plan originally named: P files
+
+## Worklist
+- [ ] src/components/Button.tsx:42 — direct usage
+- [ ] src/index.ts — barrel re-export
+- [ ] src/components/Button.stories.tsx — story + snapshot
+- [ ] tests/button.test.tsx:17 — assertion references old name
+...
+
+## Exceptions (intentionally NOT changed — justify each)
+- (none yet)
+
+## Newly discovered during execution (append here, then work them)
+- (none yet)
+```
+
+**State the totals out loud to the user**: "Found N occurrences across M files; the original plan named only P. I'll burn down all N." Announcing the full count up front commits you to the real scope and makes any later shortfall visible. Also create the equivalent native task list (TodoWrite / Cursor task list) so progress is visible in the UI — but `.cursor/burndown-state.md` is the source of truth because it persists.
+
+## Phase 2 — Execute in small batches, persisting progress every batch
+
+Work the checklist top-to-bottom in small batches (5–10 files is a good default) so every batch is ticked in the state file before the next starts. For each batch:
+
+1. Apply the change to those files. Prefer mechanical, pattern-driven edits so coverage is verifiable rather than judgment-based. Keep edits minimal and consistent with DONE.
+2. **Immediately** flip those lines `[ ]` → `[x]` in `.cursor/burndown-state.md`. Do the bookkeeping per-batch, never deferred — if context is truncated mid-run, an un-ticked completed item is lost work and a ticked incomplete item is a false "done."
+3. Run a fast scoped check on just the touched files if cheap (lint/typecheck the batch). Fix what you broke before moving on.
+4. If you discover new occurrences while editing (a usage the grep missed, a follow-on file), **append them to the "Newly discovered" section** and include them in the burndown — do not silently absorb or skip them.
+
+Do not stop between batches to ask "should I continue?" — continue until the worklist is exhausted. Compaction may happen mid-run; after any compaction, re-read `.cursor/burndown-state.md` to recover the remaining list rather than trusting memory. A long run is not a reason to wrap up.
+
+## Phase 3 — Prove completeness (the anti-stop gate)
+
+Report done only when every check below passes — completion is defined by verification, not by the sense of having finished.
+
+1. **Fresh from-scratch search.** Re-run the Phase 1 `rg` for MATCH across the entire repo *as if starting over*. Expected: **zero** hits, except items explicitly listed under Exceptions (each justified). Any new hit → add to worklist, return to Phase 2.
+2. **Orphan sweep.** Search for things that must move *with* the change: barrel exports, type defs, tests, stories, mocks, docs referencing the old form. A migrated component whose test/story/snapshot still references the old form is **not** done.
+3. **Whole-project typecheck** (not just touched files), e.g. `tsc --noEmit`. New errors reveal remaining work.
+4. **Lint the repo.** Unused-import / unresolved-import / no-undef errors frequently expose half-finished migrations.
+5. **Run the test suite** (or at least the affected projects). Update snapshots only where the change legitimately changes output; never blanket-update to hide regressions.
+6. **Build** if there's a build step.
+7. **Checklist is clean:** zero `[ ]` lines remain in `.cursor/burndown-state.md`.
+
+If any check surfaces new occurrences or failures, **add them to the checklist and loop back to Phase 2.** Repeat the gate until a fresh search is clean and all configured checks pass. The loop terminates on verified emptiness, not on effort spent.
+
+## Phase 4 — Report and clean up
+
+Produce a concise final report:
+
+- **Change applied:** one sentence.
+- **Coverage:** N occurrences across M files completed. **Call out the (M − P) files the original plan missed** — this is the value the burndown added.
+- **Verification results:** `rg <MATCH>` → 0 hits; typecheck → clean; lint → clean; tests → pass; build → ok. Show the actual commands and outcomes.
+- **Intentional exceptions:** each file left unchanged, with reason.
+- **Genuine ambiguities for a human:** anything you could not resolve mechanically. Surface these explicitly — never silently skip an occurrence to reach a clean number.
+
+Leave `.cursor/burndown-state.md` in place (fully ticked) as an audit trail unless the user asks to delete it, and keep it out of the commit. Suggest committing the change as one reviewable unit, or splitting mechanical vs. judgment edits into separate commits if that aids review.
+
+---
+
+## Operating principles (keep these in working memory)
+
+- The plan is a hypothesis about scope; the repo is bigger than the plan and bigger than what you remember of it.
+- The checklist file is your memory; the fresh grep is your source of truth. When they disagree, the grep wins.
+- "I edited the files in the plan" is **not** completion. "A from-scratch search for the old pattern returns zero and the project checks clean" is completion.
+- Whether this MATCH/DONE ratchet itself can be gamed (DONE without evidence, count going down) is `audit-gate-logic`. Whether the transform preserved behavior is `audit-codemod-safety`.
+- Work in small batches and persist progress every batch, so a truncated context never costs progress.
+- Your turn ends in one of two shapes: the Phase 4 report after the gate passed, or a precise statement of what is left and why you cannot resolve it (a genuine ambiguity needing a human decision, or a verification failure you cannot repair). It does not end with "should I continue?", with a summary of the remaining batches, with "I'll pick this up next", or with a partial batch ticked as done. Before ending your turn, read your last paragraph: if it describes work you could do now, do it.

package/skills/complete-everything/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: complete-everything
+description: >
+  Closure mode for one approved plan: finish every open item and connected
+  deferral, verify each acceptance criterion, require completion-judge PASS.
+  Use when "complete everything", "don't defer", "fix out of scope too", or a
+  plan was falsely marked done.
+---
+
+# Complete Everything
+
+**Degree of freedom: MIXED.** Relevance of parked items `[HIGH freedom]`;
+state-file ticks, verification ladder, and completion-judge
+`[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — plan items, parked quotes, git diff, baseline failures
+2. **Interpret** — connected to the approved goal vs explicit non-goal
+3. **Classify** — plan / previously-parked / discovered / human-gate
+4. **Severity** — an unchecked acceptance criterion blocks the report
+
+## Worked example
+
+> **Observe:** plan shipped the UI; "out of scope" noted the RLS migration file; live API 404s.
+> **Interpret:** the parked migration is connected — the UI cannot work without it.
+> **Classify:** previously-parked now in scope; deploy+verify the RPC.
+> **Done:** state file ticked with evidence; completion-judge PASS.
+
+## Self-critique before reporting
+
+- **Evidence** — every tick cites a fresh command/result
+- **No deferral language** — connected parked work was closed, not restated
+- **Judge** — `completion-judge` ran; CONTINUE loops back
+- **Right owner** — one mechanical pattern → `burndown-full`; dirty-tree PR → `workflow-release-prep`
+
+## Completion contract
+
+Drive the approved outcome through implementation, repair, and verification in
+one continuous run. Do not stop at phase boundaries or ask whether to continue.
+Do not claim success from memory, compilation alone, or the original plan's
+checkboxes.
+
+The **closure set** contains:
+
+- every unfinished or partially finished plan item;
+- every `out of scope`, follow-up, optional, nice-to-have, or future-work item
+  parked by the plan or prior completion report that is materially connected to
+  the approved goal;
+- every defect, missing test, contract mismatch, or regression discovered in
+  the affected blast radius;
+- every failure introduced by the work or blocking proof of the outcome.
+
+This is not permission for unrelated repository-wide cleanup. Do not silently
+reopen explicit user non-goals, rejected features, or unrelated pre-existing
+debt. Record those as baseline context, not closure items. If relevance is
+unclear, decide from the approved user outcome; ask only when the answer would
+materially change product behavior.
+
+Only these may block execution:
+
+- missing credentials, access, or a real endpoint/contract;
+- destructive production-data operations or irreversible external actions;
+- auth behavior, RLS semantics, secrets, payments, destructive data mutation,
+  or an unconfirmed deployment target where project rules require approval;
+- a genuine product decision with materially different valid outcomes.
+
+Ask one precise question immediately when blocked. Effort, context length, an
+uncertain implementation approach, or a failing test are not blockers.
+Your turn ends in one of two shapes: the Phase 4 report after completion-judge PASS, or a single precise question on a real blocker. It does not end with "should I continue?", with a summary of the remaining items, with "I'll pick this up next", or with a partial ladder run. Before ending your turn, read your last paragraph: if it describes work you could do now, do it.
+
+## Phase 0 — Recover scope and establish a baseline
+
+1. Read the full plan, including appendices, exclusions, acceptance criteria,
+   and checked items. If no path is supplied, inspect `.cursor/plans/`, the
+   conversation, and recent plan/report files.
+2. Read the prior completion report or chat summary. Search plan and report
+   text for parked work:
+
+   ```bash
+   rg -n -i \
+     'out of scope|follow[- ]?up|nice to have|later|defer(red)?|skip(ped)?|not in this (pr|pass|phase)|left as|TODO|FIXME|won.t do|optional|future work|beyond scope' \
+     <plan-and-report-paths>
+   ```
+
+3. Inspect `git status`, staged and unstaged diffs, and recent commits. Do not
+   overwrite unrelated user work.
+4. Discover exact verification commands from manifests, CI, `AGENTS.md`,
+   `CLAUDE.md`, README files, Makefiles, or equivalent project tooling.
+5. Run the cheapest representative baseline checks before editing when
+   practical. Record pre-existing failures so later results distinguish
+   regressions from baseline debt.
+6. Convert every closure item into an observable acceptance statement: what a
+   user can do, which contract holds, or which test/command proves it.
+
+Announce: **"Closing N items (P planned + D previously parked + G discovered).
+No plan-related deferrals this run."**
+
+## Phase 1 — Externalize the work
+
+Create `.cursor/complete-everything-state.md` as the durable source of truth:
+
+```md
+# Complete Everything: <approved outcome>
+Plan: <path or conversation>
+Baseline: <commands and pre-existing failures>
+Verify: typecheck=`...` lint=`...` test=`...` build=`...` e2e=`...|none`
+
+## Plan items
+- [ ] <item> — acceptance: <observable proof>
+
+## Previously parked — now in scope
+- [ ] <item> — parked as: "<short quote>" — acceptance: <proof>
+
+## Discovered while closing
+- [ ] <item> — source: <test/diff/runtime/review> — acceptance: <proof>
+
+## Human gates
+- [ ] <item> — blocked by: <real blocker> — question: <one precise ask>
+
+## Verification ladder
+- [ ] changed-file diagnostics
+- [ ] typecheck
+- [ ] lint
+- [ ] focused unit/integration tests
+- [ ] related/full tests
+- [ ] API contract verification (if applicable)
+- [ ] build (if configured)
+- [ ] real user-flow smoke (if applicable)
+- [ ] independent completion judge
+
+## Evidence and decisions
+- <timestamp or milestone>: <command/result or decision/rationale>
+```
+
+A ladder rung the repo cannot run (no typecheck, no build, no UI) is written
+`- [-] <rung> — n/a: <evidence it is absent>` when the Phase 0 baseline shows
+it is missing. `[-]` means not applicable, never passed. The Stop hook skips a
+`[-]` line only when it carries an `n/a:` reason, and completion-judge checks
+that reason.
+
+Mirror the milestones in the runtime's native task list when available. The
+state file wins after context compaction: re-read it before each milestone and
+before any completion claim.
+
+### Arm host-level continuation
+
+Instruction text alone cannot reliably prevent premature stops. Use the host's
+continuation mechanism in addition to the state file:
+
+- **Cursor and Claude Code:** the packaged Stop hook reads
+  `.cursor/complete-everything-state.md` and continues the turn only while
+  actionable unchecked items remain. It ignores completed states, errored or
+  aborted turns, human-gate-only states, items marked
+  `blocked by: <who or what>`, and a state file untouched for 24 hours. Each
+  conversation gets three follow-ups while none of the items it saw closes;
+  closing one restores them, and another agent's edits neither spend nor
+  reset them. The counter lives outside the repo, in
+  `~/.cache/kenji/completion-gate/`. Claude Code labels each block
+  "Stop hook error occurred" — that is the gate working, not a failure. If
+  hooks are disabled, continue manually from the state file; do not lower
+  the completion contract.
+- **Claude Code 2.1.139+:** start the run with:
+
+  ```text
+  /goal All actionable items in .cursor/complete-everything-state.md are checked, every applicable verification gate has fresh passing evidence after the final edit, and completion-judge returns PASS at the claimed completion level.
+  ```
+
+  `/goal` supplies an independent per-turn evaluator. The state file remains
+  the auditable source of truth. If `/goal` is unavailable or hooks are
+  disabled, continue the same workflow without pretending the evaluator ran.
+
+## Phase 2 — Close every item
+
+Work in small, independently verifiable milestones. For each item:
+
+1. Mark it in progress in the native task list; keep it unchecked in the state
+   file until its acceptance evidence exists.
+2. Read the relevant implementation and tests. Preserve existing public
+   behavior unless the approved plan explicitly changes it.
+3. Implement the root-cause fix with surgical edits — change the lines the fix needs, not whole files. Do not delete features, narrow behavior, weaken tests, blanket-update snapshots, or silence errors to get green.
+4. Add or update tests whenever behavior, contracts, or error handling change.
+5. Run the cheapest focused validation. Repair failures before moving on.
+6. Append newly discovered connected work to **Discovered while closing** and
+   close it in this run. Never hide it in the final report as a follow-up.
+7. Tick the item only after recording its evidence.
+
+If the approach is uncertain, use the `research` skill, record the decision and
+source, then implement. Delegate to a subagent only a sizeable, independent track — a read-only inventory, a test run whose output you do not need in your context, or parallel verification — never a handful of tool calls. Brief it once with everything it needs, launch independent subagents in one message, and keep the closure set and integration in the main agent.
+
+### Required routing by change signal
+
+- **Searchable migration or rename remains:** use `burndown-full` for the
+  mechanical sweep, then return here for behavioral verification.
+- **Behavior changed or coverage is missing:** use `test-unit`; tests must be
+  capable of failing for the regression.
+- **API clients, routes, RPCs, webhooks, request/response types changed:** use
+  `audit-fe-api`; fix every mismatch in the affected contract.
+- **4xx/5xx, validation, serialization, CORS, or FE/BE drift appears:** use
+  `debug-fe-be-integration` and verify both sides.
+- **UI flow changed:** use `test-playwright` with
+  `protocol-browser-anti-stall`; drive the real touched flow and fix failures.
+- **Fetching, polling, realtime, lists, images, or heavy rendering changed:**
+  measure the affected path and use `audit-performance` when evidence shows a
+  performance gap. Optimize the root cause; do not add speculative complexity.
+- **Schema, RPC, edge function, RLS, bucket, secret, or cron changed:** obey
+  `full-stack-ship-discipline`; keep local migration/config artifacts aligned
+  with the verified target environment and honor protected-surface approvals.
+
+## Phase 3 — Full post-enhancement verification
+
+Completion requires fresh evidence from this run. Execute every applicable step
+in this order:
+
+1. Re-read the state file. Zero closure items may remain unchecked. A human gate
+   means the run is **blocked**, not complete.
+2. Review the full diff against the plan, parked-item inventory, acceptance
+   statements, and repository conventions.
+3. Run diagnostics on changed files and fix introduced issues.
+4. Run the configured whole-project or affected-package typecheck.
+5. Run lint/format checks using the repository's commands.
+6. Run focused unit/integration tests, then the related or full suite required
+   by the blast radius.
+7. Run API/FE-BE/runtime truth checks when those surfaces changed. Verify remote
+   backend objects and client roles when required.
+8. Run the build when configured.
+9. For user-facing changes, drive the real flow in a headed browser or the
+   repository's platform-appropriate E2E harness. Confirm UI, console, network,
+   persistence, and error states.
+10. Re-run any gate invalidated by a later fix.
+11. Invoke the `completion-judge` subagent with the approved outcome, state-file
+    path, relevant diff range, baseline, and fresh command/runtime evidence.
+    - `PASS` permits the closure report at the judge's claimable level.
+    - `CONTINUE` adds every finding to the state file and returns to Phase 2.
+    - `BLOCKED` records the precise human gate; it is not completion.
+
+On failure: diagnose, add the repair to the state file, fix it, and restart from
+the failed gate. Never report "known failure, ship anyway." If a whole-project
+gate failed before the run, fix it when connected to the closure set or when it
+blocks proof; otherwise report the unchanged baseline failure separately
+without mislabeling the plan closure as a fully green repository.
+
+## Phase 4 — Evidence-only closure
+
+Use this structure:
+
+```md
+## Complete Everything — report
+
+**Goal:** <approved outcome>
+**Closed:** N planned + D previously parked + G discovered
+**Blocked on you:** none | <real blocker and one precise question>
+
+### Evidence
+- diagnostics: `<tool/command>` → <result>
+- typecheck: `<command>` → <result>
+- lint: `<command>` → <result>
+- tests: `<command>` → <result>
+- API / FE-BE: ran / n/a — <result>
+- performance: measured / n/a — <result>
+- build: `<command>` → <result>
+- user flow: `<flow>` → <result>
+- completion judge: `PASS` — claimable level: <level>
+
+### Baseline unrelated failures
+- none | <failure that existed before and why it is outside the closure set>
+
+### Intentionally unchanged
+- none | <explicit user non-goal or protected human gate>
+```
+
+Forbidden success language: "left as follow-up", "out of scope for now", "can
+be done later", "should work", "probably fine", or any claim unsupported by
+fresh evidence.
+
+Leave `.cursor/complete-everything-state.md` fully ticked as the audit trail
+unless the user asks to remove it.
+
+## Relationship to other workflows
+
+- `complete-everything` closes plan intent, parked work, behavior, and evidence.
+- `housekeep-backlog` inventories parked work across the repo into
+  `BACKLOG.md`; this skill executes one approved plan from that register
+  (or from a named plan file).
+- `burndown-full` proves repo-wide mechanical pattern coverage.
+- `workflow-quality-gate` assesses release readiness; it does not replace this
+  implementation loop.
+- `verification-before-completion` defines the evidence levels and mandatory
+  final gate used by this workflow.
+- `completion-judge` is the independent read-only verdict; the implementation
+  agent cannot self-certify a wide closure run.
+- `workflow-git-commit` may create the scoped commit only when requested;
+  it never pushes. `workflow-pr` may push/open/manage only when requested.
+  Whole dirty-tree preparation is `workflow-release-prep`, which stops
+  before merge.

package/skills/data-pipeline/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: data-pipeline
+description: >
+  Wire ETL, ingestion, cron, and queue jobs with idempotency, atomic writes,
+  data contracts, and dead-letters. Use for "build a pipeline", "sync X into
+  Y", "cron double-counts", "dedupe", "backfill", or "the numbers are wrong
+  after a retry".
+license: MIT
+---
+
+# Data Pipeline Correctness
+
+**Degree of freedom: MIXED.** Layering and window design `[HIGH freedom]`;
+idempotency, atomic writes, overlap lock, and the DoD `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — job, retry path, write targets, schedule
+2. **Interpret** — at-least-once vs atomic vs contract vs overlap
+3. **Classify** — upsert / window-recompute / quarantine / lock / watermark
+4. **Severity** — retry double-count outranks a missing metric
+
+## Worked example
+
+> **Observe:** nightly `refresh_order_stats` does `count = count + 1`; cron overlapped twice; dashboard totals jumped.
+> **Interpret:** at-least-once delivery + non-idempotent delta.
+> **Classify:** recompute-and-replace the day window; `pg_try_advisory_lock`; persist a watermark.
+> **Verify:** re-run the same window → identical rows; overlap skipped; `pipeline_runs` recorded.
+
+## Self-critique before reporting
+
+- **Idempotent** — same-window re-run proven identical, not assumed
+- **Atomic** — mid-fail leaves no half-written batch
+- **Locked** — the scheduled job has an overlap guard
+- **Right owner** — schema/constraints → `audit-db-schema`; post-hoc corruption hunt → `plan-data-integrity`
+
+> Pipelines fail silently: a retry double-counts, a partial write corrupts a table, a schema drift poisons a dashboard, and nobody notices until the numbers are wrong. This skill bakes correctness in at build time. It complements post-hoc data-integrity audit skills (which *detect* these after the fact) and the Supabase plugin (DB/Edge Functions/RLS).
+
+## When this fires
+Any job that **moves, transforms, or aggregates** data: ingestion/ETL/ELT, scheduled aggregations, edge-function workers, `pg_cron` jobs, queue consumers, webhook processors, backfills, materialized-view refreshes.
+
+## Non-negotiables (the 5 that prevent silent corruption)  [LOW freedom — run exactly]
+
+1. **Idempotency** — running the same job twice must not change the result. Retries, at-least-once queues, and overlapping cron fires are guaranteed, not hypothetical.
+ - Use `INSERT ... ON CONFLICT (natural_key) DO UPDATE` (upsert), not blind `INSERT`.
+ - Derive a deterministic dedup key from the source event, not `now()` or a random id.
+ - For aggregates: recompute-and-replace a window, or use idempotent deltas — never `count = count + 1` on a path that can retry.
+
+2. **Atomicity** — a job either fully applies or not at all. No half-written batches.
+ - Wrap multi-row writes in a transaction; stage to a temp/raw table then swap.
+ - A function that writes to 3 tables must not leave 1 of them updated on failure.
+
+3. **Data contracts** — validate shape at the boundary before trusting input.
+ - Parse/validate (zod / pydantic / JSON schema) at ingestion; reject or quarantine bad rows, don't `any`-cast them downstream.
+ - Pin expected columns/types; fail loudly on schema drift instead of silently coercing.
+
+4. **Explicit delivery semantics** — know and document whether each stage is at-least-once, at-most-once, or exactly-once, and make the consumer match. Most queues/cron are at-least-once → consumers MUST be idempotent (see #1).
+
+5. **Observability** — a pipeline you can't see is a pipeline that's already broken.
+ - Emit per-run: rows in / out / rejected, duration, watermark, status. Persist it (a `pipeline_runs` table or logs), don't just `console.log`.
+ - Alert on: zero rows when rows expected, reject-rate spike, run overran, run skipped.
+
+## Staging architecture (default to 4 layers)  [HIGH freedom]
+```
+Raw → land source data unchanged, append-only, with ingested_at + source id
+Staged → cleaned, typed, validated, deduped (1 row per natural key)
+Curated → business entities, joined/enriched, the query surface
+Aggregated→ rollups / metrics / materialized views for dashboards
+```
+Each layer is rebuildable from the one before it. Never transform-in-place on raw; never let dashboards read raw.
+
+## Backfills  [HIGH freedom]
+- Make jobs **parameterized by window** (`--from`, `--to` / date partition), not "everything since forever". The same code runs the nightly slice and the historical backfill.
+- Backfills must be idempotent and chunked (partition by day/range) so a failure resumes, not restarts.
+- Use a **watermark** (last-processed timestamp/id, persisted) for incremental runs; never re-scan the whole source each run.
+
+## Failure handling  [HIGH freedom]
+- **Dead-letter** bad/failed records to a quarantine table or DLQ with the error + payload; keep the main run moving. Silent `try/catch {}` that swallows errors is banned.
+- Retries: bounded, with backoff; only retry transient errors (network/timeout), never validation failures (they'll just fail again).
+- Make partial progress resumable via the watermark, not a full redo.
+
+## Anti-patterns (reject on sight)  [HIGH freedom]
+- **Monolithic DAG / mega-function** doing fetch+transform+load+notify in one untestable blob → split into testable stages.
+- `count = count + 1` / `balance = balance + x` on a retryable path → not idempotent.
+- `SELECT *` into a typed model without a contract → schema drift time bomb.
+- N+1 writes in a loop instead of a batched upsert → slow + non-atomic.
+- Cron with no overlap guard (job B starts before job A finishes) → double processing. Add a lock / `pg_try_advisory_lock` / "skip if running".
+- Reading dashboards straight off raw ingestion tables.
+
+## Supabase / edge-function specifics  [LOW freedom — run exactly]
+- `pg_cron` is at-least-once and can overlap under load → make the SQL/function idempotent and guard with an advisory lock.
+- Edge-function workers triggered by table inserts: dedupe on the row's natural key; the trigger can fire more than once.
+- Heavy aggregation belongs in SQL / materialized views (refresh on a schedule), not in a function looping row-by-row.
+- Deploy + verify the function, cron, and any new table/policy on the remote in the same turn — see `full-stack-ship-discipline`.
+
+## Definition of done  [LOW freedom — do not skip]
+- [ ] Re-running the job produces the identical result (idempotency proven, not assumed).
+- [ ] A mid-run failure leaves no half-applied state (atomicity).
+- [ ] Bad input is rejected/quarantined with a contract, not silently coerced.
+- [ ] Incremental runs use a persisted watermark; backfill is windowed + chunked.
+- [ ] Per-run metrics are emitted and an alert exists for zero-rows / reject-spike / overrun.
+- [ ] No overlap hazard on scheduled jobs (lock or skip-if-running).
+
+## Composes with
+- `audit-db-schema` — the schema/constraints the pipeline writes into.
+- `supabase-postgres-best-practices` — Postgres-level query/index tuning (official Supabase plugin).
+- `full-stack-ship-discipline` — deploy + verify functions/cron/policies on the remote.
+- `workflow-spec-tdd` — spec the contract + test idempotency/edge cases before coding.
+- Project-local data-integrity audit skills — post-hoc detection of the failures this prevents.