ticketwright 2.0.0__py3-none-any.whl

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

@@ -0,0 +1,59 @@
+---
+name: setup
+description: Set up Ticketwright in a repo — detect your tools, ask at most 5 questions, write the config, scaffold folders. Also onboards a teammate (--teammate) and adopts existing repos.
+argument-hint: "(none) | --teammate [name] | <seam-to-add: chat|docstore|warehouse>"
+allowed-tools: [Read, Write, Edit, Bash, Glob, AskUserQuestion]
+disable-model-invocation: true
+---
+
+# /setup
+
+One skill, three jobs: **configure a repo** (run once), **add a tool later** (`/setup chat`), and
+**onboard a person** (`/setup --teammate`). Detect first, ask last: the goal is a working setup
+after **at most 5 questions**.
+
+## Mode: `--teammate` — onboard a person to an already-configured repo
+Follow [teammate.md](teammate.md): install checklist → per-tool auth walk-through → verify →
+read-the-map → guided first-ticket dry run. Requires an existing `stack.yaml`.
+
+## Mode: `<seam>` — add one tool to an existing config
+E.g. `/setup chat`. Detect candidates for just that seam, ask one question, add the seam block to
+`stack.yaml`, verify it, and re-render `AGENTS.md`. Nothing else changes.
+
+## Default mode — configure the repo
+
+### Phase 1 — Detect (no questions yet)
+1. **CLIs:** `!for c in snow acli gh glab bq databricks yq jq git; do command -v $c >/dev/null && echo "✓ $c" || echo "– $c"; done`
+2. **MCP servers** connected this session (tracker / chat / warehouse servers).
+3. **Existing state:** if `.claude/config/stack.yaml` exists → offer to edit, don't overwrite.
+   If the repo already has ticket folders, an index, or custom `.claude/commands` → this is an
+   **existing repo**: switch to [adopt.md](adopt.md) (map onto what's there; write MIGRATION.md).
+
+### Phase 2 — Ask (≤ 5 questions, detected options pre-selected, defaults visible)
+One AskUserQuestion round covering only:
+1. **Tracker** (detected options first);
+2. **Warehouse** (or *none* — non-data repos are fine);
+3. **VCS**;
+4. **Ticket key prefix** (e.g. `ENG`) — and accept the tracker's project key as the default;
+5. **Assignee folder name** (default: the user's short name).
+Everything else ships as a **commented default** the user can edit later: chat + docstore seams
+(add via `/setup chat` / `/setup docstore`), `default_epic`, `terminal_status` (default `Done`),
+word limits, role (`generalist`), and all 9 policies at their defaults. Each chosen tool's required
+keys (per its adapter's `requires:` frontmatter): take the detected value where possible; otherwise
+include the key commented with a `# TODO` and keep going — `verify` will point at it.
+
+### Phase 3 — Write & scaffold
+4. Compose `.claude/config/stack.yaml` per `stack.schema.md` (chosen seams live; optional seams as
+   commented blocks; the 9 policies with a one-line "when to change this" comment each). Warn if a
+   chosen adapter is `status: stub`.
+5. Scaffold the repo per [scaffold.md](scaffold.md): render `AGENTS.md` (+ role focus),
+   `.claude/settings.json` (hooks + read-only CLI allows), folders, `.gitignore` (with the
+   anchored `**/final_deliverables/*.csv` export guard), the AI-layer index, and the seeded ticket
+   index.
+
+### Phase 4 — Verify & hand off
+6. Run `!bash "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/selftest.sh"` (kit integrity — a failure here is fatal) and
+   `!bash "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/verify_stack.sh"` (per-seam reachability — an unreachable seam is
+   **not** fatal at setup time; print its adapter's auth notes as the fix).
+7. **Report:** the chosen stack, files written, any `# TODO` keys or stub adapters, and the next
+   step — `/ticket <id>` to start work, or `/setup --teammate` for a new person.

ticketwright/_kit/.claude/skills/setup/adopt.md

@@ -0,0 +1,43 @@
+# Adopt mode — set up Ticketwright on a repo that already has ticket work
+
+Triggered automatically when Phase 1 detection finds an existing repo: ticket-looking folders
+(`tickets/**` or similar), an existing `INDEX.md`, an `AGENTS.md`/`CLAUDE.md`, or custom
+`.claude/commands` / `.claude/skills`. The rule: **map onto what exists — never scaffold over it,
+never demand a rewrite.**
+
+## 1 · Inventory what's there (read-only)
+- **Ticket layout:** find the ticket folders and infer `project.ticket_path` from the observed
+  structure (e.g. `tickets/{assignee}/{id}`), the key prefix(es) from folder names, and the
+  assignee dirs. Confirm the inference with the user in ONE question.
+- **Tools in use:** infer seams from evidence — CI configs, helper scripts, MCP servers, CLIs on
+  PATH, existing docs. Pre-select these in the (still ≤5-question) interview.
+- **Custom commands/skills:** list everything in `.claude/commands/` and `.claude/skills/` and
+  classify each against the plugin's skills: **shadows** (does what a plugin skill does),
+  **extends** (domain-specific variant — e.g. a warehouse-specific spec/build flow), or
+  **unrelated** (keep as-is).
+- **Existing rules file:** if `AGENTS.md`/`CLAUDE.md` exists, do NOT overwrite it.
+
+## 2 · Write config from observed reality
+Compose `stack.yaml` from the inventory + interview answers. Point `project.*` at the *existing*
+layout. Skip any scaffold step whose target already exists (folders, `.gitignore` — merge new rules
+in, never replace).
+
+## 3 · Non-destructive scaffold
+- `AGENTS.md` exists → render the template to `AGENTS.ticketwright.md` instead and note the diff
+  worth merging (the stack table, the policies, the lifecycle line). The human merges.
+- Ticket index: seed `index_data.json` only if absent; then `/refresh index --all` to bootstrap
+  the catalog over the existing backlog (deterministic render first, curated enrichment after).
+
+## 4 · Write `MIGRATION.md` (the adoption checklist)
+One row per finding, with a recommendation:
+| Item | Classification | Recommendation |
+|---|---|---|
+| custom `start-work.md` command | shadows `/ticket` | **replace** — plugin covers it; delete after a trial ticket |
+| custom warehouse-specific spec/build flow | extends `/spec-and-build` | **keep** — domain-optimized; note it in AGENTS.md |
+| hand-maintained rules file | overlaps rendered AGENTS.md | **merge** — adopt the stack table + policies block |
+Include: what was auto-configured, what needs a human decision, and the suggested trial — run ONE
+real ticket through `/ticket → /review → /ship` before deleting anything custom.
+
+## 5 · Verify & report
+Same as Phase 4 of the default mode (selftest + verify_stack). The report leads with the
+MIGRATION.md path and the trial-ticket suggestion — adoption is incremental by design.

ticketwright/_kit/.claude/skills/setup/scaffold.md

@@ -0,0 +1,38 @@
+# Scaffold details — what `/setup` writes into a fresh repo
+
+## Global rules (`AGENTS.md`)
+Render `templates/AGENTS.md.tmpl` → `AGENTS.md` (tokens from `stack.yaml`: tool names, key_prefix,
+terminal_status, word limits, policies). Fill `{{role_focus}}` from `templates/roles/<role>.md`
+using `project.role` (`generalist` unless the user changed it). This is the always-loaded tier —
+keep it the rendered template; repo-specific rules get added by humans over time.
+
+## Hooks + settings (`.claude/settings.json`)
+Render `.claude/settings.json.tmpl` → `.claude/settings.json`, keeping the `hooks` block:
+- **PreToolUse** `db_write_guard.py` — makes `db_write_requires_approval` mechanical: asks before
+  any destructive warehouse statement, even one hidden in a `-f` file;
+- **SessionStart** `session_context.py` + `ticket_index_context.py` — primes each session with the
+  stack + the ticket catalog;
+- **PostToolUse** `regenerate_ticket_index.py` — keeps `tickets/INDEX.md` fresh on folder changes;
+plus the statusline. Then append the chosen warehouse/tracker/vcs **read-only** CLI allows to
+`permissions.allow` (e.g. `Bash(<warehouse_cli> …:*)`). Confirm `.claude/hooks/` and
+`.claude/statusline.sh` are present (plugin installs run them from `${CLAUDE_PLUGIN_ROOT}`).
+
+## Folders + `.gitignore`
+Create `tickets/{assignee_dir}/`, `documentation/`, `resources/`, `specs/` (and `ci/` if wanted).
+Render `templates/gitignore.tmpl` → `.gitignore` (merge if one exists). It ships the **anchored**
+`**/final_deliverables/*.csv` rule so ticket exports (customer data) can't be silently committed at
+any depth — *exports go to the docstore, not git*. If the tracker adapter ships an
+attachment-download helper, copy it into `resources/`.
+
+## AI-layer index (`documentation/AI_LAYER_INDEX.md`)
+A one-line-each inventory of the installed skills (`setup`, `ticket`, `spec-and-build`, `review`,
+`ship`, `productize`, `refresh`), the `qc-reviewer` agent, the hooks, and the adapters in use — so
+humans and agents can find what exists.
+
+## Ticket index
+Seed an empty curated store — `tickets/index_data.json` with
+`{"schema_version": 1, "tickets": []}` — then run
+`python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/build_ticket_index.py"` to write the
+initial `tickets/INDEX.md`. From here it self-maintains (PostToolUse regen on folder changes,
+SessionStart surfacing, curated summaries at ship time). An existing backlog gets bootstrapped with
+`/refresh index --all`.

ticketwright/_kit/.claude/skills/setup/teammate.md

@@ -0,0 +1,33 @@
+# `--teammate` mode — onboard a person to an already-configured repo
+
+Reads `.claude/config/stack.yaml` and the adapters to produce a **personalized, tool-specific
+checklist** and walk it with them. If `stack.yaml` is absent, stop — run plain `/setup` first.
+
+## 1 · Install prerequisites
+Check what's present: `for c in <the CLIs named in stack.yaml seams> yq jq git; do command -v $c
+>/dev/null && echo "✓ $c" || echo "✗ $c (install)"; done`. For each missing tool give the install
+command (Homebrew / winget / apt as appropriate).
+
+## 2 · Authenticate each configured tool
+For every seam, open its adapter's `auth:` notes and walk the person through signing in — tracker
+CLI/MCP auth, warehouse connection (`config.toml`/ADC), chat MCP connect, docstore mount, vcs auth
+login. Pure instructions — the person runs the auth themselves.
+
+## 3 · Verify connectivity
+Run `bash "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/selftest.sh"` first (the kit itself),
+then `bash "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/verify_stack.sh"`. Walk any ✗/⚠ with
+the relevant adapter's auth notes until green (MCP-only seams: confirm the server is connected this
+session). Mention the `db_write_guard` hook so they know destructive warehouse statements prompt
+for confirmation **by design**.
+
+## 4 · Read the map
+Point them at, in order: `AGENTS.md` (the rules — read end to end),
+`documentation/AI_LAYER_INDEX.md` (what exists), and the `documentation/` knowledge pack (built by
+`/refresh context`) for domain grounding. Summarize the lifecycle: **`/ticket` → `/spec-and-build`
+→ `/review` → `/ship`** — context loads automatically inside `/ticket`.
+
+## 5 · Guided first-ticket dry run
+Pick a real, small ticket (or have them name one) and run `/ticket <id>` in **dry-run spirit** —
+set up the workspace and prime context, but stop before any external action so they see the flow
+end to end safely. Explain the hard-halt gates and the DB-write approval protocol as you go.
+Finish with a checklist of done vs outstanding, and hand them their first real ticket.

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

@@ -0,0 +1,53 @@
+---
+name: ship
+description: Finalize and deliver a reviewed ticket — backup, tracker comment, chat draft, commit + PR — with a hard halt before any external post. Run after /review approves.
+argument-hint: <ticket-id> [--go]   (--go authorizes the external Phase B after review)
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
+disable-model-invocation: true
+---
+
+# /ship
+
+Ships a ticket that has **passed `/review`**. Split into a safe Phase A (local, no approval) and a
+gated Phase B (every external side effect), honoring `hard_halt_before_external_posts`. Reads
+`.claude/config/stack.yaml`; routes through the docstore / tracker / chat / vcs adapters, so it
+works regardless of the underlying tools.
+
+## Phase A — Finalize (no approval needed; internal to repo)
+1. Read `stack.yaml` + the ticket README + the `/review` verdict. If the verdict isn't APPROVE,
+   **stop** and send the user back to `/review`.
+2. Re-run the final deliverable queries once more; confirm **byte-identical** output to the
+   committed files (`deterministic_outputs` — explicit `ORDER BY`).
+3. Tidy: remove redundant/version-sprawl files (overwrite, don't duplicate); confirm filenames
+   carry record counts; confirm the README tells the full business + methodology + QC story. Then
+   **refresh this ticket's index entry** so its `tickets/INDEX.md` row gets a curated one-line
+   summary: `python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/enrich_ticket.py" <id>` (or
+   `/refresh index <id>`). The PostToolUse hook already keeps the row present; this upgrades it
+   from auto-derived (`▱`) to curated.
+4. **Draft the comms artifacts** (don't post yet): render the tracker comment and the chat message
+   from the ticket facts. Tracker comment ≤ `word_limits.tracker_comment`; business-first;
+   segmented with counts/%/$. Chat ≤ `word_limits.chat`; includes `seams.chat.always_include`;
+   **hyperlink everything** (`hyperlink_everything`). If chat/docstore aren't configured, skip
+   those artifacts and note `/setup chat` / `/setup docstore` as the enabler — don't block.
+
+## Phase B — External delivery (HARD HALT → requires `--go` or explicit "go ahead")
+Print a summary of exactly what will happen, then **stop and wait** for the user. Only on explicit
+authorization, execute in order:
+5. **docstore.backup** the ticket folder (full-title dest name); then `docstore.link_for` each
+   delivered file to get shareable URLs.
+6. **tracker.comment** — post via the adapter's rich path (smart-link cards for the docstore
+   files). Never before this point (no tracker comments without human review).
+7. **chat.draft** to `seams.chat.default_channel` (policy `chat_default_draft` — the human clicks
+   send unless they said "send it", in which case `chat.send`). Smart links for ticket id(s),
+   files, PR.
+8. **vcs.commit** (stage this ticket's paths **plus `tickets/INDEX.md` + `tickets/OBJECTS.md` +
+   `tickets/index_data.json`** — all three, or `--check` flags drift in CI; semantic message +
+   Co-Authored-By) then **vcs.open_pr** (semantic title; body = Business Impact / Deliverables /
+   Technical Notes / QC).
+9. **transition** the ticket toward `project.terminal_status` if appropriate.
+
+## Phase C — System-evolution retro (always, even on success)
+10. Reflect briefly: did anything go wrong or get re-done this ticket? If so, **which layer was
+    insufficient** — a global rule, the context pack, a skill, or an adapter? Propose the concrete
+    fix to *that* artifact (policy `system_evolution`) and note it. A repeated manual step is a
+    signal to `/productize` it. Fixing the layer, not just the ticket, is what compounds.

ticketwright/_kit/.claude/skills/spec-and-build/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: spec-and-build
+description: Research-rich spec then execute it. `spec` mode writes a PRP-style blueprint (committed before building); `build` mode implements it in fresh context with independent validation. The IMPLEMENT phase.
+argument-hint: spec <ticket-id> "<what to build>" | build <ticket-id> [spec-path]
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent]
+---
+
+# /spec-and-build
+
+The **build** step of the lifecycle, split into two committed steps so planning and execution use
+separate context (context-reset discipline). Generalizes the PRP (product-requirement-prompt) pattern
+(`generate-data-object-prp` → `prp-data-object-execute`) to any warehouse via the adapter.
+
+Reads `.claude/config/stack.yaml`. Front-loads decisions into a spec **before** any code — the
+context-engineering core idea: AI fails from missing context, not weak models.
+
+---
+
+## Mode: `spec` — author the blueprint (this is still PLAN-adjacent; no production writes)
+
+1. **Preflight** the warehouse seam (verify; halt with auth notes if unreachable). If no warehouse
+   configured, the spec is code/analysis-only — proceed without warehouse steps.
+2. **Research in parallel, never implement.** Spawn read-only research (Agent/Explore, or re-run
+   the priming slices from `/ticket` — see `skills/ticket/priming.md`):
+   - explore the objects via `warehouse.describe` + samples; map dependencies + grain;
+   - read the 2–4 closest prior tickets (from `/ticket`'s reuse brief, or
+     `bin/recall.py --for <id>`) and reuse their SQL/QC where it fits;
+   - pull the business rules from the `documentation/` glossary (the domain slice).
+   Research agents return findings only; **they do not write code.**
+3. **Write the spec** from `templates/spec.md.tmpl` into the ticket's folder
+   (`specs/<id>-<slug>.md` or `final_deliverables/`): operation type (new/alter), data grain,
+   sources + join/cast rules, transformation logic, **validation gates** (the exact QC the build must
+   pass), downstream impact, dev-env target (`seams.warehouse.dev_db`), and a **confidence score
+   (1–10)**.
+4. **Reduce assumptions:** before finalizing, list open questions and **ask the user** (don't guess).
+5. **Commit the spec** via vcs `commit` (`docs: <id> spec for <thing>`) — policy
+   `commit_plan_before_implement` enables blame-free retry if the build later reveals a gap.
+
+## Mode: `build` — execute the committed spec (fresh context)
+
+6. **Load** the committed spec (path arg or newest in the ticket's `specs/`). Treat it as the source
+   of truth, but **validate each step independently** — don't blindly follow; the spec can be wrong.
+7. **Implement in small build-and-check sub-loops:** one object/step at a time. Develop against
+   `seams.warehouse.dev_db` first; parameterize values at the top; explicit `ORDER BY` on any export
+   (deterministic outputs).
+8. **Embed validation between steps** — after each, run the relevant gate from the spec; self-correct.
+9. **Any non-SELECT / DDL** ⇒ policy `db_write_requires_approval`: show the exact SQL, explain the
+   change, wait for explicit `yes`. Dev-env objects still get shown but are lower-risk.
+10. **Hand off to the check step:** when the build passes its own gates, stop and recommend
+    `/review <id>` for the independent pass. Do not ship from here.
+
+## Generalizes
+`generate-data-object-prp` + `prp-data-object-execute` + `PRPs/templates/data-object-initial.md`,
+warehouse-agnostic via `seams.warehouse`.

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

@@ -0,0 +1,59 @@
+---
+name: ticket
+description: The front door — open or resume a ticket, auto-load its context and prior art, and route to the next step (spec, build, review, or ship). Start every ticket here.
+argument-hint: <ticket-id> | --create "<summary>" [--type T] [--worktree] | --recall "<topic>" | --recall --object <NAME>
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent]
+---
+
+# /ticket
+
+One command owns the ticket lifecycle: it opens (or creates) the ticket, sets up the workspace,
+loads exactly the context this ticket needs, surfaces the closest prior work, and then tells you the
+right next step — **plan → build → check → ship**. Reads `.claude/config/stack.yaml`; everything
+tool-specific resolves through the adapters, so it works with any configured tracker/warehouse/vcs.
+
+## Mode: `--recall` (standalone prior-art lookup, no workspace setup)
+`/ticket --recall "<topic>"` or `--recall --object <NAME>` — rank prior tickets and write a reuse
+brief, nothing else. Follow [priming.md](priming.md) § Recall. Useful mid-session ("have we built
+this before?", "which tickets touched VW_X?").
+
+## Phase 0 — Resolve & preflight (halt-on-fail)
+1. Read `.claude/config/stack.yaml`: `project.*`, `seams.tracker`, `seams.vcs`. If the file is
+   missing, say so and offer `/setup` — don't scaffold blind.
+2. **Verify** the tracker + vcs seams (run their `verify` commands). If one is unreachable, print
+   that adapter's `auth` notes and offer to continue **local-only** (workspace + context still work;
+   tracker fetch is skipped) — degrade, don't die.
+3. Determine the ticket id: `$ARGUMENTS` id, or (for `--create`) create it first via the tracker
+   adapter's `create_ticket` verb (`project.default_epic` as parent if set), then use the new id.
+
+## Phase 1 — Resume, don't restart
+4. Render `project.ticket_path` → the ticket dir. If it exists: read its `README.md`, list
+   `final_deliverables/`, check `git log --oneline -10` + `git status`, summarize what's done and
+   what remains, re-fetch the ticket for new comments, then **skip to Phase 3**.
+
+## Phase 2 — Workspace (new ticket)
+5. **Branch** via the vcs adapter, named `<id>`, off `seams.vcs.default_branch` — or a **worktree**
+   when `--worktree` is passed (isolates this ticket from other in-flight work; recommended when you
+   run several tickets in parallel).
+6. **Scaffold** `project.ticket_path` with `project.ticket_subdirs`; tracker adapter
+   `download_attachments` → `source_materials/` (silent if none); render
+   `templates/ticket-README.md.tmpl` → the ticket dir.
+
+## Phase 3 — Prime context automatically (the part you never have to ask for)
+7. Follow [priming.md](priming.md), in order:
+   - **Ticket slice** — the ticket body + folder + related prior tickets;
+   - **Recall** — rank prior art (`bin/recall.py`), read the top 2–4, note what to **reuse**;
+   - **Domain slice** — glossary/rules for the ticket's topic (from `documentation/`);
+   - **Warehouse slice** — schemas/samples/lineage for the specific objects in play (skip cleanly
+     if no warehouse is configured).
+   Keep the whole brief tight (≤ ~300 words) — slices, not the whole knowledge base.
+
+## Phase 4 — Route
+8. Report the context brief (including the reuse brief) and the recommended next step:
+   - non-trivial work → `/spec-and-build spec <id>` (blueprint first, build second);
+   - small change → build directly, then `/review <id>`;
+   - after review passes → `/ship <id>`.
+
+## Stops here
+No SQL, no analysis, no external posts. If the request is ambiguous, state your interpretation and
+ask before scaffolding heavy structure (`reduce_assumptions`).

ticketwright/_kit/.claude/skills/ticket/priming.md

@@ -0,0 +1,47 @@
+# Context priming — the four slices `/ticket` loads
+
+Small, scoped priming keeps the build phase focused and cheap. Load *slices*, never the whole
+knowledge base. Each slice below was a separate command in v1 (`/prime-ticket`, `/recall`,
+`/prime-domain`, `/prime-warehouse`); `/ticket` now runs them as one pass.
+
+## 1 · Ticket slice
+
+- **Fetch the ticket** via the tracker adapter's `fetch_ticket` verb (title, description, type,
+  status, links). If the tracker seam is down, fall back to the local `README.md`.
+- **Read the ticket folder** at the rendered `project.ticket_path` if it exists: `README.md` +
+  a listing of `final_deliverables/` — summarize prior progress (resume, don't restart).
+- Note the ticket's key nouns (objects, stakeholders, report names) — they drive the other slices.
+
+## 2 · Recall (prior art — never rebuild what's built)
+
+- **Rank candidates** (deterministic, instant — no vector store):
+  ```
+  python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/recall.py" --for <id>
+  #  or: --query "<topic>"   |   --tags a,b   |   --object <NAME>   (add --json for structured)
+  ```
+  Scoring is transparent: object match ×4, tag ×3, cross-ref link +5, keyword overlap ×1; recency
+  is a tiebreak. The seed ticket is excluded.
+- **Read the top 2–4** candidate READMEs (+ their `final_deliverables/` and `qc_queries/`
+  listings). Many candidates → spawn read-only Explore agents in parallel (findings only).
+- **Write the reuse brief** (≤ ~200 words): the closest prior work, **what to copy** (which SQL/QC
+  artifact + path), known **gotchas** those tickets carried, and **what's different** this time.
+
+## 3 · Domain slice (business meaning)
+
+- `grep -ril "<topic>" documentation/` and read only the matching sections — the definitions,
+  status taxonomies, calculation/eligibility rules, exclusions, and documented data-quality
+  gotchas for this topic.
+- Scan `AGENTS.md` for any hard rule mentioning the topic (e.g. "as-of date is month-end").
+- If `documentation/` is empty, note that `/refresh context` would build the knowledge pack —
+  don't block on it.
+
+## 4 · Warehouse slice (only the objects in play)
+
+- Skip cleanly if `seams.warehouse` is absent/null ("no warehouse configured").
+- **Preflight** the warehouse seam (`seams.warehouse.verify`); if it fails, halt this slice with
+  the adapter's auth notes — don't guess at schemas.
+- **Resolve object names** (topic → real names via the local pack and the adapter's discovery
+  query), then per object: `describe` (columns/types/DDL), a 5-row sample via `query`, and
+  dependencies per the adapter's `dialect_notes` lineage approach.
+- Brief per object: key columns, join keys (+ cast/filter rules from `dialect_notes`), grain, and
+  the safest source layer to read from.

ticketwright/_kit/.claude/statusline.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# statusline.sh — compact Ticketwright status line for Claude Code.
+# Shows: <key_prefix> · <git branch/ticket> · tracker→warehouse tools.
+# Claude Code pipes session JSON on stdin; we only need cwd/branch + stack.yaml.
+set -uo pipefail
+
+# Read (and ignore) the stdin payload so the pipe doesn't block.
+cat >/dev/null 2>&1 || true
+
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+stack="$root/.claude/config/stack.yaml"
+
+prefix="?"; tracker="—"; warehouse="—"
+if [[ -f "$stack" ]]; then
+  prefix=$(grep -m1 -E '^\s*key_prefix:' "$stack" | sed -E 's/.*key_prefix:[[:space:]]*//; s/[[:space:]#].*//')
+  tracker=$(awk '/^  tracker:/{f=1} f&&/tool:/{print $2; exit}' "$stack")
+  warehouse=$(awk '/^  warehouse:/{f=1} f&&/tool:/{print $2; exit}' "$stack")
+fi
+
+branch=$(git -C "$root" branch --show-current 2>/dev/null || echo "-")
+
+printf "⛭ %s · ⎇ %s · %s→%s" "${prefix:-?}" "${branch:--}" "${tracker:-—}" "${warehouse:-—}"

ticketwright/_kit/adapters/README.md

@@ -0,0 +1,103 @@
+# Adapters — the verb contract
+
+Skills are written **once** against abstract *verbs*. An **adapter** is a small markdown playbook
+that translates those verbs into one concrete tool's commands. To support a new tool (Asana, BigQuery,
+Teams, …) you write **one adapter** — you never touch a skill.
+
+```
+skill  ──calls──▶  verb (e.g. tracker.fetch_ticket)
+                     │
+   stack.yaml ──picks──▶ adapter (tracker/jira.md)
+                     │
+                     ▼
+            concrete command (acli jira workitem view DI-123)
+```
+
+A skill resolves a verb like this:
+1. Read `stack.yaml` → `seams.<seam>.adapter`.
+2. Open that adapter, find the verb's section.
+3. Run the command shown there, substituting `{tokens}` from `stack.yaml` + skill args.
+4. If `seams.<seam>.verify` fails first (hybrid preflight), **halt** with the adapter's auth notes.
+
+Every adapter file has the same shape: a **frontmatter** block (seam, tool, transport, required
+config keys, auth/setup notes) followed by one `## verb: <name>` section per verb in that seam's
+contract. A verb section gives the command(s), inputs, the expected output shape, and any gotchas.
+
+---
+
+## The contract (verbs by seam)
+
+### `tracker` — the ticket system
+| Verb | Inputs | Returns |
+|---|---|---|
+| `fetch_ticket` | `id` | title, description, status, type, assignee, links, attachments list |
+| `create_ticket` | type, summary, description, assignee, parent/epic | new `id` + URL |
+| `transition` | `id`, `status` | ok/fail |
+| `comment` | `id`, body, optional smart-link cards | ok/fail (rendered, not plain text) |
+| `search` | query (JQL/equivalent), limit | list of `{id, summary, status}` |
+| `download_attachments` | `id`, dest dir | files written (silent if none) |
+
+### `warehouse` — the data/work backend
+| Verb | Inputs | Returns |
+|---|---|---|
+| `query` | SQL, optional `--format csv` | rows / CSV (header row 1, no preamble) |
+| `describe` | object name | columns + types (and DDL when supported) |
+| `dialect_notes` | — | *static section*: function names, sizing model, dedup idiom, type-cast rules, the warehouse-specific anti-patterns the `review` skill checks |
+
+### `chat` — team messaging
+| Verb | Inputs | Returns |
+|---|---|---|
+| `draft` | channel, body, mentions | a saved draft (human clicks send) |
+| `send` | channel, body, mentions | posted message (only on explicit "send it") |
+| `lookup_user` | name/email | user ID for mentions |
+| `lookup_channel` | name | channel ID |
+
+### `docstore` — durable backup + shareable links
+| Verb | Inputs | Returns |
+|---|---|---|
+| `backup` | local ticket dir, dest name | files copied to the store |
+| `link_for` | a backed-up file | a shareable URL (for tracker/chat smart links) |
+
+### `vcs` — version control + PRs
+| Verb | Inputs | Returns |
+|---|---|---|
+| `branch` | name (`{key_prefix}-NNNN`) | branch created/checked out |
+| `worktree` | branch | isolated worktree path (the Plan→Implement context reset) |
+| `commit` | paths, message (semantic) | commit sha |
+| `open_pr` | title (semantic), body | PR URL |
+
+---
+
+## Adapters shipped
+
+Pick the one matching your stack (or copy the closest as a starting point). All implement the full
+verb contract for their seam:
+
+- **tracker:** `jira`, `azure-devops` (Azure Boards), `linear`, `asana`, `monday`, `github-issues`
+- **warehouse:** `snowflake`, `bigquery`, `databricks`, `postgres`, `redshift`, `synapse` (also Azure SQL / SQL Server / Fabric)
+- **chat:** `slack`, `teams`
+- **docstore:** `gdrive`, `sharepoint`
+- **vcs:** `github`, `gitlab`, `azure-repos`
+
+Don't see your tool? Adding one is a single file — see "Writing a new adapter" below. Three worked
+`stack.yaml` configs ship (Jira/Snowflake/Slack/Drive/GitHub, Asana/BigQuery/Teams/SharePoint/GitLab,
+and Azure DevOps/Synapse/Teams/SharePoint/Azure Repos) — the same skills run against all three.
+
+> **MCP-transport adapters** (Asana, Linear, Monday, Teams, Slack) reference each operation with a
+> server-namespaced placeholder like `mcp__<server>__<op>`. The exact tool name + parameters depend on
+> your connected MCP server — confirm them once and adjust the adapter (never the skills).
+
+## Writing a new adapter
+
+1. Copy the closest reference adapter in the same seam.
+2. Keep the frontmatter keys (`seam`, `tool`, `transport`, `requires`, `auth`).
+3. Implement **every** verb section for that seam — if the tool can't do one, say so and give the
+   manual fallback (skills will surface it rather than silently skipping).
+4. Add a `verify` command to your `stack.yaml` seam entry (read-only, exits non-zero when unreachable).
+5. Run `bash bin/verify_stack.sh` — it confirms each seam's adapter file exists and runs the seam's
+   read-only `verify` to check reachability. (`bash bin/selftest.sh` checks verb coverage vs. this contract.)
+
+**Rule:** adapters may name concrete tools/CLIs/IDs freely. **Skills may not.** `bin/selftest.sh`
+(section 3) enforces this: it greps `.claude/skills/**` + `.claude/commands/**` for tool names, with
+two sanctioned exceptions (the CLI-detection probe in `setup` and the self-lint line in
+`productize`).

ticketwright/_kit/adapters/chat/slack.md

@@ -0,0 +1,46 @@
+---
+seam: chat
+tool: slack
+transport: mcp         # mcp__slack__* tools only
+requires: [mcp]        # stack.yaml seams.chat.{mcp, default_channel, default_mode, always_include}
+auth: |
+  The `slack` MCP server must be connected. Verify with a read-only search.
+  Verify: a `mcp__slack__slack_search_channels` call returns without error.
+note: |
+  MCP cannot create a brand-new multi-person DM — create it once in the Slack UI, then reuse it.
+---
+
+# Slack adapter
+
+Maps the `chat` verb contract to Slack via the `mcp__slack__*` tools. **Two hard rules from saved
+memory:** (1) default to *draft*, not send — the human clicks send unless they say "send it";
+(2) never solo-DM a stakeholder — every message includes `{always_include}` (e.g. Alice).
+
+## verb: draft   (the default — policy chat_default_draft)
+```
+mcp__slack__slack_send_message_draft(channel_id=<id or {default_channel}>, message=<body>, thread_ts=<optional>)
+```
+Body rules: standard Markdown (the MCP tools accept markdown); **hyperlink everything** with
+`[text](URL)` — ticket IDs (`[ENG-123](https://<site>/browse/ENG-123)`), doc files, PRs. Honor `word_limits.chat` (<100).
+Include `{always_include}` mentions. Resolve mentions/channels via the lookups below.
+
+## verb: send    (ONLY on explicit "send it"/"post it")
+```
+mcp__slack__slack_send_message(channel_id=<id>, message=<body>)
+```
+
+## verb: lookup_user
+```
+mcp__slack__slack_search_users(query=<name or email>)   # → user ID for <@ID> mentions
+```
+
+## verb: lookup_channel
+```
+mcp__slack__slack_search_channels(query=<name>)          # → channel ID
+```
+Existing group DMs can be reused by searching; new multi-person DMs must be created in the UI first.
+
+## gotchas
+- The `mcp__slack__*` tools take **standard Markdown** — use `[text](URL)` links, not Slack `<URL|text>` mrkdwn.
+- Exact parameter names vary by Slack MCP server; this adapter targets one exposing `channel_id` + `message`. If yours differs, adjust here (not in the skills).
+- Tag the stakeholders the channel context calls for, but `{always_include}` is non-negotiable.

ticketwright/_kit/adapters/chat/teams.md

@@ -0,0 +1,38 @@
+---
+seam: chat
+tool: teams
+transport: mcp         # a Microsoft Teams / Graph MCP, or incoming-webhook fallback
+requires: [channel, default_mode, always_include]
+auth: |
+  A Teams MCP server (Graph) connected, OR an incoming-webhook URL per channel.
+  Verify: a read-only "list channels"/"list teams" MCP call returns without error.
+---
+
+# Microsoft Teams adapter (reference for the abstraction proof)
+
+Maps the `chat` verb contract to Teams. Same two rules as Slack: default to **draft**, and always
+include `{always_include}`. Teams uses Adaptive Cards / HTML rather than Slack mrkdwn.
+
+## verb: draft
+Compose the message and **hold it for the human** (Teams has no native "draft to a channel" — stage
+the Adaptive Card JSON / message text in the ticket folder as `chat_draft.json` for the human to send).
+
+## verb: send   (ONLY on explicit "send it")
+```
+<teams mcp> post-message(channel={channel}, body=<HTML/Adaptive Card>)   # or POST to webhook URL
+```
+Hyperlink everything: `<a href="URL">text</a>` (Teams renders HTML), ticket IDs, files, PRs.
+Honor `word_limits.chat`.
+
+## verb: lookup_user
+```
+<teams mcp> search-users(query=<name/email>)        # → user id for the mention
+```
+
+## verb: lookup_channel
+```
+<teams mcp> list-channels(team=<team>)               # → channel id
+```
+
+## gotchas
+- Incoming-webhook transport can post but can't @mention reliably — prefer the Graph MCP when mentions matter.

ticketwright/_kit/adapters/docstore/gdrive.md

@@ -0,0 +1,39 @@
+---
+seam: docstore
+tool: gdrive
+transport: cli         # filesystem copy into the mounted Google Drive (CloudStorage)
+requires: [base_path]  # stack.yaml seams.docstore.base_path
+auth: |
+  Google Drive for Desktop must be mounted at the CloudStorage path.
+  Verify: `test -d "{base_path}"`.
+---
+
+# Google Drive adapter
+
+Maps the `docstore` verb contract to a mounted Google Drive shared drive. Backups are plain
+filesystem copies; shareable links come from the file's macOS extended attribute.
+
+## verb: backup
+**In:** local ticket dir, dest name (**always full title, not just the ID** — saved memory).
+```bash
+dest="{base_path}/<TICKET-ID> <Full Ticket Title>"
+rm -rf "$dest"                       # remove ONLY this exact destination (never a wildcard like <ID>*)
+cp -r "<local ticket dir>" "$dest"
+ls -la "$dest"                       # verify
+```
+Requires explicit approval (external side effect) — policy `hard_halt_before_external_posts`.
+**Never** `rm -rf "<ID>"*` — a prefix glob also matches `<ID>0`, `<ID>1234`, etc. If a prior backup
+used a different title, `ls "{base_path}"` and remove that one exact path by name.
+Note: clean `rm`+`cp` mints **new** Drive item-ids, so any previously shared links go stale — repost.
+
+## verb: link_for
+**In:** a backed-up file path. **Out:** a shareable Drive URL (for tracker/chat smart links).
+```bash
+xattr -l "<gdrive file path>" | grep item-id          # NOT xattr -p (zsh eats the #S suffix)
+# → build: https://drive.google.com/file/d/<ITEM_ID>
+```
+Item-id is blank for a few minutes after an in-place copy — wait, or use the clean rm+cp path.
+
+## gotchas
+- Stakeholder CSV *inputs/provenance* are committed to git; large *exports* go here, linked from Drive — never committed.
+- Jira/Slack must link the **specific Drive file**, never a PR or folder link (saved memory).