ticketwright 2.0.0__py3-none-any.whl

ticketwright/_kit/adapters/docstore/sharepoint.md

@@ -0,0 +1,41 @@
+---
+seam: docstore
+tool: sharepoint
+transport: cli         # OneDrive/SharePoint sync folder (filesystem), or MS Graph API
+requires: [base_path]  # stack.yaml seams.docstore.{base_path, drive_id?}
+auth: |
+  OneDrive/SharePoint sync mounted at base_path, OR a Graph API token (Files.ReadWrite.All).
+  Verify (synced): `test -d "{base_path}"`.
+---
+
+# SharePoint / OneDrive adapter
+
+Maps the `docstore` verb contract to SharePoint/OneDrive. Two transports: the **synced folder**
+(simplest — treat like a local path) or the **Graph API** (when nothing is mounted).
+
+## verb: backup
+**In:** local ticket dir, dest name (**always full title, not just the ID**).
+```bash
+# Synced transport:
+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
+
+# Graph transport (per file):
+#   PUT https://graph.microsoft.com/v1.0/drives/{drive_id}/root:/<path>/<file>:/content
+```
+External side effect ⇒ policy `hard_halt_before_external_posts` (approval first).
+
+## verb: link_for
+**In:** a backed-up file. **Out:** a shareable URL for tracker/chat smart links.
+```
+# Synced: derive the web URL from the SharePoint library's sync-path → URL mapping.
+# Graph:  POST /drives/{drive_id}/items/{item-id}/createLink  { "type": "view", "scope": "organization" }
+#         → response.link.webUrl
+```
+
+## gotchas
+- Sync can lag — confirm the file appears in the library before generating a link.
+- Org sharing policy may force "people in your org only"; pick the `scope` your stakeholders can open.
+- Large *exports* live here and are linked; committed git holds only inputs/provenance.

ticketwright/_kit/adapters/tracker/asana.md

