ticketwright 4.1.0__tar.gz → 4.2.0__tar.gz

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.example.azure.yaml

@@ -4,8 +4,8 @@
 # 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]
+  key_prefix: TEST                      # branch/index display convention (ADO ids are bare integers)
+  key_prefixes: [TEST]
   assignee_dir: dana
   ticket_path: "tickets/{assignee}/{id}"
   ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.example.multi-audience.yaml

@@ -19,12 +19,12 @@
 # Field docs: stack.schema.md  ·  Validate: bash bin/verify_stack.sh .claude/config/stack.example.multi-audience.yaml
 
 project:
-  key_prefix: ENG
-  key_prefixes: [ENG]
+  key_prefix: TEST
+  key_prefixes: [TEST]
   assignee_dir: alice
   ticket_path: "tickets/{assignee}/{id}"
   ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]
-  default_epic: ENG-100
+  default_epic: TEST-100
   terminal_status: Done
   ticket_url_template: "https://acme.atlassian.net/browse/{id}"
   word_limits: {tracker_comment: 100, chat: 100, pr: 200, ticket: 200}

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.example.multi-warehouse.yaml

@@ -9,12 +9,12 @@
 # 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]
+  key_prefix: TEST
+  key_prefixes: [TEST]
   assignee_dir: alice
   ticket_path: "tickets/{assignee}/{id}"
   ticket_subdirs: [source_materials, final_deliverables, qc_queries, exploratory_analysis]
-  default_epic: ENG-100
+  default_epic: TEST-100
   terminal_status: Done
   ticket_url_template: "https://acme.atlassian.net/browse/{id}"
   word_limits: {tracker_comment: 100, chat: 100, pr: 200, ticket: 200}
@@ -96,7 +96,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-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.example.no-warehouse.yaml

@@ -13,8 +13,8 @@
 # Field docs: stack.schema.md  ·  Validate: bash bin/verify_stack.sh .claude/config/stack.example.no-warehouse.yaml
 
 project:
-  key_prefix: ENG                       # display/branch convention; GitHub issue ids are bare numbers
-  key_prefixes: [ENG]
+  key_prefix: TEST                      # display/branch convention; GitHub issue ids are bare numbers
+  key_prefixes: [TEST]
   assignee_dir: ana
   ticket_path: "tickets/{assignee}/{id}"
   ticket_subdirs: [source_materials, final_deliverables, qc_queries, working_notes]
@@ -34,7 +34,7 @@ seams:
     transport: cli
     repo: "acme/analysis-repo"
     verify: "gh auth status"
-    # Folder/branch ids read ENG-<number> locally; adapter verbs take the bare issue number —
+    # Folder/branch ids read TEST-<number> locally; adapter verbs take the bare issue number —
     # see the adapter's note (key_prefix is a display/branch convention for GitHub Issues).
 
   # warehouse is deliberately omitted — this team's analysis work doesn't run through a database.

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.example.solo.yaml

@@ -5,7 +5,7 @@
 # the unit of work, and its README.md is the ticket.
 #
 # Two settings carry that: `tracker: local` (the tracker verbs read and write the folder itself) and
-# `id_mode: slug` (the folder name is the id, instead of a tracker key like ENG-1234). Chat and
+# `id_mode: slug` (the folder name is the id, instead of a tracker key like TEST-1234). Chat and
 # docstore are simply absent — /ship skips those artifacts and names the /setup command that would
 # enable them, rather than blocking.
 #
@@ -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-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.schema.md

@@ -111,13 +111,13 @@ policies:       # behavioral rules every skill inherits (the kit's "global rules
 
 | Field | Type | Example | Meaning |
 |---|---|---|---|
-| `key_prefix` | string | `ENG` | Ticket-ID prefix. Branch names = `{key_prefix}-NNNN`. Omit it when `id_mode: slug` — there are no keys to prefix. |
+| `key_prefix` | string | `TEST` | Ticket-ID prefix. Branch names = `{key_prefix}-NNNN`. Omit it when `id_mode: slug` — there are no keys to prefix. |
 | `id_mode` | enum | `keyed` | `keyed` (default) = folder names carry a tracker key; `slug` = the folder name **is** the id. See "Trackerless work". |
