ticketwright 3.2.0__tar.gz → 3.4.0__tar.gz

{ticketwright-3.2.0 → ticketwright-3.4.0}/.claude/config/stack.example.asana-bq.yaml

@@ -59,7 +59,7 @@ seams:
 
 policies:
   hard_halt_before_external_posts: true
-  db_write_requires_approval: true
+  db_write_requires_approval: high_risk   # off | high_risk | all — see stack.schema.md
   chat_default_draft: true
   hyperlink_everything: true
   skillify_everything: true

{ticketwright-3.2.0 → ticketwright-3.4.0}/.claude/config/stack.example.azure.yaml

@@ -64,7 +64,7 @@ seams:
 
 policies:
   hard_halt_before_external_posts: true
-  db_write_requires_approval: true
+  db_write_requires_approval: high_risk   # off | high_risk | all — see stack.schema.md
   chat_default_draft: true
   hyperlink_everything: true
   skillify_everything: true

ticketwright-3.4.0/.claude/config/stack.example.multi-warehouse.yaml

@@ -0,0 +1,104 @@
+# stack.example.multi-warehouse.yaml — a team that must reach TWO warehouses.
+#
+# Jira / Snowflake + Databricks / Slack / Google Drive / GitHub. Everything except the warehouse
+# seam is identical to stack.yaml; this file exists to prove one claim — one warehouse seam can
+# hold several named targets, and every target is independently reachable.
+#
+# Skills resolve which target to use per `adapters/README.md` § Multi-target seams; a `.sql` file
+# names its own target in a `-- warehouse-target: <name>` header comment.
+# Field docs: stack.schema.md  ·  Validate: bash bin/verify_stack.sh .claude/config/stack.example.multi-warehouse.yaml
+
+project:
+  key_prefix: ENG
+  key_prefixes: [ENG]
+  assignee_dir: alice
+  ticket_path: "tickets/{assignee}/{id}"
+  ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]
+  default_epic: ENG-100
+  terminal_status: Done
+  ticket_url_template: "https://acme.atlassian.net/browse/{id}"
+  word_limits: {tracker_comment: 100, chat: 100, pr: 200, ticket: 200}
+  graph_notes: true
+  graph_config: true
+
+seams:
+  tracker:
+    tool: jira
+    adapter: adapters/tracker/jira.md
+    transport: both
+    site: acme.atlassian.net
+    cli: acli
+    mcp: atlassian
+    verify: 'acli jira workitem search --jql "project = {key_prefix}" --limit 1'
+
+  # ── MULTI-TARGET warehouse seam ───────────────────────────────────────────────────────────────
+  # The presence of `targets:` is the discriminator — NOT `default:`, because other seams already
+  # use default_channel / default_mode / default_branch and `default` must never carry type meaning.
+  #
+  # List the DEFAULT target FIRST. Readers that predate this feature (an un-relaunched session's
+  # statusline and SessionStart banner) display the first target they find, so first == default
+  # keeps them honest instead of quietly naming the wrong warehouse.
+  #
+  # Scalar keys at the SEAM level are inherited by every target, and a target's own key wins —
+  # handy when two targets share an account (one `cli:` up here, differing `default_warehouse:`
+  # per target).
+  warehouse:
+    default: prod
+    targets:
+      prod:
+        tool: snowflake
+        adapter: adapters/warehouse/snowflake.md
+        transport: both
+        cli: snow
+        default_warehouse: ANALYTICS_WH
+        pii_role: PII_READER
+        dev_target: ANALYTICS_DEV       # canonical; a legacy `dev_db:` is still honored
+        verify: "snow connection test"
+      lake:
+        tool: databricks
+        adapter: adapters/warehouse/databricks.md
+        transport: cli
+        cli: dbsqlcli
+        warehouse_id: 0a1b2c3d4e5f6789
+        catalog: main
+        schema: analytics
+        dev_target: main_dev            # was `dev_catalog:`
+        profile: DEFAULT
+        verify: "databricks --profile {profile} current-user me"
+
+  chat:
+    tool: slack
+    adapter: adapters/chat/slack.md
+    transport: mcp
+    mcp: slack
+    default_channel: C0XXXXXXXXX
+    default_mode: draft
+    always_include: [Alice]
+    verify: null
+
+  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
+  skillify_everything: true
+  reduce_assumptions: true
+  commit_plan_before_implement: true
+  system_evolution: true
+  deterministic_outputs: true

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

