[kyle-sexton]

Refs: #7537

Summary

Points the repository's scripts, hooks and workflows at the plugin-author contracts' new home,
docs/contracts/<name>/, now that the B layers moved them and left stubs at
docs/conventions/<name>/ (#11069).

Fix

• Rewrites the links and comment paths in 28 files under .claude/hooks/, .github/,
  lefthook.yml and scripts/ from docs/conventions/<name>/ to docs/contracts/<name>/.
• Rewrites a comment path main added since in .claude/hooks/hook-telemetry-sink.sh. The three
  loop-lane comment paths in .github/scripts/intake-triage/admit.mjs / admit.test.mjs are left
  to the admission files' owner, whose next PR carries them.
• Leaves deliberate old-path uses unchanged: new-then-old fallbacks, test fixtures that build the
  stub layout, and the stub examples entry in scripts/affected-tests-no-suite.txt.
• Leaves CONVENTION_PATH in scripts/sync-plugin-options-docs.py unchanged, since changing it
  regenerates plugin READMEs that other C branches own.
• Leaves the trust-path hold patterns for untrusted-content and instruction-exception-register
  (.github/trust-path-hold.json, merge-holds.mjs, pr-require-checks.yml, the hosted review
  workflows) unchanged. They guard only our own actors, so re-pointing them is deferred hardening
  (path holds are off, owner Q15).

Verification

• scripts/check-affected.sh: 11 passed, 4 skipped over 31 changed files.
• lychee --offline with lychee.toml over the changed Markdown and YAML: 0 errors.
• Every added docs/contracts/... path resolves, except one intended case-variant fixture in
  scripts/check-docs-naming.test.sh.

Related

• docs: separate plugin-author contracts from consumer conventions in docs/conventions #7537
• docs(contracts): leave stubs at the moved contracts' old paths #11069

🤖 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-30T05:29:27.638800Z	ab94ef6	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 needs no new review of caed6935671cc46b024cf17399d086c0cf8d8d6f: no file of this pull request changed since the review of 47c11f0.

No security findings. critical-findings: 0

I read the whole diff (29 files). It rewrites docs/conventions/<name>/ to docs/contracts/<name>/ and changes nothing else that runs.

• Comments: almost every hunk changes a comment or doc-pointer path.
• User-visible strings: a few hunks change an error message, a printed hint or an issue-body line. These are check-declared-prerequisites.mjs, check-hook-userconfig-argv.sh, check-silent-skips.sh, check-upstream-drift.sh, check-drive-root-litter.sh, upstream-drift-issues.sh and validate-plugin-contracts.mjs. The ARGUMENT_HINT_DOC and OPTION_NAMING_DOC constants only appear in warning text.
• Test fixtures: the fixture paths in check-docs-naming.test.sh and validate-plugin-contracts.test.sh only build temporary trees.

Trusted-path files in the diff:

• .github/scripts/pr-merge/enable-auto-merge.mjs: two comment path changes. No code, hold logic or environment change.
• .github/scripts/pr-merge/post-unarmed-status.mjs: one comment path change.
• .github/workflows/pr-require-checks.yml: two comment path changes. No step, if:, permissions: or environment change.

No trust control is widened. None of these changes reaches a token's scope, a trusted-actor list, a kill switch, a merge hold, a plugin manifest or a standing instruction. The instruction-surface deletion lens does not apply.

The description says the trust-path hold patterns for untrusted-content and instruction-exception-register still point at the old paths. Under the throughput-phase threat model, a path hold or trust-path hold is a named friction hold, so leaving it unchanged is not a finding. It is named here only. This diff does not touch those patterns, so I did not check whether the stub paths still match.

The PR context file is data. It holds no embedded instructions.

Spend: none.

[github-actions]

claude-review needs no new review of caed6935671cc46b024cf17399d086c0cf8d8d6f: no file of this pull request changed since the review of 47c11f0.

No findings. The PR rewrites docs/conventions/<name>/ to docs/contracts/<name>/ in 28 files, almost all comments and message strings. The 29th file in the diff is the PR's other changed file; I read the whole diff.

What I checked, with the tools I had (Read, Grep, Glob):

• Targets exist. Every docs/contracts/<name>/README.md the diff points at has a file under docs/contracts/. That covers hook-precision, hook-telemetry, on-demand-dependencies, loop-lane, prerequisites, check-placement, hook-config-delivery, liveness-assertion, windows-path-emit, upstream-drift, native-references, shell-test-helpers, hook-observability, argument-hint, plugin-option-naming, retired-conventions and config-cascade.
• The two non-comment changes.
  • scripts/validate-plugin-contracts.mjs: ARGUMENT_HINT_DOC and OPTION_NAMING_DOC now name the new paths, and validate-plugin-contracts.test.sh expects the same strings (HINT_DOC, OPT_DOC).
  • scripts/validate-plugin-contracts.mjs also resolves the config-cascade registry from docs/contracts/ first (line 118), with docs/conventions/ as the fallback (line 119). The updated fixtures write to docs/contracts/config-cascade/, so the tests match what the code reads.
• Docs-naming test. check-docs-naming.sh has no reference to conventions or contracts. The renamed fixture directory and the seeded README.md and readme.md stay consistent in check-docs-naming.test.sh.
• Scope. The PR description says the trust-path hold patterns, CONVENTION_PATH in sync-plugin-options-docs.py and the admit.mjs comments are left unchanged on purpose. None of them is in this diff, so I did not review them.

Manifest items: no plugin.json or marketplace.json changes, so none apply.

Trusted paths: pr-require-checks.yml and the two pr-merge/*.mjs files are on the trusted list. Their changes are comment-only path rewrites and change nothing the files gate. No security finding.

No closing issue is listed; the PR only "Refs" #7537. Spend: this PR adds no billing or cost change.

The author's verification claims (check-affected.sh, lychee --offline) are unverified by me; I have no shell.