-| `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]`). |
+| `key_prefixes` | list | `[TEST]` | Prefixes the ticket index recognizes in folder names. Optional; defaults to `[key_prefix]`. Use when one repo holds tickets from several trackers (e.g. `[TEST, OPS]`). |
 | `assignee_dir` | string | `alice` | Last-resort owner subdir under `tickets/`, used only when **no people map exists at all** (`bin/whoami.py` returns `miss` and there are no `people/*.yaml`). With a people map, the whoami-resolved person is the owner, and an unresolved person is a **hard stop** — never this key, which would file a new teammate's work in a colleague's folder. `effective_config.py` reports which case applies as `owner_source` (`resolved` / `unbound` / `assignee_dir_fallback` / `none`) and the answer as `owner`. |
 | `ticket_path` | template | `tickets/{assignee}/{id}` | Where a ticket folder lives. `{assignee}` `{id}` tokens; `{assignee}` is the ticket's **owner** — the whoami-resolved person for new work, or the locator's owner (`owner/id`) when named explicitly. |
 | `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). |
+| `default_epic` | string \| null | `TEST-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. |
 | `intake` | list | `[tracker, email]` | Where work arrives; any of `tracker`, `email`, `chat`, `meetings`. Optional; **defaults to `[tracker]`** — the example shows email intake *added* (a "email carries work in" answer in the setup interview), not the default. Consumer: when `email`/`chat`/`meetings` is listed, `/ticket`'s priming step reads `source_materials/` for material a human dropped in — intake beyond the tracker arrives as files, not API calls. **`meetings`** names the AI-notetaker channel: export the notes or a curated transcript excerpt as `source_materials/YYYY-MM-DD-<slug>-meeting.md`. That name is the **committed, curated form** — trimmed to decisions and action items. Raw full transcripts stay out of git by default (`templates/gitignore.tmpl`) and are gated before any commit or docstore copy by `source_material_guard`, whose classifier (`bin/scan_source_materials.py`) matches filenames and document shape, **never meaning** — a curated summary quoting confidential material verbatim passes, so this is a gate against the bulk artifact, not a confidentiality review. |
@@ -386,10 +386,10 @@ What changes:
 
 | | `keyed` (default) | `slug` |
 |---|---|---|
-| A folder is a ticket when | its name contains a tracker key (`ENG-12`) | its whole name, after an optional leading status emoji, matches `[a-z0-9][a-z0-9_-]*` |
+| A folder is a ticket when | its name contains a tracker key (`TEST-12`) | its whole name, after an optional leading status emoji, matches `[a-z0-9][a-z0-9_-]*` |
 | The id is | the matched key | the whole folder name |
 | `key_prefix` | conventional (absent, the index falls back to matching any `LETTERS-digits`) | omit it — the banner and statusline label the repo by its directory |
-| Cross-references come from | any `ENG-1234` in the README prose | **only** `[[wiki-links]]` |
+| Cross-references come from | any `TEST-1234` in the README prose | **only** `[[wiki-links]]` |
 | Ordering | date, then ticket number, then id | date, then id (every slug scores 0 on the number) |
 
 Two consequences worth knowing before you adopt it:

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/config/stack.yaml

@@ -13,12 +13,12 @@
 # stack.example.no-warehouse.yaml (no warehouse seam — document/report deliverables).
 
 project:
-  key_prefix: ENG                       # ticket-ID prefix; branch names = {key_prefix}-NNNN
-  key_prefixes: [ENG]                   # prefixes the ticket index recognizes (defaults to [key_prefix])
+  key_prefix: TEST                      # ticket-ID prefix; branch names = {key_prefix}-NNNN
+  key_prefixes: [TEST]                  # 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)
+  default_epic: TEST-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
   # intake: [tracker]                   # where work arrives (tracker | email | chat); email/chat intake = forwarded threads in source_materials/

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/hooks/ticket_index_context.py

@@ -60,8 +60,23 @@ def discovered_total(root: Path) -> int | None:
         return None
 
 
+def hidden_keyed(root: Path) -> list[str]:
+    """Keyed folders slug mode is hiding (see build_ticket_index.hidden_keyed_folders). Fails open."""
+    try:
+        import sys
+        kit = os.environ.get("CLAUDE_PLUGIN_ROOT")
+        bindir = (Path(kit).resolve() if kit else Path(__file__).resolve().parent.parent.parent) / "bin"
+        sys.path.insert(0, str(bindir))
+        from build_ticket_index import hidden_keyed_folders, hidden_keyed_warning  # type: ignore
+        hidden = hidden_keyed_folders(root)
+        return [hidden_keyed_warning(hidden)] if hidden else []
+    except Exception:
+        return []
+
+
 def main() -> int:
     root = project_root()
+    warn = hidden_keyed(root)
     data_file = root / "tickets" / "index_data.json"
     index_file = root / "tickets" / "INDEX.md"
 
@@ -79,6 +94,10 @@ def main() -> int:
         if index_file.is_file():
             print("## Ticket index\nCatalog of prior ticket work: `tickets/INDEX.md` — grep it before "
                   "starting related work (same object / stakeholder / report).")
+            if warn:
+                print(warn[0])
+        elif warn:
+            print("## Ticket index\n" + warn[0])
         return 0
 
     total = discovered_total(root) or len(tickets)
@@ -106,8 +125,11 @@ def main() -> int:
         lines.append(f"- {t.get('owner')}/{t.get('id')} ({d}) — {title}")
     if total > len(tickets):
         lines.append(f"({total - len(tickets)} newer ticket(s) on disk not yet enriched — run the index workflow.)")
