feat(work-items): document the re-decompose (rerouting) flow in decompose

[kyle-sexton]

Closes #2949

Summary

Absorbs the course's rerouting recipe (Lane E of spec container #2933) into /work-items:decompose as a documented re-decompose flow — a usage pattern of existing seam verbs, not a new capability or skill. /work-items:ship's existing "slices no longer fit the spec" route now lands on an owned, documented flow.

Fix

• plugins/work-items/skills/decompose/SKILL.md — new ## Re-decompose (rerouting) section covering the five steps with seam verbs named: (1) close unimplemented children as not-planned (provider-mechanic close through the bound adapter, one-line comment linking the superseding direction; claimed items are coordinated with — or routed to /work-items:track audit on a stale lease — never closed from under their holder), (2) keep implemented children untouched, (3) re-interview/edit the spec where it lives (container body under the spec-on-tracker model, or the topic Brief when no container exists), (4) regenerate remaining slices through the normal draft → approve → publish steps (create-item --parent --blocked-by, mandatory approval gate), (5) continue on the updated frontier. The disposable-tickets/editable-spec doctrine is stated once; the "when NOT to reroute" bounds cover post-ship wrongness (new spec, never a patch to a closed container) and small drift (ordinary body edit). Frontmatter description gains re-decompose trigger phrases.
• docs/upstream/aihero-shipping-course.md — Lane E verdict row flipped to ADOPTED; new ## Lane E (#2949) section records the per-concept verdicts.
• plugins/work-items/CHANGELOG.md / plugin.json — work-items 0.36.1.

Acceptance criteria of #2949: re-decompose section with seam verbs named ✔; doctrine stated once ✔; works against both spec homes (topic Brief and tracker container) ✔.

Verification

• markdownlint-cli2 over the three changed markdown files: 0 issues.
• jq empty on the bumped plugin.json: valid.
• plugins/work-items/tests/no-hardcoded-priority-scheme.test.sh: PASS.
• plugins/work-items/tools/work-item-tracker/work-item-tracker.test.sh: 6/6 suites, all PASS (32 cases).

Related

Refs #2933 (spec container — Lane E), #2934 (Lane A spec-on-tracker model the flow builds on), #3010 (the /work-items:ship router whose re-slice route lands here).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CnzwTKoTa6xNY7iyEzMYpm

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 3m 12s —— View job

---

Claude finished the code review

• Load /review:code-review skill and gather context
• Fetch PR diff and check skip gate (PR is open, not a draft, non-trivial — proceeded)
• Review changed files against CLAUDE.md / REVIEW.md criteria
• Post findings (inline comment + summary)

Summary

This is a clean, internally consistent documentation PR. I traced every seam-verb and cross-reference claim the new ## Re-decompose (rerouting) section makes against the actual implementation and sibling docs:

