ticketwright 2.0.0__py3-none-any.whl

ticketwright/_kit/.claude/hooks/regenerate_ticket_index.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""PostToolUse hook — auto-regenerate tickets/INDEX.md when a ticket folder changes.
+
+Fires after Write/Edit. If the edited file lives under tickets/ (and isn't the index
+artifacts themselves), it re-renders tickets/INDEX.md so the catalog always reflects
+reality: a new ticket appears immediately (marked ▱ until curated), and an edited README
+flags its row ⚠ (summary may be stale). LLM-authored summaries are *not* regenerated here
+(a hook can't run the model synchronously) — those refresh at ticket close via
+bin/ingest_index_records.py.
+
+Deterministic + fast (re-renders from disk + index_data.json). Writes only when the
+rendered output actually changes, so irrelevant edits produce no churn. Fails open.
+
+Wire in .claude/settings.json:
+  "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [
+    { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/regenerate_ticket_index.py\"" } ] } ] }
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0  # nothing to do
+
+    tool_input = payload.get("tool_input") or {}
+    fp = tool_input.get("file_path") or tool_input.get("path") or ""
+    if not fp:
+        return 0
+
+    root = Path(os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or ".").resolve()
+    tickets_dir = root / "tickets"
+    try:
+        changed = Path(fp).resolve()
+        changed.relative_to(tickets_dir)  # raises if not under tickets/
+    except (ValueError, OSError):
+        return 0  # edit was not under tickets/
+
+    # Don't react to the *generated* artifacts (else the hook's own write re-triggers it).
+    # index_data.json is source, NOT generated — editing the store SHOULD re-render.
+    if changed.name in ("INDEX.md", "OBJECTS.md"):
+        return 0
+
+    sys.path.insert(0, str(root / "bin"))
+    try:
+        from build_ticket_index import build_rows, render, render_objects  # type: ignore
+        rows = build_rows(root)
+        fresh = {tickets_dir / "INDEX.md": render(rows), tickets_dir / "OBJECTS.md": render_objects(rows)}
+    except SystemExit:
+        return 0  # malformed index_data.json — surfaced when the agent runs the renderer
+    except Exception:
+        return 0  # fail open
+
+    try:
+        changed_any = False
+        for p, txt in fresh.items():
+            if (p.read_text() if p.is_file() else None) != txt:
+                p.write_bytes(txt.encode("utf-8")); changed_any = True
+        if changed_any:
+            print("Auto-regenerated tickets/INDEX.md + OBJECTS.md (ticket folder changed). "
+                  "Run bin/ingest_index_records.py to refresh a ticket's curated summary.")
+    except OSError:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ticketwright/_kit/.claude/hooks/session_context.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""SessionStart hook — prime every session with the configured stack + AI-layer index.
+
+Prints a compact summary (becomes session additionalContext) so the agent always knows
+which tools are wired, which skills/commands exist, and the lifecycle — without anyone
+having to load all of AGENTS.md. This is the always-on, *tiny* slice of context; the
+`/prime-*` commands load the rest on demand.
+
+Wire it in settings.json:
+  "hooks": { "SessionStart": [ { "hooks": [
+    { "type": "command", "command": "python3 .claude/hooks/session_context.py" } ] } ] }
+
+Stdlib only. Fails open (prints nothing) if the kit isn't configured yet.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def project_root() -> Path:
+    if os.environ.get("CLAUDE_PROJECT_DIR"):
+        return Path(os.environ["CLAUDE_PROJECT_DIR"])
+    # hook lives at <root>/.claude/hooks/
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def scan_stack(stack: Path) -> dict:
+    text = stack.read_text(errors="replace")
+    out = {}
+    m = re.search(r"^\s*key_prefix:\s*([A-Za-z0-9_-]+)", text, re.MULTILINE)
+    out["key_prefix"] = m.group(1) if m else "?"
+    # tool per seam: find "  <seam>:" then the nested "    tool: <x>"
+    for seam in ("tracker", "warehouse", "chat", "docstore", "vcs"):
+        m = re.search(rf"^\s{{2}}{seam}:\s*\n(?:\s+.*\n)*?\s+tool:\s*([A-Za-z0-9_-]+)", text, re.MULTILINE)
+        out[seam] = m.group(1) if m else "—"
+    return out
+
+
+def main() -> int:
+    root = project_root()
+    stack = root / ".claude/config/stack.yaml"
+    if not stack.is_file():
+        return 0  # not configured — say nothing
+
+    try:
+        s = scan_stack(stack)
+    except OSError:
+        return 0
+
+    skills = sorted(p.parent.name for p in (root / ".claude/skills").glob("*/SKILL.md")) \
+        if (root / ".claude/skills").is_dir() else []
+    # Hide deprecated v1 alias stubs — they route to v2 skills and shouldn't re-clutter the surface.
+    commands = sorted(
+        p.stem for p in (root / ".claude/commands").glob("*.md")
+        if "Deprecated" not in p.read_text(errors="replace")[:200]
+    ) if (root / ".claude/commands").is_dir() else []
+
+    lines = [
+        "## Ticketwright — session context",
+        f"Stack ({s['key_prefix']}-tickets): tracker={s['tracker']} · warehouse={s['warehouse']} · "
+        f"chat={s['chat']} · docstore={s['docstore']} · vcs={s['vcs']}.",
+        "Lifecycle: /ticket (opens + auto-primes context) → /spec-and-build → /review → /ship.",
+    ]
+    if skills:
+        lines.append("Skills: " + ", ".join(skills) + ".")
+    if commands:
+        lines.append("Commands: " + ", ".join(commands) + ".")
+    lines.append("Policies enforced: DB writes & external posts require approval (db_write_guard hook + "
+                 "skill hard-halts); chat defaults to draft; outputs deterministic. See AGENTS.md.")
+    print("\n".join(lines))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ticketwright/_kit/.claude/hooks/ticket_index_context.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""SessionStart hook — surface the ticket index so Claude recalls prior work.
+
+Prints a compact block (becomes session additionalContext): the catalog size, a
+status breakdown, and the most recent tickets, plus a pointer to grep the full
+`tickets/INDEX.md` before starting related work. The authoritative *count* comes from
+discovering ticket folders on disk (so a newly-added, not-yet-enriched ticket still
+counts); the per-ticket detail comes from the enriched `tickets/index_data.json`.
+Stdlib only; fails open (prints nothing) on any error.
+
+Wire in .claude/settings.json:
+  "hooks": { "SessionStart": [ { "hooks": [
+    { "type": "command", "command": "python3 .claude/hooks/ticket_index_context.py" } ] } ] }
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+RECENT = 12
+STATUS_ORDER = ["Deployed", "Completed", "In Review", "In Progress", "Blocked", "Unknown"]
+
+
+def project_root() -> Path:
+    if os.environ.get("CLAUDE_PROJECT_DIR"):
+        return Path(os.environ["CLAUDE_PROJECT_DIR"])
+    return Path(__file__).resolve().parent.parent.parent  # .claude/hooks/ -> root
+
+
+def ticket_number(tid: str) -> int:
+    m = re.search(r"-(\d+)", tid)
+    return int(m.group(1)) if m else 0
+
+
+def discovered_total(root: Path) -> int | None:
+    """True ticket count from the renderer's discovery (cheap globs, no README reads)."""
+    try:
+        import sys
+        sys.path.insert(0, str(root / "bin"))
+        from build_ticket_index import discover  # type: ignore
+        return len(discover(root))
+    except Exception:
+        return None
+
+
+def main() -> int:
+    root = project_root()
+    data_file = root / "tickets" / "index_data.json"
+    index_file = root / "tickets" / "INDEX.md"
+
+    tickets = []
+    if data_file.is_file():
+        try:
+            loaded = json.loads(data_file.read_text())
+            if isinstance(loaded, dict) and isinstance(loaded.get("tickets"), list):
+                tickets = [t for t in loaded["tickets"] if isinstance(t, dict)]
+        except (OSError, json.JSONDecodeError):
+            tickets = []
+
+    if not tickets:
+        # Catalog may exist but not be enriched yet — emit a bare pointer if INDEX.md is there.
+        if index_file.is_file():
+            print("## Ticket index\nCatalog of prior ticket work: `tickets/INDEX.md` — grep it before "
+                  "starting related work (same object / stakeholder / report).")
+        return 0
+
+    total = discovered_total(root) or len(tickets)
+    by_status: dict[str, int] = {}
+    for t in tickets:
+        s = t.get("status") or "Unknown"
+        by_status[s] = by_status.get(s, 0) + 1
+    extra = sorted(s for s in by_status if s not in STATUS_ORDER)
+    status_line = " · ".join(f"{s} {by_status[s]}" for s in (STATUS_ORDER + extra) if by_status.get(s))
+
+    recent = sorted(tickets, key=lambda t: (t.get("date") or "0000-00-00", ticket_number(t.get("id", ""))),
+                    reverse=True)[:RECENT]
+
+    lines = [
+        "## Ticket index — recall before starting work",
+        f"{total} tickets indexed ({status_line}). Full catalog: `tickets/INDEX.md` — "
+        "**grep it for prior work on the same object / stakeholder / report before starting a ticket, and reuse it.**",
+        f"Most recent {len(recent)}:",
+    ]
+    for t in recent:
+        title = (t.get("title") or "").strip()
+        if len(title) > 72:
+            title = title[:71].rstrip() + "…"
+        d = t.get("date") or "—"
+        lines.append(f"- {t.get('owner')}/{t.get('id')} ({d}) — {title}")
+    if total > len(tickets):
+        lines.append(f"({total - len(tickets)} newer ticket(s) on disk not yet enriched — run the index workflow.)")
+    print("\n".join(lines))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ticketwright/_kit/.claude/settings.json.tmpl

