docs(work-items): document local-markdown branch and worktree confinement by kyle-sexton · Pull Request #2975 · melodic-software/claude-code-plugins

kyle-sexton · 2026-08-17T18:01:15Z

Summary

Documents the local-markdown adapter's branch, worktree, and lease confinement — working-tree files are never a coordination surface — in the seam contract, a new adapter README (matching github/jira siblings), the setup provider comparison, and the plugin README operations pointer.

Fix

CONTRACT.md ## local-markdown adapter gains ### Branch, worktree, and lease confinement (relative storage_dir roots at the binding file; shared vs divergent worktrees; identity; reclaim: false; work-map container cross-ref).
New adapters/local-markdown/README.md operations reference (offline-only; no gh/curl recipes).
Setup skill provider-comparison bullet names confinement (kept under the 500-line SKILL.md cap).
Plugin README cites the local-markdown operations README alongside GitHub.
Plugin version 0.35.24 → 0.35.25 with matching CHANGELOG.

Verification

bash plugins/work-items/tools/work-item-tracker/lib/binding.test.sh — 23 PASS (relative storage_dir already covered).
scripts/check-changed-skills.sh origin/main — setup SKILL.md 499/500, PASS.

This PR is documentation-only: it adds a "Branch, worktree, and lease confinement" section to CONTRACT.md, a new adapters/local-markdown/README.md operations reference, a provider-comparison note in the setup skill, a README pointer, and a version/changelog bump. No adapter code, scripts, or CI workflows are touched, and the diff contains no executable commands (gh/curl recipes are explicitly excluded from the new adapter README by design).

Per the skip gate (no security-relevant surface after reading the diff), no security review findings apply here.

View job run

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c301c631c8

ℹ️ 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".

…#2944) Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

claude · 2026-08-17T18:35:59Z

Claude finished @cursor[bot]'s task in 1m 27s —— View job

Code review complete

Gather context (PR diff, changed files)
Apply skip gate check
Review changed files for correctness/maintainability findings
Adversarially validate candidate findings
Post inline comments and summary

No findings to report. This is a documentation-only PR (CONTRACT.md, new adapter README, setup skill, plugin README, changelog/version bump) with no adapter code changes.

I checked the two pre-existing Codex review comments against the current HEAD (4e11baa) and both are already resolved by the latest commit, "honest local-markdown isolation and number-only ids" (4e11baa), which landed after those comments were posted against an earlier commit (c301c631c8):

"Do not claim uncommitted items are branch-isolated" — CONTRACT.md#L345-L351 now explicitly states untracked/uncommitted item files are not branch-isolated in the same worktree, that git switch normally carries them onto the new branch, and that a nonconflicting uncommitted lease edit can likewise follow. Invisibility is now correctly scoped to sibling worktrees and committed-but-unmerged branch state.
"Enforce namespaces before calling cross-namespace edges unresolved" — adapters/local-markdown/README.md#L16-L19 now documents that lookups key by number only and the owner/repo in the id is not re-validated against the store, and that cross_repo_edges: false means there's no second store to consult — not that a foreign-looking qualified id fails lookup. This matches the actual implementation (get-item.sh's own comment: "The ID's owner/repo namespace is opaque here"; common.sh's wit_emit_local_item extracts only the numeric suffix via ${bid##*#}).

Additionally verified:

plugins/work-items/skills/setup/SKILL.md is 499 lines, under the claimed 500-line cap.
capabilities.json confirms reclaim: false, matching the new CONTRACT.md/README claims.
list-items.sh's --repo handling matches the new README's "accepted for interface parity, does not re-target" claim.
link-blocks.sh behavior (records the blocker id verbatim, resolves state by numeric suffix only) matches the new docs.

github-actions · 2026-08-17T18:37:54Z

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

Both #2975 (merged) and this branch claimed work-items 0.35.25. This branch's contract-hygiene entries move to a new 0.35.26 section; plugin.json bumped to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CnzwTKoTa6xNY7iyEzMYpm

