[kyle-sexton]

Closes #7537

Summary

docs/conventions/ held two kinds of file: contracts for plugin authors working in this repository, and the convention and settings files a consumer repository would also have (ADR 0064). Plugins resolve a consumer's convention home to docs/conventions/ by default, so this repository's own folder now holds only what a consumer's would.

Fix

• 48 plugin-author contract folders move from docs/conventions/<name>/ to docs/contracts/<name>/ (for example hook-budget, enforcement-ladder, mod-authoring, hook-precision, loop-lane, config-cascade).
• Old paths that keep a stub:
  • Every moved README keeps a stub carrying each heading of the moved file, so existing links and #anchor references still resolve.
  • The 11 other moved files that something under plugins/, lib/, scripts/ or .github/ on main cites, which installed plugin versions carry:
    • check-placement/adopting-git-hooks.md, config-cascade/consumer-gotchas.md and hook-precision/guard-precision.md keep a heading and a "Moved to" link.
    • ecosystem-commands/ecosystem.schema.json, hook-telemetry/envelope.schema.json, hook-telemetry/data/{block-windows-drive-tmp,lane-stop-gate,stale-path-verify}.schema.json and standards/standards.schema.json are JSON Schemas that keep the old $id and $ref the new file's $id.
    • ecosystem-commands/examples/{dotnet,go}.yaml are comment-only pointers; no lane reads them, so scripts/affected-tests-no-suite.txt records them.
• The other moved files (changelogs, the remaining schemas and examples, sub-docs) get no stub: nothing in those trees cites their old paths.
• docs/conventions/ keeps the <concern>.yaml and .md settings files and pr-pipeline/, which moves later behind its own gate.
• References across plugins, scripts, .claude/ and AGENTS.md point at docs/contracts/. The config-cascade and prerequisites readers read from docs/contracts/.
  • A few comment links in files with no test suite stay on the old README paths, where the stubs resolve them.
  • The plugin copy of hook-telemetry-sink.sh stays in step with its .claude/ copy.
• The AGENTS.md "Team standards" paragraph now says where contracts and settings live.
• docs/contracts/ecosystem-commands/examples.test.sh validates the moved examples against ecosystem.schema.json, with a negative case.
• Changelog fragments for every plugin the branch touches.

Verification

• Pre-push on head ddf6655e27, merged with main 2026-10-28:
  • check-affected passed: 12 passed, 5 skipped.
  • guardrails-remote-reference-verify passed in 150 s.
• Main's reference-verify.sh over the whole branch range: exit 0 in 87 s.
• examples.test.sh in the affected-tests suite: 138/138.
• Stub commit: every old non-README path was checked with git grep -l -F <old path> origin/main -- plugins lib scripts .github; the 11 stubbed are the hits other than standards/CHANGELOG.md, which only this repository's check-standards-contract-bump scripts name and this branch repoints. The six stub schemas pass check-jsonschema --check-metaschema; check-affected passed (11 passed, 4 skipped) and check-changelog-fragments.sh --check-required passed.

Related

• ADR 0064 (convention folders hold plugin settings).
• fix(contracts): read contracts from docs/contracts with a docs/conventions fallback #10593 landed the contracts-path fallback this branch relies on.
• test(harness-config): restore SIGINT for the signal case when the suite runs as a background job #10627 landed the SIGINT test fix found while gating this branch.

🤖 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	✅ Completed 2026-10-28T21:59:27.195354Z	3b34f3a	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 0e0cc61b1deb7909299869c40bdfdc3207b6061a: 0 finding(s), 0 as inline comments.

No security findings.

critical-findings: 0

This is a path move: 48 contract folders go from docs/conventions/ to docs/contracts/, with stubs left at the old paths. I read the diff directly and did not dispatch hunter or verifier subagents. My shell tool was disabled, so I searched .claude-lane/pr.diff and the checkout with Grep and Read.

What I read in the trusted paths

