coding-os 0.3.2__py3-none-any.whl

core/skills/supabase/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: supabase
+tier: stack
+domain: [backend, data]
+description: Build on Supabase correctly — Row Level Security, auth, realtime, storage, edge functions, and the Postgres underneath. Use when wiring a Supabase client, writing or reviewing RLS policies, debugging "anyone can read everyone's rows", setting up auth, adding realtime subscriptions, handling file storage, or deciding what belongs in an edge function vs the database. The #1 footgun — a table with RLS disabled is fully public — gets first-class coverage. Triggers — "Supabase", "RLS", "row level security", "policy", "anon key", "realtime subscription", "edge function", "supabase auth". Pairs with sql-authoring (the queries), db-design (the schema), auth-patterns (the token model), security-web (exposure review).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# Supabase
+
+Supabase is Postgres with a public API in front of it. That inversion is the whole risk model: the `anon` key ships to the browser, so **the database — not the application — is the security boundary**. Row Level Security is not optional hardening; it is the only thing standing between a user and everyone else's rows.
+
+> Scan a migration for tables left without RLS:
+> `python3 scripts/check_rls.py supabase/migrations/*.sql`
+
+## RLS is the security boundary (enable it on every table)
+
+```sql
+-- Wrong — table is reachable via the anon key with NO policy = fully public
+create table notes (id uuid primary key, user_id uuid, body text);
+
+-- Correct — enable RLS, then policies grant the minimum
+create table notes (id uuid primary key, user_id uuid references auth.users, body text);
+alter table notes enable row level security;
+
+create policy "owner reads own notes" on notes
+  for select using (auth.uid() = user_id);
+create policy "owner writes own notes" on notes
+  for insert with check (auth.uid() = user_id);
+```
+
+A table created without `enable row level security` is readable and writable by
+anyone holding the `anon` key — which is every visitor. Enable RLS on **every**
+table in a public schema, then add policies. `using` filters which rows are
+visible/updatable; `with check` validates rows being inserted/updated. Detail →
+[references/rls-and-auth.md](references/rls-and-auth.md).
+
+## The two keys — never confuse them
+
+```
+anon key        → ships to the browser. RLS applies. Safe to expose IF RLS is on.
+service_role key → bypasses RLS entirely. SERVER ONLY. Never in client code, never in git.
+```
+
+```javascript
+// Wrong — service_role in the browser = total database access for every visitor
+const supabase = createClient(url, SERVICE_ROLE_KEY);   // in frontend code
+
+// Correct — anon key client-side (RLS enforced); service_role only in a server/edge function
+const supabase = createClient(url, ANON_KEY);
+```
+
+The `service_role` key bypasses all RLS — leaking it is a full database breach.
+It belongs only in server-side code (edge functions, your backend) and a secret
+store, never bundled to the client.
+
+## Auth — `auth.uid()` is your policy anchor
+
+Supabase Auth issues a JWT; inside RLS, `auth.uid()` returns the authenticated
+user's id and `auth.jwt()` exposes claims. Policies key off these. The token
+model (refresh rotation, session vs JWT, storage on mobile) is owned by
+[auth-patterns](../auth-patterns/SKILL.md) — Supabase is one provider of that
+model, not a replacement for understanding it.
+
+## Realtime + storage — RLS still rules
+
+```javascript
+supabase.channel("notes")
+  .on("postgres_changes", { event: "*", schema: "public", table: "notes" }, handler)
+  .subscribe();
+```
+
+Realtime broadcasts only rows the subscriber's RLS lets them see — but you must
+enable the table for realtime and keep RLS correct, or you leak via the socket.
+Storage buckets have their own RLS-style policies; a "public" bucket is public to
+the internet — default to private + signed URLs. Detail →
+[references/realtime-and-storage.md](references/realtime-and-storage.md).
+
+## Edge functions vs database
+
+| Put it in the database | Put it in an edge function |
+|---|---|
+| row-level rules (RLS), constraints | calling a third-party API (Stripe, email) |
+| triggers, computed columns | webhooks, server-only secrets |
+| anything RLS can express | orchestration the client shouldn't see |
+
+Push authorization into RLS and constraints (the database enforces them for every
+client); use edge functions for server-only work and secrets. Don't reimplement in
+an edge function what a policy already guarantees.
+
+## Anti-patterns (reject on sight)
+
+- A table in a public schema with RLS disabled → fully public; enable it.
+- `service_role` key anywhere client-side or in git → full breach.
+- RLS enabled but **no policy** → table is locked to everyone (also a bug — add policies).
+- Trusting client-sent `user_id` in a policy instead of `auth.uid()` → spoofable.
+- A "public" storage bucket for user uploads → internet-readable; private + signed URLs.
+- Business authorization in the client/edge function that RLS should own → bypassed by a direct API call.
+
+## See also
+
+- [references/rls-and-auth.md](references/rls-and-auth.md) — policies, `auth.uid()`, performance, common policy shapes.
+- [references/realtime-and-storage.md](references/realtime-and-storage.md) — channels, storage policies, signed URLs.
+- [assets/supabase-checklist.md](assets/supabase-checklist.md) — the ship gate.
+- [sql-authoring](../sql-authoring/SKILL.md) · [db-design](../db-design/SKILL.md) · [auth-patterns](../auth-patterns/SKILL.md) · [security-web](../security-web/SKILL.md).

