ticketwright 4.0.0__tar.gz → 4.0.2__tar.gz

{ticketwright-4.0.0 → ticketwright-4.0.2}/.claude/config/stack.schema.md

@@ -114,7 +114,7 @@ policies:       # behavioral rules every skill inherits (the kit's "global rules
 | `key_prefix` | string | `ENG` | 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]`). |
-| `assignee_dir` | string | `alice` | Last-resort owner subdir under `tickets/`, used only when no people map exists (`bin/whoami.py` returns `miss` and there are no `people/*.yaml`). With a people map, the whoami-resolved person is the owner. |
+| `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). |

{ticketwright-4.0.0 → ticketwright-4.0.2}/.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; teammates are prompted to install), 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.",
+  "_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.",
   "hooks": {
     "PreToolUse": [
       {

{ticketwright-4.0.0 → ticketwright-4.0.2}/.claude/skills/setup/SKILL.md

@@ -130,6 +130,34 @@ which prints the resolved commands without launching anything. Never commit this
 ## Default mode — configure the repo
 
 ### Phase 1 — Detect (no questions yet)
+0. **Preflight — the ways a run is doomed before it starts.** Both probes are read-only and cheap;
+   run them before anything else, because neither failure is fixable by anything this skill writes.
+   - **Is this a clone?** `!git rev-parse --show-toplevel` — a non-zero exit means there is no
+     repository here. **Halt**, and say why: "There is no `.git` in this folder. If it came from a
+     Download-ZIP button (the folder name usually ends in `-main`), Ticketwright cannot branch,
+     commit, or open a PR from it, and no config would fix that. Clone the repo instead —
+     `git clone <the repository's URL>` — then re-run `/setup` inside the clone."
+   - **Is the kit installed and usable here?**
+     `!python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/plugin_doctor.py" --json` — one
+     read-only pass over the install prerequisites (it never installs anything, and makes no
+     network call). Report **every** finding that is not `ok`, each with its `fix` lines
+     **verbatim**: they are exact commands, and a paraphrased command is one nobody can run.
+     A `fail` on any of these three is a **halt**, because nothing setup writes reaches the cause:
+     - `scope_supported` — the agent CLI is too old to install a plugin for one repo; the fix names
+       both the in-session install route and the update command for how it was installed;
+     - `repo_install` — nothing is installed for this repository;
+     - `install_payload` — the install record points at a directory that does not exist.
+     Everything else (`warn`, `unknown`, a global-only install, a stale catalog) is reported and
+     the run continues. On a non-plugin install — a vendored kit, a pip install — the install
+     checks answer `unknown`: that is the expected answer there, not a failure. If the script is
+     absent (an older kit copy), say so in one line and carry on.
+   - **`yq`** — when `yq_present` is not `ok`, Phase 4's kit-integrity check cannot run at all.
+     Print the platform install command the doctor gives, and **offer to run it now**, while it is
+     still cheap — not at the moment the check fails. Say in the same breath what that check costs:
+     it runs 1,200+ assertions over several minutes, longer than a typical tool timeout, so give it
+     the background or a raised timeout and judge it by its **exit code**, never by whether the
+     tail of its output looks green.
+   Identity routing is unchanged: it happens at step 4 below.
 1. **CLIs:** `!for c in snow acli gh glab bq databricks yq jq git rclone; do command -v $c >/dev/null && echo "✓ $c" || echo "– $c"; done`
 2. **MCP servers** connected this session (tracker / chat / warehouse servers).
 3. **Repo facts — probes, not questions.**
@@ -140,7 +168,9 @@ which prints the resolved commands without launching anything. Never commit this
      confirms instead of asking. The default branch comes from
      `git symbolic-ref refs/remotes/origin/HEAD` — **not** `git symbolic-ref HEAD`, which reports
      whatever branch happens to be checked out and would misconfigure any setup run from a
-     feature branch.
+     feature branch. On a repo nothing has been pushed to yet that probe exits 128 ("not a
+     symbolic ref") — fall back to the current local branch and confirm it in prose; never leave the
+     agent to improvise on a failed probe.
    - **Obsidian:** installed or not (e.g. `command -v obsidian`, or the OS application folder).
      Never a question — `graph_notes`/`graph_config` already default correctly; this only decides
      which one-liner the Phase-4 report prints (step 8).
@@ -258,7 +288,9 @@ Only on explicit confirmation, execute — **source of truth first, derived file
 7. **Two distinct checks — keep them labeled as such in the report:**
    - `!bash "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/selftest.sh"` — **kit integrity**. It
      validates the plugin's *own bundled example* stacks, **not** your repo's config. A failure here
-     is fatal.
+     is fatal. It runs 1,200+ assertions and takes several minutes — longer than a typical
+     tool timeout, so run it in the background or with a raised timeout, and judge it by its exit
+     code (non-zero on any failure), not by whether the tail of its output looks green.
    - `!bash "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/verify_stack.sh" .claude/config/stack.yaml`
      — **your repo's stack** reachability (pass the repo stack path explicitly so it's unambiguous
      which config was checked). An unreachable tool slot is **not** fatal at setup time; print its
@@ -278,6 +310,11 @@ Only on explicit confirmation, execute — **source of truth first, derived file
    - **The punch list** — one entry per skipped round, each naming its re-entry command
      (`/setup role` for round 5, `/setup policies` for round 6). Deferring must be trackable;
      "took defaults" must never be indistinguishable from "chose".
+   - **`project.assignee_dir`, in one line — what the key is for, not a warning.** It is the
+     last-resort owner subdir under `tickets/` for a repo with no `people/` roster. Once a roster
+     exists, the owner of new work is whoever `whoami` resolves, and a person it does not
+     recognize is a stop (`/setup --teammate`) rather than a fall-back to this key — so say that,
+     and never describe it as something setup is refusing to touch.
    - **Email, when round 4 recorded delivery:** say plainly that email is **configured but not
      yet activated** — the commented target block holds the answers, and nothing will send until
      someone deliberately activates it: convert the chat slot to `targets:` form with a declared
@@ -296,4 +333,6 @@ Only on explicit confirmation, execute — **source of truth first, derived file
    ticket PR references rules/adapters absent from the repo's history. Offer a commit (e.g.
    `chore: initialize ticketwright workspace`). First flag that `stack.yaml` may hold internal
    identifiers (tracker site, warehouse project/dataset) — config, not secrets, but worth a glance
-   before committing to a public repo.
+   before committing to a public repo. On a remote created empty (no default branch yet), this
+   first push seeds `main` directly — there is nothing to open a PR against — and the PR flow
+   starts with the next change; say so rather than colliding with a never-push-to-main rule.

{ticketwright-4.0.0 → ticketwright-4.0.2}/.claude/skills/setup/interview.md

@@ -21,6 +21,12 @@ it in later" is always a valid answer: write the key as a `# TODO` and keep goin
 `verify_stack.sh` names every unset required key as a warning on every run, so a deferred key is a
 tracked choice, not a silent hole.
 
+One key deserves a precision note wherever it is asked: a slot's **`mcp:` value must be the
+runtime's exact tool prefix** — the `<name>` in `mcp__<name>__*` — because adapters render tool
+names from it. Tell the person to copy it from a tool name they can see, not from a UI label; a
+friendly name that matches no connected server makes every rendered tool name point at nothing,
+and nothing errors until a skill tries to call one.
+
 Never promise a question count, in this file or in any report — a stated number becomes the
 binding constraint on correctness, which is exactly the defect this round structure replaced.
 

{ticketwright-4.0.0 → ticketwright-4.0.2}/.claude/skills/setup/scaffold.md

@@ -79,8 +79,9 @@ Render `${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/.claude/settings.json.tmpl`
 **On a plugin install, also commit a project-scoped enablement.** A plugin can't set its own install
 scope — the *repo* opts in. Merge these two keys
 into the rendered `.claude/settings.json` so the plugin is enabled *for this repo* (committed →
-travels with the repo; teammates who open and trust it are prompted to install it; it survives the
-original author leaving) and refreshes
+travels with the repo; it survives the original author leaving). Registering the marketplace is not
+installing the plugin — a teammate who opens and trusts the repo gets the marketplace clone, then
+runs the install themselves (Track 2). It also refreshes
 itself:
 
 ```json

{ticketwright-4.0.0 → ticketwright-4.0.2}/.claude/skills/setup/teammate.md

@@ -38,11 +38,34 @@ commits `/ship` makes. If either is unset, have the person set them now — repo
 re-run step 0): the identity recorded is now one this machine actually resolves by.
 
 ## 1 · Install prerequisites
-Check what's present: `for c in <the CLIs named by the configured tool slots> yq jq git; do
+**First, the two that make everything after them pointless.** Both probes are read-only:
+
+- **Is this a clone?** `!git rev-parse --show-toplevel` — a non-zero exit means there is no
+  repository here. **Halt**: "There is no `.git` in this folder. If it came from a Download-ZIP
+  button (the folder name usually ends in `-main`), Ticketwright cannot branch, commit, or open a
+  PR from it. Clone the repo instead — `git clone <the repository's URL>` — then re-run this
+  inside the clone."
+- **Is the kit installed and usable here?**
+  `!python3 "${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/bin/plugin_doctor.py" --json` — a
+  read-only pass over the install prerequisites; it installs nothing and makes no network call.
+  Report every finding that is not `ok` with its `fix` lines **verbatim** — they are exact
+  commands. A `fail` on `scope_supported` (the agent CLI is too old to install a plugin for one
+  repo), `repo_install` (nothing is installed for this repository) or `install_payload` (the
+  install record points at a directory that does not exist) is a **halt**: none of it is fixable
+  by anything this flow writes, and the fix text names the route out — including the in-session
+  install and the update command for how the CLI was installed. `warn`/`unknown` findings are
+  reported and the flow continues; on a vendored or pip install the install checks answer
+  `unknown`, which is the expected answer there. If the script is absent (an older kit copy), say
+  so in one line and carry on.
+
+Then check the rest: `for c in <the CLIs named by the configured tool slots> 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). Scope note: `yq` is needed only by
 the kit's own `selftest.sh` (step 5 runs it once, as a kit-integrity check) — no skill in a
-configured repo invokes it day to day, so a missing `yq` blocks that one check, nothing else.
+configured repo invokes it day to day, so a missing `yq` blocks that one check, nothing else. When
+`yq_present` is not `ok`, print the doctor's platform install command and **offer to run it now**,
+before step 5 needs it — and say what step 5 costs: several minutes, longer than a typical tool
+timeout, judged by its **exit code**, not by how green the tail of its output looks.
 
 ## 2 · Authenticate each configured tool
 For every configured tool slot, open its adapter's `auth:` notes and walk the person through

{ticketwright-4.0.0 → ticketwright-4.0.2}/.claude/skills/ticket/SKILL.md

@@ -18,19 +18,30 @@ brief, nothing else. Follow [priming.md](priming.md) § Recall. Useful mid-sessi
 this before?", "which tickets touched VW_X?").
 
 ## Phase 0 — Resolve & preflight (halt-on-fail)
-0. **Resolve WHO first** — `bash "${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo .)}/bin/tw" whoami.py`
-   and show its one-line "Working as …" display. This person is the default owner for everything
-   below. By status:
-   - `resolved` — proceed; new work belongs to this person.
-   - `miss` with a people map present (any `people/*.yaml`) — ask once ("I don't recognize
-     `<identity>`. Who are you?"), then `whoami.py --bind <id>`; never infer from a name.
-   - `miss` with **no people map at all** — fall back to `project.assignee_dir`, the documented
-     last resort for repos that predate owner routing.
-   - `ambiguous` — ask which person it is; never rank or pick.
-   - `conflict` — proceed as the machine-pinned person and surface the warning line verbatim.
-1. Read the merged config — `bash "${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo .)}/bin/tw" effective_config.py --json`,
-   never raw `stack.yaml`: `project.*`, `seams.tracker`, `seams.vcs`. If the team config is
-   missing, say so and offer `/setup` — don't scaffold blind.
+0. **Read the merged config first — it is what decides WHO** — `bash "${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo .)}/bin/tw" effective_config.py --json`,
+   never raw `stack.yaml`. It carries `project.*`, `seams.tracker`, `seams.vcs` — and it settles the
+   owner **mechanically**, in one field, so no skill re-derives the rule. If the team config is
+   missing, say so and offer `/setup` — don't scaffold blind. Branch on **`owner_source`**, never on
+   a `people/` listing of your own: a roster can live entirely in
+   `$XDG_CONFIG_HOME/ticketwright/people/` and never appear in this repo, and only the resolver
+   looks in both homes — "no `people/*.yaml` here" is not the same question.
+   - `resolved` — proceed; `owner` is this person and owns everything below.
+   - `unbound` — **HARD STOP here, before any ticket path is rendered.** Say:
+     "I can't tell who you are: `people/<id>.yaml` is a placeholder (or no `people/` entry matches
+     this machine's identity). Run `/setup --teammate` first — it asks who you are, binds it, and
+     sets up your machine." Do **not** fall back to `project.assignee_dir`: with a roster present
+     that key names a COLLEAGUE, and their `tickets/<owner>/` folder is exactly where an unbound
+     teammate's work silently lands. Never infer an owner from a name.
+   - `assignee_dir_fallback` — proceed with `owner`: there is no roster in either home, so
+     `project.assignee_dir` is the documented last resort for repos that predate owner routing.
+   - `none` — stop: no roster and no `assignee_dir`. Offer `/setup`.
+   Read `owner`, never `project.assignee_dir` directly.
+1. **Then show who that is** — `bash "${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo .)}/bin/tw" whoami.py`,
+   and show its one-line "Working as …" display. This is the display-and-binding step; the routing
+   decision was already made in step 0, and whoami never overrides it. Two statuses still change
+   what you do next: `ambiguous` — ask which person it is; never rank or pick, and step 0's hard
+   stop stands until they answer. `conflict` — proceed as the machine-pinned person and surface the
+   warning line verbatim.
 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.
@@ -44,10 +55,11 @@ this before?", "which tickets touched VW_X?").
 ## Phase 1 — Resume, don't restart
 4. Render `project.ticket_path` → the ticket dir, filling `{assignee}` with the **locator's owner**
    (the step-0 resolved person for new or bare-id work — never the static `project.assignee_dir`,
-   except through step 0's no-people-map last resort). If the dir 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**. Resuming another
-   person's ticket (locator owner ≠ resolved person) is fine — say so out loud.
+   except through step 0's `assignee_dir_fallback` last resort). If the dir exists: read its
+   `README.md`, list `final_deliverables/`, check `git log --oneline -10` + `git status`, and
+   summarize what's done and what remains, re-fetch the ticket for new comments, then **skip to
+   Phase 3**. Resuming another person's ticket (locator owner ≠ resolved person) is fine — say so
+   out loud.
 
 ## Phase 2 — Workspace (new ticket)
 5. **Branch** via the vcs adapter, named `<id>`, off `seams.vcs.default_branch` — or a **worktree**

{ticketwright-4.0.0 → ticketwright-4.0.2}/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); this project uses semantic-ish versioning.
 
 
+## [4.0.2] — 2026-09-03
+
+### Added
+- **`bin/plugin_doctor.py` — every install state gets a name and a fix.** Onboarding onto a repo that
+  already carries the committed enablement failed in ways nothing in the kit could describe: a CLI too
+  old to accept `--scope` (Claude Code 2.0.x has neither `--scope` nor `plugin list`), a marketplace
+  registered with nothing installed, a global install nobody meant, an install record whose
+  `installPath` was never created (the install reports success, re-running it is a no-op), and a
+  "Download ZIP" folder with no `.git`. The doctor checks all of that in one command — plus `yq`, git
+  identity, the update channel to update through, and whether the installed version is behind the
+  marketplace catalog — and prints the fix for each, human-readable or `--json`. It runs from the
+  marketplace clone before anything is installed
+  (`python3 ~/.claude/plugins/marketplaces/ticketwright/bin/plugin_doctor.py`, a fork substitutes its
+  own marketplace name) and through `bin/tw` afterwards. Stdlib only, no network, no writes; it never
+  runs an install, and it reuses `update_notice.py` so its upgrade fix is the same string the session
+  banner prints. `/setup` runs it at preflight and halts on the states nothing setup writes can fix.
+- **Install prerequisites an agent can read before the plugin loads.** README Track 2 and
+  `templates/AGENTS.md.tmpl` carry the same fourteen checks in the same order as the doctor, each
+  tagged with a `doctor-check` marker; selftest pins the set and order against the doctor's own check
+  list, so the three surfaces cannot drift.
+
+### Fixed
+- **The joiner install no longer lands at user scope.** README Track 2, `docs/troubleshooting.md` and
+  the rendered `AGENTS.md` all gave the bare `claude plugin install ticketwright@ticketwright`, which
+  defaults to `--scope user` — installing Ticketwright for every repo on the machine while the repo
+  itself got nothing. All three now give the `--scope project` pair, run from the repository root
+  (a project-scope install keys to the session's directory, claude-code#82830), with the in-app
+  `/plugin install` → Project-scope route as the fallback for a CLI too old for the flag.
+- **The "teammates are prompted to install" claim is gone.** It was in the README, `setup/scaffold.md`,
+  `.claude/settings.json.tmpl` and `templates/AGENTS.md.tmpl`, and it is not what happens: registering
+  the marketplace is not installing the plugin, and the documented behavior (Claude Code 2.1.195 and
+  later report the plugin as not installed and show the install command; older builds say nothing) is
+  now what those four files say.
+- **"Restart" says what it means.** Every restart instruction now names `/reload-plugins` or a new
+  session first, then a full quit of the Claude app (Cmd+Q, or File → Exit) if the skills are still
+  absent — a new chat inside the running app is not a restart.
+- **`bin/update_notice.py` recognises a `local` install row** (the desktop app writes one) and emits
+  the uninstall/reinstall pair at the scope the record actually carries, instead of assuming
+  `--scope project`.
+- **An unbound teammate no longer writes into someone else's folder.** A `people/<id>.yaml` placeholder
+  with no identities resolved to the project's `assignee_dir`, so a first ticket opened before
+  `/setup --teammate` landed under another person's directory. The ticket front door now halts and
+  names the fix.
+
+### Changed
+- **`/setup` preflight order:** git repo → the doctor's findings → `yq` (with the platform install
+  command offered before the self-test needs it) → identity. A ZIP folder or a broken install is
+  reported before setup writes anything, since nothing setup writes would repair it.
+
+### Docs
+- `docs/troubleshooting.md`: cause 2 is now "Your Claude Code CLI is too old" with per-channel update
+  commands; a new cause covers an install record with no payload, including the safety conditions on
+  the copy-the-clone recovery; the upgrade table gains a `local`-scope row; a new block names the three
+  ways to run the doctor.
+
+## [4.0.1] — 2026-09-02
+
+### Fixed
+- **The kit-integrity selftest passes on a plugin install.** Section 31 ran `bin/tw` from inside the
+  kit's own tree and expected the kit root — right only when the kit is a git repo, so on a plugin
+  install (a cache, not a repo) two assertions failed for a reason no user ever meets. The test now
+  builds a git project and runs from a ticket subdirectory, which is the real scenario; `bin/tw`
+  itself was already correct there.
+- **A verify can no longer hang setup.** `verify_stack.sh` runs each slot's verify under a wall-clock
+  cap (`VERIFY_TIMEOUT`, default 30s) and reports a timeout as "appears to need interactive auth"
+  — a browser-SSO warehouse connection used to block the whole check with no output.
+
+### Docs
+- `/setup`: fall back to the current local branch when `refs/remotes/origin/HEAD` is unset (an
+  unpushed repo); expect `selftest.sh` to take several minutes and judge it by exit code; on a
+  remote created empty, the scaffold's first push seeds `main` and the PR flow starts with the next
+  change; a slot's `mcp:` value must be the runtime's exact tool prefix (`mcp__<name>__*`).
+
 ## [4.0.0] — 2026-09-02
 
 Breaking: `/productize` is now `/skillify`, and `templates/productized-skill/` is now

{ticketwright-4.0.0 → ticketwright-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ticketwright
-Version: 4.0.0
+Version: 4.0.2
 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
@@ -169,9 +169,10 @@ personal install, or another repo's), `marketplace add … --scope project` prin
 declared in project settings" — expected, not an error: the cached marketplace is reused and the
 project-scoped declaration still lands in this repo's settings.
 
-**2 · Fully restart Claude Code** — quit and relaunch, not just a new prompt. Plugin skills load
-at session start, so installing and running `/setup` in the same session silently fails: the
-command simply doesn't exist yet.
+**2 · Reload the plugin, or restart.** Plugin skills load at session start, so installing and
+running `/setup` in the same session silently fails: the command simply doesn't exist yet. Run
+`/reload-plugins` or start a new session. If the commands still do not appear, fully quit the Claude
+app (Cmd+Q on macOS, File → Exit on Windows/Linux) and relaunch — a new chat is not a restart.
 
 *Check:* `/ticketwright:setup` shows up in the new session's command list.
 
@@ -253,20 +254,124 @@ start, but does NOT install the plugin.** Verified live: a teammate's `installed
 stayed `{}` across restarts until the manual install in step 2. Skip step 2 and
 `/ticketwright:setup` is not a command that exists.
 
-**1 · Clone the repo and open it in Claude Code** (trust the workspace when prompted).
+#### If you are the agent helping someone install — read this first
+
+One command answers most of what follows. The marketplace clone lands on disk as soon as the person
+opens and trusts the repo — before anything is installed — so this runs at the moment nothing else
+does:
+
+```bash
+python3 ~/.claude/plugins/marketplaces/ticketwright/bin/plugin_doctor.py
+```
+
+That path names the `ticketwright` marketplace; a fork substitutes its own marketplace name. The
+doctor prints one line per check below, with the fix for each, and takes `--json` for a
+machine-readable report. Once the plugin is installed the same checks run as
+`bash "${CLAUDE_PLUGIN_ROOT:-.}/bin/tw" plugin_doctor.py`.
+
+The checks, in the order the doctor runs them:
+
+1. **A clone, not a downloaded ZIP.** <!-- doctor-check: git_clone -->
+   `ls -d .git`. A "Download ZIP" folder (named `<repo>-main`, no `.git`) cannot branch, commit, or
+   open a PR. Fix: `git clone <repo url>` and work in the clone.
+2. **You are at the repository root.** <!-- doctor-check: cwd_is_root -->
+   `git rev-parse --show-toplevel` matches your working directory. A project-scope install keys to
+   the session's directory rather than the repo root
+   ([claude-code#82830](https://github.com/anthropics/claude-code/issues/82830)), so run both
+   install commands from the root.
+3. **The `claude` CLI is on PATH.** <!-- doctor-check: claude_on_path -->
+   `command -v claude`. Missing: install Claude Code and reopen the terminal. The in-app route
+   below needs no terminal at all.
+4. **Which version that CLI is.** <!-- doctor-check: claude_version -->
+   `claude --version`. Reported, not judged: from Claude Code 2.1.195 the app itself reports a
+   repo's plugin as not installed and shows the install command; older builds say nothing, which is
+   why this checklist exists.
+5. **That CLI understands `--scope`.** <!-- doctor-check: scope_supported -->
+   `claude plugin install --help` mentions `--scope`. If it does not, the CLI is too old for either
+   install command — use the in-app route below, then update it.
+6. **How that CLI was installed.** <!-- doctor-check: install_channel -->
+   `readlink -f "$(command -v claude)"` says which channel to update through: native installer →
+   `claude update`; npm or nvm → `npm install -g @anthropic-ai/claude-code@latest`; Homebrew →
+   `brew upgrade claude-code`. An nvm `claude` earlier on PATH shadows a native one; `claude doctor`
+   lists conflicting installs.
+7. **The marketplace is registered.** <!-- doctor-check: marketplace_registered -->
+   A `ticketwright` entry in `~/.claude/plugins/known_marketplaces.json` whose `installLocation`
+   exists on disk. Missing: the first command of the pair below.
+8. **This repo has an install record.** <!-- doctor-check: repo_install -->
+   A row in `~/.claude/plugins/installed_plugins.json` whose `projectPath` is this repo.
+   Registration never creates one. Fix: the pair below, from the repository root, then restart.
+9. **The install record points at files that exist.** <!-- doctor-check: install_payload -->
+   The recorded `installPath` holds a `.claude-plugin/plugin.json`. Seen on Claude Code 2.0.22:
+   install prints "Successfully installed" and the directory is never created, so re-running install
+   is a no-op. Fix: update the CLI, then
+   `claude plugin uninstall ticketwright@ticketwright --scope <the recorded scope>` and install
+   again; if uninstall answers "not found", copy the marketplace clone into the recorded path —
+   recipe in [`docs/troubleshooting.md`](docs/troubleshooting.md).
+10. **No machine-wide install nobody meant.** <!-- doctor-check: user_install -->
+    A row with `scope: "user"` turns Ticketwright on for every repo on the machine. If you meant
+    this repo only: `claude plugin uninstall ticketwright@ticketwright --scope user`, then the pair
+    below.
+11. **The installed version matches the marketplace catalog.** <!-- doctor-check: catalog_current -->
+    Behind means a tagged release has not been picked up; the fix is the uninstall-and-install pair
+    the session banner names, at the scope the install record carries.
+12. **`yq` is installed.** <!-- doctor-check: yq_present -->
+    `command -v yq`. Needed only by `bin/selftest.sh`, where its absence fails a dozen-plus checks
+    from one cause. macOS: `brew install yq`. Linux: your distribution's package. Windows:
+    `winget install MikeFarah.yq`.
+13. **Git identity is set.** <!-- doctor-check: git_identity -->
+    `git config --get user.name` and `git config --get user.email`. Unset, the first commit fails:
+    `git config user.name "…"` and `git config user.email "…"`.
+14. **Restart the right way.** <!-- doctor-check: restart -->
+    Printed whenever an install check above is not clean. Run `/reload-plugins` or start a new
+    session. If the skills still do not appear, fully quit the Claude app (Cmd+Q on macOS,
+    File → Exit on Windows/Linux) and relaunch. A new chat inside the running app is not a restart.
+
+The install itself is two commands, run from the repository root:
+
+```bash
+claude plugin marketplace add https://github.com/kyle-chalmers/ticketwright.git --scope project
+claude plugin install ticketwright@ticketwright --scope project
+```
+
+When the repo's committed settings already registered the marketplace, the first command prints
+"already on disk — declared in project settings" — expected, not an error. **No terminal, or a CLI
+that rejects `--scope`?** Run `/plugin install ticketwright@ticketwright` in the session and choose
+**Project** scope, or use **+ → Plugins → Add plugin** in the desktop app; both run in the app's own
+engine. Then update the CLI (check 6).
+
+*Verify:* `claude plugin list` shows `ticketwright@ticketwright … enabled`, and
+`/ticketwright:setup` appears in the next session's command list. `bin/selftest.sh` takes several
+minutes — judge it by its exit code, not by how long it has been running. Anything still
+unexplained: [`docs/troubleshooting.md`](docs/troubleshooting.md).
+
+**1 · `git clone` the repo and open it in Claude Code** (trust the workspace when prompted). Use a
+clone, not GitHub's "Download ZIP" — a `<repo>-main` folder with no `.git` cannot branch, commit, or
+open a PR.
 
 *Check:* `.claude/config/stack.yaml` exists — that's the team config Track 1 committed.
 
-**2 · Install the plugin explicitly:**
+**2 · Install the plugin explicitly**, from the repository root:
 
 ```bash
-claude plugin install ticketwright@ticketwright
+claude plugin marketplace add https://github.com/kyle-chalmers/ticketwright.git --scope project
+claude plugin install ticketwright@ticketwright --scope project
 ```
 
-*Check:* `claude plugin list` shows `ticketwright@ticketwright … enabled`.
+Both commands default to `--scope user`, which would install Ticketwright for every repo on your
+machine instead of this one. The marketplace is usually registered already from the committed
+settings, so the first command prints "already on disk — declared in project settings" — expected,
+not an error. If your CLI rejects `--scope`, it is too old: run `/plugin install
+ticketwright@ticketwright` in the session and choose **Project** scope (or use **+ → Plugins → Add
+plugin** in the desktop app), then update the CLI — see the checklist above.
+
+*Check:* `claude plugin list` shows `ticketwright@ticketwright … enabled`. If your CLI answers
+`unknown command 'list'` or `unknown option '--scope'`, it is too old — Claude Code 2.0.x has
+neither; see the checklist above.
 
-**3 · Fully restart Claude Code** — quit and relaunch, not just a new prompt. Plugin skills load
-at session start; installing and running `/setup` in the same session silently fails.
+**3 · Reload the plugin, or restart.** Plugin skills load at session start; installing and running
+`/setup` in the same session silently fails. Run `/reload-plugins` or start a new session. If the
+commands still do not appear, fully quit the Claude app (Cmd+Q on macOS, File → Exit on
+Windows/Linux) and relaunch — a new chat is not a restart.
 
 *Check:* `/ticketwright:setup` shows up in the new session's command list.
 
@@ -373,9 +478,10 @@ means later ticket PRs reference rules that aren't in the repo's history.
 ### Project-scoped by default
 
 A plugin can't set its own install scope — the **repo** does. `--scope project` writes the enablement
-into the repo's `.claude/settings.json`, so it travels *with the repo*: every teammate who opens (and
-trusts) it is prompted to install Ticketwright (no marketplace to add, no config to write), and it keeps
-working after the person who set it up moves on. Commit the file. This is what the two Track 1
+into the repo's `.claude/settings.json`, so it travels *with the repo*, and it keeps working after
+the person who set it up moves on. Registering the marketplace is not installing the plugin — a
+teammate who opens and trusts the repo gets the marketplace clone, then runs the install themselves
+(Track 2). Commit the file. This is what the two Track 1
 install commands produce, plus the one key they don't write:
 
 ```json