-    elif len(tickets) > total:
+    elif len(tickets) > total and not warn:
+        # Not while slug mode is hiding keyed folders: those records DO have folders, and pruning
+        # would delete them. The warning below says what to do instead.
         lines.append(f"({len(tickets) - total} record(s) have no folder on disk — run /refresh index --prune.)")
+    lines += warn
     print("\n".join(lines))
     return 0
 

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/settings.json.tmpl

@@ -1,5 +1,5 @@
 {
-  "_README": "Rendered to .claude/settings.json by /setup. The hooks block below is for a VENDORED (cp -r) install, where nothing else wires the kit's hooks. On a PLUGIN install (CLAUDE_PLUGIN_ROOT set), .claude-plugin/plugin.json already wires these same hooks from the plugin dir, so /setup OMITS this hooks block to avoid double-firing (double db-write prompts, double index regen) AND MERGES an 'extraKnownMarketplaces' (ticketwright source {source:'git', url:'https://github.com/kyle-chalmers/ticketwright.git'} — the discriminator `claude plugin marketplace add` writes itself; 'git' and 'url' are different source types — plus autoUpdate:true) + 'enabledPlugins' (ticketwright@ticketwright:true) block so the REPO opts every user into the plugin at PROJECT scope (a plugin cannot set its own install scope — the repo does; registering the marketplace is not installing the plugin, so teammates must still run the two --scope project install commands themselves, README Track 2), committed with the repo, and self-updates on formal releases only (version-string change; never un-released main commits). The documented install already writes most of that block via `--scope project` on both `marketplace add` and `plugin install` (everything except autoUpdate), so setup MERGES into those two maps — preserving unrelated entries, an existing ticketwright source (a fork edits that URL), and any explicit autoUpdate:false — rather than overwriting. Do NOT add those two keys on a vendored install — there is no marketplace to enable from. permissions + statusLine are written in both modes (setup appends stack-specific CLI allows); on a plugin install setup copies statusline.sh into .claude/ so the relative command resolves. The db_write_guard hook turns 'db_write_requires_approval' into a mechanical ask before any destructive warehouse statement; the source_material_guard hook turns 'source_material_guard' into a mechanical ask before a raw meeting transcript is staged for commit or copied into a docstore backup; the review_verdict_guard hook turns 'hard_halt_before_external_posts' into a mechanical ask before a git push / PR of a ticket with deliverables and no APPROVE verdict on file.",
+  "_README": "Rendered to .claude/settings.json by /setup. The hooks block below is for a VENDORED (cp -r) install, where nothing else wires the kit's hooks. On a PLUGIN install (CLAUDE_PLUGIN_ROOT set), .claude-plugin/plugin.json already wires these same hooks from the plugin dir, so /setup OMITS this hooks block to avoid double-firing (double db-write prompts, double index regen) AND MERGES an 'extraKnownMarketplaces' (ticketwright source {source:'git', url:'https://github.com/kyle-chalmers/ticketwright.git'} — the discriminator `claude plugin marketplace add` writes itself; 'git' and 'url' are different source types — plus autoUpdate:true) + 'enabledPlugins' (ticketwright@ticketwright:true) block so the REPO opts every user into the plugin at PROJECT scope (a plugin cannot set its own install scope — the repo does; registering the marketplace is not installing the plugin, so teammates must still run the two --scope project install commands themselves, docs/getting-started.md Track 2), committed with the repo, and self-updates on formal releases only (version-string change; never un-released main commits). The documented install already writes most of that block via `--scope project` on both `marketplace add` and `plugin install` (everything except autoUpdate), so setup MERGES into those two maps — preserving unrelated entries, an existing ticketwright source (a fork edits that URL), and any explicit autoUpdate:false — rather than overwriting. Do NOT add those two keys on a vendored install — there is no marketplace to enable from. permissions + statusLine are written in both modes (setup appends stack-specific CLI allows); on a plugin install setup copies statusline.sh into .claude/ so the relative command resolves. The db_write_guard hook turns 'db_write_requires_approval' into a mechanical ask before any destructive warehouse statement; the source_material_guard hook turns 'source_material_guard' into a mechanical ask before a raw meeting transcript is staged for commit or copied into a docstore backup; the review_verdict_guard hook turns 'hard_halt_before_external_posts' into a mechanical ask before a git push / PR of a ticket with deliverables and no APPROVE verdict on file.",
   "hooks": {
     "PreToolUse": [
       {

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/build/SKILL.md

@@ -33,7 +33,9 @@ foreign owners share is a hard stop listing the `owner/id` choices, never a pick
      first; every ticket is scoped before it is built." (A spec passed as an argument does not
      substitute: the plan is the approval record.)
    - **`spec:` names a path** → that spec is the executable detail; load it (the argument path wins
-     if one was given). If the named file does not exist → stop: "`plan.md` for `<owner>/<id>` names
+     if one was given). The path is repo-root-relative (`<ticket-dir>/specs/<id>-<slug>.md`); a bare
+     `specs/<id>-<slug>.md` from an older plan resolves inside `<ticket-dir>`, never at the repo
+     root. If the named file does not exist → stop: "`plan.md` for `<owner>/<id>` names
      a spec that is not on file — run `/ticket <owner>/<id>` to finish scoping."
    - **`spec: not required`** → the plan is the blueprint.
    - **`spec: after-root-cause`** → run only the plan's investigation steps (read-only against the
@@ -69,8 +71,10 @@ foreign owners share is a hard stop listing the `owner/id` choices, never a pick
    first warehouse run (a bad join is cheapest to catch before it costs a warehouse-minute), and
    hand the exported CSVs over after. Both via
    `bash "$(git rev-parse --show-toplevel 2>/dev/null || echo .)/bin/tw" handoff.sh <paths>`, then wait for
-   sign-off before continuing. It exits 0 and stays silent when that user has no viewer config —
-   note it once and carry on; this never blocks a build.
+   sign-off before continuing. Say a file was opened only when handoff printed an `opened:` line
+   for it. With no viewer config, `enabled: false`, or only `would run:` lines, nothing opened: say
+   so once, with the reason handoff gave (for example "No viewer is configured, so nothing was
+   opened"), list the paths, and carry on. This never blocks a build.
 5. **Any mutation** ⇒ policy `db_write_requires_approval` (`off` | `high_risk` | `all`). Under the
    default `high_risk`: show the exact SQL, explain the change, and wait for explicit `yes` before
    anything irreversible or access-changing (DROP/DELETE/UPDATE/TRUNCATE/MERGE/GRANT/

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/review/SKILL.md

@@ -78,9 +78,12 @@ canonical order resolves next — the ticket's declared target before the seam d
   bullet when it is `off`). Layers ①–④ prove the query is *internally* consistent; only a person can
   say the numbers are the right numbers. Do not emit a verdict before this:
   1. `bash "$(git rev-parse --show-toplevel 2>/dev/null || echo .)/bin/tw" handoff.sh <final_deliverables + qc_queries paths>`
-     — routes each file to the app that user chose. It exits 0 and stays silent when they have no
-     viewer config; in that case say so **once** and continue, never block.
-  2. If it produced no output and no **usable** config exists, offer the one-time setup: which app
+     routes each file to the app that user chose. **Say a file was opened only when handoff
+     printed an `opened:` line for it.** With no `opened:` line (no viewer config, `enabled: false`,
+     or `would run:` in a session with no desktop), nothing was opened: say so plainly and **once**
+     (for example "No viewer is configured, so nothing was opened"), list the paths so the person
+     can open them, and continue. Never block. Its stderr names which case it was.
+  2. If it opened nothing and no **usable** config exists, offer the one-time setup: which app
      for `.sql`, which for `.csv`, this repo only or all their repos. Their answers are written to
      `.claude/config/viewer.local.yaml` (gitignored, per-user) or the user-level path — see
      `.claude/config/viewer.example.yaml`. "None / don't ask again" writes `enabled: false`.

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/setup/interview.md

@@ -233,7 +233,7 @@ deliverables open for human sign-off at `/review` only."
 
 ```yaml
 project:
-  key_prefix: ENG
+  key_prefix: TEST
   assignee_dir: alice
   ticket_path: "tickets/{assignee}/{id}"
   terminal_status: Done

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/setup/scaffold.md

@@ -156,7 +156,8 @@ project-relative `.claude/statusline.sh`, so on a plugin install **copy
 vendored install it's already there).
 
 ## Folders + `.gitignore`
-Create `tickets/{assignee_dir}/`, `documentation/`, `resources/`, `specs/` (and `ci/` if wanted).
+Create `tickets/{assignee_dir}/`, `documentation/`, `resources/` (and `ci/` if wanted). No repo-root
+`specs/`: a spec lives with its ticket, at `<ticket-dir>/specs/`, written by `/ticket`.
 Render `<KIT>/templates/gitignore.tmpl` → `.gitignore` (merge if
 one exists). Deliverable exports (`final_deliverables/*.csv` etc.) are **committed by default** so
 results live with the ticket and show in the PR; PII/customer data opts out via a `*.private.csv`

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/ticket/SKILL.md

@@ -133,8 +133,9 @@ context brief (including the reuse brief) first, then:
      **nothing is written to the ticket until step 12; no runtime mode is required.** Read-only here
      is GUIDANCE the agent follows, not a gate the runtime enforces — say so if asked.
 9. **Draft the plan — compose it, do not write it yet.** Its shape is `templates/plan.md.tmpl` under
-   `kit_root`: Goal, Scope (in / explicitly out), Deliverables expected, Approach, Validation
-   strategy, Touched, Questions for the requester, Risks, Next step, Confidence. Inputs: the priming
+   `kit_root`: Goal, Scope (in / explicitly out), Builds on (each prior ticket from the reuse brief and
+   why it matched), Deliverables expected, Approach, Validation strategy, Touched, Questions for
+   the requester, Risks, Next step, Confidence. Inputs: the priming
    brief + the reuse brief. Decide the **`spec:` value** by the criteria in the template's header —
    `not required`, or a spec path (required when the work creates or alters a persisted object others
    depend on, reconciles two or more sources, or confidence is below 7), or `after-root-cause` for an

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/ticket/priming.md

@@ -56,6 +56,11 @@ knowledge base. Each slice below was a separate command in v1 (`/prime-ticket`,
   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.
+  **Name every prior ticket you build on by `<owner>/<id>` and say why it matched**, translating the
+  bracketed reasons recall printed beside it into plain words: `obj:` → "shares the object `X`",
+  `tag:` → "shares the tag `t`", `ref` → "the two tickets cross-reference each other", `kw:` alone →
+  "keyword overlap only" (the weakest signal; say so). A match with no stated reason reads as
+  staged, and the reason is what lets a reader check it.
 
 ## 3 · Domain slice (business meaning)
 

{ticketwright-4.1.0 → ticketwright-4.2.0}/.claude/skills/ticket/spec.md

@@ -30,8 +30,10 @@ the scope, the deliverables and the open questions — read it first and do not
    returned — no second launcher call) and fill every section it defines; its **validation gates**
    become `/review`'s checklist, and its **dev target** is `seams.warehouse.dev_target`, else the key
    the warehouse adapter names in its `dev_key:` frontmatter. Set the plan's `spec:` line to the path
-   it will be written to, `specs/<id>-<slug>.md`. Like the plan, it is drafted now and written to the
-   ticket only at `/ticket` step 12, after approval.
+   it will be written to, `<ticket-dir>/specs/<id>-<slug>.md`, spelled out from the repo root (for
+   example `tickets/alice/TEST-130/specs/TEST-130-returns.md`) so `/build` cannot resolve it anywhere
+   else. Like the plan, it is drafted now and written to the ticket only at `/ticket` step 12, after
+   approval.
 4. **Reduce assumptions:** add the spec's open questions to the plan's list — `/ticket` asks them all
    at once, before approval (`reduce_assumptions`).
 5. **Do not write or commit here.** `/ticket` step 12 writes the plan and the spec and commits them

{ticketwright-4.1.0 → ticketwright-4.2.0}/CHANGELOG.md

@@ -4,6 +4,106 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); this project uses semantic-ish versioning.
 
 
+## [Unreleased]
+
+## [4.2.0] — 2026-10-03
+
+### Changed
+- **Upgrades now remove retired skills instead of only warning about them.** A repo installed
+  before the `productize` → `skillify` or `spec-and-build` → `build` rename kept the old skill
+  directory, so `/productize` and `/spec-and-build` still showed up in the slash menu beside their
+  replacements. `ticketwright init` and `ticketwright install --runtime <name>` now delete a retired
+  directory when every file in it is byte-identical to a version Ticketwright shipped (or, in an
+  emitted tree, still carries the installer's provenance header), and print what they removed. A
+  directory with anything edited is kept, and the warning now names the files that differ. A
+  vendored copy upgraded with `git pull` can run the same check with `bash bin/tw retired_skills.py`.
+  The verify-only paths still delete nothing. The rule and the list of shipped-version hashes live
+  in one place, `bin/retired_skills.py`, which both installers import.
+- **Example tickets use the `TEST` project key.** The README's team-repo tree, the docs, the shipped
+  `stack.yaml` and every stack example, the adapter docs, the setup interview's sample config, the
+  example index store, the golden-replay template and the CLI help all showed `ENG-` (and one
+  `DEMO-`) keys; they now use `TEST-` with the same numbers, so cross-references in the examples
+  still line up. Test fixtures keep their existing keys, and `ENG-`/`DEMO-`/`TEST-`/`SAMPLE-` all
+  stay legal fixture prefixes.
+- **The README is a two-minute read.** It dropped from about 7,300 words to under 600 words of
+  prose, and now shows how the system works as two diagrams (the ticket lifecycle, and how skills
+  reach your tools through adapters) and what a working team repo looks like as a folder tree:
+  one folder per person, one per ticket, each file labeled with the step that writes it. Nothing was cut: the install tracks, the doctor
+  checklist, the committed settings block, adoption and non-plugin installs moved verbatim to
+  [docs/getting-started.md](docs/getting-started.md); the team-brain mechanisms, lifecycle detail,
+  voice profiles, safety rails and the full hooks table moved to
+  [docs/how-it-works.md](docs/how-it-works.md). Every selftest pin on that text follows it to its
+  new home, and a new section 58 holds the README to a 600-word prose budget, requires the
+  visuals, and checks that every relative link resolves.
+- **The hooks table now lists every hook, and the DB guard's reach is stated honestly.** The old
+  README's "Hooks, in full" table left out `source_material_guard.py`; it is listed now. The
+  safety-rails line said the DB guard inspects "every warehouse command", but it sees only CLI
+  commands run through Bash, and SQL sent through an MCP tool never reaches it. Both surfaces now
+  say so.
+- **Upgrades are stated as manual, because they are.** `autoUpdate` refreshes the marketplace
+  catalog and never upgrades the installed plugin (claude-code #61854, #52218, #49410, #17361). The
+  README, `docs/getting-started.md` (Track 1 step 4, "What setup writes", the committed-settings
+  notes) and the troubleshooting upgrade table now say so plainly, and name the upgrade as
+  uninstall, install, relaunch. ROADMAP's open question on this is closed with the finding.
+- **A plan names the prior work it builds on, and why recall matched it.** The reuse brief now names
+  each prior ticket by `owner/id` with the reason `recall.py` already prints (a shared object, a
+  shared tag, a cross-reference, or keyword overlap only), and `templates/plan.md.tmpl` gains a
+  `## Builds on` section to carry it into the approved plan.
+- **The example configs spell the write policy out.** `stack.example.solo.yaml` and
+  `stack.example.multi-warehouse.yaml` used the legacy `db_write_requires_approval: true`; they now
+  say `high_risk`, which is what `true` already meant.
+
+### Added
+- **`plugin_doctor` names the "network source differs" install failure.** A new check,
+  `marketplace_source`, reads your user-level `settings.json` for the marketplace's declared source.
+  When it differs from what this repo declares (most often the GitHub shorthand left by an older
+  install), `claude plugin marketplace add` fails with "its network source differs from the one
+  declared for it in settings". The check says so before you hit it and gives the fix. Only the
+  source's kind is reported, never the value. The install checklists in `docs/getting-started.md`
+  and `templates/AGENTS.md.tmpl` gain the matching line (now fifteen checks).
+
+### Fixed
+- **The review hand-off no longer lets an agent claim it opened files it did not.** With no viewer
+  configured, or `enabled: false`, `bin/handoff.sh` opened nothing and printed nothing, and an agent
+  told a person "I've opened the note and the checklist for you to read". It now says on stderr that
+  nothing was opened and why (stdout stays empty), and `/review` and `/build` claim a file opened
+  only when handoff printed an `opened:` line for it.
+- **Switching a keyed repo to `id_mode: slug` no longer loses tickets silently.** A slug id must be
+  lowercase, so folders named with a tracker key (`tickets/alice/TEST-14`) stopped being tickets and
+  dropped out of `INDEX.md`, `OBJECTS.md` and the graph with no message (an audit saw `OBJECTS.md`
+  go from 3 objects to 0). Worse, their curated records then looked orphaned: the session banner
+  recommended `/refresh index --prune`, and `--prune` deleted them. `bin/build_ticket_index.py` now
+  prints a `WARNING` naming the hidden folders on every run (render, `--check`, `--stats`,
+  `--prune`); `--check` keeps its staleness exit code. `--prune` refuses while any are hidden, and
+  the session banner shows the warning instead of recommending a prune. Slug discovery itself is
+  unchanged.
+- **A spec has one home: its ticket folder.** `/ticket` wrote the spec to `<ticket-dir>/specs/`,
+  but the plan's `spec:` line (the path `/build` loads) read a bare `specs/<id>-<slug>.md`, and
+  `/setup` also created an empty repo-root `specs/` that nothing ever wrote to. The same path
+  therefore named two places, depending on where it was resolved. `/setup` no longer creates the
+  root folder; the plan template and `spec.md` now write the full `<ticket-dir>/specs/<id>-<slug>.md`
+  path; and `/build` resolves a bare `specs/` path from an older plan inside the ticket folder, so
+  plans already on file keep working. A repo that already has an empty root `specs/` can delete it.
+
+
+## [4.1.1] — 2026-09-18
+
+### Fixed
+- **A refused delivery destination now says which character was refused, and what to do.** The
+  delivery resolver's shell-metacharacter refusal (`bin/delivery_plan.py`) named only the key —
+  "the `drive_folder` value carries shell metacharacters" — and left the reader to find the
+  offending character themselves. Every refusal (destination, recipients, sender; both the routing
+  halt `/ship` acts on and the `--audit` advisory `verify_stack` prints) now names the character(s)
+  and the remedy — pointing at the value's actual source: the tool slot config (including a
+  literal `base_path` pinned there), the machine-local half of a composed docstore path
+  (`mount_root` / `remote`), or, for a tool-only chat slot, `chat.channel:` / `chat.recipients:`
+  in the ticket's delivery plan. A folder name such as `Reports & Analysis` is the common trigger. What is refused is unchanged — the same
+  values still halt; they are now explained. `effective_config.offending_chars()` is the one
+  helper behind every message. One path is deliberately unchanged and noted for a follow-up: the
+  `verify:`-template refusal in `bin/verify_stack.sh` (a `{base_path}` token whose machine-local
+  half is unsafe) still names only the token, not the character.
+
+
 ## [4.1.0] — 2026-09-12
 
 ### Added

ticketwright-4.2.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: ticketwright
+Version: 4.2.0
+Summary: Tool-agnostic AI layer for ticket-driven work repos: prior-art recall, object reverse-index, deep QC, and a self-maintaining ticket index. Stdlib-only, no vector store.
+Project-URL: Homepage, https://github.com/kyle-chalmers/ticketwright
+Project-URL: Repository, https://github.com/kyle-chalmers/ticketwright
+Project-URL: Issues, https://github.com/kyle-chalmers/ticketwright/issues
+Author: Kyle Chalmers
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,jira,linear,qc,recall,snowflake,ticket-index,tickets,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ticketwright
+
+[![CI](https://github.com/kyle-chalmers/ticketwright/actions/workflows/ci.yml/badge.svg)](https://github.com/kyle-chalmers/ticketwright/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/tag/kyle-chalmers/ticketwright?label=release&sort=semver&color=blue)](https://github.com/kyle-chalmers/ticketwright/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3%20%C2%B7%20stdlib--only-3776AB)
+![tool-agnostic](https://img.shields.io/badge/works%20with-your%20tracker%20%C2%B7%20warehouse%20%C2%B7%20chat%20%C2%B7%20docs%20%C2%B7%20meetings%20%C2%B7%20git-success)
+
+## Mission
+
+**Ticketwright empowers a team to do a high volume of analysis without letting quality slide, on whatever tools they already use.**
+
+## Vision
+
+**Any new or experienced member can pick up any analysis and be productive the same day, because the team's past work is written down and organized, and AI can trace it.**
+
+---
+
+Built for analysts, BI, ops, research and reporting teams whose work product is an answer rather
+than a feature. It sits beside your tracker, warehouse and dashboards.
+
+## What it builds: a team brain
+
+Every ticket lands in one folder with its business context, written assumptions, QC verdict and
+deliverables. An auto-maintained catalog (`tickets/INDEX.md`) and object map (`tickets/OBJECTS.md`)
+make that history searchable by people and agents, so `/ticket` opens new work with the closest
+prior work already ranked. Details: [docs/how-it-works.md](docs/how-it-works.md).
+
+## The lifecycle is the map
+
+Every ticket moves through the same five phases, and each shipped ticket feeds the next:
+
+```mermaid
+flowchart LR
+    B[("Team brain<br/>tickets/ + INDEX.md")] -- "closest prior work" --> P1
+    P1["1 · Open the work<br/>/ticket"] --> P2["2 · Do the work<br/>/build"] --> P3["3 · Quality-check<br/>/review"] --> P4["4 · Deliver<br/>/ship"] --> P5["5 · Announce<br/>/ship"]
+    P4 -- "files the ticket, its assumptions and QC verdict" --> B
+```
+
+Quality checking has no slot of its own: `/review` borrows the warehouse to re-run your queries,
+then a person signs off.
+
+Skills speak to tool slots, never to a vendor, so swapping a tool is one config line and one
+adapter file:
+
+```mermaid
+flowchart LR
+    S["Skills<br/>/ticket · /build · /review · /ship"] -- "verbs: fetch_ticket,<br/>query, backup, draft" --> Y["stack.yaml<br/>which tool fills<br/>each slot"]
+    Y --> A["adapters/slot/tool.md<br/>verb to real command"]
+    A --> T["Your tools<br/>Jira · Snowflake · Slack<br/>GitHub · Drive · ..."]
+    H{{"Hooks ask first:<br/>destructive SQL,<br/>unreviewed push"}} -. guard .-> T
+```
+
+Cloud-drive backup needs one machine-local step: [docs/drive-mount.md](docs/drive-mount.md).
+
+| Tool slot | Works with |
+|---|---|
+| Tracker | Jira, Azure DevOps, Linear, Asana, Monday, GitHub Issues, or none (`id_mode: slug`) |
+| Warehouse | Snowflake, BigQuery, Databricks, Postgres, Redshift, Synapse, or none |
+| Chat | Slack, Teams, Gmail, Outlook |
+| Docs | Google Drive, SharePoint, or Dropbox/S3/Box through rclone |
+| Meetings | Zoom, Fireflies, Granola, Teams, Notion (optional) |
+| Git | GitHub, GitLab, Azure Repos |
+
+These adapters ship today; another tool is [one more adapter file](adapters/README.md).
+
+## What a working repo looks like
+
+`/setup` writes the top half once. The `tickets/` half grows as the team works: one folder per
+person, one folder per ticket, and the same shape inside every ticket. The labels show which step
+writes each piece.
+
+```
+your-repo/
+├── AGENTS.md                  # team rules, read by people and agents alike
+├── CLAUDE.md                  # one line: @AGENTS.md
+├── bin/tw                     # launcher that finds the installed kit
+├── .claude/config/
+│   ├── stack.yaml             # which tool fills each slot, plus team policies
+│   └── connections.local.yaml # your machine only (gitignored)
+├── people/
+│   ├── alice.yaml             # one file per teammate: identities, viewer, voice
+│   └── bob.yaml
+├── documentation/             # the domain knowledge pack
+└── tickets/
+    ├── INDEX.md               # every owner's tickets in one catalog      (auto)
+    ├── OBJECTS.md             # table or view -> tickets that touched it  (auto)
+    ├── graph/  objects/       # Obsidian nodes for tickets and tables     (auto)
+    ├── bob/
+    │   └── TEST-118/          # returns baseline, shipped last month
+    └── alice/
+        ├── TEST-127/          # shipped
+        └── TEST-130/          # in progress, builds on bob's TEST-118
+            ├── README.md              /ticket   business context, every assumption
+            ├── plan.md                /ticket   the plan you approved
+            ├── specs/                 /ticket   the spec, when the plan calls for one
+            ├── source_materials/      /ticket   attachments, curated meeting notes
+            ├── exploratory_analysis/  /build    scratch queries, kept for the record
+            ├── final_deliverables/    /build    01_returns_by_region_1284rows.sql + .csv
+            ├── qc_queries/            /build    numbered checks, then /review's verdict
+            └── delivery-plan.yaml     /ship     who received it, and where
+```
+
+Nobody maintains the catalog by hand. `/ship` files each finished ticket into `INDEX.md`,
+`OBJECTS.md` and the graph, and `/ticket` searches every owner's past work, not only yours. When
+Alice's TEST-130 mentions Bob's TEST-118, the two are linked, so her reviewer can trace the numbers
+back to his. A new teammate adds one `people/` file and gets their own folder. Nothing else changes.
+
+## How work flows
+
+```
+/ticket <id>        opens or resumes the ticket, auto-loads its context + closest prior work,
+                    writes the plan (and the spec when the plan calls for one), and waits for
+                    your approval before anything is built ↓
+/build              executes the approved plan or spec in fresh context, then runs /review itself
+/review [--deep]    the independent QC pass /build runs for you: re-runs queries, walks the validation
+                    pyramid → APPROVE / REQUEST-CHANGES; run it directly to re-check or go --deep
+                    …and at the top of that pyramid, opens the deliverables in YOUR apps and waits
+/ship [--go]        backup → tracker comment → chat draft → commit + PR — HARD HALT before anything
+                    external; warns, waits for a typed `ship unreviewed`, and records it when no
+                    review verdict is on file
+```
+
+Also: `/setup` (configure once, onboard a teammate), `/refresh` (rebuild the catalog), and
+`/skillify` (turn a recurring workflow into its own skill). On a plugin install, prefix each one:
+`/ticketwright:ticket`.
+
+## Get started
+
+Install project-scoped, from the root of the repo you work tickets in:
+
+```bash
+claude plugin marketplace add https://github.com/kyle-chalmers/ticketwright.git --scope project
+claude plugin install ticketwright@ticketwright --scope project
+```
+
+Run `/reload-plugins` (or fully quit the app; a new chat is not a restart), then
+`/ticketwright:setup`, which detects your tools and interviews you before writing anything. First
+person in a repo (Track 1) or joining one (Track 2): [docs/getting-started.md](docs/getting-started.md)
+has both, with a prompt to paste to your agent. `autoUpdate` never upgrades the plugin:
+[uninstall, install, relaunch](docs/troubleshooting.md#upgrading).
+
+## Safety rails
+
+- Destructive warehouse SQL run through a CLI asks first, even when it's hidden in a `-f` file.
+- `/ship` stops before any external post and shows exactly what it will send.
+- Pushing a ticket's deliverables with no approving review on file asks first.
+
+Every hook is listed in [docs/how-it-works.md](docs/how-it-works.md#hooks-in-full).
+
+## See it as a graph (Obsidian)
+
+The index also writes `tickets/graph/` and `tickets/objects/`, so opening the repo as an Obsidian
+vault shows which tickets touched which tables. See [docs/obsidian.md](docs/obsidian.md).
+
+## Learn more
+
+- [docs/getting-started.md](docs/getting-started.md): install tracks, what setup writes, adopting
+  a repo, pip and other runtimes
+- [docs/how-it-works.md](docs/how-it-works.md): the lifecycle, voice profiles, every hook
+- [docs/architecture.md](docs/architecture.md): adapters, the verb contract, adding a tool
+- [docs/troubleshooting.md](docs/troubleshooting.md): failed skills, unreachable tools, upgrades
+- [docs/obsidian.md](docs/obsidian.md) and [docs/drive-mount.md](docs/drive-mount.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md) · [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT, see [`LICENSE`](LICENSE).