@@ -0,0 +1,157 @@
+# `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. |
+| `graph_notes` | bool | `true` | Generate the Obsidian graph layer (`tickets/graph/` + `tickets/objects/`). On by default; set `false` to disable. |
+| `graph_config` | bool | `true` | Also write/merge `.obsidian/graph.json` (tickets↔objects filter + color groups) so the Graph view opens ready-to-read. Create/merge-only — never clobbers manual tweaks. On by default; set `false` to keep the nodes but not manage the Obsidian config. Ignored when `graph_notes` is `false`. |
+
+## `seams`
+
+Exactly these five keys: `tracker`, `warehouse`, `chat`, `docstore`, `vcs`. Each is **either** a
+single mapping (below) **or** a *multi-target* mapping — see "Multiple warehouses". Fields of a
+single mapping:
+
+| 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.
+
+### Multiple warehouses (named targets)
+
+A repo that must reach more than one warehouse — prod Snowflake plus a Databricks lakehouse, or two
+Snowflake accounts — declares **named targets** instead of one flat mapping:
+
+```yaml
+  warehouse:
+    default: prod              # REQUIRED when `targets:` is present; must name a key below
+    cli: snow                  # seam-level scalars are inherited by every target
+    targets:
+      prod: { tool: snowflake,  adapter: adapters/warehouse/snowflake.md,  verify: "snow connection test" }
+      lake: { tool: databricks, adapter: adapters/warehouse/databricks.md, verify: "…" }
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `targets` | map | Named targets. **Its presence is the discriminator** for a multi-target seam. |
+| `default` | string | Which target skills use when nothing else selects one. Required with `targets`. |
+
+Rules:
+
+- **Inheritance.** A target inherits any key it doesn't define itself, including `tool` / `adapter` /
+  `verify` — so two targets on one account can share all three and differ only in, say,
+  `default_warehouse`. A target's own key wins. Inheritance is keyed on *absence*: an explicit
+  `verify: null` on a target means "skip", it does not fall back to the seam's command.
+- **List the default first.** Readers that predate this feature (an un-relaunched session's statusline
+  and SessionStart banner) show the first target they find, so first == default keeps them honest.
+  `bin/verify_stack.sh` warns when the default isn't first, and fails when `default` is missing or
+  names an unknown target.
+- **Which target is active** is resolved per `adapters/README.md` § Multi-target seams. A `.sql` file
+  names its own target in a `-- warehouse-target: <name>` header comment; that never goes in a CSV,
+  whose header must stay on row 1 with no preamble.
+- v1 implements multi-target for **`warehouse`** only. `verify_stack.sh` handles the shape for any
+  seam, but no skill resolves targets for the other four, so don't rely on it there yet.
+
+**Known limitation:** `tickets/OBJECTS.md` and the graph layer fold object names case-insensitively
+and are warehouse-blind, so `ANALYTICS.CUSTOMERS` on one target and `analytics.customers` on another
+collapse into one node. Usually that's the useful reading (a genuine cross-system relationship), but
+it is not a per-target index.
+
+**Dev target.** The dev environment is `seams.warehouse[.targets.<name>].dev_target`. When that key
+is absent it falls back to the key named by the warehouse adapter's `dev_key:` frontmatter (`dev_db`
+for Snowflake, `dev_dataset` for BigQuery, `dev_catalog` for Databricks, `dev_schema` for
+Postgres/Redshift/Synapse) — so configs written before `dev_target` existed keep working untouched.
+
+## `policies` (the 9 kit policies — see kit README "AI-layer" section)
+
+| Policy | Type | Default | Enforced by |
+|---|---|---|---|
+| `hard_halt_before_external_posts` | bool | `true` | `ship`, every productized skill — pause for human go before any tracker/chat/docstore write. |
+| `db_write_requires_approval` | enum | `high_risk` | the `db_write_guard` hook (Claude Code) + any skill issuing a non-SELECT. See below. |
+| `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. |
+| `skillify_everything` | `true` | recurring work → a `/productize` skill the agent can invoke, 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. |
+
+All are booleans except `db_write_requires_approval`.
+
+### `db_write_requires_approval` — the one enum
+
+| Value | Behavior | Also accepts |
+|---|---|---|
+| `off` | Never ask. | `false`, `none`, `null` |
+| `high_risk` | **Default.** Ask only for irreversible, access-changing, or unrecognized SQL. | `true`, `destructive` |
+| `all` | Ask for any mutation at all. | `strict`, `always` |
+
+Reads (`SELECT`/`SHOW`/`DESCRIBE`/`EXPLAIN`/`WITH … SELECT`/`LIST`/`USE`) pass in every value;
+`all` means every *write*, not every command.
+
+Classification is **default-deny**. Only a narrow allowlist is treated as additive — plain
+`CREATE` (no `OR REPLACE`), `INSERT INTO` (no `OVERWRITE`), `ALTER … ADD`, and `COMMENT ON`.
+Everything else that mutates is high-risk, *including anything the scanner does not recognize*.
+Enumerating dangerous forms instead would leave holes: `ALTER TABLE … MODIFY COLUMN` can change
+a type and truncate data while matching no plausible "destructive verb" list.
+
+A missing, malformed, or unrecognized value resolves to `all`, never to something weaker —
+unparseable config must not quietly widen what runs unprompted. Note the asymmetry: an explicit
+legacy `true` *does* relax to `high_risk`, because it is a value someone chose rather than a
+value the parser failed on.
+
+Under `bypassPermissions` the hook stays silent and emits a `systemMessage` instead of asking —
+the operator has already opted out of prompting, so a prompt there is incoherent. Every other
+permission mode gets a normal `ask`. For agents other than Claude Code this policy is
+**guidance, not enforcement**: they read it in `AGENTS.md` and are trusted to honor it, since
+hooks are the only mechanically enforced layer.
+
+`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). Three more
+prove the abstraction holds with zero skill edits: `stack.example.asana-bq.yaml`
+(Asana/BigQuery/Teams/SharePoint/GitLab), `stack.example.azure.yaml`
+(Azure DevOps/Synapse/Teams/SharePoint/Azure Repos), and `stack.example.multi-warehouse.yaml`
+(Jira/**Snowflake + Databricks**/Slack/Drive/GitHub — the named-targets shape above). To validate any
+config: `bash bin/verify_stack.sh`.

{ticketwright-3.2.0 → ticketwright-3.4.0}/.claude/config/stack.yaml

@@ -18,6 +18,7 @@ project:
   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}
   graph_notes: true                     # Obsidian graph layer (tickets/graph + tickets/objects); false to disable
+  graph_config: true                    # also write .obsidian/graph.json (tickets↔objects filter + colors); create/merge-only, never clobbers manual tweaks
 
 seams:
   tracker:
@@ -67,7 +68,7 @@ seams:
 
 policies:
   hard_halt_before_external_posts: true
-  db_write_requires_approval: true
+  db_write_requires_approval: high_risk   # off | high_risk | all — see stack.schema.md
   chat_default_draft: true
   hyperlink_everything: true
   skillify_everything: true

ticketwright-3.4.0/.claude/hooks/_stack.py

@@ -0,0 +1,139 @@
+"""Shared stack.yaml resolution + reading for the hooks. Stdlib only, no yaml dep.
+
+The four hooks each grew their own root-resolution and their own mini-YAML scanner,
+three mutually inconsistent ways. This module is the seam they should converge on;
+`db_write_guard` uses it today, the others can migrate without behavior change.
+
+Two properties matter more than convenience here:
+
+1. **No kit-relative fallback.** Resolution stops at the project. A hook that falls
+   back to the kit's own shipped `stack.yaml` silently activates outside a
+   configured repo and reads the worked example's policy instead of the user's —
+   which is exactly how a "repo-gated" guard ends up firing everywhere.
+2. **Block-scoped lookups.** `_block_lines` walks indentation rather than pattern-matching
+   across the whole document, so a key is read from the block that actually owns it.
+
+Seam blocks are *not* handled here — `db_write_guard.seam_block` already does that, with
+harder-won handling for inferred indent, anchors, flow mappings, and block scalars. This
+module covers the top-level `policies:` mapping only; duplicating a second seam parser
+would just create two things to keep correct.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+STACK_REL = ".claude/config/stack.yaml"
+
+
+def _iter_up(start: Path):
+    """Yield `start` and its ancestors, stopping at (and including) the repo root.
+
+    Bounded by `.git` so a subdirectory invocation still finds the project's config
+    without escaping into a parent checkout that happens to have one.
+    """
+    try:
+        cur = start.resolve()
+    except OSError:
+        return
+    while True:
+        yield cur
+        if (cur / ".git").exists() or cur.parent == cur:
+            return
+        cur = cur.parent
+
+
+def find_stack(cwd: str | None) -> Path | None:
+    """Locate the *project's* stack.yaml, or None. None means "not a ticketwright repo"."""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project_dir:
+        candidate = Path(project_dir) / STACK_REL
+        if candidate.is_file():
+            return candidate
+    if cwd:
+        for directory in _iter_up(Path(cwd)):
+            candidate = directory / STACK_REL
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def read_text(stack: Path | None) -> str:
+    if stack is None:
+        return ""
+    try:
+        return stack.read_text(errors="replace")
+    except OSError:
+        return ""
+
+
+def _block_lines(text: str, key: str) -> list[str]:
+    """Return the lines nested under `key:`, by indentation.
+
+    Stops at the first non-blank, non-comment line indented at or below the key's own
+    level — i.e. the next sibling. Blank and comment lines inside the block are kept
+    so they never terminate it early.
+    """
+    base: int | None = None
+    header = re.compile(rf"^(\s*){re.escape(key)}\s*:\s*(?:#.*)?$")
+    out: list[str] = []
+    for line in text.splitlines():
+        if base is None:
+            match = header.match(line)
+            if match:
+                base = len(match.group(1))
+            continue
+        if not line.strip() or line.lstrip().startswith("#"):
+            out.append(line)
+            continue
+        if len(line) - len(line.lstrip()) <= base:
+            break
+        out.append(line)
+    return out
+
+
+def _unquote(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    # Only strip a trailing comment from an unquoted scalar; a quoted one may contain '#'.
+    return value.split("#", 1)[0].strip()
+
+
+def _scalar(lines: list[str], key: str) -> str | None:
+    pattern = re.compile(rf"^\s*{re.escape(key)}\s*:\s*(\S.*)$")
+    for line in lines:
+        match = pattern.match(line)
+        if match:
+            return _unquote(match.group(1))
+    return None
+
+
+# ---- the db_write_requires_approval policy -------------------------------------
+
+MODE_OFF = "off"
+MODE_HIGH_RISK = "high_risk"
+MODE_ALL = "all"
+
+POLICY_KEY = "db_write_requires_approval"
+
+# Legacy `true` relaxes to high_risk (v3.4 behavior change). A missing, malformed, or
+# unrecognized value does NOT — unparseable config must never widen what runs
+# unprompted, so it falls back to `all`.
+_ALIASES = {
+    "off": MODE_OFF, "false": MODE_OFF, "no": MODE_OFF, "none": MODE_OFF, "null": MODE_OFF,
+    "high_risk": MODE_HIGH_RISK, "high-risk": MODE_HIGH_RISK,
+    "destructive": MODE_HIGH_RISK, "true": MODE_HIGH_RISK, "yes": MODE_HIGH_RISK,
+    "all": MODE_ALL, "strict": MODE_ALL, "always": MODE_ALL,
+}
+
+
+def db_write_mode(stack: Path | None) -> str:
+    text = read_text(stack)
+    if not text:
+        return MODE_ALL
+    raw = _scalar(_block_lines(text, "policies"), POLICY_KEY)
+    if raw is None:
+        return MODE_ALL
+    return _ALIASES.get(raw.strip().lower(), MODE_ALL)