tcw-cli 2.0.0__tar.gz → 2.0.1__tar.gz

{tcw_cli-2.0.0 → tcw_cli-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.0.0
+Version: 2.0.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -483,8 +483,10 @@ Every command group also has `--help`, and a `check` that validates its tree.
 
 ## Skills — the judgment layer
 
-The CLI is the _mechanism_. Seven skills in [`skills/`](skills/) supply the
-_judgment_ that drives it — the parts a deterministic tool cannot decide.
+The CLI is the _mechanism_. Fourteen skills in [`skills/`](skills/) supply the
+_judgment_ that drives it — the parts a deterministic tool cannot decide. Eight
+carry a distinct procedure; the other six all compose one lifecycle stage and
+are listed together at the end.
 
 | Skill                                                      | What it does                                                                                                                           |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -495,12 +497,27 @@ _judgment_ that drives it — the parts a deterministic tool cannot decide.
 | [`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                                                 |
 | [`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                                                   |
 
 They name `tcw` commands and never reimplement tool logic: mechanism stays in the
 binary, judgment stays in the skills.
 
-Two read-only review agents ship alongside them — `tcw-verifier` and
-`tcw-post-mortem` — plus slash commands for each skill's main procedure
+### 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`.
+
+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-triage-issues`, `/tcw-audit-work-backlog`,
 `/tcw-taxonomy-init`, `/tcw-capabilities-init`, `/tcw-docs-sync-setup`,

{tcw_cli-2.0.0 → tcw_cli-2.0.1}/README.md

@@ -267,8 +267,10 @@ Every command group also has `--help`, and a `check` that validates its tree.
 
 ## Skills — the judgment layer
 
-The CLI is the _mechanism_. Seven skills in [`skills/`](skills/) supply the
-_judgment_ that drives it — the parts a deterministic tool cannot decide.
+The CLI is the _mechanism_. Fourteen skills in [`skills/`](skills/) supply the
+_judgment_ that drives it — the parts a deterministic tool cannot decide. Eight
+carry a distinct procedure; the other six all compose one lifecycle stage and
+are listed together at the end.
 
 | Skill                                                      | What it does                                                                                                                           |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -279,12 +281,27 @@ _judgment_ that drives it — the parts a deterministic tool cannot decide.
 | [`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                                                 |
 | [`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                                                   |
 
 They name `tcw` commands and never reimplement tool logic: mechanism stays in the
 binary, judgment stays in the skills.
 
-Two read-only review agents ship alongside them — `tcw-verifier` and
-`tcw-post-mortem` — plus slash commands for each skill's main procedure
+### 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`.
+
+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-triage-issues`, `/tcw-audit-work-backlog`,
 `/tcw-taxonomy-init`, `/tcw-capabilities-init`, `/tcw-docs-sync-setup`,

{tcw_cli-2.0.0 → tcw_cli-2.0.1}/pyproject.toml

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

tcw_cli-2.0.1/tcw/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.1"

{tcw_cli-2.0.0 → tcw_cli-2.0.1}/tcw_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.0.0
+Version: 2.0.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -483,8 +483,10 @@ Every command group also has `--help`, and a `check` that validates its tree.
 
 ## Skills — the judgment layer
 
-The CLI is the _mechanism_. Seven skills in [`skills/`](skills/) supply the
-_judgment_ that drives it — the parts a deterministic tool cannot decide.
+The CLI is the _mechanism_. Fourteen skills in [`skills/`](skills/) supply the
+_judgment_ that drives it — the parts a deterministic tool cannot decide. Eight
+carry a distinct procedure; the other six all compose one lifecycle stage and
+are listed together at the end.
 
 | Skill                                                      | What it does                                                                                                                           |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -495,12 +497,27 @@ _judgment_ that drives it — the parts a deterministic tool cannot decide.
 | [`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                                                 |
 | [`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                                                   |
 
 They name `tcw` commands and never reimplement tool logic: mechanism stays in the
 binary, judgment stays in the skills.
 
-Two read-only review agents ship alongside them — `tcw-verifier` and
-`tcw-post-mortem` — plus slash commands for each skill's main procedure
+### 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`.
+
+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-triage-issues`, `/tcw-audit-work-backlog`,
 `/tcw-taxonomy-init`, `/tcw-capabilities-init`, `/tcw-docs-sync-setup`,

{tcw_cli-2.0.0 → tcw_cli-2.0.1}/tests/test_plugin_manifests.py

@@ -5,8 +5,11 @@ drift is `/tcw-doctor`'s job, not this test's).
 """
 import json
 import os
+import re
 import subprocess
 import tomllib
+
+import yaml
 from pathlib import Path
 
 import pytest
@@ -65,9 +68,28 @@ def test_claude_agents_key_is_md_files_not_a_directory():
 NUMBER_WORDS = {
     1: "one", 2: "two", 3: "three", 4: "four", 5: "five", 6: "six",
     7: "seven", 8: "eight", 9: "nine", 10: "ten", 11: "eleven", 12: "twelve",
+    13: "thirteen", 14: "fourteen", 15: "fifteen", 16: "sixteen",
+    17: "seventeen", 18: "eighteen", 19: "nineteen", 20: "twenty",
 }
 
 
+def _names_missing_from(blob: str, names) -> list[str]:
+    """Which of `names` the description does not mention, matching each as a
+    **whole token** rather than as a bare substring.
+
+    The distinction is load-bearing and was not before the per-stage skills
+    shipped: `tcw-work-stage` is a substring of `tcw-work-stage-spec`, so a plain
+    `n in blob` finds the generic skill inside every specialised one and reports
+    it present when the description never names it. The whole enumeration guard
+    for that skill would be dead — its name could be deleted from the
+    description with the suite green.
+
+    The lookahead is the fix: a trailing `-` or word character means the match
+    landed inside a longer name, not on the one being checked.
+    """
+    return [n for n in names if not re.search(re.escape(n) + r"(?![-\w])", blob)]
+
+
 def test_the_codex_description_counts_the_skills_it_ships():
     """The Codex manifest describes the plugin in prose and enumerates every
     skill by name. Prose does not check itself: it said "eight skills" and named
@@ -86,10 +108,25 @@ def test_the_codex_description_counts_the_skills_it_ships():
     assert f"{word} skills" in blob, (
         f"the Codex description does not say '{word} skills' for the "
         f"{len(names)} that ship: {', '.join(names)}")
-    missing = [n for n in names if n not in blob]
+    missing = _names_missing_from(blob, names)
     assert not missing, f"shipped but unnamed in the description: {missing}"
 
 
+def test_a_shared_name_prefix_cannot_stand_in_for_the_shorter_name():
+    """The guard above, guarded. `tcw-work-stage` is a prefix of all five
+    `tcw-work-stage-<stage>` skills, so under the substring match this test
+    replaces, dropping the generic skill from the description was invisible:
+    its name was still found, inside its own specialisations.
+
+    Asserting on the real description would not catch a revert — it names every
+    skill, so both matchers agree on it. This asserts the discrimination
+    directly, on a blob that names only the longer skill.
+    """
+    blob = "ships fourteen skills, among them tcw-work-stage-spec"
+    assert _names_missing_from(blob, ["tcw-work-stage-spec"]) == []
+    assert _names_missing_from(blob, ["tcw-work-stage"]) == ["tcw-work-stage"]
+
+
 @pytest.mark.parametrize("skill", sorted((REPO / "skills").glob("*/SKILL.md")), ids=lambda p: p.parent.name)
 def test_every_skill_has_name_and_description_frontmatter(skill):
     """Codex refuses to load a skill whose SKILL.md lacks `---` frontmatter with
@@ -98,8 +135,17 @@ def test_every_skill_has_name_and_description_frontmatter(skill):
     lines = skill.read_text(encoding="utf-8").splitlines()
     assert lines and lines[0] == "---", f"{skill} is missing YAML frontmatter"
     end = lines.index("---", 1)
-    keys = {ln.split(":", 1)[0] for ln in lines[1:end] if not ln.startswith((" ", "\t"))}
-    assert {"name", "description"} <= keys, f"{skill} frontmatter lacks name/description"
+
+    # Parsed as YAML, not scanned line by line. A plain scalar containing ": "
+    # is a YAML error, and every one of the five per-stage skills shipped with
+    # one on first write — a `when_to_use` reading "runs no gate: `tcw work
+    # stage gate` is what refuses". The line-based scan below sees the keys and
+    # passes; Codex, which actually parses this, refuses to load the skill. The
+    # scan cannot tell those apart, so it is no longer the only check.
+    front = yaml.safe_load("\n".join(lines[1:end]))
+    assert isinstance(front, dict), f"{skill} frontmatter is not a YAML mapping"
+    assert {"name", "description"} <= set(front), (
+        f"{skill} frontmatter lacks name/description")
 
 
 def test_hooks_manifest_wires_one_executable_session_start_script():

{tcw_cli-2.0.0 → tcw_cli-2.0.1}/tests/test_skill_lifecycle_parity.py

@@ -300,27 +300,108 @@ def test_the_router_routes_to_every_reference_file():
     assert not orphans, f"unreachable from SKILL.md: {orphans}"
 
 
-# ── the composing skill ──────────────────────────────────────────────────────
+# ── the composing skills ─────────────────────────────────────────────────────
+#
+# Six documents compose a stage out of `cat <router>` + `tcw work stage prompt`:
+# the generic `tcw-work-stage`, which takes the stage id as an argument, and one
+# `tcw-work-stage-<stage>` per stage a person actually drives, which bakes it in.
+#
+# Every property below held for one file before the five shipped. Each is now
+# parametrised over all six, because a guard that covers one of six near-identical
+# documents has stopped being a guard.
 
 STAGE_SKILL = REPO / "skills/tcw-work-stage/SKILL.md"
 
-
-def test_the_composing_skill_reads_a_router_that_exists_for_every_stage():
-    """`tcw-work-stage` interpolates the stage id into a path. Nothing at
-    runtime checks that path — a failed `cat` is swallowed by `|| true` so the
-    rest of the skill still renders, which is the right behaviour and also the
-    reason a rename would go unnoticed. Resolve the template here instead."""
-    body = STAGE_SKILL.read_text()
+# Derived from STAGE_IDS, never written out as a second list — a stage added to
+# the lifecycle shows up here rather than being silently skipped. Only the two
+# exclusions are hand-written, and each is excluded for a reason that would have
+# to stop being true before it gets a skill:
+#   inbox      — runs before an item exists and takes no work item reference on
+#                either verb, so a per-stage skill would wrap a zero-argument
+#                command and add nothing.
+#   postmortem — already has `tcw-post-mortem`, with a read-only agent behind it;
+#                a second skill for the stage would compete with it.
+NO_PER_STAGE_SKILL = {"inbox", "postmortem"}
+PER_STAGE_IDS = tuple(s for s in STAGE_IDS if s not in NO_PER_STAGE_SKILL)
+PER_STAGE_SKILLS = {s: REPO / f"skills/tcw-work-stage-{s}/SKILL.md"
+                    for s in PER_STAGE_IDS}
+
+# The generic skill keyed by None: it has no single stage, and every parametrised
+# test below has to say what it does differently for that case anyway.
+COMPOSING_SKILLS = {None: STAGE_SKILL, **PER_STAGE_SKILLS}
+
+
+def _composing(stage):
+    """The path for a stage id, or for the generic skill when `stage` is None."""
+    return COMPOSING_SKILLS[stage]
+
+
+composing = pytest.mark.parametrize(
+    "stage", sorted(COMPOSING_SKILLS, key=lambda s: s or ""),
+    ids=lambda s: s or "generic")
+
+
+def test_the_per_stage_skills_are_exactly_the_stages_that_get_one():
+    """Both directions. A stage in `PER_STAGE_IDS` with no file is a skill that
+    was planned and never written; a `skills/tcw-work-stage-*/` directory with no
+    matching stage is one that appeared without the exclusion list being
+    revisited — most likely `postmortem`, whose exclusion is a judgement call
+    someone will eventually want to reverse. Reversing it should mean editing
+    `NO_PER_STAGE_SKILL`, not just adding a folder.
+
+    The glob discriminates on its own: every per-stage skill carries the
+    `tcw-work-stage-` prefix and the generic skill does not match it.
+    """
+    missing = sorted(s for s, p in PER_STAGE_SKILLS.items() if not p.is_file())
+    assert not missing, f"stages with no skill file: {missing}"
+    on_disk = {p.parent.name.removeprefix("tcw-work-stage-")
+               for p in REPO.glob("skills/tcw-work-stage-*/SKILL.md")}
+    assert on_disk == set(PER_STAGE_IDS), (
+        f"skills on disk {sorted(on_disk)} disagree with the stages that get one "
+        f"{sorted(PER_STAGE_IDS)}; excluded deliberately: {sorted(NO_PER_STAGE_SKILL)}")
+
+
+@pytest.mark.parametrize("stage", PER_STAGE_IDS)
+def test_a_per_stage_skill_takes_the_item_alone(stage):
+    """The whole point of splitting the generic skill. `arguments: [stage, item]`
+    made the caller restate a stage they already knew, and forced the item to be
+    supplied positionally after it; `arguments: [item]` leaves one argument, and
+    an omitted one interpolates to the empty string, which the CLI accepts."""
+    front = _composing(stage).read_text().split("---")[1]
+    args = next(l for l in front.splitlines() if l.startswith("arguments:"))
+    assert args.strip() == "arguments: [item]", args
+    assert "$stage" not in _composing(stage).read_text(), (
+        f"tcw-work-stage-{stage} still interpolates a stage argument")
+
+
+@composing
+def test_the_composing_skill_reads_a_router_that_exists(stage):
+    """Each of these skills names a router path. Nothing at runtime checks it —
+    a failed `cat` is swallowed by `|| true` so the rest of the skill still
+    renders, which is the right behaviour and also the reason a rename would go
+    unnoticed. Resolve the path here instead.
+
+    The generic skill's path is a template holding `$stage`, so it is resolved
+    against every stage id; a per-stage skill's names one stage literally and is
+    checked once. Same property, two shapes.
+    """
+    body = _composing(stage).read_text()
     m = re.search(r'cat "\$\{CLAUDE_PLUGIN_ROOT\}/(\S+?)"', body)
     assert m, "the skill no longer cats a router out of the plugin root"
     template = m.group(1)
-    assert "$stage" in template, template
-    for stage_id in STAGE_IDS:
-        target = REPO / template.replace("$stage", stage_id)
+    if stage is None:
+        assert "$stage" in template, template
+        targets = {s: REPO / template.replace("$stage", s) for s in STAGE_IDS}
+    else:
+        assert f"stage-{stage}.md" in template, (
+            f"tcw-work-stage-{stage} cats {template}, not its own stage router")
+        targets = {stage: REPO / template}
+    for stage_id, target in targets.items():
         assert target.is_file(), f"{stage_id}: {target} does not exist"
 
 
-def test_the_composing_skill_names_the_gate_in_its_own_prose():
+@composing
+def test_the_composing_skill_names_the_gate_in_its_own_prose(stage):
     """The whole hazard of composing a stage out of `prompt`: it resolves the
     instructions without the gate. A skill that stopped naming `gate` would be
     a documented route around the legality check and the `pre` bindings.
@@ -333,15 +414,17 @@ def test_the_composing_skill_names_the_gate_in_its_own_prose():
     biting: the entire warning could be deleted with this test still green.
     Neither change was wrong on its own, which is why nothing caught it.
     """
-    body = STAGE_SKILL.read_text()
-    assert "tcw work stage prompt $stage $item" in body
+    slot = "$stage" if stage is None else stage
+    body = _composing(stage).read_text()
+    assert f"tcw work stage prompt {slot} $item" in body
     prose = re.sub(r"```.*?```", "", body, flags=re.DOTALL)
-    assert "tcw work stage gate $stage $item" in prose, (
+    assert f"tcw work stage gate {slot} $item" in prose, (
         "the skill names the gate only inside its manual-fallback fence, so the "
         "prose warning against routing around the gate can be deleted freely")
 
 
-def test_every_injected_command_survives_its_own_failure():
+@composing
+def test_every_injected_command_survives_its_own_failure(stage):
     """The second of two ways this skill renders empty, and the one that shipped
     unguarded.
 
@@ -353,7 +436,7 @@ def test_every_injected_command_survives_its_own_failure():
 
     The sibling test covers the other cause, an undeclared command.
     """
-    body = STAGE_SKILL.read_text()
+    body = _composing(stage).read_text()
     injected = re.findall(r"^!`(.+)`$", body, flags=re.MULTILINE)
     assert injected, "the skill no longer injects any command"
     for cmd in injected:
@@ -362,11 +445,12 @@ def test_every_injected_command_survives_its_own_failure():
             f"non-zero: {cmd}")
 
 
-def test_the_composing_skill_declares_the_commands_it_injects():
+@composing
+def test_the_composing_skill_declares_the_commands_it_injects(stage):
     """An injected command that is not pre-approved aborts the whole skill
     invocation — the model is shown nothing at all, not an error. Both commands
     have to be in `allowed-tools` or the skill silently renders empty."""
-    body = STAGE_SKILL.read_text()
+    body = _composing(stage).read_text()
     front = body.split("---")[1]
     allowed = next(l for l in front.splitlines() if l.startswith("allowed-tools:"))
     assert "Bash(tcw *)" in allowed and "Bash(cat *)" in allowed, allowed

tcw_cli-2.0.0/tcw/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.0.0"