@@ -0,0 +1,55 @@
+---
+seam: tracker
+tool: asana
+transport: mcp         # mcp__plugin_productivity_asana__*
+requires: [workspace_gid]   # stack.yaml seams.tracker.{workspace_gid, default_project_gid}
+auth: |
+  The `asana` MCP server (plugin_productivity_asana) must be connected (OAuth).
+  Verify: an Asana MCP "list workspaces" / "typeahead search" call returns without error.
+note: |
+  Asana has no "Epic" concept — `default_epic` maps to a parent task or a project section.
+  Asana task GIDs are the ticket "id"; there is no DI-style prefix, so set project.key_prefix to a
+  short tag you add to task names (e.g. "DI") if you want branch parity.
+---
+
+# Asana adapter (reference for the abstraction proof)
+
+Maps the `tracker` verb contract to Asana via its MCP. Demonstrates that swapping Jira→Asana is a
+**config + adapter** change with **zero skill edits** — the skills still call `tracker.fetch_ticket`.
+
+## verb: fetch_ticket
+**In:** task GID. **Out:** name, notes, status (section/custom field), assignee, links, attachments.
+```
+mcp__plugin_productivity_asana__* get-task(task_gid=<id>)
+```
+
+## verb: create_ticket
+```
+create-task(workspace={workspace_gid}, projects=[{default_project_gid}],
+            name=<summary>, notes=<desc>, assignee=<email/gid>)
+```
+Parent/epic → set `parent` task GID or add to a project section instead of `--parent`.
+
+## verb: transition
+Asana "status" = moving a task between **sections** or setting a custom field.
+```
+update-task(task_gid=<id>, ...) / add-task-to-section(section_gid=<terminal_status section>)
+```
+`terminal_status` in stack.yaml names the "done" section.
+
+## verb: comment
+```
+create-task-comment(task_gid=<id>, text=<body with URLs>)
+```
+Asana stories render URLs inline. Honor `word_limits.tracker_comment`; never post pre-review.
+
+## verb: search
+```
+search-tasks(workspace={workspace_gid}, text=<topic>)   # or typeahead-search
+```
+
+## verb: download_attachments
+```
+get-attachments-for-task(task_gid=<id>)  → download each attachment's `download_url` with curl
+```
+(No prebuilt script like Jira's — fall back to curl per attachment.)

ticketwright/_kit/adapters/tracker/azure-devops.md

@@ -0,0 +1,68 @@
+---
+seam: tracker
+tool: azure-devops
+transport: cli         # `az boards` (Azure CLI + azure-devops extension); REST API as fallback
+requires: [org, project]   # stack.yaml seams.tracker.{org, project, done_state}
+auth: |
+  `az login` + the devops extension: `az extension add --name azure-devops`.
+  Set defaults: `az devops configure --defaults organization=https://dev.azure.com/{org} project={project}`.
+  A PAT (env `AZURE_DEVOPS_EXT_PAT`) works for non-interactive/CI.
+  Verify: `az boards work-item show --id {default_epic}` (read-only) or `az devops project show`.
+note: |
+  Azure Boards "work items" are the tickets; ids are plain integers (e.g. 1234), so `key_prefix` is a
+  display convention, not part of the id. "Epic" is a work-item type (Epic→Feature→User Story→Task)
+  linked via parent/child relations; "status" = the work item's **State** (New / Active / Resolved /
+  Closed, or your process's states). Convention: name ticket folders/branches `{key_prefix}-<number>`
+  so the index discovers them, but set `ticket_url_template` to use the `{number}` token (not `{id}`)
+  and pass the bare integer to `az boards` — the work-item URL and CLI need the number, not the prefix.
+---
+
+# Azure DevOps (Boards) adapter
+
+Maps the `tracker` verb contract to Azure Boards via the `az boards` CLI.
+
+## verb: fetch_ticket
+**In:** work-item id (integer). **Out:** title, description, state, type, assignee, relations, attachments.
+```bash
+az boards work-item show --id <id> --output json
+```
+Description is `fields."System.Description"` (HTML). Relations (parents, attachments) are in `relations`.
+
+## verb: create_ticket
+```bash
+az boards work-item create --title "<summary>" --type "User Story" \
+  --assigned-to "<email>" --fields "System.Description=<html/desc>" --output json
+# link to an epic/feature parent:
+az boards work-item relation add --id <new-id> --relation-type parent --target-id {default_epic}
+```
+Returns the new integer id + `_links.html.href` (the URL).
+
+## verb: transition
+```bash
+az boards work-item update --id <id> --state "<State>"      # e.g. {done_state} for terminal_status
+```
+States are process-specific (Agile: New/Active/Resolved/Closed; Basic: To Do/Doing/Done) — map
+`project.terminal_status` → `{done_state}`.
+
+## verb: comment
+```bash
+az boards work-item update --id <id> --discussion "<body>"   # adds a comment to the work item
+```
+Discussion accepts HTML (links render). Honor `word_limits.tracker_comment`; never post before review.
+
+## verb: search
+```bash
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State] FROM workitems \
+  WHERE [System.TeamProject]='{project}' AND [System.Title] CONTAINS '<text>' \
+  ORDER BY [System.ChangedDate] DESC" --output json
+```
+
+## verb: download_attachments
+`az boards work-item show --id <id>` → `relations[?rel=='AttachedFile']`. Each has a `url`;
+`curl -L -u :$AZURE_DEVOPS_EXT_PAT "<url>" -o <dest>/<name>` (silent if none).
+
+## gotchas
+- Ids are integers, not prefixed — keep `key_prefix` for branches/index display, but `fetch_ticket`
+  takes the bare number.
+- State names differ per process template — resolve `{done_state}` from the project, don't assume "Done".
+- HTML (not markdown) in description/discussion fields.

ticketwright/_kit/adapters/tracker/github-issues.md

@@ -0,0 +1,59 @@
+---
+seam: tracker
+tool: github-issues
+transport: cli         # `gh issue` (GitHub CLI); REST/GraphQL as fallback
+requires: [repo]       # stack.yaml seams.tracker.{repo, done_label?}  (repo = "owner/name")
+auth: |
+  `gh auth login` (or `GH_TOKEN`). Verify: `gh auth status`.
+note: |
+  GitHub Issues ids are per-repo integers (#123), so `key_prefix` is a branch/index display
+  convention, not part of the id — set `ticket_url_template` to use the `{number}` token and pass the
+  bare number to `gh issue`. "Epic" ≈ a tracking issue, a **milestone**, or a Project; "status"
+  ≈ open/closed (+ optionally a Projects "Status" field or a label). If the same repo hosts code,
+  this pairs naturally with the `vcs: github` adapter.
+---
+
+# GitHub Issues adapter
+
+Maps the `tracker` verb contract to GitHub Issues via `gh`.
+
+## verb: fetch_ticket
+**In:** issue number. **Out:** title, body (markdown), state, assignees, labels, milestone.
+```bash
+gh issue view <number> --repo {repo} --json number,title,body,state,assignees,labels,milestone,url
+```
+
+## verb: create_ticket
+```bash
+gh issue create --repo {repo} --title "<summary>" --body "<markdown>" \
+  --assignee "<login>" --label "<type>" --milestone "<epic>"
+```
+Returns the new issue URL (number is the id). Epic → `--milestone` or a parent tracking issue.
+
+## verb: transition
+```bash
+gh issue close <number> --repo {repo}                       # map terminal_status → closed
+gh issue edit <number> --repo {repo} --add-label "{done_label}"   # if you track status via labels/Projects
+```
+
+## verb: comment
+```bash
+gh issue comment <number> --repo {repo} --body "<markdown>"
+```
+Full markdown links render. Honor `word_limits.tracker_comment`; never post before human review.
+
+## verb: search
+```bash
+gh issue list --repo {repo} --search "<query>" --state all --limit <n> \
+  --json number,title,state
+```
+`--search` takes GitHub's issue search syntax (`is:open label:bug ...`).
+
+## verb: download_attachments
+GitHub stores issue attachments as URLs embedded in the body/comments. Parse them
+(`gh issue view --json body,comments`), then `curl -L "<url>" -o <dest>/<name>` (silent if none).
+
+## gotchas
+- Ids are bare numbers — `fetch_ticket` takes `123`, not `PROJ-123`.
+- "Status" is open/closed unless you adopt a Projects Status field or label convention — set
+  `done_label` (or map terminal_status → closed) so `transition` is unambiguous.

ticketwright/_kit/adapters/tracker/jira.md

@@ -0,0 +1,71 @@
+---
+seam: tracker
+tool: jira
+transport: both        # acli (CLI) for reads/creates/transitions; Atlassian MCP for rich comments
+requires: [site, cli]  # stack.yaml seams.tracker.{site, cli, mcp, default_epic, terminal_status}
+auth: |
+  CLI:  acli jira auth   (token in ~/.config/acli/token.txt; site/email in jira_config.yaml)
+  MCP:  the `atlassian` MCP server must be connected (OAuth). Used for comment rendering.
+  Verify: `acli jira workitem view {default_epic}` (read-only).
+---
+
+# Jira adapter
+
+Maps the `tracker` verb contract to Atlassian Jira via the `acli` CLI and the Atlassian MCP server.
+Reads/creates/transitions go through `acli`; **comments go through the MCP** because ADF renders
+clickable smart links and @mentions (acli posts plain text — links don't render).
+
+## verb: fetch_ticket
+**In:** `id` (e.g. `ENG-1234`). **Out:** title, description, status, type, assignee, links.
+```bash
+acli jira workitem view <id>
+```
+For structured fields: `acli jira workitem view <id> --json`.
+
+## verb: create_ticket
+**In:** type, summary, description, assignee (email), parent/epic.
+```bash
+acli jira workitem create \
+  --project "{key_prefix}" --type "<TYPE>" \
+  --summary "<SUMMARY>" --description "<DESC>" \
+  --assignee "<email>" --parent "<epic or {default_epic}>"
+```
+Notes: **every DI type needs `--parent` (an Epic)** or create fails. Assignee is the **email**, not
+username. Valid types: Reporting, Data Pull, Automation, Dashboard, Research, Data Engineering Task,
+Data Engineering Bug, Epic.
+
+## verb: transition
+```bash
+acli jira workitem transition --key "<id>" --status "<status>"
+```
+The done state is `{terminal_status}` (here `Deployed`, not "Done"). Common: Backlog, In Spec,
+In-Progress, Blocked, Deployed.
+
+## verb: comment
+Use the **Atlassian MCP**, not acli — ADF format renders links/mentions.
+```
+mcp__atlassian__addCommentToJiraIssue(cloudId, issueIdOrKey=<id>, commentBody=<ADF>)
+```
+For a clickable Google-Drive Smart Link, embed an `inlineCard` ADF node with the file URL (see
+docstore/gdrive.md `link_for`). Plain text only otherwise — Jira has its own formatter (no markdown).
+Honor `word_limits.tracker_comment`. **Never post until the human has reviewed** (policy
+`hard_halt_before_external_posts`).
+
+## verb: search
+```bash
+acli jira workitem search --jql "<JQL>" --limit <N> --json   # --csv / --fields also supported
+# MCP alt: mcp__atlassian__searchJiraIssuesUsingJql
+```
+Example (related prior tickets): `project = {key_prefix} AND text ~ "<topic>" ORDER BY created DESC`.
+
+## verb: download_attachments
+Pull a ticket's attachments into its `source_materials/` (skip silently when there are none).
+`acli jira workitem attachment list <id>` only LISTS attachments — to DOWNLOAD, use a small `curl`
+script against the REST API that follows the 303 redirect to the download URL:
+```bash
+# e.g. a helper you keep in bin/: download_jira_attachments.sh <id> <dest_dir>
+```
+
+## gotchas
+- `acli` Duo/MFA: an instant `250001/370001` = lockout (wait 15 min, don't retry); a hang = push pending.
+- Epic link errors ⇒ you forgot `--parent`. "User not found" ⇒ use the exact email.

ticketwright/_kit/adapters/tracker/linear.md

@@ -0,0 +1,56 @@
+---
+seam: tracker
+tool: linear
+transport: mcp         # mcp__plugin_productivity_linear__*
+requires: [team_id]    # stack.yaml seams.tracker.{team_id, done_state_id}
+auth: |
+  The `linear` MCP server (plugin_productivity_linear) must be connected (OAuth).
+  Verify: a read-only issue/team query returns without error.
+note: |
+  Linear has first-class issue identifiers (e.g. ENG-123) — a natural fit for project.key_prefix and
+  branch names (Linear even suggests `username/eng-123-slug`). "Epic" ≈ a **Project** or a parent
+  issue; "status" = workflow **state** (Backlog / Todo / In Progress / Done / Canceled).
+---
+
+# Linear adapter
+
+Maps the `tracker` verb contract to Linear via its MCP.
+
+## verb: fetch_ticket
+**In:** issue id (e.g. `ENG-123`). **Out:** title, description (markdown), state, assignee, labels,
+attachments, parent/project.
+```
+mcp__plugin_productivity_linear__* get-issue(id=<id>)
+```
+
+## verb: create_ticket
+```
+create-issue(team={team_id}, title=<summary>, description=<markdown>,
+             assignee=<email/userId>, project=<epic project id>, parentId=<optional>)
+```
+Linear auto-mints the identifier from `{team_id}` (your `key_prefix`). Epic → set `project` or `parentId`.
+
+## verb: transition
+```
+update-issue(id=<id>, stateId={done_state_id})     # move to the workflow state for terminal_status
+```
+Fetch the team's states once to map `project.terminal_status` → `{done_state_id}`.
+
+## verb: comment
+```
+create-comment(issueId=<id>, body=<markdown>)
+```
+Linear comments support full markdown links — `[DI-123](url)`, file links, PR links. Honor
+`word_limits.tracker_comment`; never post before human review.
+
+## verb: search
+```
+list-issues(team={team_id}, query=<text>, filter={state, label, ...})
+```
+
+## verb: download_attachments
+Read the issue's `attachments{ url }`, `curl -L` each to the dest dir. (Linear attachments are URLs.)
+
+## gotchas
+- State ids are team-specific — don't hardcode; resolve from the team's workflow states.
+- Linear's native git-branch naming convention pairs well with the `vcs.branch` verb.

ticketwright/_kit/adapters/tracker/monday.md

@@ -0,0 +1,62 @@
+---
+seam: tracker
+tool: monday
+transport: mcp         # mcp__plugin_productivity_monday__*  (GraphQL under the hood)
+requires: [board_id]   # stack.yaml seams.tracker.{board_id, status_column_id, done_label}
+auth: |
+  The `monday` MCP server (plugin_productivity_monday) must be connected (OAuth).
+  Verify: a read-only board/items query returns without error.
+note: |
+  monday models work as **items** on **boards**. "Status" is a status **column** (set by label),
+  not a workflow transition; "epic" maps to a parent item or a board **group**. There is no DI-style
+  id prefix — item ids are numeric, so set project.key_prefix to a short tag you put in item names if
+  you want branch parity (e.g. branch "OPS-<itemId>").
+---
+
+# monday.com adapter
+
+Maps the `tracker` verb contract to monday.com via its MCP (GraphQL items API).
+
+## verb: fetch_ticket
+**In:** item id. **Out:** name, column values (incl. status), updates, assignee, file-column assets.
+```
+mcp__plugin_productivity_monday__* get-item(item_id=<id>)
+# or GraphQL: items(ids:[<id>]){ name column_values{ id text value } updates{ body } assets{ url } }
+```
+
+## verb: create_ticket
+```
+create-item(board_id={board_id}, item_name=<summary>,
+            column_values={ "status": {"label":"<initial>"}, "person": {"personsAndTeams":[…]} })
+```
+Parent/epic → create as a **subitem** of the parent item, or place in the epic **group** (`group_id`).
+monday has no `--parent` flag; the group/subitem is the equivalent.
+
+## verb: transition
+"Status" = set the status column's label to `{done_label}` (or any workflow label).
+```
+change-column-value(item_id=<id>, board_id={board_id}, column_id={status_column_id},
+                    value="{\"label\":\"<status>\"}")
+```
+`project.terminal_status` maps to `{done_label}`.
+
+## verb: comment
+```
+create-update(item_id=<id>, body=<text with URLs>)
+```
+Updates render links inline. Honor `word_limits.tracker_comment`. Never post before human review
+(policy `hard_halt_before_external_posts`).
+
+## verb: search
+```
+items-page-by-column-values(board_id={board_id}, columns=[…])   # filter by column
+# or a text query across the board's items
+```
+
+## verb: download_attachments
+Read the item's **file column** `assets{ url }`, then `curl -L <asset url> -o <dest>` per file.
+(No prebuilt script like Jira's.)
+
+## gotchas
+- Status changes require the exact **label text** the board defines — fetch the column's labels first.
+- monday rate-limits GraphQL by complexity; batch item reads rather than looping single-item calls.

ticketwright/_kit/adapters/vcs/azure-repos.md

@@ -0,0 +1,58 @@
+---
+seam: vcs
+tool: azure-repos
+transport: cli         # git + `az repos` (Azure CLI + azure-devops extension)
+requires: [default_branch]   # stack.yaml seams.vcs.{default_branch, semantic_pr, worktree_root, org, project, repo}
+auth: |
+  `az login` + `az extension add --name azure-devops`; git creds via Git Credential Manager or a PAT.
+  Set defaults: `az devops configure --defaults organization=https://dev.azure.com/{org} project={project}`.
+  Verify: `az repos list --query "[].name"` (or `az devops project show`).
+---
+
+# Azure Repos adapter
+
+Maps the `vcs` verb contract to git + the `az repos` CLI (Azure DevOps Pull Requests). Mirrors the
+GitHub/GitLab flow; "PR" = Azure DevOps Pull Request. Pairs with the `azure-devops` tracker when the
+whole stack is Microsoft.
+
+## verb: branch
+```bash
+git checkout {default_branch} && git pull origin {default_branch}
+git checkout -b <TICKET-ID>
+```
+
+## verb: worktree   (the Plan→Implement context reset)
+```bash
+git worktree add "{worktree_root}/<name>" -b <TICKET-ID>
+```
+
+## verb: commit
+Stage only files you changed (never `git add .`); semantic message + trailer.
+```bash
+git add <paths>
+git commit -m "$(cat <<'EOF'
+<type>: <TICKET-ID> <description>
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+Types: feat, fix, docs, refactor, chore, test, ci. Small atomic commits per build step; commit the
+plan/spec artifact before implementing (policy `commit_plan_before_implement`).
+
+## verb: open_pr
+```bash
+git push -u origin <TICKET-ID>
+az repos pr create --repository {repo} --source-branch <TICKET-ID> --target-branch {default_branch} \
+  --title "<type>: <TICKET-ID> <description>" \
+  --description "Business Impact / Deliverables / Technical Notes / QC Results" \
+  --work-items <ticket-number>          # links the PR to the Boards work item
+```
+`semantic_pr: true` ⇒ keep the title semantic if branch policies lint it. Honor `word_limits.pr`.
+External action ⇒ requires approval (policy `hard_halt_before_external_posts`).
+
+## gotchas
+- `--work-items` ties the PR to the Azure Boards item (the tracker side) — use the bare integer id.
+- Branch policies (required reviewers, build validation) may gate completion — surface required
+  approvals rather than force-completing the PR.
+- Self-hosted Azure DevOps Server uses `--organization https://<server>/<collection>`.

ticketwright/_kit/adapters/vcs/github.md

@@ -0,0 +1,55 @@
+---
+seam: vcs
+tool: github
+transport: cli         # git + gh
+requires: [default_branch]  # stack.yaml seams.vcs.{default_branch, semantic_pr, worktree_root}
+auth: |
+  git credentials in keychain; `gh auth login` for PRs.
+  Verify: `gh auth status`.
+---
+
+# GitHub adapter
+
+Maps the `vcs` verb contract to git + the GitHub CLI. Branch = ticket ID; PR titles are semantic.
+
+## verb: branch
+```bash
+git checkout {default_branch} && git pull origin {default_branch}
+git checkout -b <TICKET-ID>                 # branch name IS the ticket id
+```
+
+## verb: worktree   (the Plan→Implement context reset)
+```bash
+git worktree add "{worktree_root}/<name>" -b <TICKET-ID>
+```
+A fresh worktree gives implementation its own clean context, separate from planning. (This repo's
+worktree-manager scripts under `~/.claude/skills/worktree-manager/` can also be used.)
+
+## verb: commit
+Stage only files you changed (never `git add .`); semantic message.
+```bash
+git add <paths>
+git commit -m "$(cat <<'EOF'
+<type>: <TICKET-ID> <description>
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+Types: feat, fix, docs, refactor, chore, test, ci. Small atomic commits per build step (git-log-is-memory).
+Commit the **plan/spec artifact before implementing** (policy `commit_plan_before_implement`).
+
+## verb: open_pr
+```bash
+git push -u origin <TICKET-ID>      # gh pr create is interactive if the branch isn't pushed yet
+gh pr create --title "<type>: <TICKET-ID> <description>" \
+  --body "Business Impact / Deliverables / Technical Notes / QC Results"
+```
+`semantic_pr: true` ⇒ non-semantic titles fail the Semantic-PR check. Honor `word_limits.pr` (<200).
+External action ⇒ requires approval (policy `hard_halt_before_external_posts`).
+
+## gotchas
+- `gh pr create` prompts interactively (which can hang an agent) unless the branch is already pushed
+  — push first, as above.
+- Branch protection / required status checks may gate the merge — surface the required reviews/checks
+  rather than force-merging.

ticketwright/_kit/adapters/vcs/gitlab.md

@@ -0,0 +1,52 @@
+---
+seam: vcs
+tool: gitlab
+transport: cli         # git + `glab` CLI
+requires: [default_branch]   # stack.yaml seams.vcs.{default_branch, semantic_pr, worktree_root}
+auth: |
+  git credentials in keychain/credential-helper; `glab auth login` for merge requests.
+  Verify: `glab auth status`.
+---
+
+# GitLab adapter
+
+Maps the `vcs` verb contract to git + the GitLab CLI. Merge Requests (MRs) replace PRs; otherwise the
+flow mirrors GitHub. Branch = ticket id; MR titles are semantic.
+
+## verb: branch
+```bash
+git checkout {default_branch} && git pull origin {default_branch}
+git checkout -b <TICKET-ID>
+```
+
+## verb: worktree   (the Plan→Implement context reset)
+```bash
+git worktree add "{worktree_root}/<name>" -b <TICKET-ID>
+```
+
+## verb: commit
+Stage only files you changed (never `git add .`); semantic message + trailer.
+```bash
+git add <paths>
+git commit -m "$(cat <<'EOF'
+<type>: <TICKET-ID> <description>
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+Types: feat, fix, docs, refactor, chore, test, ci. Small atomic commits per build step. Commit the
+plan/spec artifact before implementing (policy `commit_plan_before_implement`).
+
+## verb: open_pr
+```bash
+glab mr create --title "<type>: <TICKET-ID> <description>" \
+  --description "Business Impact / Deliverables / Technical Notes / QC Results" \
+  --target-branch {default_branch} --remove-source-branch
+```
+`semantic_pr: true` ⇒ keep the title semantic if a pipeline lint enforces it. Honor `word_limits.pr`.
+External action ⇒ requires approval (policy `hard_halt_before_external_posts`).
+
+## gotchas
+- `glab` needs the host set for self-managed GitLab: `glab auth login --hostname <gitlab.company.com>`.
+- MR approvals/merge-trains may gate the merge — surface required approvals rather than forcing.

ticketwright/_kit/adapters/warehouse/bigquery.md

@@ -0,0 +1,44 @@
+---
+seam: warehouse
+tool: bigquery
+transport: cli         # `bq` CLI (gcloud SDK)
+requires: [project, dataset]   # stack.yaml seams.warehouse.{project, dataset, dev_dataset}
+auth: |
+  gcloud auth (ADC) + `bq` in PATH.
+  Verify: `bq query --use_legacy_sql=false --dry_run "SELECT 1"` (read-only, no cost).
+---
+
+# BigQuery adapter (reference for the abstraction proof)
+
+Maps the `warehouse` verb contract to Google BigQuery via `bq`. Same verbs as Snowflake — only the
+commands and `dialect_notes` differ, so `review`/`spec-and-build`/`refresh context` run
+unchanged.
+
+## verb: query
+```bash
+bq query --use_legacy_sql=false --format=csv "<SQL>"
+bq query --use_legacy_sql=false --format=csv < file.sql
+```
+- Deterministic exports: explicit `ORDER BY` (BQ result order is not guaranteed).
+- Cost guard: `--dry_run` to estimate bytes; `--maximum_bytes_billed` to cap.
+
+## verb: describe
+```bash
+bq show --schema --format=prettyjson {project}:{dataset}.<table>
+bq show --format=prettyjson {project}:{dataset}.<view>     # has the view DDL ("query" field)
+```
+Object inventory: `bq ls {dataset}`; lineage via `INFORMATION_SCHEMA.*` views.
+
+## verb: dialect_notes  (read by the review skill)
+- **Functions:** `IFNULL`/`COALESCE`, `SAFE_DIVIDE(a,b)` (div-by-zero), `SAFE_CAST`,
+  `STRING_AGG` (vs LISTAGG), `ARRAY_AGG`. Standard SQL (`--use_legacy_sql=false`) always.
+- **Sizing:** on-demand (bytes scanned) or slots — partition + cluster columns to prune scans;
+  filtering a partition column is the main "warehouse size" lever.
+- **Joins:** type-match with `CAST`/`SAFE_CAST`; mind `STRING` vs `INT64` keys.
+- **Partition pruning** is the analog of clustered-column filtering; `SELECT *` on wide tables is
+  the expensive anti-pattern (scans all columns) — list columns.
+- **Dev/deploy:** dev objects in `{dev_dataset}`; promote via scripted `CREATE OR REPLACE`.
+
+## gotchas
+- Non-SELECT/DDL ⇒ policy `db_write_requires_approval`.
+- Watch query cost — surface estimated bytes before running anything large.