@@ -0,0 +1,59 @@
+{
+  "_README": "Rendered to .claude/settings.json by /setup. Wires the kit's hooks (policy enforcement + session priming + ticket-index surfacing/auto-regen), a conservative read-only permission baseline (setup appends stack-specific query/CLI allows), and the stack statusline. The db_write_guard hook turns 'db_write_requires_approval' into a mechanical ask before any destructive warehouse statement.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "python3 .claude/hooks/db_write_guard.py" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "python3 .claude/hooks/session_context.py" },
+          { "type": "command", "command": "python3 .claude/hooks/ticket_index_context.py" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "python3 .claude/hooks/regenerate_ticket_index.py" }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "_README": "Read-only baseline that is safe in any stack. setup appends the chosen warehouse/tracker/vcs read verbs (e.g. Bash(snow sql:*)) here; the db_write_guard hook still gates destructive statements even when the CLI is allowed.",
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(tree:*)",
+      "Bash(rg:*)",
+      "Bash(grep:*)",
+      "Bash(fd:*)",
+      "Bash(find:*)",
+      "Bash(jq:*)",
+      "Bash(yq:*)",
+      "Bash(python3 bin/build_ticket_index.py:*)",
+      "Bash(python3 bin/ingest_index_records.py:*)",
+      "Bash(python3 bin/recall.py:*)",
+      "Bash(python3 bin/enrich_ticket.py:*)",
+      "Bash(bash bin/verify_stack.sh:*)",
+      "Bash(bash bin/render.sh:*)",
+      "Bash(bash bin/selftest.sh:*)"
+    ],
+    "deny": []
+  },
+  "statusLine": {
+    "type": "command",
+    "command": ".claude/statusline.sh"
+  }
+}

