[kyle-sexton]

Refs: #7537

Summary

Part B1, layer 1 of 5, of the #7537 split. It moves 38 of the 48 plugin-author contract folders from docs/conventions/<name>/ to docs/contracts/<name>/ as pure renames (109 files). It replaces #10952 together with the four layers above it. Main stays green with this layer alone: part A (#10942) and A2 (#10949) made every contract reader try docs/contracts first.

Merge order. #10952 is re-split into five stacked layers so each review diff stays under pr-review-main's 300 KB cap (MAX_DIFF_BYTES, measured with #10969's write-diff.py):

1. M docs/7537-b1-moves: 38 folders' pure moves (collapsed to rename lines) and the TEMPORARY link-check entries.
2. M2 docs/7537-b1-moves-registered: the 7 folders a registry names by README path, with those registries and the synced copies.
3. M3 docs/7537-b1-moves-lane: rendered-views and the two lane-source folders, plus every lane-source reference edit.
4. R docs/7537-b1-refs: the remaining reference rewrites.
5. B2 docs/7537-b2-stubs-v2: docs(contracts): leave stubs at the moved contracts' old paths #10957's stubs.

Merge in that order: M, M2, M3, R, then B2. Each layer targets the branch below it. main squash-merges, so after a layer lands, retarget the next layer to main and merge main into it; until then its diff still carries the landed layer and is over the cap.

Why five layers. Over the cap, write-diff.py collapses a pure move to its rename lines, but it prints a move whole when an added line names its new path, its last directory and name, its name or its name without extension. A registry line such as docs/contracts/standards/README.md names every moved README.md, and the two lane-source folders always print whole and name README.md in their text. Either one in this layer would print every move whole (measured 2.17 MB). So the folders a registry names, and the lane-source folders, move in layers 2 and 3, where the patch is under the cap and prints whole anyway.

Fix