• list-sub-items <parent> --state all, create-item --parent --blocked-by — real, matching flags (work-item-tracker.sh, CONTRACT.md).
• GitHub not planned close reason + comment in one call — real (adapters/github/README.md#L114-123).
• "Bound adapter's operations reference" for provider-mechanic closes — matches the established convention used throughout this plugin (reference/tracker-seam.md, track/actions/done.md).
• /planning:interview and /work-items:track audit — both real, existing skills.
• The "container-lifecycle drift doctrine" cross-reference (closed container never becomes a living doc) matches the doctrine already stated earlier in the same file (SKILL.md "Ship ritual" section).
• /work-items:ship's "slices no longer fit the spec" routing row already existed and points at /work-items:decompose, consistent with this PR's claim that it "now lands on an owned, documented flow."
• CHANGELOG/plugin.json version bump (0.36.0 → 0.36.1) is consistent; no stale version references elsewhere, and the marketplace manifest doesn't pin plugin versions.
• No markdownlint-shaped issues found (no trailing whitespace, heading levels consistent with siblings).

One finding worth a look, posted inline on plugins/work-items/skills/decompose/SKILL.md (lines 261-306): the new five-step flow ships without a matching case in evals/evals.json, unlike the comparably-sized container-lifecycle addition in 0.36.0 (which got eval case 6). Evals are "warranted, not mandatory" per this repo's skill-quality:check, so it's not a blocker — flagging as a maintainability suggestion given the flow's several correctness-critical constraints (claimed-item skip, implemented-child no-touch, mandatory approval gate on regenerate).

Note: the PR body's markdownlint/jq/test-suite verification claims are author-reported; I did not independently re-run them (no need to — I checked the actual diff for markdownlint-relevant issues by hand and traced all seam-verb claims against the source).
· branch claude/pocock-shipping-breakdown-ukohlx

[claude]

Claude finished @kyle-sexton's task in 47s —— View job

---

Security review — skipped (no security-relevant surface)

• Load /review:security-review skill instructions
• Fetch PR diff (origin/main...HEAD)
• Apply skip gate / assess security-relevant surface
• Deep review — not applicable (skip gate triggered)
• Post final findings

Skip gate triggered: all four changed files are documentation/config —
docs/upstream/aihero-shipping-course.md (verdict-table update + new Lane E
notes), plugins/work-items/skills/decompose/SKILL.md (new markdown
"Re-decompose (rerouting)" section plus a frontmatter description edit),
plugins/work-items/CHANGELOG.md (changelog entry), and
plugins/work-items/.claude-plugin/plugin.json (version bump 0.36.0 →
0.36.1). No code, no scripts, no GitHub Actions workflows, no
authorization/access-control logic, no secret/token handling, no shell
invocations, and no changes to the tracker adapter's executable seam. There is
no security-relevant surface in this diff, so per the skip gate this lane
posts no findings.

[github-actions]

Last security-reviewed head: 9144dcf5f6dfc3b01028a55481ea5d24ed5fd69c. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0ef65a6b71

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 44s —— View job

---

Security review — skipped (no security-relevant surface)

• Load /review:security-review skill instructions
• Fetch PR diff / incremental diff since last reviewed head
• Apply skip gate / assess security-relevant surface
• Deep review — not applicable (skip gate triggered)
• Post final findings

Skip gate triggered. Since the last reviewed head (0ef65a6), the only new
commit (dfbb097, "fix(work-items): correct the Brief-only paths in the
re-decompose flow") edits prose in plugins/work-items/skills/decompose/SKILL.md
— it reconstructs the no-container slice-closure guidance and corrects the
/work-items:ship routing note for Brief-only journeys, both prompted by the
earlier Codex review comments on this PR. No code, scripts, GitHub Actions
workflows, authorization/access-control logic, secret/token handling, or shell
invocations are touched.

All four files changed in the full PR diff remain documentation/config:
docs/upstream/aihero-shipping-course.md, plugins/work-items/skills/decompose/SKILL.md,
plugins/work-items/CHANGELOG.md, and plugins/work-items/.claude-plugin/plugin.json
(version bump 0.36.0 → 0.36.1). There is no security-relevant surface in
this diff, so per the skip gate this lane posts no findings.

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 49s —— View job

---

Security review — skipped (no security-relevant surface)

• Load /review:security-review skill and gather context
• Fetch PR diff (gh pr diff 3016, current head 9144dcf)
• Apply skip gate
• Post final findings

Skip gate triggered: all five changed files are documentation/config —
docs/upstream/aihero-shipping-course.md (verdict-table flip + new Lane E notes),
plugins/work-items/skills/decompose/SKILL.md (new "Re-decompose (rerouting)" markdown section plus a frontmatter description edit),
plugins/work-items/CHANGELOG.md (changelog entry),
plugins/work-items/.claude-plugin/plugin.json (version bump 0.36.0 → 0.36.1), and
plugins/work-items/skills/decompose/evals/evals.json (a new grading-harness fixture, plain JSON data with no executable content).

No code, no scripts, no GitHub Actions workflows, no authorization/access-control
logic, no secret/token handling, no shell invocations, and no changes to the
tracker adapter's executable seam. This holds across the full current diff,
including the two commits (dfbb097, 9144dcf) added since the prior run of
this lane. There is no security-relevant surface in this diff, so per the skip
gate this lane posts no findings.
· branch claude/pocock-shipping-breakdown-ukohlx

[claude]

Claude finished @kyle-sexton's task in 2m 3s —— View job

---

Claude finished the code review

• Load /review:code-review skill and gather context
• Fetch PR diff (origin/main...HEAD) and check skip gate
• Review changed files against CLAUDE.md / REVIEW.md criteria
• Post findings (inline comments + summary)

Summary

Re-reviewed after the two fixup commits (dfbb097, 9144dcf) landed on top of the version already reviewed. Both prior-round findings are resolved correctly, and the new eval case is sound:

• Codex P2 chore: initialize marketplace scaffold #1 (no durable slice list for the Brief-only path) — fixed. SKILL.md step 1 (L274-286) now reconstructs the set via a provider search for open items citing the topic slug in their ## Parent section, user-confirmed before any close. I checked this against the actual template (L162-169): Brief-only slices do carry a Source: PLAN Phase N, topic <slug> line in that section, so the reconstruction strategy is technically sound, not just plausible-sounding.
• Codex P2 fix: correct plugin-system inaccuracies and harden references #2 (Brief-only reroute looping through ship) — fixed. Step 5 (L302-306) now splits: container journeys continue via /work-items:ship, Brief-only journeys go straight to /work-items:work or the frontier ordering, correctly noting ship "has nothing to stand on without" a container.
• My own prior finding (missing eval coverage) — addressed. New case id 7, re-decompose-reroute-disposable-tickets-editable-spec (evals.json L87-101), exercises exactly the correctness-critical constraints flagged: claimed-item skip, implemented-child no-touch, spec-edited-before-regenerate ordering, and the approval gate. Structurally consistent with sibling cases (same id/name/prompt/expected_output/expectations shape), valid JSON.
• Verified "$TRACKER" list-sub-items "<container-id>" --state all (SKILL.md#L274-275) against CONTRACT.md#L136: signature list-sub-items <parent-id> [--state open|closed|all] matches exactly.
• CHANGELOG/plugin.json/Lane-E doc updates are internally consistent with the SKILL.md changes and with each other.

No new findings on this diff — both open threads from the prior rounds are correctly closed out, and the eval addition doesn't introduce anything questionable.

Note: I re-derived the diff via git diff HEAD~3...HEAD since this is a shallow clone without a merge-base against origin/main; that range matches the PR's stated 5 changed files and +111/-3. I did not re-run markdownlint-cli2/jq/the test suites myself — the author-reported verification in the PR body is unverified by me, consistent with the prior round's note.
· branch claude/pocock-shipping-breakdown-ukohlx