[kyle-sexton]

Refs: #7537

Summary

Part B1 of the #7537 split moves the 48 plugin-author contract folders from docs/conventions/<name>/ to docs/contracts/<name>/ as pure renames. No file is left at an old path, so git pairs every rename and the diff stays readable (about 330 KB, against #10719's 3.5 MB). The old-path stubs follow in B2 right after this.

Main stays green with B1 alone. Part A (#10942) made every contract reader try docs/contracts before docs/conventions, and A2 (#10949) covers the last one. A temporary .lycheeignore entry skips file:// links into the 48 moved folders until B2's stubs land and remove it.

Fix

• git mv of the 48 contract folders (125 renames).
• The ADR 0064 Decision 6 amendment and the convention registry in docs/plugin-philosophy.md, the owner's decision for docs: separate plugin-author contracts from consumer conventions in docs/conventions #7537.
• AGENTS.md, .claude/rules/* and .claude/code-metrics.yaml: the owner-approved path edits, unchanged from docs(contracts): move plugin-author contracts out of docs/conventions #10719.
• Prose in docs/ and .github/, the scripts/*.txt and .json registries, and the 11 generated plugin copies of the standards, enforcement-ladder and pr-scope-budget contracts point at the new paths.
• release-publish-plugins.yml:231 stages docs/contracts. The path must exist, because git add -A -- … docs/contracts … exits 128 with "did not match any files" when it does not, so the line ships with the move.
• .lycheeignore: the temporary entry, marked TEMPORARY (#7537). .lycheeignore is also added to scripts/affected-tests-no-suite.txt.

The only executable file in the diff is the one-line release-publish-plugins.yml change.

Per-folder calls. The owner's decision (#7537 (comment)) leaves standards/, commit-convention/, loop-lane/ and pr-body-convention/ to a per-folder call in the move PR. The decision's own rule is that a convention folder is a plugin contract and a top-level <concern>.yaml/.md file is this repository's setting. All four are folders that shipped plugins read, so all four move:

• standards/: read by discipline, improvement, planning and review.
• commit-convention/: read by docs-hygiene, guardrails (the commit-msg hook's convention) and source-control. The docs: separate plugin-author contracts from consumer conventions in docs/conventions #7537 body gives commit-convention/ as an example of what a consumer would also have. The folder holds one file, its README, which calls itself the "Owner doc for the machine-readable enforcement read … consumed by more than one plugin", a contract. The consumer-side file is docs/conventions/source-control/commit-convention.yml, read at that path by lib/resolve-convention-pattern.sh:82 and plugins/guardrails/hooks/block-convention-violation.sh:201, and it stays where it is: this PR does not touch docs/conventions/source-control/.
• loop-lane/: read by attribution, autonomy, docs-hygiene, harness-ops, implementation, playbooks, rate-limit-guard, source-control and work-items.
• pr-body-convention/: read by source-control and testing.

(Counts: git grep -l "docs/conventions/<name>/" -- plugins/ on main.) pr-pipeline/ stays put for its own gate, as the decision says.

Not path-only, by design. scripts/affected-tests-no-suite.txt names docs/contracts/ecosystem-commands/examples.test.sh, which landed on main with part A (#10942), so the comment points at a real suite. Everything else in the diff is a path rewrite. In particular, config-cascade/README.md differs from main only in paths.

Verification

• On main + A2 + this branch: lychee offline with the repo's flags reports 0 errors. Without the entry it reports 46 broken links, all into the moved folders. check-affected --tests passes everything except one network-bound planning suite (tracer-live.test.sh, a real cloudflared tunnel that CI skips). Every whole-repo scanner matches the main baseline.
• On main + A2 + this branch + B2: lychee offline reports 0 errors with the entry removed, and check-affected exits 0.
• A search of every non-markdown file for the 48 moved names (495 hits) found no runtime read that fails after the move.

Related

• fix(contracts): resolve contract paths under docs/contracts #10942 (A) and fix(harness-ops): count contracts under docs/contracts in surface discovery #10949 (A2): the both-home readers.
• B2: the old-path stubs, stacked on this branch. Its PR opens right after this one, so the window is one merge.
• docs(contracts): move plugin-author contracts out of docs/conventions #10719: the superseded single PR.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	🔄 Running since 2026-10-29T13:54:38.586140Z	e55b810	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

claude-security-review reviewed 08bd36a63b7af5e362559712cffcbcc31ce27d30: 0 finding(s), 0 as inline comments.

No security issues found in this incremental change.

The only change since cc2b5cc is in docs/contracts/config-cascade/README.md. In the review-digest row of the conformance table, the "Keys owned by" link target changes from ../review-digest.md to ../../conventions/review-digest.md. The rest of the row is byte-identical.

The change touches no trust control, no trusted path, no instruction surface and no plugin manifest. It adds no executable code and no wording that loosens a standing rule. The link now points at a docs/conventions file, which matches the commit message. Skip gate 2 applies (no security-relevant surface).

critical-findings: 0

[github-actions]

claude-review: 2 inline finding(s) on e55b8103b18711a0549ad59a0313e3679a15067e; the summary is in this lane's pull request comment.

claude-lane: claude-review

[github-actions]

This sentence is false at this commit: B1 leaves nothing at the old docs/conventions/<name>/ paths. The stubs arrive in B2. If B2 slips or changes shape, the released changelog says a stub exists that does not.

The same sentence is in the other eight docs-7537-b-move-*.md fragments and in .changes/pr-pipeline/docs-7537-contracts-split-a29773ae.md. The ADR 0064 Decision 6 amendment also says each folder moved "leaving a stub README at its old path". Either word these for what B1 does (the contract moved, and a stub is planned), or land the fragments and the ADR sentence in B2 with the stubs.

claude-lane: claude-review

[github-actions]

This fragment (bump: minor, the attended label feature) has nothing to do with the contract move, and no file in this diff implements it. The base side of the loop-lane README already documents attended, so the feature looks already merged. It may be a stray or resurrected fragment from the main merge. If main already released it, this publishes a duplicate pr-pipeline minor entry. If it is still unreleased there, it should not be re-added here. Drop it from this PR unless it is meant to be here.

claude-lane: claude-review

[github-actions]

claude-review reviewed 08bd36a63b7af5e362559712cffcbcc31ce27d30: 0 finding(s), 0 as inline comments.

Incremental review of docs/contracts/config-cascade/README.md (changes since cc2b5cc). The only change is the review-digest row's "Keys owned by" link, from ../review-digest.md to ../../conventions/review-digest.md.

I confirmed that docs/conventions/review-digest.md exists. From docs/contracts/config-cascade/, ../../conventions/review-digest.md resolves to that file. The old link resolved to docs/contracts/review-digest.md, so it was broken. A search of the README found no other ../<name>.md links of the same shape. No findings.

Nothing in this change spends credits or triggers a billed resource, and there is no hold. Files outside this increment were not re-reviewed. I did not run link-checking tools or tests. The link check above was done by reading file paths only.

[github-actions]

The pr-verify verifier failed head 08bd36a63b7af5e362559712cffcbcc31ce27d30. What it wrote, as data:

Summary: Refs #7537 (partial delivery). The PR body names its part (B1: move 48 contract folders to docs/contracts/ and rewrite references) and the remaining work (B2 old-path stubs, the pr-pipeline move later). Both are within the owner's 2026-10-22 decision. The renames, relative-link fixes, registry and AGENTS.md updates, the ADR 0064 Decision 6 amendment and the one-line release-publish-plugins.yml change all read correctly. The problem is that B1 is not coherent on its own. It removes every file at the old docs/conventions/<name>/ paths without the stub READMEs the owner's decision requires "so installed plugin versions keep working". That breaks the roughly 199 shipped absolute URLs into main/docs/conventions/<name>/ and the 46 local links that the PR silences with a temporary .lycheeignore entry. The issue also requires that "Plugin skills that cite these contracts by path must keep resolving". Nothing makes B2 merge right after B1, and the amended ADR text already says stubs exist.
- docs/conventions/: this change deletes every file at the 48 old contract paths with no stub README in its place. The owner's decision on #7537 says each moved folder leaves a stub at its old path so installed plugin versions keep working, and the issue says plugin skills that cite these contracts by path must keep resolving. With B1 alone on main, the shipped absolute URLs into main/docs/conventions/<name>/ return 404 until B2 merges, and nothing guarantees B2 merges next. Fix: add the B2 stub READMEs to this PR. If diff readability matters, keep them as a separate commit in the same PR so the move and the stubs land in one merge.
- .lycheeignore:252-253: the TEMPORARY (#7537) entry hides 46 broken local links that main would carry once B1 merges. Once the stubs are in this PR, delete this entry and the .lycheeignore line added to scripts/affected-tests-no-suite.txt, so the link check stays fully enforced on main.
- docs/adr/0064-home-plugin-customization-in-docs-conventions-yaml.md:691: the amendment says the contract folders moved "each leaving a stub README at its old path", which is false while this PR lands without B2. Fixed by shipping the stubs in this PR; otherwise reword it to match what is actually on main.
- docs/contracts/consumer-config-layering/README.md: this file is a compatibility tombstone that exists so old cached code-tidying and testing copies that fetch docs/conventions/consumer-config-layering/README.md do not get a 404. Moving it breaks that purpose. Keep a stub at the old path, and fix its relative link `../config-cascade/README.md` so it resolves from wherever the stub sits.
- README.md:325,334: unrelated prose rewording ("an hours-long wall" becomes "takes hours", ":" becomes ", because"). The spec does not ask for it. It is harmless, but drop it or call it out in the PR body.
- docs/contracts/commit-convention/README.md: the #7537 body gives commit-convention/ as an example of a consumer convention, but the owner's decision left it to a per-folder call in the move PR. The PR body argues that it is a contract and that the consumer file docs/conventions/source-control/commit-convention.yml stays put. Reasonable, but a human should confirm this call.
- .github/workflows/release-publish-plugins.yml:231: adding docs/contracts to `git add -A` is needed and correct once the folder exists. No other executable file changes.

This pull request leaves the merge queue, and ci-status holds it out while it carries pr-verify-failed. A pr-verify pass at a new commit removes the label.

[github-actions]

claude-security-review: 1 inline finding(s) on cc2b5ccf2d64d8942142f70c32991ec3c71d60c7; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

[github-actions]

severity: IMPORTANT

This rename moves a gate-class contract out of every hold-path list. The lists still name the old folder, and this diff does not touch them:

• .github/scripts/pr-merge/merge-holds.mjs:347 and :346 (docs/conventions/untrusted-content/** and docs/conventions/instruction-exception-register/**)
• .github/workflows/pr-review-hosted.yml:284-285 and pr-review-security-hosted.yml:284-285
• plugins/source-control/skills/babysit-prs/scripts/babysit_risk.py:364-365 and :465-466

After the merge, a PR that weakens this framing contract (or the instruction-exception register) at docs/contracts/... matches no gate glob. It gets no hold and no trusted-path scrutiny. .github/CODEOWNERS has no docs/contracts entry either, so nothing else routes it to a person.

Fix: add the docs/contracts/untrusted-content/** and docs/contracts/instruction-exception-register/** globs to all three lists in this PR. Keep the old globs until the B2 stubs land.

_{claude-security-review}

claude-lane: claude-security-review

[melodic-automation-lanes]

The pr-unblock lane stopped resolve-conflicts on this pull request: the merge stages the pull request's own .github/workflows/ changes together with the base's, which the lane token cannot push, so a session merges main by hand. The lane sets no label: the run ends in a failing pr-unblock/conflict status on the head the lane gated.

• Reason: workflow-staged
• Head: 08bd36a63b7af5e362559712cffcbcc31ce27d30
• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/40910406695

When a retry on this head can change the outcome, the lane runs one on its own, up to its per-head cap, and edits this comment if it stops again; a run that does not stop clears the status. When no retry can (a review thread the lane does not take or settle, or a failing check after the retries are spent), a person resolves the threads or gets the checks green, then dispatches the workflow below: that run finds the cause gone and clears the status. On a pull request the lanes App opened, the dispatchers start that run once per stop; on any other, a person does. A new commit to the branch starts clean.

To run it again on this head now, dispatch the pr-unblock workflow:

gh workflow run pr-unblock.yml -R melodic-software/claude-code-plugins -f pr-number=10952 -f activity=resolve-conflicts

[kyle-sexton]

Superseded by the five stacked layers that split this change: #11031 (moves), #11056 (registry-named moves), #11060 (lane-source moves), #11062 (reference rewrites) and #11069 (stubs at the old paths). They merge in that order.