Skip to content

docs: reconcile CLAUDE.md and README to v0.2.0 + Unreleased reality#16

Merged
jasperboerhof merged 1 commit into
mainfrom
engineer/doc-edit-bundle
May 12, 2026
Merged

docs: reconcile CLAUDE.md and README to v0.2.0 + Unreleased reality#16
jasperboerhof merged 1 commit into
mainfrom
engineer/doc-edit-bundle

Conversation

@Goosterhof
Copy link
Copy Markdown
Contributor

@Goosterhof Goosterhof commented May 6, 2026

Summary

Doc-only reconciliation against shipped reality. Scope reduced from the original PR after rebase: PR #21 (publish-channel framing) and PR #20 (rules-table addition for EnforceResourceDataValidatorOptInRule) absorbed earlier scope items from main. This PR now ships only the still-valid edits.

CLAUDE.md (four edits):

  • Rules table — extend LogRule identifier note with the static-call shapes (Model::destroy() / Model::forceDestroy()) shipped via [Unreleased] v0.3.0.
  • Commands table — extend from 4 rows to all 8 composer scripts (adds test:coverage, coverage:check, mutation, mutation:ci).
  • Versioning section — surface the 0.x caret-semantics trap explicitly: under Composer, ^0.1.0 does NOT auto-pull v0.2.0 (caret locks at minor in 0.x). Document today's ^0.{minor} pin convention and the 1.0 transition.
  • New ## War Room ADR Projections section per ADR-0015 — most cross-project ADRs project as Non-applicable here because the package distributes their enforcement rather than consuming it. Includes ADR-0009 entry noting that the new EnforceResourceDataValidatorOptInRule (Phase 2, [Unreleased]) distributes ADR-0009 enforcement.

README.md (two edits):

  • Rules table — add row for EnforceAuditSnapshotOnRetryRule (shipped v0.2.0; was already in CHANGELOG / extension.neon / CLAUDE.md but missing from README — PR engineer: add EnforceResourceDataValidatorOptInRule (queue #55 Phase-2 promotion) #20 added the EnforceResourceDataValidatorOptIn row but did not backfill the EnforceAuditSnapshotOnRetry gap).
  • L83 versioning narrative — replace "Pin to a major version (^1.0)" with today's ^0.2 guidance; cross-link CLAUDE.md § Versioning for the 0.x caret-semantics rationale.

Operational urgency: consumer territories pinning ^0.1.x against a v0.2.0 package are stuck pre-v0.2.0 because of the caret-semantics trap. This PR documents the trap so consumers know to bump pins on each minor.

Scope dropped (already on main)

Originally this PR included these edits — main has since absorbed them via other PRs and they have been dropped from this rebase:

Sources

  • Adjutant first-contact field report: reports/phpstan-warroom-rules/field/2026-05-06-adjutant-first-contact.md (findings F-ADJ-01..06).
  • Cartographer first-contact field report: reports/phpstan-warroom-rules/field/2026-05-06-cartographer-first-contact.md (README rules-table drift finding).
  • Campaign report: campaigns/phpstan-warroom-rules/2026-05-06-first-contact-wave.md.

Verification

All gates green locally on rebased PR head:

  • composer phpstan[OK] No errors
  • composer format:check{"result":"passed"}
  • composer test → 43/43 (74 assertions)

Diff scope: only CLAUDE.md (+41/-2) and README.md (+2/-1) modified. CHANGELOG anchor references unchanged.

Test plan

  • CI green on check (8.4) and check (8.5).
  • One reviewer approval per the branch protection rules that just landed.
  • Spot-check that the rendered Versioning section explains why ^0.1.0 doesn't auto-pull v0.2.0.
  • Spot-check that the rendered Rules table on README now lists 6 rules (including EnforceAuditSnapshotOnRetryRule).

jasperboerhof
jasperboerhof previously approved these changes May 7, 2026
CLAUDE.md
- Rules table: extend LogRule identifier note with the static-call
  shapes (Model::destroy / Model::forceDestroy) shipped via [Unreleased]
  v0.3.0.
- Commands table: extend from 4 rows to all 8 composer scripts
  (test:coverage, coverage:check, mutation, mutation:ci added).
- Versioning section: surface the 0.x caret-semantics trap explicitly —
  Composer's `^0.x` caret locks at minor, so v0.2.0 does not propagate
  to consumers pinned `^0.1.0`. Document today's `^0.{minor}` pin
  convention and the 1.0 transition.
- Add ## War Room ADR Projections section per ADR-0015 (most cross-
  project ADRs project as Non-applicable — the package distributes
  enforcement of those ADRs rather than consuming them).

README.md
- Rules table: add EnforceAuditSnapshotOnRetryRule row (shipped v0.2.0
  in CHANGELOG / extension.neon / CLAUDE.md but missing from README
  through PR #20's rule addition).
- Versioning narrative: replace `^1.0` pin guidance with today's `^0.2`;
  cross-link CLAUDE.md § Versioning for the 0.x caret-semantics
  rationale.

Sources: Adjutant first-contact F-ADJ-01..06; Cartographer first-contact
README rules-table drift finding. PR #21 (publish-channel framing) and
PR #20 (EnforceResourceDataValidatorOptInRule rules-table addition)
already absorbed earlier scope items from this PR — this commit only
applies the still-valid edits.
@jasperboerhof jasperboerhof merged commit 48a138c into main May 12, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants