coding-os 0.3.2__py3-none-any.whl

core/skills/thinking_os/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: thinking_os
+tier: methodology
+domain: [universal]
+description: >
+  Cognitive operating system for structured problem solving. Use when
+  designing features, planning projects, debugging issues, implementing
+  solutions, analyzing requirements, writing specs, breaking down tasks,
+  investigating bugs, architecting systems, reviewing designs, or
+  thinking through any non-trivial problem. Supersedes genius-thinking.
+last_reviewed: "2026-05-11"
+
+---
+
+# Thinking OS — Full Methodology
+
+## Purpose
+
+Complement the always-active Kernel rule (`thinking_os.md`, in your adapter's rules dir) with the complete Zoom cycle, Process Manager, and 10 Thinking Tools. Load this skill when the Complexity Gate returns COMPLICATED or COMPLEX. Source of truth: consumer projects read `docs/workflow/thinking_os-final-edition.md` (copied by `cos init`); the meta-repo canonical lives at `src/core/docs/thinking_os-final-edition.md`.
+
+> Naming note: the skill slug `thinking_os` intentionally keeps the underscore to mirror the `thinking_os` Python subsystem it fronts (other skills use kebab-case). A deliberate, documented exception to the kebab-case convention — not an oversight.
+
+---
+
+## Kernel Decisions (Detailed)
+
+### Complexity Gate (Depth Routing)
+
+Gate classification (Q1 + Q2) is handled by the always-active rule. Use this matrix to determine **depth of analysis**:
+
+```
+                │ 1 dim         │ 2-4 dim         │ 5+ dim
+────────────────┼───────────────┼─────────────────┼─────────────────
+CLEAR           │ Just do it    │ Quick checklist  │ Rare — batch it
+COMPLICATED     │ Single Zoom In│ Light Zoom cycle │ Full Zoom cycle
+COMPLEX         │ Probe + test  │ Zoom + test/dim  │ Full Zoom + prototype
+CHAOTIC         │ Act now       │ Act now, Zoom    │ Act now, Zoom later
+CONFUSION       │ Break it down │ Break it down    │ Separate problems
+```
+
+For COMPLEX problems, activate **Experiment Protocol** before full Zoom In:
+1. HYPOTHESIS: "I believe [X] will work because [Y]."
+2. SMALLEST TEST: cheapest/fastest way to validate
+3. SUCCESS/FAILURE SIGNALS: measurable metrics
+4. TIMEBOX: max time before deciding
+5. LEARN: update Orient and continue
+
+### Zoom Out
+
+**First Zoom Out (before any work):**
+1. IDENTIFY DIMENSIONS — independent aspects of the problem
+2. PRIORITY HEURISTIC — which dimension first?
+   - (a) DEPENDENCY: most dependencies → build first
+   - (b) UNCERTAINTY: most unknowns → validate early
+   - (c) BOTTLENECK: blocks others → unblock it
+   - (d) EVOLUTION (Wardley): novel → deep analysis, commodity → best practice
+   - Priority: (c) > (a) > (b) > (d)
+3. ASSIGN DEPTH per dimension: Deep / Medium / Light
+4. ASSIGN PHASE per dimension: MVP / v1 / v2
+5. FLAG UNKNOWNS — state assumptions explicitly
+
+**Subsequent Zoom Outs:**
+1. Ask Process Manager: "What's done? Pending? Needs revisit?"
+2. Consistency check: cross-dimension outputs compatible?
+3. Cross-dimension insights: patterns to unify? shared components duplicated?
+4. Reframe Trigger check (4 conditions)
+5. Max iteration check (3rd cycle? → deliver with caveats)
+6. Route: highest priority pending dimension → Zoom In
+
+### System Sketch (First Cycle Only)
+
+Before going deep on ANY dimension, draw a rough map of the whole system. For each dimension: PURPOSE (1 sentence), KEY ENTITIES, CONNECTIONS to other dimensions, RISK SMELL (most likely failure). Must fit one screen. Max 10% of total effort.
+
+### Orient (Separate Phase in Core Loop — Between Classify and Plan)
+
+Orient is a **dedicated phase** in the Core Loop, not just a transition step. It is the ONLY phase where targeted file reading happens. From John Boyd's OODA Loop — the most critical step.
+
+**In the Core Loop context:**
+
+- Classify phase produces a Dimension Map + Read List (dry, no files read)
+- Orient phase reads ONLY the files from that Read List
+- Plan phase synthesizes Orient findings into an action plan
+
+**Orient steps:**
+
+1. **TARGETED READ** — Read each file from the Classify Read List. After each file, note key findings in task Notes. Don't rely on raw file staying in context. Do NOT read files not in the Read List.
+2. **MEMORY CHECK** (3-layer protocol, max 500tok total):
+   - **Step 1 — Search:** `cos_search(query="{domain} {task_title}", limit=5)` → index-level results (~50tok)
+   - **Step 2 — Suggest:** `cos_learn_suggest(domain="{domain}", complexity="{complexity}")` → actionable patterns with spaced repetition
+   - **Step 3 — Details (if high-confidence hit):** `cos_details(pattern_id, source)` for patterns with confidence > 0.7 (~500tok)
+   - **Post-task:** After task-done, call `cos_learn_validate(pattern_id, was_helpful)` for each pattern used
+   - **Empty result:** If no patterns found, proceed normally — "No relevant past patterns found"
+   - **Token guard:** Drop lowest-confidence results first if budget exceeded
+3. **REPO SEARCH** — Grep/Glob for existing code related to the task. [P1] If found, diff against spec. [P2]
+4. **MODEL UPDATE**: "Has my understanding changed? Adjust Dimension Map? New files to read?"
+   - If new dimensions discovered → read new files, update map
+   - If Reframe Trigger fires (problem redefined, actor missing, boundary changed, constraint changed) → back to Classify
+5. **EVOLUTION CHECK** (Wardley): Novel → deep. Emerging → research. Good Practice → adapt. Commodity → use off-the-shelf.
+6. **BIAS CHECK**: "Am I anchored to first idea? Avoiding uncomfortable dimension? Over-engineering interesting one?"
+
+### Stakeholder Checkpoint (First Cycle Only)
+
+Present plan before diving deep:
+1. "Here's how I understand the problem"
+2. "I've identified these dimensions"
+3. "Going deep on [X] first because [reason]"
+4. "Final deliverable will be: [format from Q7]"
+5. "Assuming [key assumptions]. Correct?"
+6. "Anything missing or reprioritize?"
+
+For AI agents: if prompt is ambiguous → ASK. If clear → "Here's my plan, proceeding unless you say otherwise."
+
+### Zoom In
+
+1. SCOPE this dimension — run Tool 1 (Problem Framing) scoped to it
+2. SELECT TOOLS — use Tool Selection Guide below
+3. SELECT DEPTH — Deep / Medium / Light from Zoom Out
+4. EXECUTE — run selected tools at selected depth
+5. VALIDATE — "Anything that affects other dimensions? Am I guessing? Is output testable?"
+
+### Dimension Dependency Matrix
+
+```
+→ = outputs to    ← = depends on    ↔ = bidirectional    ↑↓ = constrains
+```
+When a dimension completes, check matrix for affected dimensions. Kernel decides: revisit now or defer.
+
+---
+
+## Process Manager
+
+Prevents the most dangerous failure: **thinking you're done when you're not.**
+
+### Dimension Map
+
+```
+Dimension        │ Status    │ Depth  │ Phase │ Revisit? │ Blocked by
+─────────────────┼───────────┼────────┼───────┼──────────┼───────────
+[fill per task]  │ ○/◐/✓    │ D/M/L  │ MVP/v1│ Yes/No   │ [dim]
+```
+
+### Assumption Registry
+
+```
+#  │ Assumption                    │ Source     │ Confidence │ Validated?
+───┼───────────────────────────────┼────────────┼────────────┼───────────
+[fill per task]                    │ Decision/  │ High/Med/  │ Yes/No/
+                                   │ Assumption │ Low        │ Test!
+```
+
+### Cross-Dimension Conflict Log
+
+```
+# │ Dim A │ Dim B │ Issue │ Resolved?
+```
+
+### 7 Rules
+
+1. **No Premature Completion** — never "done" while any MVP dimension is Pending
+2. **Revisit Enforcement** — "Needs Revisit" must be revisited before completion
+3. **Consistency Gate** — for each dependency pair (→ or ↔), verify outputs are compatible
+4. **Phase Discipline** — all MVP dimensions complete before v1 starts. Exception: v1 blocks MVP → pull forward
+5. **Assumption Review** — before final output, review all assumptions with confidence < High
+6. **Conflict Resolution** — all Conflict Log items resolved before completion
+7. **Mandatory Documentation** — Tool 10 (Record) MUST run before declaring completion
+
+---
+
+## The 10 Thinking Tools
+
+Called BY the Kernel, not in fixed order.
+
+### Tool 1 — Problem Framing
+**When:** Starting any new problem or dimension.
+7 questions: PROBLEM (testable), ACTORS/GOALS, BOUNDARY (data ownership), CONSTRAINTS, SUCCESS (measurable), ASSUMPTIONS (hidden assumption = future bug), OUTPUT FORMAT (determines analysis depth).
+First Principles: "What is the source of truth?" · "What events change state?" · "Am I copying a pattern or solving MY problem?"
+
+### Tool 2 — Decompose
+**When:** Problem too big to tackle whole.
+Two types needed for complex systems:
+- **Technical** (how it's built): Backend, Database, API, Frontend, Infrastructure
+- **Domain** (what it's about, from DDD): Identity & Auth, Content Management, Billing, etc.
+Rules: no item in two parts, nothing important missing, clear membership criterion.
+
+### Tool 3 — Behavior Modeling
+**When:** Something changes over time with distinct states.
+No independent dimensions → flat state machine. Independent dimensions → orthogonal regions. Shared behavior → hierarchical nesting.
+Per transition: Event, Guard, Side Effect, Timeout.
+Validation: impossible state combo? unhandled event? dead-end state?
+
+### Tool 4 — Rules Modeling
+**When:** 2-5 conditions combine to produce outcome. (6+ conditions → split tables or rule engine)
+Build decision table. Every table specifies: default behavior, conflict resolution.
+Collapse: remove impossible combos, merge same-result rows, use * for don't-care.
+
+### Tool 5 — Scenario Modeling
+**When:** Verifying real usage flows. Run AFTER Behavior (Tool 3) → Rules (Tool 4).
+Three types: Happy Path, Alternate Path, Exception Path.
+Per scenario: Trigger, Preconditions, Steps, Postconditions, User sees, System sees.
+**Critical:** Run scenarios PER RELEVANT DIMENSION.
+
+### Tool 6 — Risk Pass
+**When:** Finding what could go wrong before it does.
+Four lenses: Inversion, Pre-Mortem, Threat Modeling, Abuse Cases.
+8 categories: Security, Data Integrity, UX Failure, Operational, Legal/Compliance, Abuse/Fraud, Performance/Scaling, Dependency/Vendor.
+Output: Risk Register (# / Risk / Category / Severity / Mitigation / Phase).
+This tool discovers risks — does NOT redesign. If new state/rule/actor found → flag for Kernel.
+
+### Tool 7 — Second-Order Thinking
+**When:** Important decision with lasting consequences.
+Ask "And then what?" 2+ layers: Decision → 1st order → 2nd order → 3rd order.
+Don't confuse with Tool 3: "What happens if we delete?" = consequences (here). "From which states is deletion allowed?" = behavior (Tool 3).
+
+### Tool 8 — Simplify Without Lying
+**When:** After divergent thinking (Tools 2-7), before output.
+Remove: fake complexity, unrealistic scenarios, premature abstractions, duplicates, features nobody asked for.
+Keep: real risks, legal constraints, genuine edge cases.
+Phase: MVP ("broken if removed"), v1 ("users complain but survive"), v2 ("future speculation").
+Mark "Deferred" not "Deleted." Deferred = wisdom, Deleted = negligence.
+
+### Tool 9 — Convert to Action
+**When:** Thinking done, time to make executable.
+Per action: what to do, due, depends on, done-when (testable criteria), linked risks, linked states, phase.
+
+### Tool 10 — Record and Communicate
+**When:** Output needs capture or sharing.
+Pyramid Principle: conclusion first → supporting branches → details.
+Document type (Diátaxis): Tutorial / How-to / Reference / Explanation. Don't mix types.
+Architecture docs only: C4 model (Context → Container → Component → Code).
+
+---
+
+## Tool Selection Guide
+
+```
+Dimension Type          │ Essential Tools            │ Notes
+────────────────────────┼────────────────────────────┼──────────────────────
+Core Logic (backend)    │ 1, 2, 3, 4, 5, 6, 7, 8, 9 │ Full analysis
+Data / Schema (DB)      │ 1, 2, 3, 4, 8, 9          │ Behavior = states map to fields
+Interface Contract (API)│ 1, 2, 4, 5, 8, 9          │ Scenarios matter
+User Experience (FE)    │ 1, 2, 5, 6, 7, 8, 9       │ Scenarios per platform!
+Security (auth, crypto) │ 1, 3, 4, 6, 8, 9          │ Risk Pass is king
+Infrastructure (CI/CD)  │ 1, 2, 6, 8, 9             │ Risk = what breaks in prod
+Standards / Style       │ 1, 2, 8, 9                │ Lightweight pass
+Content / Marketing     │ 1, 2, 5, 7, 8, 9, 10      │ Scenarios + Record
+```
+
+If dimension spans multiple types → take UNION of tools for all applicable types.
+
+## Depth Levels
+
+- **Deep:** All selected tools run completely. Every state modeled, every scenario written, risk pass thorough. Use for: core business logic, security, primary user flows.
+- **Medium:** Tools on critical paths only. Key states, main scenarios (happy + top 2 exceptions), quick risk scan. Use for: database schema, API contract, secondary flows.
+- **Light:** Problem Framing + Decompose + Simplify only. No detailed modeling. Use for: code standards, peripheral features, v2 items.
+
+## Safety Mechanisms
+
+- **Max 3 Zoom cycles** — then deliver with caveats listing uncertainties
+- **Max 8 MVP dimensions** — more = problem too big, break into separate problems
+- **Reframe Trigger** — if during any Zoom In: problem redefined, actor missing, boundary changed, constraint changed → STOP → Tool 1 → restart
+- **Experiment Protocol** — for COMPLEX: hypothesis → smallest test → success/failure signal → timebox → learn
+
+---
+
+## Domain Skills Registry
+
+See `skill-enforcement.md` (in your adapter's rules dir) for the full skill routing table. After Thinking OS analysis, defer to the appropriate domain skill(s) for implementation. Thinking OS provides analysis and thinking structure; domain skills provide implementation patterns.
+
+---
+
+## Integration with Core Loop
+
+How Thinking OS maps to AGENTS.md 5-phase Core Loop:
+
+1. **Rule** (always active) provides Complexity Gate → runs in **Classify** phase (dry, no reads)
+2. **CLEAR** → skip to Execute phase directly, no skill needed
+3. **COMPLICATED / COMPLEX** → load this skill:
+   - **Classify phase** (dry): Complexity Gate + Dimension Map + Read List
+   - **Orient phase** (read): Targeted file reads + Memory Check + Repo Search + Model Update
+   - **Plan phase** (think): Zoom In/Out cycles (up to 3) using 10 Thinking Tools:
+     - Zoom Out → identify dimensions, assign depth/phase
+     - System Sketch → rough map of whole system
+     - Stakeholder Checkpoint → confirm plan with user
+     - Zoom In → execute tools on one dimension
+     - Repeat until all MVP dimensions covered
+   - **Execute phase** (do): implement the plan, on-demand reads only
+4. Output of Plan phase feeds into Execute: domain skill selection, implementation plan, risk awareness
+5. After task completion: outcome recorded to coding-os.db via `cos_metric_record`. Every 10 tasks, Learning Loop extracts patterns and may promote them to rules or skill-enforcement updates.

core/skills/thinking_os/scripts/classify.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Cynefin + dimension-count classifier helper for the Complexity Gate.
+# Interactive: walks the agent through Q1 (Cynefin domain) + Q2 (dimensions)
+# and emits a single-line classification suitable for write-state.sh.
+#
+# Usage:
+#   bash classify.sh                # interactive, asks both questions
+#   bash classify.sh --q1 COMPLICATED --q2 3   # non-interactive shortcut
+#   bash classify.sh --print-only --q1 COMPLEX --q2 5  # echo without writing
+#
+# Output: emits the classification line (e.g. "COMPLICATED 3") to stdout
+# and, by default, writes it to $COS_PANEL_DIR/.thinking_os-gate via
+# write-state.sh (the canonical gate-marker script — `cos_state_path`
+# auto-routes the bare `.thinking_os-gate` basename to the per-panel dir).
+set -euo pipefail
+
+# Safety: ensure core POSIX tools resolvable even when caller PATH is restricted.
+export PATH="/usr/bin:/bin:/usr/local/bin:${PATH:-}"
+
+# ── Argument parsing ────────────────────────────────────────────────
+Q1=""
+Q2=""
+PRINT_ONLY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --q1) Q1="$2"; shift 2 ;;
+    --q2) Q2="$2"; shift 2 ;;
+    --print-only) PRINT_ONLY=1; shift ;;
+    -h|--help)
+      sed -n '2,12p' "$0"
+      exit 0
+      ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+# ── Non-interactive safety: refuse to prompt when stdin isn't a TTY ──
+# An agent calling this script in batch mode must pass --q1/--q2;
+# otherwise we'd silently hang on `read` or accept empty input.
+if [ -z "$Q1" ] || [ -z "$Q2" ]; then
+  if [ ! -t 0 ]; then
+    echo "[classify] non-interactive context detected — pass --q1 <CLEAR|COMPLICATED|COMPLEX|CHAOTIC|CONFUSION> --q2 <N>" >&2
+    exit 2
+  fi
+fi
+
+# ── Interactive prompts (only if not provided) ──────────────────────
+if [ -z "$Q1" ]; then
+  cat >&2 <<'EOF'
+
+Q1 — Problem nature (Cynefin)
+  1) CLEAR        — known solution, just do it
+  2) COMPLICATED  — known type, details need analysis
+  3) COMPLEX      — unknown answer until tested
+  4) CHAOTIC      — broken NOW, act first
+  5) CONFUSION    — can't classify; decompose first
+
+EOF
+  read -r -p "Choose 1-5: " choice
+  case "$choice" in
+    1) Q1=CLEAR ;;
+    2) Q1=COMPLICATED ;;
+    3) Q1=COMPLEX ;;
+    4) Q1=CHAOTIC ;;
+    5) Q1=CONFUSION ;;
+    *) echo "Invalid choice: $choice" >&2; exit 2 ;;
+  esac
+fi
+
+# Validate
+case "$Q1" in
+  CLEAR|COMPLICATED|COMPLEX|CHAOTIC|CONFUSION) ;;
+  *) echo "Invalid Q1: $Q1 (must be one of CLEAR|COMPLICATED|COMPLEX|CHAOTIC|CONFUSION)" >&2; exit 2 ;;
+esac
+
+if [ -z "$Q2" ]; then
+  cat >&2 <<'EOF'
+
+Q2 — Dimensions involved
+  1     — single pass, no Zoom needed
+  2-4   — standard Zoom cycle
+  5+    — full Zoom with Dimension Map
+  8+    — break into separate problems (consider CONFUSION)
+
+EOF
+  read -r -p "Dimensions (integer): " Q2
+fi
+
+# Validate integer
+if ! [[ "$Q2" =~ ^[0-9]+$ ]]; then
+  echo "Invalid Q2: $Q2 (must be a non-negative integer)" >&2
+  exit 2
+fi
+
+# ── Emit + persist ──────────────────────────────────────────────────
+CLASSIFICATION="$Q1 $Q2"
+echo "$CLASSIFICATION"
+
+if [ "$PRINT_ONLY" -eq 1 ]; then
+  exit 0
+fi
+
+# Compute target state file path. Prefer cos-env.sh contract; fall back
+# to .coding-os/<agent>/.thinking_os-gate.
+AGENT_DIR="${COS_AGENT_DIR:-${COS_STATE_DIR:-.coding-os}/${COS_AGENT:-unknown}}"
+GATE_FILE="$AGENT_DIR/.thinking_os-gate"
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+WRITE_STATE="$REPO_ROOT/src/core/hooks/write-state.sh"
+[[ ! -f "$WRITE_STATE" ]] && WRITE_STATE="$REPO_ROOT/core/hooks/write-state.sh"
+[[ ! -f "$WRITE_STATE" ]] && WRITE_STATE="$REPO_ROOT/.${COS_AGENT:-claude}/hooks/write-state.sh"
+
+if [ -x "$WRITE_STATE" ] || [ -f "$WRITE_STATE" ]; then
+  bash "$WRITE_STATE" "$GATE_FILE" "$CLASSIFICATION" >/dev/null 2>&1 || {
+    echo "[classify] write-state.sh failed; gate not recorded" >&2
+    exit 1
+  }
+  echo "[classify] gate recorded at $GATE_FILE" >&2
+else
+  echo "[classify] write-state.sh not found at $WRITE_STATE — gate NOT recorded" >&2
+  exit 1
+fi