ticketwright/_kit/.claude/skills/productize/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: productize
+description: Turn a recurring "clone-the-last-ticket" workflow into a parameterized skill of its own — phased pipeline, QC checkpoints, golden-replay test, hard-halt before external posts.
+argument-hint: "<workflow name> (e.g. monthly vendor reconciliation)"
+allowed-tools: [Read, Write, Edit, Bash, Glob, AskUserQuestion]
+disable-model-invocation: true
+---
+
+# /productize
+
+The meta-skill (`commandify_everything`). When a task recurs (quarterly sale, monthly report,
+periodic reconciliation), this stamps out a new **folder skill** with the productized skeleton:
+a phased pipeline with hard halts, parameterized SQL/steps, a QC checkpoint, a golden-replay
+regression test, and a hard halt before any external post. `/refresh index` + the `--recurring`
+flag of `bin/build_ticket_index.py` surface candidates ("this object shows up in 7 tickets").
+
+## Phase 1 — Interview the workflow (reduce_assumptions)
+Ask (AskUserQuestion) for:
+- **Name & cadence** (→ kebab skill name) and the **parameters** that change each run (e.g.
+  `--period`, `--as-of-date`, `--ticket`, an input file) — with formats + validation rules.
+- **Steps**: the ordered phases. For each, what it reads, what it writes, and whether it has
+  external side effects or DB writes (those become hard-halt / approval gates).
+- **QC checks**: per check — what it tests, and its tier (hard-halt / warn / info) + remediation hint.
+- **Determinism anchor**: the known-good prior run to use as the **golden fixture** (counts/totals
+  to assert; the byte-identical output file to diff against).
+
+## Phase 2 — Stamp from the template
+1. Copy `templates/productized-skill/` → `.claude/skills/<name>/` (SKILL.md + `sql/ templates/
+   bin/ golden/`).
+2. Render `SKILL.md.tmpl` with the interview answers into the canonical phase shape:
+   **Phase 0** pre-flight (validate params + `verify_stack` for touched seams + an object drift
+   check → halt-on-fail) → **render & run** parameterized steps → **QC** atomic checkpoint
+   (hard-halt tiers) → **export** (deterministic `ORDER BY`) → **render docs** (README +
+   tracker-comment draft) → **HARD HALT for human review** → **post-review** (the external posts,
+   in a separate invocation).
+3. Write the `{{token}}` step files into `sql/` (or `bin/` for non-SQL), the output templates into
+   `templates/`, and seed `golden/<run>.json` with the determinism anchor. **Follow the two SQL
+   authoring rules in [authoring.md](authoring.md)** — a render gate enforces both.
+4. Scaffold `bin/drift_check.sh` (confirms every object the workflow reads is still reachable —
+   the Phase-0 catch for relocations).
+
+## Phase 3 — Wire to the stack & self-test
+5. The stamped skill reads `.claude/config/stack.yaml` and resolves all I/O through adapters (no
+   hardcoded tools in the orchestration). Confirm the SKILL.md prose is tool-neutral:
+   `!grep -REn "acli|snow |slack|gh " .claude/skills/<name>/SKILL.md || echo OK`. (The leaf
+   `bin/drift_check.sh` is allowed to name your warehouse CLI — it's the tool-bound probe.)
+6. Wire the **render gate** (`bin/render_and_validate.sh`) and **export helpers**
+   (`bin/split_and_export.sh`) into the stamped phases so authoring defects fail *closed*, not
+   silently — details and rationale in [authoring.md](authoring.md).
+7. Document the **golden test** + **failure-mode tests** in the new SKILL.md (how to replay the
+   known run and assert the fixture; how each Phase-0/QC/render-gate halt is expected to trigger).
+8. **Report** the new skill path, its parameters, and how to run its golden test.
+
+## Output shape (what every stamped skill guarantees)
+Parameterized · phased · QC-gated · golden-tested · hard-halts before external posts · idempotent
+where possible (re-run converges) · records a rollback key for any DB write. Heavy pulls run in the
+**background**, not the foreground — mark slow phases at stamp time so the operator launches them
+detached from the start.

ticketwright/_kit/.claude/skills/productize/authoring.md

@@ -0,0 +1,36 @@
+# SQL-template authoring rules + the render gate
+
+Two hard rules for every `sql/*.tmpl` in a productized skill. Both have burned real runs; the
+render gate (`bin/render_and_validate.sh`) enforces both mechanically.
+
+## Rule 1 — Never put a token in a SQL comment
+The renderer expands tokens everywhere, **including inside a `--` comment**. A multi-line value
+(e.g. a long `VALUES` list) then spills past the `--` and the continuation rows are parsed as bare
+SQL → compile error. Describe parameters in *prose*, not tokens:
+
+```sql
+-- step SQL — params described in prose, never as tokens   ✓
+-- NOTE: substitutes {{vals}} before the run               ✗ (gate rejects this)
+```
+
+## Rule 2 — Quote any token used as a SQL string/date literal
+`SET d = '{{asof}}'::DATE`, not `= {{asof}}`. Unquoted, `= 2026-06-30` is read as *arithmetic*
+(= 1990), not a date → **silent wrong results**. The quotes live in the template, never injected at
+call time. (The gate warns by default, fails under `--strict`.)
+
+## The render gate — `bin/render_and_validate.sh`
+Run it on every render (in the stamped skill's Phase 0/1, and once at stamp time). Stdlib-only, no
+warehouse round-trip — cheap insurance. It asserts: zero leftover tokens · no token in a comment ·
+balanced single-quotes / parens · flags an unquoted SQL literal. Halt on any error.
+
+```bash
+bash bin/render_and_validate.sh sql/step.sql.tmpl asof=2026-06-30 src=T [--strict]
+```
+
+## Export helpers — `bin/split_and_export.sh`
+Keeps multi-deliverable skills from re-improvising CSV plumbing:
+- `--strip-only <file>` robustly drops the multi-statement CLI preamble (through the last
+  `Statement executed successfully.`, then leading blanks) so the header is row 1;
+- split mode turns one multi-`SELECT` file (delimited by `-- Query N` markers) into N runnable
+  files — each carrying the shared preamble — and `--run` executes each via *your* warehouse verb
+  and strips its CSV.

ticketwright/_kit/.claude/skills/refresh/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: refresh
+description: Maintain the repo's knowledge — `index` rebuilds the ticket catalog (INDEX.md), `context` rebuilds the domain knowledge pack (documentation/). Day-to-day, hooks keep these fresh automatically.
+argument-hint: index [--all | TICKET-ID ...] | context [--refresh] [schema-or-scope] | all
+allowed-tools: [Read, Write, Bash, Glob, Grep]
+---
+
+# /refresh
+
+One maintenance skill for the two knowledge stores the other skills read:
+
+- **`/refresh index`** — the ticket catalog: `tickets/INDEX.md` (every ticket, status, one-line
+  summary, tags, cross-refs) + `tickets/OBJECTS.md` (object → tickets reverse map). This is what
+  `/ticket`'s recall mines. Details: [index.md](index.md).
+- **`/refresh context`** — the domain knowledge pack in `documentation/`: data catalog, DDL, ERD,
+  dependency graph, business glossary. This is what `/ticket`'s domain + warehouse priming reads.
+  Details: [context-pack.md](context-pack.md).
+- **`/refresh all`** — both.
+
+## You rarely need this
+Day-to-day the index maintains itself: the PostToolUse hook re-renders `INDEX.md` on every ticket
+folder change, the SessionStart hook surfaces the catalog, and `/ship` curates each ticket's
+summary at close. Invoke `/refresh` to:
+- **bootstrap** an existing backlog (`/refresh index --all` — render every ticket, then enrich);
+- **re-enrich** a batch after bulk edits (`/refresh index ID1 ID2 …`);
+- **build or update the knowledge pack** (`/refresh context`, scoped to a schema if given;
+  `--refresh` updates in place — overwrite, don't sprawl).
+
+## Mode: `index`
+Follow [index.md](index.md): render deterministically (`bin/build_ticket_index.py` — stdlib, no
+model), enrich the un-enriched/stale set (the model writes one curated record per ticket, ingested
+via `bin/ingest_index_records.py`), re-render, then verify with `--check` and commit all three
+index files together (`INDEX.md`, `OBJECTS.md`, `index_data.json`).
+
+## Mode: `context`
+Follow [context-pack.md](context-pack.md): verify the warehouse seam, introspect via the adapter
+(inventory → DDL → dependencies → usage ranking), generate `data_catalog.md` / `erd.md` /
+`glossary.md` into `documentation/` with freshness stamps, and update
+`documentation/AI_LAYER_INDEX.md`. Don't invent business meaning — flag glossary gaps for a human
+(`reduce_assumptions`).

ticketwright/_kit/.claude/skills/refresh/context-pack.md

@@ -0,0 +1,34 @@
+# `/refresh context` — the domain knowledge pack in detail
+
+Builds the on-demand knowledge base that `/ticket`'s domain + warehouse priming reads, so
+day-to-day tickets prime *slices* instead of re-discovering the warehouse every time. Reads
+`.claude/config/stack.yaml`; introspects via the warehouse adapter, so it works on Snowflake,
+BigQuery, Databricks, etc.
+
+## Phase 0 — Setup
+1. Read `stack.yaml`; verify the warehouse seam (halt with auth notes if unreachable). Scope to
+   the given schema/dataset or the whole configured warehouse. `--refresh` updates an existing
+   pack in place (overwrite, don't sprawl).
+
+## Phase 1 — Introspect (read-only, via adapter)
+2. **Object inventory** — list tables/views/dynamic-tables in scope, using whatever
+   object-inventory idiom the adapter's `dialect_notes` specifies (e.g. an
+   `INFORMATION_SCHEMA`/`system` query).
+3. **DDL dump** — `warehouse.describe` each object; write authoritative DDL to
+   `documentation/erd/ddl_<schema>_<object>.sql`.
+4. **Dependency graph** — derive what-reads-what (lineage views) → an object→object edge list.
+5. **Usage ranking** — rank objects by how often they appear across `tickets/**` (`grep -roh …`)
+   so the catalog leads with what's actually used.
+
+## Phase 2 — Generate the pack (into documentation/)
+6. **`data_catalog.md`** — per object: purpose, grain, key columns, join keys + cast/filter rules
+   (from `dialect_notes`), source layer, usage rank.
+7. **`erd.md`** — the relationships + a high-level diagram; per-object DDL lives under `erd/`.
+8. **`glossary.md`** — business terms, status taxonomies, calculation rules, known data-quality
+   caveats. Seed from existing READMEs/runbooks; **flag gaps for a human to fill** — don't invent
+   business meaning (`reduce_assumptions`).
+9. Add a freshness stamp + scope to each file (re-check if >30 days old).
+
+## Phase 3 — Index & report
+10. Update `documentation/AI_LAYER_INDEX.md` with the pack's contents. Report what was generated,
+    the top-N most-used objects, and which glossary sections need human input.

ticketwright/_kit/.claude/skills/refresh/index.md

@@ -0,0 +1,45 @@
+# `/refresh index` — the ticket catalog in detail
+
+Two layers, kept separate so the catalog is reproducible and CI/pre-commit-safe:
+
+- **`bin/build_ticket_index.py`** — deterministic, LLM-free renderer. Discovers every ticket folder
+  (tracker keys from `stack.yaml` `key_prefixes`/`key_prefix`), merges curated fields from
+  `tickets/index_data.json`, and writes `INDEX.md` + `OBJECTS.md` (object → tickets reverse index;
+  objects = enrichment ∪ a deterministic grep of each ticket's SQL). `--check` (staleness gate,
+  covers both files) · `--stats` (coverage) · `--recurring` (frequently-touched objects —
+  productization candidates).
+- **`tickets/index_data.json`** — the curated store (title/status/date/summary/tags/cross_refs/
+  objects + each README's content hash). This skill writes it.
+
+## Phase 0 — Preflight
+1. Confirm `stack.yaml` has `key_prefix`/`key_prefixes` and (optionally) `ticket_url_template`.
+2. `python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/build_ticket_index.py" --stats` — how
+   many tickets are discovered, enriched, un-enriched (`▱`), stale (`⚠`).
+
+## Phase 1 — Render (always cheap, no model)
+3. `python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/build_ticket_index.py"` — every ticket
+   on disk now has a row (un-enriched ones get a deterministic title + first-paragraph summary,
+   marked `▱`).
+
+## Phase 2 — Enrich (the model half)
+4. Decide scope: the given ticket id(s); `--all` for the whole backlog; or default to the
+   un-enriched/stale set from `--stats`.
+5. For each target ticket, read its `README.md` and write ONE record:
+   `{id, owner, title, status, date, summary (<=180 chars, lead with what was delivered + key
+   numbers), tags (1-4 kebab-case), cross_refs (other ticket ids), objects (qualified data objects
+   the ticket read/wrote, e.g. SCHEMA.VIEW; [] if none)}`. **id/owner come from the folder, not
+   your judgment.** Status vocab: Completed · Deployed · In Review · In Progress · Blocked · Unknown.
+6. Collect them and upsert + re-render:
+   ```bash
+   echo '{"records":[ ... ]}' | python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/ingest_index_records.py" --from-json -
+   python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/build_ticket_index.py"
+   ```
+   (Claude-Code convenience: `python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/enrich_ticket.py" <ID>`
+   does steps 5–6 for one ticket via `claude -p`. The inline path above is agent-agnostic.)
+
+## Phase 3 — Verify
+7. `python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/build_ticket_index.py" --check` must
+   pass (INDEX.md + OBJECTS.md == fresh render).
+8. Report: total tickets, status breakdown, any still un-enriched. Commit `tickets/INDEX.md` +
+   `tickets/OBJECTS.md` + `tickets/index_data.json` (all three — `--check` gates the two generated
+   files).

ticketwright/_kit/.claude/skills/review/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: review
+description: Independent quality review of a ticket's deliverables — re-runs queries and walks a tiered validation pyramid to an APPROVE / REQUEST-CHANGES verdict. Run before shipping.
+argument-hint: <ticket-id> [--deep]
+allowed-tools: [Read, Bash, Glob, Grep, Agent]
+---
+
+# /review
+
+The **check** step of the lifecycle. An *independent* second pass over a ticket's deliverables —
+re-runs queries, walks a tiered validation pyramid, sweeps for anti-patterns, and returns an
+APPROVE / REQUEST-CHANGES verdict. Reads `.claude/config/stack.yaml`; warehouse specifics come from
+the adapter's `dialect_notes`, so the same review runs on Snowflake, BigQuery, or Databricks.
+Read-only: it reviews and re-runs, it does not edit code (the build owns fixes).
+
+## Phase 0 — Setup
+1. Read `stack.yaml`; verify the warehouse seam (halt with auth notes if unreachable). Load
+   `seams.warehouse.dialect_notes` from the adapter — it parameterizes the lint layer.
+2. Read the ticket README, the spec (if any), and list `final_deliverables/` + `qc_queries/`.
+
+## The validation pyramid (bottom = cheap/automated, top = human)
+
+**① Dialect lint** (static, per `dialect_notes`)
+- `= NULL` → must be `IS NULL`; missing div-by-zero guard; `SELECT *` in deliverables; functions on
+  filtered columns; implicit cross-source type mismatches (missing `CAST`); hardcoded values that
+  should be parameters; missing required schema/instance filters; `LEFT JOIN` predicate in `WHERE`
+  that silently becomes an inner join; `NOT IN` with nullable columns; `UNION` vs `UNION ALL`.
+
+**② Counts & dedup** (re-run independently)
+- Re-run the row-count; compare to the documented count. **Duplicate detection is the primary test:**
+  `COUNT(*)` vs `COUNT(DISTINCT <grain key>)` — any gap is a halt until explained.
+- NULL-rate on critical/key columns; value-range sanity (no negative amounts where impossible).
+
+**③ Cross-source reconciliation**
+- Join-match rates (unmatched `LEFT JOIN` rows quantified, not hidden). Date ranges within scope.
+- Reconcile totals against the source of truth (e.g. SUM vs the input file/feed) within tolerance.
+
+**④ Independent re-run + anti-pattern sweep**
+- Re-execute the main deliverable query end-to-end; diff results to the committed output (byte-level
+  for CSVs — `deterministic_outputs` requires explicit `ORDER BY`).
+- Sweep the full anti-pattern set (correctness, performance, data-quality, dialect-specific,
+  maintainability). Classify each finding Critical / Should-fix / Review.
+
+**⑤ Human sign-off**
+- Output format check (CSV headers row 1, no preamble/blank rows; filenames carry record counts).
+- README completeness (assumptions enumerated, QC results, business context). Flag for the human.
+
+## Tiers & halting
+- **Hard-halt** findings (Critical, count mismatch, dup gap, reconciliation break) → verdict
+  REQUEST-CHANGES with structured remediation.
+- **Warn** findings (perf, style) → list but don't block.
+- **Info** (distributions) → record.
+
+## Deep mode (`--deep`) — adversarial panel
+For high-blast-radius work (compliance/regulatory pulls, irreversible writes), replace the single
+pass with a panel, using the host agent's own subagents (the `Agent` tool):
+1. **Fan out** one independent `qc-reviewer` subagent per pyramid layer (① dialect-lint ·
+   ② counts&dedup · ③ cross-source reconcile · ④ re-run + anti-pattern sweep) — each scoped to its
+   layer, re-running its own queries, returning findings only. Run them in parallel.
+2. **Adversarially verify** every reported finding before it counts: a second pass re-reads the
+   cited `file:line` / re-runs the query and rules each finding confirmed / false-positive /
+   **uncertain**. A finding it cannot reproduce is **uncertain, not dismissed** — silently dropping
+   a Critical / count / reconcile finding is the expensive failure. Only a clear, demonstrated
+   non-issue is ruled false-positive.
+3. **Synthesize** confirmed findings (deduped across layers) into one verdict — and **carry
+   uncertain findings into the verdict too**: any uncertain Critical / count / reconcile finding
+   forces REQUEST-CHANGES (or explicit human sign-off), never a silent APPROVE.
+
+Default (no flag) is the single `qc-reviewer` pass. `/ticket` recommends `--deep` automatically for
+high-risk tickets (external/compliance deliverables, irreversible writes) — reach for it whenever
+the cost of a missed defect is high.
+
+## Phase N — Verdict
+Emit the structured report (Summary · pyramid results per layer · findings by severity ·
+verification queries run · **APPROVE** or **REQUEST-CHANGES**). Save it into the ticket's
+`qc_queries/` for the audit trail. APPROVE ⇒ recommend `/ship <id>`.