feat: ship the retired-conventions mechanism (Phase 2b) - #3597
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f7aec1549d
ℹ️ 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".
f7aec15 to
f3d0a22
Compare
d03621c to
0f63e34
Compare
Implements the approved hybrid (unanimous blind tournament + user approval; ADR 0018): - plugins/claude-config/lib/check-retirements.sh (+174-check test suite): manifest-driven detection and gated cleanup of retired consumer conventions. TSV findings, exit 0/1/2, CRLF-safe matching, --clean with the migrate --i-migrated gate, content_match reused-path guard at clean time too. - retirements.yaml schema validation wired into scripts/validate-plugin-contracts.mjs: flat-YAML-subset parser, field and enum rules, append-only vs VALIDATE_CONTRACTS_BASE_REF (legal edits: status flip, note/successor defect fix), bidirectional wiring (manifest <-> synced helper copy + setup reference), and one eval per retirement record as a validator failure. Fixture coverage in the test harness; real corpus stays green. - scripts/sync-check-retirements.sh + registry entry (commented until the first carrier lands in Phase 2c, per the drift checker's stale rule) + check-retirements-sync CI job; affected-tests now supports canonical-only sync clusters. - docs/conventions/retired-conventions/ (contract 1.0): schema, helper contract, the two fixed setup lines, demotion rule, eval-per-record, fleet sweep, deferred CI aggregate with revive trigger. Registry rows for retired-conventions and plugin-reconfiguration. - claude-config audit-pass gains the runtime fleet-sweep lane over installed plugins' retirements.yaml (read-only, never cleans). - plugins/claude-config/lib/resolve-convention-home.sh (+61-check test suite): the AGENTS.md pointer-line resolver per config-cascade's expression doctrine; untrusted-input hardened. Gates: helper 174/174, resolver 61/61, validator suite all green, real tree validates, shellcheck clean, markdownlint clean, catalog ok. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014uBXt1tMEReShbpG5gsFUd Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
… newline) - git index exec bits set on the five new shell scripts (exit 126 in check-retirements-sync and the hygiene chmod finding). - validate-plugin-contracts.test.sh clears GIT_DIR/GIT_WORK_TREE/ GIT_CONFIG before building git fixtures (fixture-git-isolation-gate). - audit-pass SKILL.md trimmed back under the 500-line hard cap (the sweep-lane bullet and carve-out compress; detail lives in the spoke). - typos-format manifest final newline restored (bump-edit artifact, hygiene editorconfig check). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014uBXt1tMEReShbpG5gsFUd
generic-api-key treats CLAUDE_SHIM=0 as the secret because the preceding CLAUDE_TOKEN="" line supplies keyword context. Both inits are parser state, not credentials. Inline gitleaks:allow per .gitleaks.toml policy (issues 3610/3599). Historical fingerprints stay in .gitleaksignore; this annotation covers the working tree and later commits. Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
3315cbc to
26502c9
Compare
|
Claude finished @cursor[bot]'s task in 2m 48s —— View job Code reviewTodo list
SummaryReviewed the full diff ( Codex's five findings all check out — verified each against the actual code, all real:
One new finding, posted inline: validate-plugin-contracts.mjs:643 has the same parity bug as the line-636 finding above but for single-quoted values — Everything else reviewed clean:
No security-relevant findings beyond the file-cleanup containment gap already covered above (this lane is scoped to correctness/maintainability; a security-review lane would be the place for a deeper look at that gap's severity). |
|
Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
File and line --clean now re-resolve the parent with pwd -P and refuse a target that lands outside --root, matching the dir branch. The contract parser matches the helper's exact --- separator, quote-stripping, path grammar, and complete retirement-id eval coverage. Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
|
Claude finished @cursor[bot]'s task in 2m 49s —— View job Code reviewTodo list
SummaryThis run was triggered by the All six previously-reported findings are fixed, and each got a regression test:
I traced No new issues found in this delta, and nothing else in the PR changed since the last review round. I wasn't able to execute the shell/Node test suites directly in this sandbox (commands beyond trivial ones required approval that wasn't available), so this verification is from reading the diff and cross-referencing runtime vs. validator logic, not from running No inline comments posted this round — there's nothing new to anchor; the prior round's inline findings are now resolved by |
…ce line editorconfig rejects trailing whitespace in the test file. The --- plus space record break is now printf'd so the fixture still exercises the helper grammar without failing the hygiene lane. Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
|
Claude finished @cursor[bot]'s task in 1m 29s —— View job Code reviewTodo list
SummaryThis run was triggered by That commit touches only I traced this against I wasn't able to execute the shell/Node test suites directly in this sandbox (commands beyond trivial ones required approval that wasn't available in this run), so this verification is from reading the diff and tracing the stdin plumbing by hand, not from running No inline comments posted this round — nothing new to anchor. All prior findings from the two earlier review rounds remain fixed and unaffected by this commit. |
…ment check The Phase 2c copy was written against pre-2b helper bytes. After #3597 the canonical file refuses a symlink parent on file and line --clean; the carrier copy must stay byte-identical. Also mark the new sync script executable. Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
…ne the rest (Phase 2c) (#3601) Closes #3600 ## Summary Phase 2c of the customization-consistency program: convert the one schema-expressible bespoke retirement (source-control's neutral-SSOT migration) to the retirements.yaml mechanism Phase 2b shipped, dedupe the context-guard/rate-limit-guard twin legacy-statusline detection through the cross-plugin sync registry, and stamp every remaining bespoke migration with its reason class. **Stacked on the Phase 2b PR (#3597)**; retarget as the stack merges. ## Fix - **source-control** ships its first retirement manifest. Record `source-control-r001` detects the redundant `## convention_source` pointer naming the well-known default path (`docs/conventions/source-control/commit-convention.yml`), retired when the V2 well-known-path migration (#1185, v0.25.0) made rung 2 resolve that file pointer-free. Wiring per the owner doc: synced `lib/check-retirements.sh`, the two fixed setup lines in `check`/`apply`, one eval per record id, the registry uncomment, and the Implementers row. The shadowed-markdown WARN stays live prose with an explicit rationale: it is conditional on resolver state (a neutral file resolving *and* carrying the key), which the repo-scope presence schema cannot express, and markdown-H2 alone is still the sanctioned rung 3 — an append-only record that knowingly over-fires must not ship. - **Twin dedup** (ADR 0018, decision 6): the guards' shim-revision ladder and legacy version-pinned wiring detection now live in one byte-identical spoke, `skills/setup/reference/legacy-statusline-detect.md` (context-guard canonical), with `scripts/sync-legacy-statusline-detect.sh`, a registry entry, and the `legacy-statusline-detect-sync` CI lane in `ci-status.needs`. - **Rationale lines**: context-guard, rate-limit-guard, machine-health (machine-scope surface, outside the repo-scope schema per ADR 0018), work-items (forge-label backfill), guardrails (hook provisioning), planning and review (versioned-contract upgrade under `apply`) each state in one sentence why their migration logic stays bespoke. - Eight plugins patch-bumped with CHANGELOG entries (source-control 0.55.16, context-guard 0.7.22, rate-limit-guard 0.7.13, machine-health 0.11.5, work-items 0.39.25, guardrails 0.29.14, planning 0.34.7, review 0.26.9). ## Verification - `VALIDATE_CONTRACTS_BASE_REF=origin/main node scripts/validate-plugin-contracts.mjs` — green (1 retirement manifest: schema, append-only, helper byte-identity, setup reference, eval coverage). - Fixture-repo run of the helper: detect emits the `source-control-r001` row (exit 1); `--clean` without `--i-migrated` refuses (exit 2); `--clean --i-migrated` removes exactly the pointer line (exit 0); re-detect clean (exit 0). - `sync-check-retirements.sh` and `sync-legacy-statusline-detect.sh` `--check` / `--check-bump origin/main`, `check-cross-plugin-source-drift.sh --check`, `check-lane-coverage.sh --check` (46 lanes) — all green. - markdownlint clean on all touched markdown; shellcheck clean on the new sync script; catalog and cheatsheet checks in sync. - PLAN.md 2c Sanity Check: `grep -n "shim-revision\|legacy" plugins/source-control/skills/setup/SKILL.md` — zero hits; per skipped plugin the rationale line exists. ## Related Refs #3596 (mechanism), PR #3597, ADR 0018 (decisions 4 and 6), `docs/conventions/retired-conventions/README.md`, `docs/MIGRATION-PLAYBOOK.md` § Retired conventions. --------- Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com>
…#3620) Closes #3619 ## Summary Phase 2d PILOT of the customization-consistency program (ADR 0018): migrates plugin-quality's team-shared config surface from the dedicated `.claude/plugin-quality.md` three-layer cascade to a convention doc at the consumer's convention home (`<home>/plugin-quality/README.md`), bound by the pointer line and resolved by the shared resolver. First plugin to ship `retirements.yaml` alongside source-control's (records `plugin-quality-r001` migrate, `plugin-quality-r002` overlay delete), enrolling the check-retirements sync cluster and creating the resolve-convention-home cluster (sync script, registry entry, CI job). **Stacked on the Phase 2b PR (#3597)**; expect a trivial registry/ci.yml merge with the 2c PR (#3601) whichever lands second. ## Fix Reading side: audit resolves home → topic doc → dual-read (retired file is authority while present, WARN every run) → defaults; retired user-global/overlay layers read nowhere, WARN-visible. Setup: `check` reports the four resolver outcomes distinctly (exit 1 = INFO unconfigured, exit 3 causes = FAIL ask-don't-infer) plus the two fixed retirement lines; `apply` binds the home on operator confirmation only (marked-region append, never outside it), converges the topic doc (the old file's values are the migration source), then per-record gated cleanup. config-cascade and retired-conventions Implementers rows rewritten in the same PR per the doctrine's row rule. Bumps: plugin-quality 0.6.11, claude-config 0.40.5. ## Verification Deterministic consumer-repo sim (`scripts/pilot-plugin-quality-sim.test.sh`, 23 assertions, wired into the new resolve-convention-home-sync CI job): populated-AGENTS.md region append leaves prose byte-identical; resolver exit codes; exact detection TSV for both records; migrate-gate refusal without `--i-migrated`; clean + re-detect clean; CRLF root file. Validator (append-only + wiring + eval-per-record) green against origin/main; both sync clusters `--check`/`--check-bump` green; drift check green; resolver 61/61 and helper 174/174; markdownlint, shellcheck, eval lint, lane coverage, catalog/cheatsheet green; skill-quality PASS on both touched skills (audit SKILL.md trimmed back under the 500-line cap). ## Related Refs #3596/#3597 (mechanism), #3600/#3601 (2c), ADR 0018, config-cascade § Expression doctrine, retired-conventions convention. **POST-PILOT USER GATE:** this pilot is the template the user reviews before any other surface migrates — in particular seven flagged doctrine calls (overlay delete-not-migrate; no content_match on r002; WARN routed through the r002 record in setup while user-global stays prose-only; audit-side resolver exit-3 report-and-continue; dual-read eval living audit-side; records stamped with the shipping version; the gitignore-overlay recommendation dropped from the migrated surface). No other surface migrates until ratified. Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
Closes #3596
Summary
Phase 2b of the customization-consistency program: the approved retired-conventions mechanism (ADR 0018; unanimous blind tournament + hybrid amendments) — per-plugin append-only
retirements.yaml, one shared deterministic helper, CI schema/wiring/eval enforcement, the owner doc with the two fixed setup lines, an audit-pass fleet-sweep lane, and the pointer-line resolver. No plugin ships a manifest yet; Phase 2c lands the first carrier (source-control).Stacked on the Phase 1d PR (#3585) with the 2a branch merged in; retarget as the stack merges.
Fix
plugins/claude-config/lib/check-retirements.sh(+ 174-check.test.sh): detection (file/dir/line,content_matchreused-path guard, CRLF-safe), TSV findingsid/kind/path/action/status/note, exit 0/1/2 (invalid record fails the whole run loudly),--clean <id>with the migrate--i-migratedgate and Windows-lock exit-2 re-run rule.scripts/validate-plugin-contracts.mjs(+ fixtures in its test harness): flat-YAML-subset parser, field/enum/path rules, append-only vsVALIDATE_CONTRACTS_BASE_REF(legal edits: status flip, note/successor defect fix; whole-manifest deletion caught viagit ls-tree), manifest ⇔ synced-helper ⇔ setup-reference bidirectional wiring, one eval per record id as a validator FAILURE.scripts/sync-check-retirements.sh+ registry entry (commented until the first carrier, per the drift checker's <2-plugin stale rule) +check-retirements-syncCI job;affected-testsnow supports canonical-only clusters.docs/conventions/retired-conventions/(contract 1.0): schema, helper contract, the two fixed setup lines, demotion rule, eval-per-record, fleet sweep, dual-read window bounds, deferred CI aggregate with revive trigger. Convention-registry rows added for retired-conventions and plugin-reconfiguration.plugins/claude-configaudit-pass: runtime fleet-sweep lane over installed plugins' manifests (read-only; declared carve-out on the hub's never-reads-another-plugin rule for this published data seam) +reference/retired-conventions-sweep.mdspoke.plugins/claude-config/lib/resolve-convention-home.sh(+ 61-check.test.sh): AGENTS.md-canonical pointer-line resolver per config-cascade's expression doctrine (exit 0 resolved / 1 no pointer / 2 usage / 3 FAIL with distinct causes; pure-shim CLAUDE.md skipped; untrusted-input hardened, no eval, CR stripped, line cap).Verification
check-retirements.sh --helpexits 0; its test suite 174/174;validate-plugin-contracts.test.shall assertions passed (incl. malformed-fixture red cases); registry line present (commented, annotated);test -f docs/conventions/retired-conventions/README.mdholds.node scripts/validate-plugin-contracts.mjsgreen (51 setup skills, 0 manifests, 2951 files).retirements.yaml/check-retirementsconsumers before this change: zero (new contract).Related
Refs ADR 0018,
docs/topics/customization-consistency/PLAN.mdPhase 2b, tournament recorddesign/mechanism-validation.md, PRs #3582 #3583 #3584 #3585 #3587. Phase 2c uncomments the registry line with the first carrier.