core/skills/supabase/assets/supabase-checklist.md

@@ -0,0 +1,26 @@
+<!-- domain:BACKEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# Supabase Ship Checklist
+
+Run before exposing a Supabase project.
+
+## Security (the boundary is the database)
+- [ ] Every table in a public schema has `enable row level security`.
+- [ ] `python3 scripts/check_rls.py supabase/migrations/*.sql` → `clean`.
+- [ ] Every RLS table has policies (enabled-but-empty = locked, also a bug).
+- [ ] Policies use `auth.uid()`/`auth.jwt()`, never client-supplied identity.
+- [ ] `update` policies have BOTH `using` and `with check`.
+- [ ] `service_role` key is server-only — not in client code, not in git, in a secret store.
+- [ ] Storage buckets for user content are private + signed URLs (not public).
+
+## Performance
+- [ ] Policy filter columns (`user_id`, `team_id`) are indexed.
+- [ ] `auth.uid()` wrapped in `(select auth.uid())` in hot-table policies.
+
+## Correctness
+- [ ] Realtime tables added to the publication; channels removed on unmount.
+- [ ] TypeScript types regenerated after the latest migration (`supabase gen types`).
+- [ ] Authorization lives in RLS/constraints, not only in client/edge code.
+
+## Verify
+- [ ] Tested as an anon user: can read/write only own rows.
+- [ ] `make skills-check-versions` — Supabase CLI pin current.

core/skills/supabase/references/realtime-and-storage.md