…sue triggers (#2976)  Closes #2947 ## Summary Records ticket/issue as first-class invocation synonyms for canonical "work item", cross-links the Shipping-course SSOT both directions, and makes to-tickets / triage / wayfinder absorptions-under-different-names traceable on the v1.2 map. ## Fix - `track` and `work` skill descriptions gain ticket/issue Use-when phrases; synonymy documented once in the work-items README. - `docs/upstream/mattpocock-skills.md` links the course SSOT; course Cross-links note #2947 landed. - v1.2 map rows 15–17 name the absorbed vocabulary; questionnaire skill-body STALE stays planning-owned (not this PR). - Plugin `0.35.25` → `0.35.26` (stacked on #2975 / #2944). ## Verification - Description lengths: track 959/1536, work 813/1536. - `check-skill.sh --require-evals track` PASS; `work` PASS (existing evals). ## Related Refs #2933. Stacked on #2975 (local-markdown docs, #2944) — that PR's commits appear here until it merges. Do not edit planning plugin (questionnaire STALE is planning-owned).  <div><a href="https://cursor.com/agents/bc-60311e3e-bf89-4375-aded-ebb9933c68fa?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-60311e3e-bf89-4375-aded-ebb9933c68fa&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>

…SOT lane sections Main took 0.35.26 (#2942) and 0.35.27 (#2947); this branch's decompose entries move to 0.35.28 with plugin.json bumped to match. Course SSOT keeps both the Lane B section (this PR) and the merged Lane W section; v12-map rows 15/16 keep this PR's deliberate CONVERGENT re-classification. Stacked leftovers from already-merged #2975/#2976 (track SKILL.md, CONTRACT.md, local-markdown README) resolve to main's versions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CnzwTKoTa6xNY7iyEzMYpm

…nch fallback (#2978)  Closes #2935 ## Summary Adopts five decompose deltas from the Shipping-course audit: prefactor-first slices as blockers, one-fresh-window sizing beside S/M/L, an integration-branch fallback when expand-contract batches cannot land green alone, "work the frontier" in the report, and a PR-variant agent brief. ## Fix - `decompose` SKILL.md: C5–C8 (no token folklore; expand-contract remains the default). - `reference/agent-brief.md`: PR-variant (current-behavior-of-the-diff / finish-what-exists). - Evals cover the new rows. Course SSOT Lane B → PARTIAL. - Plugin `0.35.26` → `0.35.27`. Approval gate, born-triaged, blockers-first publish unchanged. ## Verification - `check-skill.sh --require-evals decompose` PASS (183/500 lines). - `check-evals-quality.sh` PASS (4 cases). ## Related Refs #2933. Stacked on #2976 (#2947) and #2975 (#2944).  <div><a href="https://cursor.com/agents/bc-60311e3e-bf89-4375-aded-ebb9933c68fa?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-60311e3e-bf89-4375-aded-ebb9933c68fa&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>

cursoragent and others added 2 commits August 17, 2026 17:56

docs(work-items): document local-markdown branch and worktree confine…

cdfdb1c

…ment (#2944) Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

docs(work-items): keep setup SKILL.md under the 500-line cap

c301c63

The confinement note in the local-markdown provider comparison pushed the file to 503 lines. Compress it so the skill-quality hard cap still passes. Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

kyle-sexton mentioned this pull request Aug 17, 2026

docs(work-items): course SSOT cross-links, map absorptions, ticket/issue triggers #2976

Merged

kyle-sexton marked this pull request as ready for review August 17, 2026 18:11

chatgpt-codex-connector Bot reviewed Aug 17, 2026

View reviewed changes

Comment thread plugins/work-items/tools/work-item-tracker/CONTRACT.md Outdated

Comment thread plugins/work-items/tools/work-item-tracker/adapters/local-markdown/README.md Outdated

kyle-sexton mentioned this pull request Aug 17, 2026

feat(work-items): decompose prefactor, window sizing, integration-branch fallback #2978

Merged

docs(work-items): honest local-markdown isolation and number-only ids (…

4e11baa

…#2944) Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

kyle-sexton merged commit 3466c5b into main Aug 17, 2026
48 checks passed

kyle-sexton deleted the cursor/2944-local-markdown-docs-68fa branch August 17, 2026 20:13

claude Bot mentioned this pull request Aug 17, 2026

feat(work-items): seam contract hygiene — version handshake, ADR 0014, label-default SSOT #2970

Merged

Navigation Menu

Uh oh!

docs(work-items): document local-markdown branch and worktree confinement - #2975

docs(work-items): document local-markdown branch and worktree confinement#2975
kyle-sexton merged 3 commits into
mainfrom
cursor/2944-local-markdown-docs-68fa

kyle-sexton commented Aug 17, 2026

Uh oh!

cursor Bot commented Aug 17, 2026

Uh oh!

claude Bot commented Aug 17, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Aug 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

kyle-sexton commented Aug 17, 2026

Summary

Fix

Verification

Related

Uh oh!

cursor Bot commented Aug 17, 2026

Uh oh!

claude Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Security review — skipped (no security-relevant surface)

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code review complete

Uh oh!

github-actions Bot commented Aug 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

claude Bot commented Aug 17, 2026 •

edited

Loading

claude Bot commented Aug 17, 2026 •

edited

Loading