• .github/scripts/pr-merge/enable-auto-merge.mjs and post-unarmed-status.mjs: comment-only. They repoint a loop-lane link and change no logic.
• .github/workflows/pr-require-checks.yml: two comment-only path edits. The ci-status hold steps are untouched.
• babysit_risk.py and babysit_verify_evidence.py: docstring and comment URL edits only. The risk path table (babysit_risk.py:280) and docs/conventions/pr-pipeline.yaml stay where they are.
• babysit_review_evidence.py: LANE_SOURCE_PREFIXES gains docs/contracts/instruction-exception-register/ and docs/contracts/untrusted-content/. The old docs/conventions/ prefixes stay, so editing either the stub or the moved file still marks a pull request as having changed its own review input. This widens the set of lane-source paths and weakens nothing. test_babysit_review_evidence.py covers both.
• .github/workflows/release-publish-plugins.yml:231: the staged release commit now also stages docs/contracts. It comes from the main checkout, so no untrusted input reaches it.
• Trust controls: none of trusted-actors, check-trusted-trigger, request-lane-token, check-kill-switch, resolve-config, CODEOWNERS, .gitmodules, merge-holds.mjs or the merge: settings in pr-pipeline.yaml changed. pr-pipeline.yaml and pr-pipeline/ stay in docs/conventions/, as the description says.
• Plugin manifests: the diff touches no plugin.json or marketplace.json, so there are no manifest <field> lines.
• The lib/, scripts/ and .claude/ changes are comment, link and string-literal repoints. The one functional path change is lib/hook-test-sink.sh:68, which now looks for envelope.schema.json under docs/contracts/. The schema moves in the same pull request, and the test fails closed if it is missing.

Instruction-surface check
docs/conventions/instruction-exception-register/README.md and untrusted-content/README.md become heading-only stubs that link to docs/contracts/. The full text moves intact, and docs/contracts/instruction-exception-register/README.md carries the classes. An installed older security-review skill still reads the old path. It would find the stub, which still links to the moved sections. The updated skill in this change points at the new path. No rule is deleted, so this is not a finding. The register's protected-class list was not re-read against the removed lines, because nothing in the diff deletes a rule.

No spend: this change adds no paid plan, billing setting or billed resource, and no prepaid-credit usage either.

[github-actions]

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

claude-lane: claude-review

[github-actions]

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

No findings. I did not read the whole 1065-file diff; I sampled the files where behavior can change. I had no shell, so I ran nothing and did not run the author's checks (check-affected, reference-verify.sh, examples.test.sh).

I read:

• the stub schemas that keep an old $id and $ref the new file;
• the changelog-fragment helpers convention_of and root_of in scripts/lib/changelog-fragments.sh, check-changelog-fragments.sh and write-changelog-fragments.sh, with their tests;
• the new docs/contracts/ecosystem-commands/examples.test.sh;
• the trusted-path changes: the comment-only path edits in pr-merge/enable-auto-merge.mjs, pr-merge/post-unarmed-status.mjs, babysit_risk.py and babysit_verify_evidence.py, the pr-require-checks.yml comments, and the security-review SKILL.md path edits;
• the babysit_review_evidence.py change, which adds docs/contracts/instruction-exception-register/ and docs/contracts/untrusted-content/ to LANE_SOURCE_PREFIXES next to the old stub paths;
• the release-publish-plugins.yml change that adds docs/contracts to git add, the AGENTS.md edits, and the .changes fragments.

Everything I read holds:

• Trusted-path scripts: the pr-merge and babysit edits are comment or doc-URL rewrites, plus the lane-source prefix addition above. No gate logic changed.
• Changelog helpers: the new helpers resolve docs/contracts/<name>/ and docs/conventions/<name>/, and skip a stub left at the old path or a name a plugin owns.
• Schemas and tests: the stub schemas keep the old $id, and the in-repo readers (hook-test-sink, standards scripts, prerequisites.test.mjs) now point at docs/contracts/.
• Examples test: examples.test.sh has a negative case, and it skips rather than passes when check-jsonschema is missing.
• Fragments: the fragments I read are bump: patch, which fits a path-only change.

Manifest items: the diff touches no plugin.json or marketplace.json, so the manifest checks do not apply.

Closing issue #7537: I read this against the issue's decision comments. The move, the stubs, the AGENTS.md update and the pr-pipeline/ carve-out match them. The comment says ADR 0064 Decision 6 is amended in the same change. The diff touches ADR 0064, but I did not read that edit.

Cost: no billing or paid-plan change.

[melodic-automation-lanes]

The pr-unblock lane stopped resolve-conflicts on this pull request: the lane could not resolve every conflict. The lane sets no label: the run ends in a failing pr-unblock/conflict status on the head the lane gated.

• Reason: unresolved-conflict
• Head: a6981a5a94c031554fac0efe00bd971a98358cad
• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/40787899762

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=10719 -f activity=resolve-conflicts

[github-actions]

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

claude-lane: claude-review

[github-actions]

The pr-verify verifier failed head 0e0cc61b1deb7909299869c40bdfdc3207b6061a. What it wrote, as data:

Summary: Issue #7537 asks for the plugin-author contracts in docs/conventions/ to move to docs/contracts/, with stubs at the old paths, every reference rewritten, AGENTS.md updated and ADR 0064 Decision 6 amended. The diff is about 3.4 MB. It shows each moved file in full instead of as a rename, and it runs to hundreds of files. I could not review it all with confidence. The parts I read look right: the reference rewrites in .claude/, .github/, AGENTS.md and the ADRs, the AGENTS.md "Team standards" paragraph, and the one-line release-publish-plugins.yml staging change. The parts I could not read include executable code: the changelog-fragment scripts, the config-cascade and prerequisites readers, babysit_review_evidence.py and its tests, the plugin hook scripts and the plugin skill instructions. The rules require `fail` when an unread part is executable, so this fails on size and the change needs to be split. I found no correctness or safety defect in what I read.
- pr-verify-data/diff.patch: about 3.4 MB. Moved files appear as full delete and add instead of renames, so I could not review the whole diff with confidence. Split it into: (1) a pure move PR, with the docs/conventions/<name>/ to docs/contracts/<name>/ renames and the old-path stubs only, so rename detection keeps it small; (2) a PR for the prose and comment reference rewrites in docs/, plugins/*/skills and the changelog fragments; (3) a small PR for the executable changes.
- scripts/lib/changelog-fragments.sh, scripts/check-changelog-parity.sh, scripts/check-changelog-fragments.sh, scripts/write-changelog-fragments.sh: the PR adds root_of/convention_of handling for docs/contracts/. I could not find or review these changes in the diff I read. Put them in the small executable PR so a reviewer can confirm both homes resolve, including a stub left at the old home.
- babysit_review_evidence.py and tests/test_babysit_review_evidence.py: the lane-source prefix list changes (both the docs/contracts/ and the old docs/conventions/ prefixes). I could not review this. It feeds the review and merge lanes, so put it in the executable PR.
- The config-cascade and prerequisites readers now read from docs/contracts/. I could not review the code change. Put it in the executable PR with its tests.
- plugins/**/hooks/*.sh, the plugin copy of hook-telemetry-sink.sh, and plugin SKILL.md and agent instructions: many changes, not reviewed in full. A path rewrite inside an executable hook or a lane-steering instruction must be readable on its own. Keep it in a reviewable split.
- .github/workflows/release-publish-plugins.yml:231: `git add -A -- plugins docs/contracts docs/conventions .changes` is correct for the move (read and judged).
- AGENTS.md:102-106: the Team standards paragraph now names docs/contracts/ for contracts, docs/conventions/ for settings, and pr-pipeline/ staying put until its own gate. This matches the owner's 2026-10-22 decision (read and judged).
- docs/adr/0064-*.md: the owner's decision requires amending Decision 6 in this same change. I could not confirm the amendment in the part of the diff I could read. Make sure the split PRs include it, along with the conventions index update the issue asks for (step 4).
- Issue #7537: the owner's decision says the move is built attended because it touches AGENTS.md. The PR author is the owner account, which looks consistent with that.

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.

[kyle-sexton]

Closing as superseded: pr-verify failed this head for size (about 3.5 MB), and #7537 is landing as a split. #7537 stays open.