@@ -0,0 +1,55 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# Supabase Realtime & Storage
+
+> P: Stream row changes and serve files without leaking past RLS.
+> R: Adding a realtime subscription or file upload/download.
+> S: Table policies themselves — see [rls-and-auth.md](rls-and-auth.md).
+> N: [SKILL.md](../SKILL.md), [supabase-checklist.md](../assets/supabase-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Realtime — RLS still filters the stream
+
+```javascript
+const channel = supabase
+  .channel("room:1")
+  .on("postgres_changes",
+      { event: "INSERT", schema: "public", table: "messages", filter: "room_id=eq.1" },
+      (payload) => render(payload.new))
+  .subscribe();
+// later: supabase.removeChannel(channel)
+```
+
+Realtime delivers a change only if the subscriber's RLS would let them `select`
+that row — so correct policies protect the socket too. You must enable the table
+for the realtime publication (`alter publication supabase_realtime add table
+messages`). Always `removeChannel` on unmount or you leak subscriptions.
+
+## Storage — buckets are RLS for files
+
+```sql
+-- private bucket + a policy: users read only their own folder
+create policy "own folder read" on storage.objects for select
+  using (bucket_id = 'avatars' and (storage.foldername(name))[1] = auth.uid()::text);
+```
+
+A bucket marked **public** is readable by anyone with the URL — fine for static
+assets, a breach for user uploads. Default to **private** buckets and hand out
+**signed URLs** with a short expiry:
+
+```javascript
+const { data } = await supabase.storage.from("avatars").createSignedUrl(path, 60);
+```
+
+Never build a public URL for private content. Validate upload size/MIME
+server-side (an edge function or a storage policy) — the client check is advisory.
+
+## Generated types — keep the client honest
+
+```bash
+supabase gen types typescript --project-id <id> > types/database.ts
+```
+
+Generate TypeScript types from the live schema so the client's row shapes can't
+drift from the database (the api-contract-discipline rule, applied to Supabase).
+Re-generate after every migration; a stale type is a silent `undefined` at runtime.

core/skills/supabase/references/rls-and-auth.md

@@ -0,0 +1,65 @@
+<!-- domain:DB | layer:reference | ssot:true | updated:2026-06-04 -->
+# Supabase RLS & Auth — Policies That Hold
+
+> P: Write Row Level Security policies that enforce ownership correctly and stay fast.
+> R: Adding a table, a policy, or debugging "users see each other's data".
+> S: The token/session model itself — that's [auth-patterns](../../auth-patterns/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [realtime-and-storage.md](realtime-and-storage.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## The four policy verbs
+
+```sql
+alter table notes enable row level security;
+
+create policy "read own"   on notes for select using (auth.uid() = user_id);
+create policy "insert own" on notes for insert with check (auth.uid() = user_id);
+create policy "update own" on notes for update using (auth.uid() = user_id) with check (auth.uid() = user_id);
+create policy "delete own" on notes for delete using (auth.uid() = user_id);
+```
+
+`using` decides which existing rows a statement can see/touch; `with check`
+validates the new row values on insert/update. `update` needs **both** — `using`
+(can I touch this row?) and `with check` (is the result still mine?), or a user
+could move a row to another owner.
+
+## Always `auth.uid()`, never client input
+
+```sql
+-- Wrong — trusts a column the client controls; spoofable
+create policy x on notes for select using (user_id = current_setting('request.user_id'));
+
+-- Correct — auth.uid() comes from the verified JWT, not the request body
+create policy x on notes for select using (auth.uid() = user_id);
+```
+
+`auth.uid()` derives from the signed JWT — the client cannot forge it.
+`auth.jwt() ->> 'role'` exposes custom claims for role-based policies.
+
+## Performance — RLS runs per row
+
+A policy is a `WHERE` clause added to every query. Two rules keep it fast:
+
+- **Index the policy column** (`user_id`) — without an index, every query is a
+  seq scan filtered by the policy.
+- **Wrap `auth.uid()` in a subquery** so Postgres evaluates it once, not per row:
+  `using ((select auth.uid()) = user_id)`. This is the single biggest RLS perf win
+  on large tables.
+
+## Common shapes
+
+| Need | Policy |
+|---|---|
+| owner-only | `auth.uid() = user_id` |
+| team membership | `auth.uid() in (select user_id from team_members where team_id = notes.team_id)` |
+| public read, owner write | select `using (true)`; insert/update `with check (auth.uid() = user_id)` |
+| role-gated | `(auth.jwt() ->> 'role') = 'admin'` |
+| soft-delete hidden | `using (deleted_at is null and auth.uid() = user_id)` |
+
+## RLS enabled but no policy = locked, not open
+
+Enabling RLS with **zero** policies denies all access (deny-by-default). That's
+safe but usually a bug — you forgot the policies. `check_rls.py` catches the
+opposite (RLS never enabled); for "enabled but empty" the symptom is "nobody can
+read anything" — add the policies.

core/skills/supabase/scripts/check_rls.py

@@ -0,0 +1,88 @@
+"""Flag Postgres/Supabase tables created without Row Level Security enabled.
+
+PURPOSE:      A table in a public schema without RLS is reachable by the anon
+              key = fully public. This scans migration SQL and lists every
+              CREATE TABLE that has no matching ENABLE ROW LEVEL SECURITY.
+INPUT:        one or more .sql file paths (migrations). [--schema public]
+              only flag tables in this schema (default public; "" = all). [--json]
+OUTPUT:       Findings on stderr; "clean"/"N table(s) without RLS" on stdout.
+              Exit 0 clean, 1 if any unguarded table, 2 usage.
+DEPENDENCIES: stdlib only. Static SQL scan — no database needed.
+NOTES:        Heuristic regex parse (not a full SQL grammar); a clean pass is
+              necessary not sufficient. Pure scan() is unit-testable.
+              Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# create table [if not exists] [schema.]name   — capture optional schema + name
+_CREATE = re.compile(
+    r"create\s+table\s+(?:if\s+not\s+exists\s+)?"
+    r"(?:\"?(?P<schema>\w+)\"?\.)?\"?(?P<name>\w+)\"?",
+    re.IGNORECASE,
+)
+_ENABLE = re.compile(
+    r"alter\s+table\s+(?:if\s+exists\s+)?"
+    r"(?:\"?\w+\"?\.)?\"?(?P<name>\w+)\"?\s+enable\s+row\s+level\s+security",
+    re.IGNORECASE,
+)
+
+
+def _strip_sql_comments(sql: str) -> str:
+    sql = re.sub(r"/\*.*?\*/", "", sql, flags=re.DOTALL)
+    sql = re.sub(r"--[^\n]*", "", sql)
+    return sql
+
+
+def scan(sql: str, schema: str = "public") -> list[str]:
+    """Return table names created (in `schema`, or any if schema=="") without RLS."""
+    body = _strip_sql_comments(sql)
+    created: list[tuple[str, str]] = [
+        (m.group("schema") or "public", m.group("name")) for m in _CREATE.finditer(body)
+    ]
+    rls_enabled = {m.group("name").lower() for m in _ENABLE.finditer(body)}
+    missing: list[str] = []
+    for sch, name in created:
+        if schema and sch.lower() != schema.lower():
+            continue
+        if name.lower() not in rls_enabled:
+            missing.append(name)
+    return missing
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--schema", default="public")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    combined = ""
+    for path in args.files:
+        try:
+            combined += "\n" + Path(path).read_text(encoding="utf-8")
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    missing = scan(combined, args.schema)
+    for name in missing:
+        print(
+            f"  ✗ table '{name}': no ENABLE ROW LEVEL SECURITY — public via anon key",
+            file=sys.stderr,
+        )
+    if args.as_json:
+        print(json.dumps({"missing_rls": missing, "count": len(missing)}))
+    else:
+        print("clean" if not missing else f"{len(missing)} table(s) without RLS")
+    return 1 if missing else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/supabase/versions.json

@@ -0,0 +1,9 @@
+{
+  "supabase-cli": {
+    "ecosystem": "npm",
+    "package": "supabase",
+    "version": "2.105.0",
+    "source": "https://www.npmjs.com/package/supabase",
+    "checked": "2026-06-04"
+  }
+}

core/skills/task-driver/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: task-driver
+tier: workflow
+domain: [governance]
+description: Use when creating, modifying, or transitioning Scrumban tasks in docs/tasks/. Triggers on "create a task", "move task", "start task X", "what's blocked", "daily standup", "retro", or any edit to docs/tasks/TASK-*.md.
+phase: L
+last_reviewed: "2026-05-11"
+
+---
+
+# Task Driver Skill — Scrumban
+
+You are in task-management mode. Apply these rules mechanically.
+
+## Mandatory intake loop (run for every implementation request)
+
+1. **Reconcile existing tasks first.** Check whether the user request maps to:
+   - an explicit task id (`TASK-###`), or
+   - an existing open/in_progress/testing task in the same area.
+2. **If a matching task exists:** use it (do not create a duplicate).
+3. **If no matching task exists and work is non-trivial: create it fully
+   formed in ONE call.** When you already know the scope (you almost always
+   do — you just analyzed the work), the SAME `cos_task_create` call carries
+   `outcome=`, `acceptance=`, `read_first=` **and** `ready=True` (`--ready`).
+   Creating a skeleton "to fill in later" is a defect, not a shortcut: the
+   create envelope echoes `data.dor` — a non-empty `gaps` list or
+   `ready: false` you did not intend is YOUR bug; fix it before proceeding.
+   CLI flag trap: `--read-first` / `--labels` are **comma-separated single
+   flags** — repeating the flag silently keeps only the last value.
+4. **Before `in_progress`: the task body gate must already hold.** Outcome
+   (one measurable sentence), Read First (minimal links), Acceptance (G/W/T).
+   Step 3 done right makes this a no-op; the icebox→in_progress gate blocks
+   placeholders regardless.
+5. **Then execute through statuses:** `in_progress` → `testing` → `complete`.
+6. **If blocked at any time:** move to `blocked` and record the concrete blocker.
+
+## Golden rules
+
+1. **Prefer MCP tools over hand-written YAML.** Always call `cos_task_create`
+   instead of writing the frontmatter yourself. Always call `cos_task_move`
+   to transition — not an `Edit` on the MD file.
+
+2. **Rule 15 — tasks are pointers, not specs.** Never inline content from
+   `docs/**`, `src/core/rules/**`, `CLAUDE.md`, or `AGENTS.md`. If you find
+   yourself writing >800 tokens of task body: stop, find the doc to link,
+   or create a new doc (Documenter role) and link to it.
+
+3. **Acceptance = Definition of Done.** G/W/T are the tests. When all pass,
+   task is Done — not "perfect", Done. Scope creep ⇒ create a new task via
+   `cos_task_create(kind="bug"|"chore"|...)`.
+
+4. **One Outcome sentence — measurable, concrete.** Bad: "improve auth".
+   Good: "users log in with email+OTP, P95 <500ms, on iOS+Android+web".
+
+5. **WIP=1 per session by default.** The `in_progress` cap is counted per
+   `agent_session` (`workflow_policy.per_session_wip`) — concurrent sessions
+   don't block each other, but YOUR session still does one task at a time.
+   Need a second `in_progress` in the same session? Ask first. Never
+   silently `COS_WIP_OVERRIDE=1`.
+6. **`in_progress → complete` is blocked.** Route through `testing` so the
+   verification matrix runs (`workflow_policy.block_in_progress_to_complete`).
+   `force` is the only override and is audited.
+
+## The four axes (memorize)
+
+| Axis | Field | Examples |
+|---|---|---|
+| Domain | `swimlane` | `graph_os`, `backend`, `vpn-core` (from scrumban-config) |
+| Type | `kind` | `feature`, `bug`, `chore`, `spike`, `docs`, `refactor`, `test`, `security` |
+| Initiative | `epic` | `phase-l`, `mvp`, `oncall-q2` |
+| Tags | `labels` | `indexing`, `perf`, `experimental` (must NOT contain kind values) |
+
+## Bug found mid-session
+
+Create a task immediately with `cos_task_create(kind="bug", priority="P0"|"P1")`
+then continue your current work. Don't interrupt the current task to fix
+the bug unless the user asks.
+
+## Required status choreography
+
+0. **Mark ready** — a task needs the `ready` label before it can leave
+   `icebox`: `cos task-ready TASK-NNN` (or create with `--ready` / `ready=True`).
+   `icebox → in_progress` is BLOCKED otherwise (the `emergency` lane is exempt).
+1. `cos task-start TASK-NNN` before substantive edits, then **commit each logical unit autonomously as you implement** (`git commit <paths>` — never wait to be asked; [git-workflow.md](../../rules/git-workflow.md) § When to commit).
+2. If dependency/policy/tooling blocks progress:
+   `cos_task_move(task_id=..., to="blocked")` and log the blocker.
+3. After implementation: `cos_task_move(task_id=..., to="testing")` —
+   move to `testing` FIRST, then run verification. `in_progress → complete`
+   is BLOCKED, so don't run tests while still `in_progress`.
+4. Run verification commands tied to changed files.
+5. If green: append one short work-log note (token-lean), commit, then `cos task-done` (push to `main` at close).
+6. If red: keep in `testing` or move back to `in_progress` with a short reason.
+
+## Work Log (append-only, 120 char cap)
+
+- **Claude:** `capture-work-log.sh` appends automatically on Write/Edit.
+- **Codex:** MUST call `cos_work_log_append(task_id, summary)` explicitly
+  after any significant edit — no PostToolUse hook delivers for Codex.
+- NEVER rewrite or reformat existing Work Log lines.
+- Keep entries short and factual (what changed, result, blocker if any).
+
+## Session start ritual
+
+1. Run `cos daily` → see yesterday's progress + today's candidates + blockers.
+2. Reconcile the new user request against existing tasks (`cos_task_board` / `cos task-show`).
+3. If no suitable task exists: create one, fill Outcome/Read First/Acceptance.
+4. `cos task-start TASK-NNN` → enforces WIP + sets `.task-current`.
+4. Do work — **commit each logical unit autonomously**. `capture-work-log` auto-records. Status visible via `cos_task_board`.
+5. Move to `testing`, run checks, then `cos task-done TASK-NNN` when G/W/T pass.
+
+## MCP outage fallback (R-L-28)
+
+If `cos_task_move` returns `fail("transient", retryable=True)`:
+1. Wait 2s, retry once.
+2. On second failure: fall back to `Edit` on the task MD file directly.
+   The `validate-task-frontmatter.sh` hook still enforces enum + cycle rules.
+3. On next reachable MCP, re-sync via `cos task-sync`.
+
+## Surface stale tasks to the human
+
+If a task has been in `in_progress` for >3 days OR >2× its `appetite`,
+surface this observation to the user — don't silently assume progress.
+Daily/retro outputs already flag these.
+
+## Daily streak ≠ shame
+
+If `cos daily` shows a broken streak: DO NOT pressure the user. This is
+observability only. ADHD-friendly default is silence; the user asks if
+they care.
+
+## WIP enforcement (hard caps)
+
+| Status | Cap | What happens if exceeded |
+|---|---|---|
+| `in_progress` | 1 **per agent_session** (configurable via `scrumban-config.yaml::wip_limits.in_progress`) | `cos task-start` refuses for THIS session; other sessions are unaffected (`per_session_wip`). Idle in_progress tasks of dead sessions are freed by `cos task-reclaim` |
+| `testing` | 3 (board-global) | Warns; doesn't block (testing can stack while verification runs) |
+| `emergency` | 2 (board-global) | Hard block — emergency lane only for SEV-1/2 incidents |
+
+Override is by the user via `--wip-override` flag, never by the agent silently. Document why the override is justified in the work log of the over-cap task.
+
+## Daily standup template (paste-ready)
+
+When the user says "daily" / "standup" / "what's the state":
+
+```
+## Daily — YYYY-MM-DD
+
+### Yesterday
+- [TASK-NNN] {title} → moved to {status}, {one-line outcome}
+- (repeat for each task touched yesterday)
+
+### Today (candidates)
+- [TASK-NNN] {title} ({swimlane}/{kind}, priority {P})
+- (top 3 from `cos task-pick`)
+
+### Blocked
+- [TASK-NNN] {title} — blocker: {one-line reason}, since {date}
+- (action: {who/what unblocks})
+
+### WIP check
+- in_progress: {n}/cap{cap}
+- testing: {n}/cap{cap}
+- violations: {none | list}
+
+### Notable
+- {anything stale > 3 days, anything > 2× appetite, anything new from MCP discovery}
+```
+
+Source the data from `cos_task_daily` (canonical) — don't reconstruct from `cos_task_board` if `daily` is available.
+
+## Retro template (paste-ready)
+
+When the user says "retro":
+
+```
+## Retro — YYYY-MM-DD (period: {N days})
+
+### What shipped
+- [TASK-NNN] {title} → complete, {date}
+- (every task moved to complete in the period)
+
+### What broke / blocked
+- [TASK-NNN] {title} — blocked for {days}; root cause: {category}
+- (every task that hit `blocked` or rolled back)
+
+### Patterns (from `cos_failure_pattern_query`)
+- {recurring failure category}: {N occurrences}; suggested mitigation: {action}
+
+### Action items (with owners + due dates)
+- [ ] {description} — @owner — due YYYY-MM-DD
+```
+
+Source from `cos_task_retro` (canonical), which already aggregates the completed/blocked/failure-pattern signals. Add owner + due-date columns by asking the user; the data is human input.
+
+## Blocked-task escalation pattern
+
+A task moved to `blocked` is not a finished state. Escalation ladder:
+
+| Days blocked | Action |
+|---|---|
+| Day 0 | Move to blocked, record blocker, ask the user once. |
+| Day 1-2 | Daily output highlights the blocker. Agent does NOT re-prompt. |
+| Day 3 | Agent surfaces "TASK-NNN has been blocked 3 days — still relevant?" once. |
+| Day 7 | Agent suggests `cos_task_move(to="archived")` with a brief note. |
+| Day 14 | Auto-archive (configurable). The task body still exists, but it's off the active board. |
+
+**Never** silently archive without surfacing to the user first. Lost work is worse than visible blocked work.
+
+## Swimlane routing — discover from config, never hardcode
+
+Swimlanes are **project-specific**, defined ONLY in
+`.coding-os/scrumban-config.yaml` (`swimlanes:`). They differ per stack
+(django: `backend/frontend/ai-service/shared/docs/infra`; nextjs:
+`frontend/api/e2e/design/docs/infra`; the meta-repo:
+`core/thinking_os/graph_os/board_os/adapters/templates/cli/docs/infra`).
+There is **no universal list** — do not memorize or guess one.
+
+**Discover the valid lanes (don't guess):**
+
+- `cos_task_create` with an unknown swimlane fails with `valid: [...]` —
+  that list IS this project's source of truth.
+- `cos board-config` prints the full config (swimlanes + colours).
+
+**Map the work to the closest existing lane by domain concept:**
+server / API / DB → the backend-ish lane · UI / components → the
+frontend-ish lane · `src/core|cli|adapters|templates` in the meta-repo →
+the matching subsystem lane · docs-only → `docs` · CI / deploy / infra →
+`infra` (or `ops`). The lane *names* always come from config, not from a
+fixed table here.
+
+**Need a domain that doesn't exist yet?** Add it to
+`.coding-os/scrumban-config.yaml::swimlanes` (`id` + `label` + `color`).
+Config is re-read live on every call — no restart, and concurrent
+sessions pick it up immediately. Only add a lane when no existing one
+genuinely fits; prefer reuse (anti-overengineering).
+
+Ambiguous? Pick the broadest existing lane (commonly `infra` or `shared`
+when present) — the user can re-route.
+
+## `kind` (task type) — when to pick which
+
+- `feat` — net-new capability. Adds user-visible behavior.
+- `fix` — repair existing broken behavior. Pair with a regression test.
+- `chore` — internal work, no user-visible change (dependency bumps, cleanup).
+- `refactor` — code structure change, no behavior change. Tests must still pass.
+- `docs` — docs-only change. Lint applies; code doesn't.
+- `test` — adds tests to existing code. Often paired with `fix` or `feat`.
+- `spike` — time-boxed research; produces a decision doc, not a feature.
+- `security` — security fix or hardening. Often pairs with private disclosure.
+
+The `kind` choice drives commit message prefix (`feat:`, `fix:`, …) and changelog grouping.
+
+## Composing with other skills
+
+This skill is the entry point for **process**. For **content** of the task, compose with:
+
+- `thinking_os` → for the Cynefin classification recorded in the gate before any code edit on a COMPLICATED+ task.
+- `search` → for "is there already a task for this?" via `cos_task_search` before creating.
+- `graph-explorer` → for blast-radius scoping when the task says "rename X" or "refactor Y".
+- `clean-code` → mandatory secondary on any code-touching task.
+- domain skills (e.g. `python-meta-server`, `nextjs-react`) → primary on the implementation phase.
+
+The order is fixed: **task-driver lifecycle → thinking_os classify → domain skill → clean-code → search/graph as needed → implementation.**
+
+## See also
+
+- [Rule 14 — Tasks are pointers](../../../docs/governance/critical-rules.md#rule-14--tasks-are-pointers-not-specs).
+- [Rule 18 — Task reconciliation mandatory](../../../docs/governance/critical-rules.md#rule-18--task-reconciliation-is-mandatory-before-implementation).
+- [docs/governance/task-lifecycle.md](../../../docs/governance/task-lifecycle.md) — canonical lifecycle spec.
+- [thinking_os](../thinking_os/SKILL.md) — Complexity Gate before any code change.
+- [search](../search/SKILL.md) — `cos_task_search` for reconciliation.
+- [src/scripts/task-lint.sh](src/scripts/task-lint.sh) — lint TASK-*.md files (frontmatter + sections + Rule 14 size cap).