tcw-cli 2.1.2__tar.gz → 2.2.0__tar.gz

{tcw_cli-2.1.2/tcw_cli.egg-info → tcw_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.1.2
+Version: 2.2.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -247,7 +247,7 @@ other's content.
 - [Documentation](#documentation)
 - [Skills — the judgment layer](#skills--the-judgment-layer)
   - [Reading a lifecycle stage](#reading-a-lifecycle-stage)
-  - [Review agents and slash commands](#review-agents-and-slash-commands)
+  - [Review agents and command skills](#review-agents-and-command-skills)
 - [Status](#status)
 - [Further reading](#further-reading)
 
@@ -430,20 +430,20 @@ by installing `tcw-cli` from PyPI with `pipx`, so one installed mid-session
 cannot run until the next one begins. That first session needs network access. It
 installs over an existing `pipx install tcw-cli` rather than beside it, and
 leaves a development checkout (`pip install -e .`) alone. If `tcw` goes missing
-anyway, `pipx install tcw-cli` is the whole fix — the **`tcw-plugin`** skill
+anyway, `pipx install tcw-cli` is the whole fix — the **`tcw-setup`** skill
 carries the cases where it is not.
 
-In **Codex** (skills only, no slash commands):
+In **Codex**:
 
 ```bash
 codex plugin marketplace add brocef/TCW --ref main
 codex plugin add tcw@tcw
 ```
 
-Codex has no session-start hook, so ask the agent to run the **`tcw-plugin`**
-setup — it runs the same install script Claude runs automatically.
+Codex has no session-start hook, so ask the agent to run the **`tcw-setup`**
+skill — it runs the same install script Claude runs automatically.
 
-The plugin ships the agent skills, slash commands, and read-only review agents
+The plugin ships the agent skills, command skills, and read-only review agents
 listed under [Skills](#skills--the-judgment-layer).
 
 ### As a Python package
@@ -565,8 +565,10 @@ projects. Each component group also has its own `init`: `tcw taxonomy init`,
 `tcw capabilities init`, `tcw work init`.
 
 To bootstrap a taxonomy or capabilities ledger on a project that already has a
-codebase, run `/tcw-taxonomy-init` or `/tcw-capabilities-init` — the assistant
-studies your code, proposes a first draft, refines it with you, and writes it.
+codebase, ask for the `tcw-setup` skill — the assistant studies your code,
+proposes a first draft, refines it with you, and writes it. To change a working
+project's configuration afterwards — documentation entries, lifecycle bindings,
+a tracker, where stores live — ask for the `tcw-configure` skill.
 
 ---
 
@@ -579,8 +581,9 @@ a work item.
 tcw work tracker list              # tickets the configured query selects
 tcw work tracker show ENG-482      # one ticket, and whether it is yours to take
 tcw work tracker import ENG-482    # take the ticket and get a work item for it
-tcw work tracker link <slug> ENG-482       # take it for an item you already have
+tcw work tracker link <slug> ENG-482       # record that an item and a ticket are the same work
 tcw work tracker unlink <slug> --reason "wrong ticket"
+tcw work tracker sync --all        # retry tickets that did not follow their items
 ```
 
 Configuration goes in the node's `tcw-config.yaml`:
@@ -596,6 +599,11 @@ work:
             token-env: TCW_JIRA_API_TOKEN
         transitions:
             claim: Start Progress
+        statuses: # optional: where a bound ticket goes as its item moves
+            active: In Progress
+            review: In Review
+            completed: Done
+            discarded: Won't Do
         timeout-seconds: 15 # optional
 ```
 
@@ -603,6 +611,32 @@ work:
 environment variables; TCW reads them at the moment it makes a request, so a token
 cannot be committed by accident.
 
+**Write the shared settings once.** In a workspace of connected nodes, a node's
+`tracker` block takes any setting it leaves out from its parent nodes, all the way
+up. So the site, credentials and claim transition can live in the workspace root,
+and each package writes only the tickets it wants to see:
+
+```yaml
+# packages/api/tcw-config.yaml
+work:
+    tracker:
+        candidate-query: project = EX AND component = api AND status = "To Do"
+```
+
+The nearest file wins each setting, and `credentials` and `transitions` merge
+setting by setting too. A node with no `tracker` block of its own has no tracker,
+whatever its parents say. Two rules keep this safe:
+
+- **`credentials` must sit beside `base-url`.** A node that sets its own `base-url`
+  must also set both of its own `credentials` keys, even if the address is the same
+  as its parent's, so a token is never sent to a site chosen in a different file.
+- **A node with its own board is checked like any tracking node.** If it holds the
+  shared settings, it needs a `candidate-query` of its own. Keeping shared settings
+  in a node without a board avoids that.
+
+A mistake in a parent's settings is reported by `tcw validate` in every node that
+inherits it, naming the parent's file.
+
 `tracker show` reports two different things, and the distinction matters:
 
 - **claimable** — whether this ticket currently offers the transition you
@@ -625,15 +659,116 @@ ticket's text goes into the item as its raw input, with a link back, and the ite
 request still gets written the usual way. A ticket assigned to someone else is
 refused, and so is one that is already closed.
 
-Running `import` again for the same ticket gives you the same item rather than a
-second one, and if the first run took the ticket but stopped before creating the
+Running `import` again for the same ticket in the same node gives you the same item
+rather than a second one, and if the first run took the ticket but stopped before creating the
 item, the second run finishes the job. One ticket can deliberately become several
-items with `--part api`, `--part web`, and so on. `unlink` removes a wrong binding
-and keeps a record of it with your reason; it never changes the ticket in Jira.
-
-Two limits to know. On a workflow that lets anyone start a ticket from any status,
-two people can both take the same ticket, and TCW does not stop that. And two runs
-by the same Jira account at the same moment can both create an item.
+items with `--part api`, `--part web`, and so on.
+
+**Recording that a ticket and an item are the same work.** `tracker link` is the
+other half, and it does only that: it writes the cross-reference down and leaves
+Jira alone. The ticket keeps its status and whoever holds it — you can link a ticket
+somebody else is assigned, because writing a note about a ticket takes it from
+nobody. On your side nothing but the binding is written, so the item keeps its
+status, its owner and its documents. Any item can be linked, a finished one
+included, which is how work that is already done gets tied to the ticket that
+tracked it; the same goes for `unlink`, so a binding pointed at the wrong ticket is
+repairable wherever you find it. A finished item's folder is kept out of git by
+default, so a binding on one stays on your machine along with the rest of that
+item. `unlink` keeps a record of what was bound and your
+reason, and like `link` it never changes the ticket in Jira.
+
+**Seeing which ticket an item answers.** A bound item says so wherever you read it:
+`tcw work show` adds a `tracker:` line with the ticket, the provider, the part and
+the ticket's link; its row on `tcw work list` ends with the ticket key, and notes the part and anything
+not yet sent to the ticket; `tcw work show
+--json` carries it as `tracker`; and `tcw serve`'s item page shows the ticket as a
+link. What you see is what the binding records, not what Jira says right now, so
+none of it needs the tracker configured or reachable. A binding file that cannot be
+read is reported in the same places instead of breaking the board.
+
+**Tickets follow their items.** `link` claims nothing, so `tcw work start` does:
+starting a bound item claims its ticket by the same rules `import` uses. After that,
+`submit`, `rework`, `complete` and discarding move the ticket to the status you map
+the item's new status to under `statuses` (`discarded` can name a status per
+resolution, such as `duplicate: Duplicate`); a status you leave out sends nothing,
+and `active` is required once you map any other. `import` on a ticket that is only
+linked still refuses rather than claiming it.
+
+TCW moves a ticket only when it is assigned to you and is still where the item's
+previous status left it. A ticket someone else holds, one moved on in Jira, or one
+whose workflow does not offer a single transition to the mapped status is left
+alone. Your local move always happens and is committed first; when the ticket does
+not follow, the command exits 1, says the item moved, and records why — *pending*
+when Jira could not be reached or your credentials are missing, *conflicting* when
+Jira's answer stopped it. `tcw work show` and `tcw work list` show that state, and
+`tcw work tracker sync <slug>` (or `--all`) retries it once the cause is fixed. `sync`
+acts only on items you started, because it acts as whoever runs it. A ticket that
+followed first time leaves no record and no change in your repository.
+
+Two things are not caught: a move made in `tcw serve`, and a command interrupted
+between its commit and its call to Jira, leave no record, so the board shows them as
+in step; `sync <slug>` checks such an item but will not move its ticket. And a
+binding whose ticket link is on a different Jira site from the one configured is
+never written through — `import` and `link` refuse it and name the item.
+
+Five limits to know. A ticket bound to several parts moves only when the last open
+part here moves; parts in other nodes are not seen. On a workflow that lets anyone start a ticket from any status,
+two people can both take the same ticket, and TCW does not stop that outside strict
+mode (below). Two runs by the
+same Jira account at the same moment can both create an item. Each node keeps its
+own bindings: importing one ticket in two nodes of a workspace, even nodes sharing
+inherited settings, gives two items, one in each. And a ticket held by a finished
+item can be bound to a second item, open or finished, with no warning — a discarded
+item's ticket is meant to be available again, and TCW cannot tell that case from the
+other.
+
+**Comments on the ticket.** Set `comments: true` in the `tracker` block and each
+move also leaves a short comment on the ticket, such as
+`TCW: "Checkout page" (part api) went to review.`, for anyone who follows the work
+in Jira rather than in the repository. A `link` template adds a link, for example
+`link: https://tcw.example.com/work/{slug}` for a team that hosts `tcw serve`; the
+only placeholders are `{project}` and `{slug}`. Nothing from `spec.md`, `plan.md` or
+the other lifecycle documents is ever copied. A comment is posted only while the
+ticket is assigned to you, and a ticket held by someone else gets none. When a
+comment cannot be posted, the command exits 1, `show` prints a `tracker comment:`
+line, and `tcw work tracker sync` sends it later. Before resending, it looks for the
+comment on the ticket, so a post that landed without an answer is not repeated.
+Limits: a newer move's comment replaces one still waiting; two runs at once, or an
+edited or deleted comment, can still give a repeat; moves in `tcw serve` post
+nothing. On a Jira Service Management project a comment may be visible to
+customers, so leave comments off there unless item titles may be seen. Every copy
+of `tcw` on the project must understand these keys before you set them: an older
+one treats the whole `tracker` block as broken.
+
+**Strict mode: no work without a ticket.** Set `strict: true` in the `tracker` block
+when every piece of work must come from a ticket you have claimed. Then:
+
+- `tcw work new` and `tcw work inbox accept` refuse and point you at
+  `tcw work tracker import <ticket>`. `new --epic` is allowed; epics are never gated.
+- `tcw work start` refuses an item with no ticket. For a bound item it claims the
+  ticket *first*, and starts the item only if the claim worked.
+- `submit`, `rework` and completing as `done` read the ticket first and refuse unless
+  it is assigned to you and is where the item's last step left it. A `--worktree`
+  item is checked before anything is merged.
+- A claim on a workflow that would let a second person claim the same ticket is
+  refused, by `start` and by `import`; the ticket is left claimed for you to release.
+- An epic can be created and started, since it only groups work, but not with
+  `--worktree`.
+- A ticket shared by several parts is recognised only from the parts' items in
+  this checkout. If the part that held the ticket back was completed elsewhere, or
+  was not kept (`work.retain`), the last part's `complete` is refused; put the
+  ticket in the status the message names, or discard.
+- Discarding is always allowed. `drop` refuses an item that was ever bound — discard
+  it instead, so the record stays.
+- `tcw serve` refuses the same changes, since it cannot check a ticket, and names the
+  command to use.
+
+A refusal changes nothing in your project and says what to fix; a `start` or `import`
+refused after claiming leaves the ticket claimed. There is no flag to get past it;
+`--force` and `--take-over` do not. Strict mode needs Jira: while it cannot be
+reached, gated commands refuse. It also needs `statuses.active`,
+`statuses.completed` and a `statuses.discarded` covering every discard reason, which
+`tcw validate` checks. To turn it off, set `strict: false` or remove the key.
 
 Two guarantees worth stating plainly. A project with no `tracker` block behaves
 exactly as before, with no new required setting and no network access. And
@@ -663,48 +798,52 @@ Every command group also has `--help`, and a `check` that validates its tree.
 ## Skills — the judgment layer
 
 The CLI is the _mechanism_. Fifteen skills in [`skills/`](skills/) supply the
-_judgment_ that drives it — the parts a deterministic tool cannot decide. Nine
-carry a distinct procedure; the other six all compose one lifecycle stage and
-are listed together at the end.
+_judgment_ that drives it — the parts a deterministic tool cannot decide. They
+come in three groups, told apart by name: eight core skills (seven in the table
+below, and `tcw-work-stage`, which composes a lifecycle stage and is described
+after it), four `tcw-commands-*` skills for the everyday workflow, and three
+optional `tcw-extras-*` skills.
 
 | Skill                                                      | What it does                                                                                                                                               |
 | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`tcw-work`](skills/tcw-work/SKILL.md)                     | Plans a request through spec and plan, drives implementation and verification, triages the inbox, runs the lifecycle, decomposes epics, searches the board |
 | [`tcw-capabilities`](skills/tcw-capabilities/SKILL.md)     | The capability-delta planning check, contradiction detection, and the ledger flip at completion                                                            |
-| [`tcw-taxonomy`](skills/tcw-taxonomy/SKILL.md)             | Declaring vocabulary and features, linking them, and federating shared vocabulary                                                                          |
-| [`tcw-plugin`](skills/tcw-plugin/SKILL.md)                 | Installs the CLI from PyPI, and maps the other skills                                                                                                      |
-| [`tcw-report`](skills/tcw-report/SKILL.md)                 | Reporting a `tcw` bug or suggestion upstream to [this project's issues](https://github.com/brocef/TCW/issues)                                              |
-| [`tcw-triage-issues`](skills/tcw-triage-issues/SKILL.md)   | Sweeps **your** project's GitHub issues and turns the ones worth doing into work items                                                                     |
+| [`tcw-taxonomy`](skills/tcw-taxonomy/SKILL.md)             | Declaring vocabulary and features, linking them, and resolving vocabulary inherited from another project                                                   |
+| [`tcw-setup`](skills/tcw-setup/SKILL.md)                   | Gets TCW working: installs or repairs the CLI, sets up a repository, starts a taxonomy or capabilities ledger                                              |
+| [`tcw-configure`](skills/tcw-configure/SKILL.md)           | Changes a project's configuration: lifecycle bindings, Definition of Done, documentation entries, tracker, stores, connected and inherited projects        |
 | [`documentation-sync`](skills/documentation-sync/SKILL.md) | Keeps README, changelogs, release notes, and driving skills moving with the code that changes them                                                         |
 | [`tcw-post-mortem`](skills/tcw-post-mortem/SKILL.md)       | Finds which lifecycle stage could first have caught a problem, once one has surfaced                                                                       |
-| [`autonomous-work`](skills/autonomous-work/SKILL.md)       | Drives work items to completion unattended, consulting two read-only advisors wherever the lifecycle would ask you                                         |
+
+**Extras.** `tcw-extras-*` skills are optional, built for one way of working, and not needed to use TCW.
+
+| Skill | What it does |
+| ----- | ------------ |
+| [`tcw-extras-autonomous-work`](skills/tcw-extras-autonomous-work/SKILL.md) | Drives work items to completion unattended, consulting two read-only advisors wherever the lifecycle would ask you                                         |
+| [`tcw-extras-triage-issues`](skills/tcw-extras-triage-issues/SKILL.md) | Sweeps **your** project's GitHub issues and turns the ones worth doing into work items                                                                     |
+| [`tcw-extras-report`](skills/tcw-extras-report/SKILL.md) | Reporting a `tcw` bug or suggestion upstream to [this project's issues](https://github.com/brocef/TCW/issues)                                              |
 
 They name `tcw` commands and never reimplement tool logic: mechanism stays in the
 binary, judgment stays in the skills.
 
 ### Reading a lifecycle stage
 
-Six more skills do one job between them: hand you a stage's own working document
-and the instructions your project resolves for it, as a single read rather than a
-file you open and a command you run separately. They only read — `tcw work stage
-gate` is still what refuses.
-
-[`tcw-work-stage`](skills/tcw-work-stage/SKILL.md) is the general one and takes
-the stage id, so it reaches all seven stages including `inbox` and `postmortem`.
-The other five bake their stage in and ask only for the work item, which is
-optional: `tcw-work-stage-request`, `tcw-work-stage-spec`,
-`tcw-work-stage-plan`, `tcw-work-stage-implement`, `tcw-work-stage-verify`.
+One more skill, [`tcw-work-stage`](skills/tcw-work-stage/SKILL.md), hands you a
+stage's own working document and the instructions your project resolves for it,
+as a single read rather than a file you open and a command you run separately.
+It takes the stage id and the work item, so it reaches all seven stages
+including `inbox` and `postmortem`, under Claude and Codex alike. It only reads
+— `tcw work stage gate` is still what refuses.
 
-### Review agents and slash commands
+### Review agents and command skills
 
 Three read-only review agents ship alongside them — `tcw-verifier`,
 `tcw-backlog-auditor`, and `tcw-post-mortem`, which accelerates the skill of the
-same name — plus slash commands for each skill's main procedure
-(`/tcw-plan-work`, `/tcw-drive-work-to-completion`, `/tcw-verify-work`,
-`/tcw-process-inbox`, `/tcw-work-search`, `/tcw-triage-issues`,
-`/tcw-audit-work-backlog`, `/tcw-consolidate-plans`, `/tcw-taxonomy-init`,
-`/tcw-capabilities-init`, `/tcw-docs-sync-setup`, `/tcw-cut-version`,
-`/tcw-post-mortem`).
+same name. Four command skills carry the everyday workflows:
+`tcw-commands-plan-work`, `tcw-commands-drive-work-to-completion`,
+`tcw-commands-verify-work` and `tcw-commands-process-inbox`. The three extras,
+`tcw-extras-autonomous-work`, `tcw-extras-triage-issues` and
+`tcw-extras-report`, are optional. Under Claude and Codex alike, every entry
+point is a skill.
 
 ---
 

{tcw_cli-2.1.2 → tcw_cli-2.2.0}/README.md

@@ -31,7 +31,7 @@ other's content.
 - [Documentation](#documentation)
 - [Skills — the judgment layer](#skills--the-judgment-layer)
   - [Reading a lifecycle stage](#reading-a-lifecycle-stage)
-  - [Review agents and slash commands](#review-agents-and-slash-commands)
+  - [Review agents and command skills](#review-agents-and-command-skills)
 - [Status](#status)
 - [Further reading](#further-reading)
 
@@ -214,20 +214,20 @@ by installing `tcw-cli` from PyPI with `pipx`, so one installed mid-session
 cannot run until the next one begins. That first session needs network access. It
 installs over an existing `pipx install tcw-cli` rather than beside it, and
 leaves a development checkout (`pip install -e .`) alone. If `tcw` goes missing
-anyway, `pipx install tcw-cli` is the whole fix — the **`tcw-plugin`** skill
+anyway, `pipx install tcw-cli` is the whole fix — the **`tcw-setup`** skill
 carries the cases where it is not.
 
-In **Codex** (skills only, no slash commands):
+In **Codex**:
 
 ```bash
 codex plugin marketplace add brocef/TCW --ref main
 codex plugin add tcw@tcw
 ```
 
-Codex has no session-start hook, so ask the agent to run the **`tcw-plugin`**
-setup — it runs the same install script Claude runs automatically.
+Codex has no session-start hook, so ask the agent to run the **`tcw-setup`**
+skill — it runs the same install script Claude runs automatically.
 
-The plugin ships the agent skills, slash commands, and read-only review agents
+The plugin ships the agent skills, command skills, and read-only review agents
 listed under [Skills](#skills--the-judgment-layer).
 
 ### As a Python package
@@ -349,8 +349,10 @@ projects. Each component group also has its own `init`: `tcw taxonomy init`,
 `tcw capabilities init`, `tcw work init`.
 
 To bootstrap a taxonomy or capabilities ledger on a project that already has a
-codebase, run `/tcw-taxonomy-init` or `/tcw-capabilities-init` — the assistant
-studies your code, proposes a first draft, refines it with you, and writes it.
+codebase, ask for the `tcw-setup` skill — the assistant studies your code,
+proposes a first draft, refines it with you, and writes it. To change a working
+project's configuration afterwards — documentation entries, lifecycle bindings,
+a tracker, where stores live — ask for the `tcw-configure` skill.
 
 ---
 
@@ -363,8 +365,9 @@ a work item.
 tcw work tracker list              # tickets the configured query selects
 tcw work tracker show ENG-482      # one ticket, and whether it is yours to take
 tcw work tracker import ENG-482    # take the ticket and get a work item for it
-tcw work tracker link <slug> ENG-482       # take it for an item you already have
+tcw work tracker link <slug> ENG-482       # record that an item and a ticket are the same work
 tcw work tracker unlink <slug> --reason "wrong ticket"
+tcw work tracker sync --all        # retry tickets that did not follow their items
 ```
 
 Configuration goes in the node's `tcw-config.yaml`:
@@ -380,6 +383,11 @@ work:
             token-env: TCW_JIRA_API_TOKEN
         transitions:
             claim: Start Progress
+        statuses: # optional: where a bound ticket goes as its item moves
+            active: In Progress
+            review: In Review
+            completed: Done
+            discarded: Won't Do
         timeout-seconds: 15 # optional
 ```
 
@@ -387,6 +395,32 @@ work:
 environment variables; TCW reads them at the moment it makes a request, so a token
 cannot be committed by accident.
 
+**Write the shared settings once.** In a workspace of connected nodes, a node's
+`tracker` block takes any setting it leaves out from its parent nodes, all the way
+up. So the site, credentials and claim transition can live in the workspace root,
+and each package writes only the tickets it wants to see:
+
+```yaml
+# packages/api/tcw-config.yaml
+work:
+    tracker:
+        candidate-query: project = EX AND component = api AND status = "To Do"
+```
+
+The nearest file wins each setting, and `credentials` and `transitions` merge
+setting by setting too. A node with no `tracker` block of its own has no tracker,
+whatever its parents say. Two rules keep this safe:
+
+- **`credentials` must sit beside `base-url`.** A node that sets its own `base-url`
+  must also set both of its own `credentials` keys, even if the address is the same
+  as its parent's, so a token is never sent to a site chosen in a different file.
+- **A node with its own board is checked like any tracking node.** If it holds the
+  shared settings, it needs a `candidate-query` of its own. Keeping shared settings
+  in a node without a board avoids that.
+
+A mistake in a parent's settings is reported by `tcw validate` in every node that
+inherits it, naming the parent's file.
+
 `tracker show` reports two different things, and the distinction matters:
 
 - **claimable** — whether this ticket currently offers the transition you
@@ -409,15 +443,116 @@ ticket's text goes into the item as its raw input, with a link back, and the ite
 request still gets written the usual way. A ticket assigned to someone else is
 refused, and so is one that is already closed.
 
-Running `import` again for the same ticket gives you the same item rather than a
-second one, and if the first run took the ticket but stopped before creating the
+Running `import` again for the same ticket in the same node gives you the same item
+rather than a second one, and if the first run took the ticket but stopped before creating the
 item, the second run finishes the job. One ticket can deliberately become several
-items with `--part api`, `--part web`, and so on. `unlink` removes a wrong binding
-and keeps a record of it with your reason; it never changes the ticket in Jira.
-
-Two limits to know. On a workflow that lets anyone start a ticket from any status,
-two people can both take the same ticket, and TCW does not stop that. And two runs
-by the same Jira account at the same moment can both create an item.
+items with `--part api`, `--part web`, and so on.
+
+**Recording that a ticket and an item are the same work.** `tracker link` is the
+other half, and it does only that: it writes the cross-reference down and leaves
+Jira alone. The ticket keeps its status and whoever holds it — you can link a ticket
+somebody else is assigned, because writing a note about a ticket takes it from
+nobody. On your side nothing but the binding is written, so the item keeps its
+status, its owner and its documents. Any item can be linked, a finished one
+included, which is how work that is already done gets tied to the ticket that
+tracked it; the same goes for `unlink`, so a binding pointed at the wrong ticket is
+repairable wherever you find it. A finished item's folder is kept out of git by
+default, so a binding on one stays on your machine along with the rest of that
+item. `unlink` keeps a record of what was bound and your
+reason, and like `link` it never changes the ticket in Jira.
+
+**Seeing which ticket an item answers.** A bound item says so wherever you read it:
+`tcw work show` adds a `tracker:` line with the ticket, the provider, the part and
+the ticket's link; its row on `tcw work list` ends with the ticket key, and notes the part and anything
+not yet sent to the ticket; `tcw work show
+--json` carries it as `tracker`; and `tcw serve`'s item page shows the ticket as a
+link. What you see is what the binding records, not what Jira says right now, so
+none of it needs the tracker configured or reachable. A binding file that cannot be
+read is reported in the same places instead of breaking the board.
+
+**Tickets follow their items.** `link` claims nothing, so `tcw work start` does:
+starting a bound item claims its ticket by the same rules `import` uses. After that,
+`submit`, `rework`, `complete` and discarding move the ticket to the status you map
+the item's new status to under `statuses` (`discarded` can name a status per
+resolution, such as `duplicate: Duplicate`); a status you leave out sends nothing,
+and `active` is required once you map any other. `import` on a ticket that is only
+linked still refuses rather than claiming it.
+
+TCW moves a ticket only when it is assigned to you and is still where the item's
+previous status left it. A ticket someone else holds, one moved on in Jira, or one
+whose workflow does not offer a single transition to the mapped status is left
+alone. Your local move always happens and is committed first; when the ticket does
+not follow, the command exits 1, says the item moved, and records why — *pending*
+when Jira could not be reached or your credentials are missing, *conflicting* when
+Jira's answer stopped it. `tcw work show` and `tcw work list` show that state, and
+`tcw work tracker sync <slug>` (or `--all`) retries it once the cause is fixed. `sync`
+acts only on items you started, because it acts as whoever runs it. A ticket that
+followed first time leaves no record and no change in your repository.
+
+Two things are not caught: a move made in `tcw serve`, and a command interrupted
+between its commit and its call to Jira, leave no record, so the board shows them as
+in step; `sync <slug>` checks such an item but will not move its ticket. And a
+binding whose ticket link is on a different Jira site from the one configured is
+never written through — `import` and `link` refuse it and name the item.
+
+Five limits to know. A ticket bound to several parts moves only when the last open
+part here moves; parts in other nodes are not seen. On a workflow that lets anyone start a ticket from any status,
+two people can both take the same ticket, and TCW does not stop that outside strict
+mode (below). Two runs by the
+same Jira account at the same moment can both create an item. Each node keeps its
+own bindings: importing one ticket in two nodes of a workspace, even nodes sharing
+inherited settings, gives two items, one in each. And a ticket held by a finished
+item can be bound to a second item, open or finished, with no warning — a discarded
+item's ticket is meant to be available again, and TCW cannot tell that case from the
+other.
+
+**Comments on the ticket.** Set `comments: true` in the `tracker` block and each
+move also leaves a short comment on the ticket, such as
+`TCW: "Checkout page" (part api) went to review.`, for anyone who follows the work
+in Jira rather than in the repository. A `link` template adds a link, for example
+`link: https://tcw.example.com/work/{slug}` for a team that hosts `tcw serve`; the
+only placeholders are `{project}` and `{slug}`. Nothing from `spec.md`, `plan.md` or
+the other lifecycle documents is ever copied. A comment is posted only while the
+ticket is assigned to you, and a ticket held by someone else gets none. When a
+comment cannot be posted, the command exits 1, `show` prints a `tracker comment:`
+line, and `tcw work tracker sync` sends it later. Before resending, it looks for the
+comment on the ticket, so a post that landed without an answer is not repeated.
+Limits: a newer move's comment replaces one still waiting; two runs at once, or an
+edited or deleted comment, can still give a repeat; moves in `tcw serve` post
+nothing. On a Jira Service Management project a comment may be visible to
+customers, so leave comments off there unless item titles may be seen. Every copy
+of `tcw` on the project must understand these keys before you set them: an older
+one treats the whole `tracker` block as broken.
+
+**Strict mode: no work without a ticket.** Set `strict: true` in the `tracker` block
+when every piece of work must come from a ticket you have claimed. Then:
+
+- `tcw work new` and `tcw work inbox accept` refuse and point you at
+  `tcw work tracker import <ticket>`. `new --epic` is allowed; epics are never gated.
+- `tcw work start` refuses an item with no ticket. For a bound item it claims the
+  ticket *first*, and starts the item only if the claim worked.
+- `submit`, `rework` and completing as `done` read the ticket first and refuse unless
+  it is assigned to you and is where the item's last step left it. A `--worktree`
+  item is checked before anything is merged.
+- A claim on a workflow that would let a second person claim the same ticket is
+  refused, by `start` and by `import`; the ticket is left claimed for you to release.
+- An epic can be created and started, since it only groups work, but not with
+  `--worktree`.
+- A ticket shared by several parts is recognised only from the parts' items in
+  this checkout. If the part that held the ticket back was completed elsewhere, or
+  was not kept (`work.retain`), the last part's `complete` is refused; put the
+  ticket in the status the message names, or discard.
+- Discarding is always allowed. `drop` refuses an item that was ever bound — discard
+  it instead, so the record stays.
+- `tcw serve` refuses the same changes, since it cannot check a ticket, and names the
+  command to use.
+
+A refusal changes nothing in your project and says what to fix; a `start` or `import`
+refused after claiming leaves the ticket claimed. There is no flag to get past it;
+`--force` and `--take-over` do not. Strict mode needs Jira: while it cannot be
+reached, gated commands refuse. It also needs `statuses.active`,
+`statuses.completed` and a `statuses.discarded` covering every discard reason, which
+`tcw validate` checks. To turn it off, set `strict: false` or remove the key.
 
 Two guarantees worth stating plainly. A project with no `tracker` block behaves
 exactly as before, with no new required setting and no network access. And
@@ -447,48 +582,52 @@ Every command group also has `--help`, and a `check` that validates its tree.
 ## Skills — the judgment layer
 
 The CLI is the _mechanism_. Fifteen skills in [`skills/`](skills/) supply the
-_judgment_ that drives it — the parts a deterministic tool cannot decide. Nine
-carry a distinct procedure; the other six all compose one lifecycle stage and
-are listed together at the end.
+_judgment_ that drives it — the parts a deterministic tool cannot decide. They
+come in three groups, told apart by name: eight core skills (seven in the table
+below, and `tcw-work-stage`, which composes a lifecycle stage and is described
+after it), four `tcw-commands-*` skills for the everyday workflow, and three
+optional `tcw-extras-*` skills.
 
 | Skill                                                      | What it does                                                                                                                                               |
 | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`tcw-work`](skills/tcw-work/SKILL.md)                     | Plans a request through spec and plan, drives implementation and verification, triages the inbox, runs the lifecycle, decomposes epics, searches the board |
 | [`tcw-capabilities`](skills/tcw-capabilities/SKILL.md)     | The capability-delta planning check, contradiction detection, and the ledger flip at completion                                                            |
-| [`tcw-taxonomy`](skills/tcw-taxonomy/SKILL.md)             | Declaring vocabulary and features, linking them, and federating shared vocabulary                                                                          |
-| [`tcw-plugin`](skills/tcw-plugin/SKILL.md)                 | Installs the CLI from PyPI, and maps the other skills                                                                                                      |
-| [`tcw-report`](skills/tcw-report/SKILL.md)                 | Reporting a `tcw` bug or suggestion upstream to [this project's issues](https://github.com/brocef/TCW/issues)                                              |
-| [`tcw-triage-issues`](skills/tcw-triage-issues/SKILL.md)   | Sweeps **your** project's GitHub issues and turns the ones worth doing into work items                                                                     |
+| [`tcw-taxonomy`](skills/tcw-taxonomy/SKILL.md)             | Declaring vocabulary and features, linking them, and resolving vocabulary inherited from another project                                                   |
+| [`tcw-setup`](skills/tcw-setup/SKILL.md)                   | Gets TCW working: installs or repairs the CLI, sets up a repository, starts a taxonomy or capabilities ledger                                              |
+| [`tcw-configure`](skills/tcw-configure/SKILL.md)           | Changes a project's configuration: lifecycle bindings, Definition of Done, documentation entries, tracker, stores, connected and inherited projects        |
 | [`documentation-sync`](skills/documentation-sync/SKILL.md) | Keeps README, changelogs, release notes, and driving skills moving with the code that changes them                                                         |
 | [`tcw-post-mortem`](skills/tcw-post-mortem/SKILL.md)       | Finds which lifecycle stage could first have caught a problem, once one has surfaced                                                                       |
-| [`autonomous-work`](skills/autonomous-work/SKILL.md)       | Drives work items to completion unattended, consulting two read-only advisors wherever the lifecycle would ask you                                         |
+
+**Extras.** `tcw-extras-*` skills are optional, built for one way of working, and not needed to use TCW.
+
+| Skill | What it does |
+| ----- | ------------ |
+| [`tcw-extras-autonomous-work`](skills/tcw-extras-autonomous-work/SKILL.md) | Drives work items to completion unattended, consulting two read-only advisors wherever the lifecycle would ask you                                         |
+| [`tcw-extras-triage-issues`](skills/tcw-extras-triage-issues/SKILL.md) | Sweeps **your** project's GitHub issues and turns the ones worth doing into work items                                                                     |
+| [`tcw-extras-report`](skills/tcw-extras-report/SKILL.md) | Reporting a `tcw` bug or suggestion upstream to [this project's issues](https://github.com/brocef/TCW/issues)                                              |
 
 They name `tcw` commands and never reimplement tool logic: mechanism stays in the
 binary, judgment stays in the skills.
 
 ### Reading a lifecycle stage
 
-Six more skills do one job between them: hand you a stage's own working document
-and the instructions your project resolves for it, as a single read rather than a
-file you open and a command you run separately. They only read — `tcw work stage
-gate` is still what refuses.
-
-[`tcw-work-stage`](skills/tcw-work-stage/SKILL.md) is the general one and takes
-the stage id, so it reaches all seven stages including `inbox` and `postmortem`.
-The other five bake their stage in and ask only for the work item, which is
-optional: `tcw-work-stage-request`, `tcw-work-stage-spec`,
-`tcw-work-stage-plan`, `tcw-work-stage-implement`, `tcw-work-stage-verify`.
+One more skill, [`tcw-work-stage`](skills/tcw-work-stage/SKILL.md), hands you a
+stage's own working document and the instructions your project resolves for it,
+as a single read rather than a file you open and a command you run separately.
+It takes the stage id and the work item, so it reaches all seven stages
+including `inbox` and `postmortem`, under Claude and Codex alike. It only reads
+— `tcw work stage gate` is still what refuses.
 
-### Review agents and slash commands
+### Review agents and command skills
 
 Three read-only review agents ship alongside them — `tcw-verifier`,
 `tcw-backlog-auditor`, and `tcw-post-mortem`, which accelerates the skill of the
-same name — plus slash commands for each skill's main procedure
-(`/tcw-plan-work`, `/tcw-drive-work-to-completion`, `/tcw-verify-work`,
-`/tcw-process-inbox`, `/tcw-work-search`, `/tcw-triage-issues`,
-`/tcw-audit-work-backlog`, `/tcw-consolidate-plans`, `/tcw-taxonomy-init`,
-`/tcw-capabilities-init`, `/tcw-docs-sync-setup`, `/tcw-cut-version`,
-`/tcw-post-mortem`).
+same name. Four command skills carry the everyday workflows:
+`tcw-commands-plan-work`, `tcw-commands-drive-work-to-completion`,
+`tcw-commands-verify-work` and `tcw-commands-process-inbox`. The three extras,
+`tcw-extras-autonomous-work`, `tcw-extras-triage-issues` and
+`tcw-extras-report`, are optional. Under Claude and Codex alike, every entry
+point is a skill.
 
 ---
 

{tcw_cli-2.1.2 → tcw_cli-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "2.1.2"
+version = "2.2.0"
 description = "Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project."
 readme = "README.md"
 requires-python = ">=3.11"