core/skills/typescript/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: typescript
+tier: quality
+domain: [frontend, backend]
+description: Write type-safe TypeScript that catches bugs at compile time — strict config, type narrowing, discriminated unions, generics, utility types, and avoiding the any/!-escape-hatches that silently disable the checker. Use when setting up tsconfig, modeling a domain with types, fixing "type X is not assignable", deciding unknown vs any, narrowing a union, writing a generic, or reviewing TS for type-safety holes. Underpins React/Next/React-Native/Node. Triggers — "tsconfig", "type error", "TypeScript", "any vs unknown", "generic", "discriminated union", "type narrowing", any `*.ts`/`*.tsx`. Pairs with clean-code (naming/structure), nextjs-react + react-native-mobile (the frameworks), node-backend (server TS), state-management (typed stores).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# TypeScript
+
+TypeScript is only as safe as its strictness lets it be. With `strict` off (or `any`/`!` sprinkled in) it's JavaScript with extra syntax — the checker is on but blindfolded. The craft is letting the type system *prove* the bug can't happen, not narrating types after the fact.
+
+> Check a tsconfig for the strict flags that actually matter:
+> `python3 scripts/check_tsconfig.py tsconfig.json`
+
+## Strict is the floor
+
+```jsonc
+// tsconfig.json — the flags that catch real bugs
+{
+  "compilerOptions": {
+    "strict": true,                       // the umbrella — turn it on, always
+    "noUncheckedIndexedAccess": true,     // arr[i] is T | undefined (it really is!)
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+`strict: true` enables `noImplicitAny`, `strictNullChecks`, and more — without it, `null`/`undefined` are assignable everywhere and the #1 class of runtime crash goes uncaught. `noUncheckedIndexedAccess` is the highest-value non-default: it makes `arr[i]` honestly `T | undefined`. Full rationale → [references/strictness.md](references/strictness.md).
+
+## `unknown`, never `any`
+
+```typescript
+// Wrong — any disables the checker for everything downstream; the bug ships
+function parse(json: string): any { return JSON.parse(json); }
+const u = parse(s); u.naem.toUpperCase();   // typo compiles, crashes at runtime
+
+// Correct — unknown forces you to narrow before use
+function parse(json: string): unknown { return JSON.parse(json); }
+const u = parse(s);
+if (isUser(u)) u.name.toUpperCase();         // narrowed via a type guard
+```
+
+`any` is a hole in the type system that spreads — every value derived from an `any` is `any`. `unknown` is the safe top type: you must narrow it before you touch it. Reserve `any` for genuinely untypable third-party seams, and isolate it behind a typed wrapper.
+
+## Discriminated unions over optional-flag soup
+
+```typescript
+// Wrong — every field optional; illegal combinations compile
+type Result = { ok?: boolean; data?: User; error?: string };
+
+// Correct — a discriminant makes illegal states unrepresentable
+type Result =
+  | { status: "ok"; data: User }
+  | { status: "error"; error: string };
+
+function render(r: Result) {
+  if (r.status === "ok") r.data;     // narrowed — r.error doesn't exist here
+  else r.error;                       // exhaustive
+}
+```
+
+Model state as a union with a `status`/`kind` discriminant so the compiler narrows each branch and rejects impossible combinations. Add a `never` default in the switch for exhaustiveness — adding a variant then becomes a compile error until handled. Patterns → [references/type-system.md](references/type-system.md).
+
+## Narrow, don't assert
+
+```typescript
+// Wrong — ! and `as` LIE to the compiler; they don't check anything
+const el = document.querySelector(".btn")!;   // crashes if null
+const user = data as User;                      // no validation at all
+
+// Correct — narrow with a real check, or validate at the boundary
+const el = document.querySelector(".btn");
+if (!el) throw new Error("button missing");
+const user = userSchema.parse(data);            // zod/valibot validates AND types
+```
+
+`!` (non-null) and `as` (type assertion) silence the checker without proving anything — they're `any` in disguise. Validate external data (API responses, JSON, env) at the boundary with a schema validator (zod/valibot) that returns a typed value. `satisfies` checks a literal against a type *without* widening it.
+
+## Generics — constrain, don't over-parameterize
+
+```typescript
+// Correct — constrained generic preserves the input type through the function
+function first<T>(arr: readonly T[]): T | undefined { return arr[0]; }
+function pluck<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
+```
+
+A generic earns its place when it *links* types (input element → output element). If a type parameter appears once, it's just `unknown` with extra letters — drop it. Use the built-in utility types (`Partial`, `Pick`, `Omit`, `Record`, `ReturnType`) before hand-rolling.
+
+## Anti-patterns (reject on sight)
+
+- `strict: false` (or absent) → the checker is blindfolded; turn it on.
+- `any` outside a justified, isolated third-party seam → use `unknown` + narrow.
+- `!` non-null assertion to silence a nullable → narrow with an `if`.
+- `as SomeType` on external data → validate with a schema at the boundary.
+- `@ts-ignore` / `@ts-expect-error` with no comment → if you must, say why.
+- Optional-flag object where a discriminated union models the states.
+- A generic type parameter used exactly once → it's `unknown`; remove it.
+
+## See also
+
+- [references/strictness.md](references/strictness.md) — every strict flag, what bug it catches, migration order.
+- [references/type-system.md](references/type-system.md) — narrowing, unions, generics, utility/conditional/mapped types.
+- [assets/typescript-checklist.md](assets/typescript-checklist.md) — the review gate.
+- [clean-code](../clean-code/SKILL.md) · [state-management](../state-management/SKILL.md) — and your stack's framework skill (nextjs-react / react-native-mobile / node-backend) when present.

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

@@ -0,0 +1,24 @@
+<!-- domain:FRONTEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# TypeScript Review Checklist
+
+Run before merging TS/TSX.
+
+## Config
+- [ ] `strict: true` (non-negotiable).
+- [ ] `noUncheckedIndexedAccess: true`.
+- [ ] `noImplicitOverride`, `exactOptionalPropertyTypes`, `noFallthroughCasesInSwitch` on.
+- [ ] `python3 scripts/check_tsconfig.py tsconfig.json` → `clean`.
+
+## Type safety
+- [ ] No `any` except a justified, isolated third-party seam (commented).
+- [ ] External data (API/JSON/env) validated at the boundary with a schema (zod/valibot) — not `as`.
+- [ ] No `!` non-null assertions silencing a real nullable — narrowed with a check.
+- [ ] No `@ts-ignore`/`@ts-expect-error` without a why comment.
+- [ ] Multi-state values modeled as discriminated unions, with a `never` exhaustiveness default.
+- [ ] Generics link ≥2 type positions (no single-use type parameters).
+- [ ] Types derived from a single source (`as const`, `z.infer`) — not duplicated.
+
+## Hygiene
+- [ ] `tsc --noEmit` passes with zero errors (no suppressed-but-broken files in new code).
+- [ ] Public function signatures fully typed (params + return), not inferred-and-hoped.
+- [ ] `make skills-check-versions` — TS version pin current.

core/skills/typescript/references/strictness.md

@@ -0,0 +1,53 @@
+<!-- domain:FRONTEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# TypeScript Strictness — Every Flag, What It Catches
+
+> P: The compiler flags that turn TS from "JS with syntax" into a real prover, and the order to adopt them.
+> R: Setting up or tightening a tsconfig; deciding which flags to enable.
+> S: Type-level modeling — see [type-system.md](type-system.md).
+> N: [SKILL.md](../SKILL.md), [typescript-checklist.md](../assets/typescript-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## `strict: true` — the umbrella
+
+Turning on `strict` enables all of these at once. Each catches a real bug class:
+
+| Sub-flag | Catches |
+|---|---|
+| `noImplicitAny` | a parameter/variable that silently became `any` |
+| `strictNullChecks` | using a value that can be `null`/`undefined` without a check (the #1 crash) |
+| `strictFunctionTypes` | unsound function-parameter variance |
+| `strictBindCallApply` | wrong args to `.bind`/`.call`/`.apply` |
+| `strictPropertyInitialization` | a class field never assigned in the constructor |
+| `useUnknownInCatchVariables` | `catch (e)` is `unknown`, not `any` |
+
+Never ship `strict: false`. If migrating a legacy codebase, enable `strict` and
+suppress file-by-file with `// @ts-nocheck` at the top of not-yet-fixed files —
+so new code is strict and the debt is visible and shrinking.
+
+## High-value non-defaults (enable these too)
+
+| Flag | What changes | Why it matters |
+|---|---|---|
+| `noUncheckedIndexedAccess` | `arr[i]` and `obj[key]` become `T \| undefined` | array/record access really can be undefined — this makes the checker admit it |
+| `exactOptionalPropertyTypes` | `{ x?: T }` ≠ `{ x: T \| undefined }` | distinguishes "absent" from "present but undefined" |
+| `noImplicitOverride` | `override` keyword required to override | a renamed base method silently stops being overridden otherwise |
+| `noFallthroughCasesInSwitch` | a `case` with no `break`/`return` errors | classic switch fall-through bug |
+| `noImplicitReturns` | all code paths must return | a missing return branch |
+
+`noUncheckedIndexedAccess` is the single most valuable non-default — it surfaces a
+huge class of "cannot read property of undefined" before runtime.
+
+## Adoption order for an existing project
+
+1. `strict: true` — fix the null-check errors first (biggest payoff).
+2. `noUncheckedIndexedAccess` — expect many `arr[i]` sites; add guards or `?.`.
+3. The override/switch/return flags — usually few errors, quick wins.
+4. `exactOptionalPropertyTypes` — last; it's the most pedantic.
+
+## Verify
+
+`python3 ../scripts/check_tsconfig.py tsconfig.json` flags any of the above that
+are off or missing. Note: it does not resolve `extends` — if your config extends
+a base, a flag may be inherited; check the resolved output with
+`tsc --showConfig`.