• git mv of 38 contract folders (109 renames), unchanged.
• scripts/em-dash-purged-paths.txt: those folders' entries repoint to docs/contracts/.
• .lycheeignore: two entries marked TEMPORARY (#7537). The first skips file:// links into the old paths of all 48 folders until B2's stubs land and remove it. The second skips relative links inside moved folders that dangle until layers 2 and 3 move their targets and R rewrites the links to pr-pipeline/, pr-pipeline.yaml and review-digest.md; R removes it. .lycheeignore is added to scripts/affected-tests-no-suite.txt.

Per-folder calls (carried from #10952). 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 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/ (layer 2): read by discipline, improvement, planning and review.
• commit-convention/ (this layer): read by docs-hygiene, guardrails (the commit-msg hook's convention) and source-control. Its one file, the README, 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. It stays where it is: no layer touches docs/conventions/source-control/.
• loop-lane/ (this layer): read by attribution, autonomy, docs-hygiene, harness-ops, implementation, playbooks, rate-limit-guard, source-control and work-items.
• pr-body-convention/ (this layer): read by source-control and testing.

pr-pipeline/ stays put for its own gate. config-cascade/ is path-only: its README differs from main only in paths, and those edits land in R.

Verification

• Review diff as write-diff.py builds it: 35,253 bytes, all 109 moves collapsed, no line over 1,800 bytes. No lane source, so pr-review-main does not run on this layer.
• lychee --offline with the repo config: no error in the moved or registry files; the only other error is an HTML fixture's beds.png image link, which this change does not touch. check-affected.sh --tests: 11 passed. The shell runner reports all 83 selected suites passed or skipped, and the node suites pass. The Python suites pass apart from test_reader_findings.py::…non_literal_stays_partial, which fails the same way on the main checkout at d5d8ff15. Conformance, contract-clause, em-dash, shared-copies, standards-bump, changelog and config-cascade-semantics checks pass, and examples.test.sh passes at its new path.

Related

• docs(contracts): move plugin-author contracts to docs/contracts #10952 and docs(contracts): leave stubs at the moved contracts' old paths #10957: superseded by this stack and left open for the owner.
• fix(pr-pipeline): give the main-run review the lanes' credential chain and collapse exact renames #10969: the rename collapse this split is measured against.

Draft: a stacked layer of the #7537 B1 re-split; it goes through /source-control:pull-request ready in merge order, after the layer below lands and main is merged in.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VQb9Q3ucKDVyHvpcU5cfU8

[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-29T22:13:40.532801Z	2c2b974	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-review reviewed 2c2b974efbed3209077339bace876af9da814578: 0 finding(s), 0 as inline comments.

No findings on this pull request.

What I read. The pull request is 112 files. 109 are pure renames of 38 contract folders from docs/conventions/<name>/ to docs/contracts/<name>/. The other three are edits to .lycheeignore, scripts/affected-tests-no-suite.txt and scripts/em-dash-purged-paths.txt. I read all three edits in full. I had no shell, so I ran no tests or link checks. The verification in the description (lychee, check-affected.sh, the shell, node and Python suites) is author-claimed and unverified by me.

Checks on the edits.

• scripts/em-dash-purged-paths.txt: the 25 repointed globs (docs/conventions/<n>/*.md to docs/contracts/<n>/*.md) name the moved folders, including commit-convention, loop-lane and pr-body-convention. Folders that did not move are left alone.
• .lycheeignore: both new entries are marked TEMPORARY (#7537) and name the change that removes them. The first entry covers the old docs/conventions/ paths of all 48 contract folders. The second covers docs/contracts/ targets that dangle until the later layers land. The second names pr-pipeline and review-digest.md because relative links inside the moved folders point at them.
• scripts/affected-tests-no-suite.txt: adding .lycheeignore is consistent with it being a config file with no test suite.

Not reviewed.

• The head file is not visible in this lane. I could not confirm that nothing outside the diff still reads the old paths. The description says part A (fix(contracts): resolve contract paths under docs/contracts #10942) and A2 (fix(harness-ops): count contracts under docs/contracts in surface discovery #10949) made readers try docs/contracts first.
• Skip gate: the description marks this as a draft. The wrapper owns that gate and the review ran anyway.
• Closing issues: the description says "Refs: docs: separate plugin-author contracts from consumer conventions in docs/conventions #7537", not closes. There is no closing-issue section, so there are no acceptance criteria to check.
• Manifests: the diff changes no plugin.json or marketplace.json, so no manifest lines apply.
• Embedded text: the description contains no instructions directed at this lane.

Spend. None. The change adds no billed resource and no paid setting.

[github-actions]

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

No security issues found.

I read the whole diff (.claude-lane/pr.diff) and the PR context.

• Renames: 109 of the 112 changed files are git mv renames, and all 109 show similarity index 100% with no content hunks. No file content changed, so no instruction text was deleted, narrowed or softened. The instruction-surface lens finds nothing to report.
• Trusted paths: no changed file matches a trusted-path glob in a way that changes a control. docs/conventions/pr-pipeline.yaml, docs/conventions/untrusted-content/**, docs/conventions/instruction-exception-register/** and docs/standards/** are not in the diff. The register, untrusted-content and standards/ folders stay at their old paths in this layer. Their entries in scripts/em-dash-purged-paths.txt still point to docs/conventions/. The trusted-actor list, CODEOWNERS, workflows and the broker actions are untouched. I found no widening of who is trusted, token scope, the kill switch or a merge hold.
• Plugin manifests: no plugin.json or marketplace.json is changed, so there are no manifest flags.
• scripts/em-dash-purged-paths.txt: it only repoints globs for the moved folders, and the folders staying put keep their old globs. This is a docs-lint scope list, not a security control.
• scripts/affected-tests-no-suite.txt: it adds .lycheeignore, so a change to that file no longer selects a test suite. This only affects test selection and gates nothing security-related.
• .lycheeignore: it adds two temporary link-check ignore patterns for file:// links into the old and new contract folders. They only skip a docs link check. The PR says the stubs and reference-rewrite layers remove them.
• Reader fallback: the PR relies on earlier changes (fix(contracts): resolve contract paths under docs/contracts #10942, fix(harness-ops): count contracts under docs/contracts in surface discovery #10949) making contract readers try docs/contracts first. That is outside this diff, and I did not audit it.

Spend: the change adds no billed resources and no extra lane runs.

critical-findings: 0