ticketwright 2.0.0__tar.gz

ticketwright-2.0.0/.claude/agents/qc-reviewer.md

@@ -0,0 +1,50 @@
+---
+name: qc-reviewer
+description: Independent, read-only quality reviewer for a ticket's deliverables. Re-runs queries via the configured warehouse adapter, walks the validation pyramid, sweeps anti-patterns, and returns an APPROVE / REQUEST-CHANGES verdict. Spawn from /review (or before any ship) for a true second-context pass. Tool-agnostic via stack.yaml.
+tools: Read, Bash, Glob, Grep
+---
+
+# QC Reviewer (sub-agent)
+
+You are an **independent** reviewer with fresh context — you did not write this work. Your job is to
+verify a ticket's deliverables and return a clear verdict, not to fix code (the build owns fixes).
+You re-run things yourself; you do not trust the author's claimed numbers.
+
+## Setup
+1. Read `.claude/config/stack.yaml`. Load `seams.warehouse.adapter` and its `dialect_notes`
+   (function names, sizing model, dedup idiom, cast/filter rules, dialect anti-patterns). If no
+   warehouse seam, review is code/output/doc only.
+2. Read the ticket README, the spec (if any), and list `final_deliverables/` + `qc_queries/`.
+
+## Walk the validation pyramid (cheap→expensive, automated→human)
+1. **Dialect lint** (per `dialect_notes`): `=NULL` vs `IS NULL`; unguarded division; `SELECT *` in
+   deliverables; functions on filtered columns; cross-source type mismatch (missing cast); hardcoded
+   values that should be params; `LEFT JOIN` predicate misplaced into `WHERE`; `NOT IN` with nullable
+   columns; `UNION` vs `UNION ALL`; missing required schema/instance filters.
+2. **Counts & dedup** (re-run independently via the adapter's `query`): re-derive the row count and
+   compare to the documented one; **duplicate detection is the primary test** — `COUNT(*)` vs
+   `COUNT(DISTINCT <grain key>)`; NULL-rate on key columns; value-range sanity.
+3. **Cross-source reconciliation**: join-match rates (quantify unmatched `LEFT JOIN` rows);
+   date ranges within scope; totals reconciled against the source of truth within tolerance.
+4. **Independent re-run + anti-pattern sweep**: re-execute the main deliverable end-to-end; diff to
+   the committed output (byte-level for CSVs — deterministic outputs need explicit `ORDER BY`). Sweep
+   correctness / performance / data-quality / dialect / maintainability anti-patterns; classify each
+   Critical / Should-fix / Review.
+5. **Output & docs**: CSV headers row 1, no preamble/blank rows, filenames carry record counts;
+   README has assumptions enumerated + QC results + business context.
+
+## Tiers
+Hard-halt: Critical findings, count mismatch, duplicate-gap, reconciliation break → **REQUEST-CHANGES**.
+Warn: performance/style → list, don't block. Info: distributions → record.
+
+## Output (return this; it is the tool result, not a chat message)
+```
+## QC Review — <TICKET-ID>
+Verdict: APPROVE | REQUEST-CHANGES
+Pyramid: lint <ok/n> · counts&dedup <ok/n> · reconcile <ok/n> · re-run-diff <ok/n> · output&docs <ok/n>
+Findings:
+  - [Critical|Should-fix|Review] <file:line> — <what> — <remediation>
+Verification queries run:
+  - <each query you executed independently>
+```
+Read-only: never edit code, never post anything, never approve a merge — that's the human's call.

ticketwright-2.0.0/.claude/commands/build-context-pack.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /refresh context instead. Will be removed in v3.
+---
+
+# /build-context-pack (renamed in v2.0)
+
+This command is now part of `/refresh context`. Invoke the `refresh` skill with the same arguments: $ARGUMENTS
+Pass `context` mode.

ticketwright-2.0.0/.claude/commands/build-ticket-index.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /refresh index instead. Will be removed in v3.
+---
+
+# /build-ticket-index (renamed in v2.0)
+
+This command is now part of `/refresh index`. Invoke the `refresh` skill with the same arguments: $ARGUMENTS
+Pass `index` mode.

ticketwright-2.0.0/.claude/commands/configure-workspace.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /setup instead. Will be removed in v3.
+---
+
+# /configure-workspace (renamed in v2.0)
+
+This command is now part of `/setup`. Invoke the `setup` skill with the same arguments: $ARGUMENTS
+

ticketwright-2.0.0/.claude/commands/deliver-ticket.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /ship instead. Will be removed in v3.
+---
+
+# /deliver-ticket (renamed in v2.0)
+
+This command is now part of `/ship`. Invoke the `ship` skill with the same arguments: $ARGUMENTS
+

ticketwright-2.0.0/.claude/commands/onboard-teammate.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /setup --teammate instead. Will be removed in v3.
+---
+
+# /onboard-teammate (renamed in v2.0)
+
+This command is now part of `/setup --teammate`. Invoke the `setup` skill with the same arguments: $ARGUMENTS
+Pass `--teammate` mode.

ticketwright-2.0.0/.claude/commands/prime-domain.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /ticket instead. Will be removed in v3.
+---
+
+# /prime-domain (renamed in v2.0)
+
+This command is now part of `/ticket`. Invoke the `ticket` skill with the same arguments: $ARGUMENTS
+Context priming now runs automatically inside `/ticket` (slice details: `skills/ticket/priming.md`).

ticketwright-2.0.0/.claude/commands/prime-ticket.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /ticket instead. Will be removed in v3.
+---
+
+# /prime-ticket (renamed in v2.0)
+
+This command is now part of `/ticket`. Invoke the `ticket` skill with the same arguments: $ARGUMENTS
+Context priming now runs automatically inside `/ticket` (slice details: `skills/ticket/priming.md`).

ticketwright-2.0.0/.claude/commands/prime-warehouse.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /ticket instead. Will be removed in v3.
+---
+
+# /prime-warehouse (renamed in v2.0)
+
+This command is now part of `/ticket`. Invoke the `ticket` skill with the same arguments: $ARGUMENTS
+Context priming now runs automatically inside `/ticket` (slice details: `skills/ticket/priming.md`).

ticketwright-2.0.0/.claude/commands/productize-workflow.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /productize instead. Will be removed in v3.
+---
+
+# /productize-workflow (renamed in v2.0)
+
+This command is now part of `/productize`. Invoke the `productize` skill with the same arguments: $ARGUMENTS
+

ticketwright-2.0.0/.claude/commands/qc-review.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /review instead. Will be removed in v3.
+---
+
+# /qc-review (renamed in v2.0)
+
+This command is now part of `/review`. Invoke the `review` skill with the same arguments: $ARGUMENTS
+

ticketwright-2.0.0/.claude/commands/recall.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /ticket --recall instead. Will be removed in v3.
+---
+
+# /recall (renamed in v2.0)
+
+This command is now part of `/ticket --recall`. Invoke the `ticket` skill with the same arguments: $ARGUMENTS
+Pass `--recall` mode (standalone prior-art lookup, no workspace setup).

ticketwright-2.0.0/.claude/commands/start-ticket.md

@@ -0,0 +1,8 @@
+---
+description: Deprecated v1 alias — use /ticket instead. Will be removed in v3.
+---
+
+# /start-ticket (renamed in v2.0)
+
+This command is now part of `/ticket`. Invoke the `ticket` skill with the same arguments: $ARGUMENTS
+

ticketwright-2.0.0/.claude/config/stack.example.asana-bq.yaml

@@ -0,0 +1,67 @@
+# stack.example.asana-bq.yaml — ABSTRACTION PROOF (hypothetical repo).
+# A completely different stack — Asana + BigQuery + Teams + SharePoint + GitLab — with the SAME
+# skills and SAME verb contract. Nothing in .claude/skills/** changes; only this file + adapters do.
+# Try it: bash bin/verify_stack.sh .claude/config/stack.example.asana-bq.yaml --dry-run
+
+project:
+  key_prefix: GROW                      # a tag added to task names for branch parity
+  assignee_dir: ana
+  ticket_path: "tickets/{assignee}/{id}"
+  ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]
+  default_epic: null                    # Asana has no Epics; create_ticket uses a project section
+  terminal_status: Done
+  word_limits: {tracker_comment: 120, chat: 120, pr: 200, ticket: 200}
+
+seams:
+  tracker:
+    tool: asana
+    adapter: adapters/tracker/asana.md
+    transport: mcp
+    workspace_gid: "1122334455"
+    default_project_gid: "9988776655"
+    verify: null                        # MCP-only
+
+  warehouse:
+    tool: bigquery
+    adapter: adapters/warehouse/bigquery.md
+    transport: cli
+    project: growth-analytics-prod
+    dataset: analytics
+    dev_dataset: analytics_dev
+    verify: "bq query --use_legacy_sql=false --dry_run 'SELECT 1'"
+
+  chat:
+    tool: teams
+    adapter: adapters/chat/teams.md
+    transport: mcp
+    channel: "Data Team / General"
+    default_mode: draft
+    always_include: [Ana]
+    verify: null
+
+  docstore:
+    tool: sharepoint
+    adapter: adapters/docstore/sharepoint.md
+    transport: cli
+    base_path: "/Users/ana/Library/CloudStorage/OneDrive-Growth/Data Tickets"
+    verify: "test -d \"{base_path}\""
+
+  vcs:
+    tool: gitlab
+    adapter: adapters/vcs/gitlab.md
+    transport: cli
+    default_branch: main
+    semantic_pr: true
+    worktree_root: ".worktrees"
+    verify: "glab auth status"
+
+policies:
+  hard_halt_before_external_posts: true
+  db_write_requires_approval: true
+  chat_default_draft: true
+  hyperlink_everything: true
+  commandify_everything: true
+  reduce_assumptions: true
+  commit_plan_before_implement: true
+  system_evolution: true
+  deterministic_outputs: true

ticketwright-2.0.0/.claude/config/stack.example.azure.yaml

@@ -0,0 +1,73 @@
+# stack.example.azure.yaml — ABSTRACTION PROOF (hypothetical Microsoft-stack repo).
+# Azure DevOps (Boards) + Synapse + Teams + SharePoint + Azure Repos — the SAME skills and SAME
+# verb contract as the Jira/Snowflake and Asana/BigQuery examples. Only this file + adapters change.
+# Try it: bash bin/verify_stack.sh .claude/config/stack.example.azure.yaml --dry-run
+
+project:
+  key_prefix: ENG                       # branch/index display convention (ADO ids are bare integers)
+  key_prefixes: [ENG]
+  assignee_dir: dana
+  ticket_path: "tickets/{assignee}/{id}"
+  ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]
+  default_epic: 12                      # Azure Boards work-item id (integer) for the parent epic
+  terminal_status: Closed               # Agile process "done" state
+  ticket_url_template: "https://dev.azure.com/acme-corp/Platform/_workitems/edit/{number}"  # ADO ids are integers → use {number}, not {id}
+  word_limits: {tracker_comment: 100, chat: 100, pr: 200, ticket: 200}
+
+seams:
+  tracker:
+    tool: azure-devops
+    adapter: adapters/tracker/azure-devops.md
+    transport: cli
+    org: acme-corp
+    project: Platform
+    done_state: Closed
+    verify: "az boards work-item show --id {default_epic}"
+
+  warehouse:
+    tool: synapse
+    adapter: adapters/warehouse/synapse.md
+    transport: cli
+    server: acme-synapse-ondemand.sql.azuresynapse.net
+    database: analytics
+    dev_schema: dev
+    verify: "sqlcmd -S {server} -d {database} -G --authentication-method ActiveDirectoryDefault -Q \"SELECT 1\""
+
+  chat:
+    tool: teams
+    adapter: adapters/chat/teams.md
+    transport: mcp
+    channel: "Data Platform / General"
+    default_mode: draft
+    always_include: [Dana]
+    verify: null
+
+  docstore:
+    tool: sharepoint
+    adapter: adapters/docstore/sharepoint.md
+    transport: cli
+    base_path: "/Users/dana/Library/CloudStorage/OneDrive-AcmeCorp/Data Tickets"
+    verify: "test -d \"{base_path}\""
+
+  vcs:
+    tool: azure-repos
+    adapter: adapters/vcs/azure-repos.md
+    transport: cli
+    org: acme-corp
+    project: Platform
+    repo: analytics
+    default_branch: main
+    semantic_pr: true
+    worktree_root: ".worktrees"
+    verify: "az repos list --project {project} --query \"[].name\""
+
+policies:
+  hard_halt_before_external_posts: true
+  db_write_requires_approval: true
+  chat_default_draft: true
+  hyperlink_everything: true
+  commandify_everything: true
+  reduce_assumptions: true
+  commit_plan_before_implement: true
+  system_evolution: true
+  deterministic_outputs: true

ticketwright-2.0.0/.claude/config/stack.schema.md

@@ -0,0 +1,76 @@
+# `stack.yaml` — the tool registry (schema + policies)
+
+`stack.yaml` is the **single source of truth** for which concrete tool fills each abstract "seam"
+and for the project facts the skills need. Skills never hardcode `acli`, `snow`, `slack`, channel
+IDs, epics, or paths — those live **here** and in the per-tool adapters. Swapping Jira→Asana or
+Snowflake→BigQuery means editing this file and pointing at a different adapter; **no skill changes.**
+
+The `setup` skill writes this file by interviewing you and detecting installed tooling.
+`bin/verify_stack.sh` reads it to smoke-test every seam. Every skill reads it at preflight.
+
+---
+
+## Top-level shape
+
+```yaml
+project:        # facts about this workspace, tool-independent
+seams:          # one entry per abstract seam → concrete tool + adapter + verify
+policies:       # behavioral rules every skill inherits (the kit's "global rules")
+```
+
+---
+
+## `project`
+
+| Field | Type | Example | Meaning |
+|---|---|---|---|
+| `key_prefix` | string | `ENG` | Ticket-ID prefix. Branch names = `{key_prefix}-NNNN`. |
+| `key_prefixes` | list | `[ENG]` | Prefixes the ticket index recognizes in folder names. Optional; defaults to `[key_prefix]`. Use when one repo holds tickets from several trackers (e.g. `[ENG, OPS]`). |
+| `assignee_dir` | string | `alice` | Default owner subdir under `tickets/`. |
+| `ticket_path` | template | `tickets/{assignee}/{id}` | Where a ticket folder lives. `{assignee}` `{id}` tokens. |
+| `ticket_subdirs` | list | `[source_materials, final_deliverables, qc_queries, exploratory_analysis]` | Scaffolded per ticket. |
+| `default_epic` | string \| null | `ENG-100` | Parent epic for newly created tickets (null if tracker has no epics). |
+| `terminal_status` | string | `Done` | The "done" workflow state (not always "Done"). |
+| `ticket_url_template` | template \| null | `https://acme.atlassian.net/browse/{id}` | How `tickets/INDEX.md` links each ticket (`{id}` token). Null/omitted → the index renders no per-ticket link. |
+| `word_limits` | map | `{tracker_comment: 100, chat: 100, pr: 200, ticket: 200}` | Hard caps the comms skills enforce. |
+
+## `seams`
+
+Exactly these five keys: `tracker`, `warehouse`, `chat`, `docstore`, `vcs`. Each:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `tool` | string | The concrete tool, e.g. `jira` / `asana` / `monday` / `linear`. |
+| `adapter` | path | The playbook that maps the verb contract → this tool's commands. |
+| `verify` | string \| null | A **read-only** smoke-test command. `{token}` interpolation from this seam's own keys + `project`. `null` = skip (skills warn). Non-zero exit ⇒ seam "unreachable". |
+| `transport` | enum | `cli` \| `mcp` \| `both` — how the adapter talks to the tool. Drives the verify fallback. |
+| *(extra keys)* | any | Tool-specific config the adapter reads (site, warehouse, role, channel, base_path, …). |
+
+The `warehouse` seam may also be `null`/omitted for non-data repos — `review`, `spec-and-build`,
+and `refresh context` degrade gracefully (skip warehouse steps) when it is.
+
+## `policies` (the 9 kit policies — see kit README "AI-layer" section)
+
+| Policy | Default | Enforced by |
+|---|---|---|
+| `hard_halt_before_external_posts` | `true` | `ship`, every productized skill — pause for human go before any tracker/chat/docstore write. |
+| `db_write_requires_approval` | `true` | any skill issuing a non-SELECT — show SQL, explain, wait for `yes`. |
+| `chat_default_draft` | `true` | `chat.draft` not `chat.send` unless the user says "send it". |
+| `hyperlink_everything` | `true` | comms skills wrap every ticket-ID / file / PR in a smart link. |
+| `commandify_everything` | `true` | recurring work → `productize`, not a one-off. |
+| `reduce_assumptions` | `true` | ask before building; still document every assumption in the ticket README. |
+| `commit_plan_before_implement` | `true` | `spec-and-build` commits the spec/plan artifact before `build` (blame-free retry). |
+| `system_evolution` | `true` | `ship` retro: a failure fixes the AI layer (rule/context/command/adapter), not just the ticket. |
+| `deterministic_outputs` | `true` | data exports use explicit `ORDER BY`; productized skills ship golden-replay diffs. |
+
+`always_include` (under `seams.chat`) — names always added to a chat message (e.g. `[Alice]`); the
+"never solo-DM a stakeholder" rule.
+
+---
+
+## Worked example
+
+A worked example lives at [`stack.yaml`](stack.yaml) (Jira/Snowflake/Slack/Drive/GitHub). Two more
+prove the abstraction holds with zero skill edits: `stack.example.asana-bq.yaml`
+(Asana/BigQuery/Teams/SharePoint/GitLab) and `stack.example.azure.yaml`
+(Azure DevOps/Synapse/Teams/SharePoint/Azure Repos). To validate any config: `bash bin/verify_stack.sh`.

ticketwright-2.0.0/.claude/config/stack.yaml

@@ -0,0 +1,76 @@
+# stack.yaml — the tool registry + project facts + policies (single source of truth).
+#
+# This is a WORKED EXAMPLE for a fictional "Acme" data team (Jira / Snowflake / Slack /
+# Google Drive / GitHub). Replace the values with your own, or run `/setup`
+# to generate this file by detecting your tooling and interviewing you.
+# Field docs: stack.schema.md  ·  Validate: bash bin/verify_stack.sh .claude/config/stack.yaml
+# Two more examples live alongside this file: stack.example.asana-bq.yaml (Asana/BigQuery/Teams/
+# SharePoint/GitLab) and stack.example.azure.yaml (Azure DevOps/Synapse/Teams/SharePoint/Azure Repos).
+
+project:
+  key_prefix: ENG                       # ticket-ID prefix; branch names = {key_prefix}-NNNN
+  key_prefixes: [ENG]                   # prefixes the ticket index recognizes (defaults to [key_prefix])
+  assignee_dir: alice                   # default owner subdir under tickets/
+  ticket_path: "tickets/{assignee}/{id}"
+  ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]
+  default_epic: ENG-100                 # parent epic for new tickets (or null if the tracker has no epics)
+  terminal_status: Done                 # the workflow's "done" state (not always "Done")
+  ticket_url_template: "https://acme.atlassian.net/browse/{id}"  # how INDEX.md links a ticket ({id} token); omit/null = no link
+  word_limits: {tracker_comment: 100, chat: 100, pr: 200, ticket: 200}
+
+seams:
+  tracker:
+    tool: jira
+    adapter: adapters/tracker/jira.md
+    transport: both
+    site: acme.atlassian.net
+    cli: acli
+    mcp: atlassian
+    verify: "acli jira workitem view {default_epic}"
+
+  warehouse:
+    tool: snowflake
+    adapter: adapters/warehouse/snowflake.md
+    transport: both
+    cli: snow
+    default_warehouse: ANALYTICS_WH
+    pii_role: PII_READER
+    dev_db: ANALYTICS_DEV
+    verify: "snow connection test"
+
+  chat:
+    tool: slack
+    adapter: adapters/chat/slack.md
+    transport: mcp
+    mcp: slack
+    default_channel: C0XXXXXXXXX         # your channel's ID
+    default_mode: draft
+    always_include: [Alice]              # names always added to a chat message (never solo-DM a stakeholder)
+    verify: null                         # MCP-only: skills check reachability via an MCP call, not the shell
+
+  docstore:
+    tool: gdrive
+    adapter: adapters/docstore/gdrive.md
+    transport: cli
+    base_path: "/path/to/your/Shared drives/Tickets"
+    verify: "test -d \"{base_path}\""
+
+  vcs:
+    tool: github
+    adapter: adapters/vcs/github.md
+    transport: cli
+    default_branch: main
+    semantic_pr: true
+    worktree_root: ".claude/worktrees"
+    verify: "gh auth status"
+
+policies:
+  hard_halt_before_external_posts: true
+  db_write_requires_approval: true
+  chat_default_draft: true
+  hyperlink_everything: true
+  commandify_everything: true
+  reduce_assumptions: true
+  commit_plan_before_implement: true
+  system_evolution: true
+  deterministic_outputs: true

ticketwright-2.0.0/.claude/hooks/db_write_guard.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""PreToolUse hook — mechanical enforcement of the `db_write_requires_approval` policy.
+
+The starter kit's policies are only as good as the agent's memory unless something
+enforces them. This hook makes the DB-write rule mechanical: when a Bash tool call
+invokes a configured warehouse CLI with a *destructive* statement (CREATE/ALTER/DROP/
+DELETE/UPDATE/INSERT/TRUNCATE/MERGE/GRANT/REVOKE/REPLACE), it returns an `ask`
+permission decision so the human must confirm — exactly the "show SQL → explain →
+wait for yes" protocol, applied by the runtime rather than trusted to the model.
+
+Read-only statements (SELECT/DESCRIBE/SHOW/EXPLAIN/WITH/LIST/GET_DDL) pass straight
+through. Non-warehouse Bash and non-Bash tools pass through untouched.
+
+Wire it in settings.json:
+  "hooks": { "PreToolUse": [ { "matcher": "Bash",
+    "hooks": [ { "type": "command", "command": "python3 .claude/hooks/db_write_guard.py" } ] } ] }
+
+Input  (stdin): Claude Code PreToolUse JSON { tool_name, tool_input:{command}, cwd, ... }
+Output (stdout): on a destructive write, the permissionDecision JSON below; otherwise nothing.
+Stdlib only. Always exits 0 — a guard must never crash a session (fail-open, but it
+only ever *adds* a confirmation, never bypasses one).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# CLIs that talk to a data warehouse / database. Extended from stack.yaml if present.
+DEFAULT_WAREHOUSE_CLIS = ["snow", "snowsql", "bq", "databricks", "dbsqlcli", "psql", "mysql", "sqlcmd", "duckdb", "redshift-data"]
+
+DESTRUCTIVE = re.compile(
+    r"\b(CREATE\s+OR\s+REPLACE|CREATE|ALTER|DROP|DELETE|UPDATE|INSERT|TRUNCATE|MERGE|GRANT|REVOKE|REPLACE\s+INTO)\b",
+    re.IGNORECASE,
+)
+
+
+def find_stack_yaml(cwd: str) -> Path | None:
+    candidates = []
+    if os.environ.get("CLAUDE_PROJECT_DIR"):
+        candidates.append(Path(os.environ["CLAUDE_PROJECT_DIR"]) / ".claude/config/stack.yaml")
+    if cwd:
+        candidates.append(Path(cwd) / ".claude/config/stack.yaml")
+    # hook lives at <kit>/.claude/hooks/ → config is a sibling
+    candidates.append(Path(__file__).resolve().parent.parent / "config/stack.yaml")
+    for c in candidates:
+        if c.is_file():
+            return c
+    return None
+
+
+def warehouse_clis(stack: Path | None) -> list[str]:
+    clis = list(DEFAULT_WAREHOUSE_CLIS)
+    if stack:
+        try:
+            text = stack.read_text(errors="replace")
+            # tiny scan: a `cli: <name>` line under the warehouse seam (no yaml dep)
+            m = re.search(r"warehouse:.*?(?:\n\s+cli:\s*([A-Za-z0-9_-]+))", text, re.DOTALL)
+            if m and m.group(1) not in clis:
+                clis.insert(0, m.group(1))
+        except OSError:
+            pass
+    return clis
+
+
+def invokes_warehouse(command: str, clis: list[str]) -> str | None:
+    for cli in clis:
+        # word-boundary match so "show" doesn't match inside another word
+        if re.search(rf"(^|[\s;&|(]){re.escape(cli)}(\s|$)", command):
+            return cli
+    return None
+
+
+# SQL can live in a file rather than the command line — via -f/--file/--filename, OR via a shell
+# stdin redirect (`psql db < deploy.sql`). Scan both so a destructive statement can't slip past.
+_FILE_FLAG = re.compile(r"(?:-f|-i|--file|--filename|--input-file)[=\s]+([^\s;|&]+)")
+_STDIN_REDIR = re.compile(r"<\s*([^\s;|&<>]+)")
+
+
+def referenced_sql(command: str, cwd: str) -> str:
+    """Concatenate the text of any SQL files the command runs via -f/--filename or `< file`, so the
+    destructive scan sees `snow sql -f deploy.sql` / `psql < deploy.sql` content too. Size-capped."""
+    text = ""
+    for raw in _FILE_FLAG.findall(command) + _STDIN_REDIR.findall(command):
+        p = Path(raw)
+        if not p.is_absolute() and cwd:
+            p = Path(cwd) / raw
+        try:
+            if p.is_file() and p.stat().st_size < 1_000_000:
+                text += "\n" + p.read_text(errors="replace")
+        except OSError:
+            continue
+    return text
+
+
+def emit_ask(reason: str) -> None:
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason": reason,
+        }
+    }))
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0  # not invoked as a hook / no payload — do nothing
+
+    if payload.get("tool_name") != "Bash":
+        return 0
+    command = (payload.get("tool_input") or {}).get("command", "") or ""
+    if not command.strip():
+        return 0
+
+    stack = find_stack_yaml(payload.get("cwd", ""))
+    clis = warehouse_clis(stack)
+
+    cli = invokes_warehouse(command, clis)
+    if not cli:
+        return 0  # not a warehouse command
+
+    # Scan the inline command AND any SQL files it runs via -f/--filename.
+    scan_text = command + referenced_sql(command, payload.get("cwd", ""))
+
+    verb_match = DESTRUCTIVE.search(scan_text)
+    if not verb_match:
+        return 0  # read-only / non-destructive — let it through
+
+    verb = verb_match.group(1).upper()
+    reason = (
+        f"db_write_requires_approval: this `{cli}` command contains a destructive statement "
+        f"({verb}). Per the kit's policy, confirm the exact SQL and target environment before "
+        f"running — show what it changes and proceed only on explicit approval."
+    )
+    emit_ask(reason)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())