DavidHLP · DavidHLP · Sep 18, 2026 · Sep 18, 2026
@@ -1,7 +1,6 @@
 <!--
-  Thanks for the PR! This checklist mirrors CONTRIBUTING.md "Pull request
-  checklist" so it surfaces at PR-creation time. See CONTRIBUTING.md for the
-  full contributor guide and the "Architecture pointers" table.
+  Keep this checklist aligned with CONTRIBUTING.md and docs/README.md.
+  Current-state documentation has one canonical owner per topic.
 -->
 
 ## Summary
@@ -10,21 +9,28 @@
 
 ## Checklist
 
-- [ ] `./mvnw clean verify -B` passes locally (coverage gate).
-- [ ] `./mvnw checkstyle:check -B` passes locally.
+- [ ] `./mvnw clean verify -B` passes locally when source/build behavior changed (coverage gate).
+- [ ] `./mvnw checkstyle:check -B` passes when Java source changed.
 - [ ] New behavior has tests; bug fixes have a regression test.
-- [ ] Integration tests touching Redis extend `AbstractRedisIntegrationTest` (Testcontainers — Docker must be running).
+- [ ] Redis integration tests use `AbstractRedisIntegrationTest`; Cluster tests use `AbstractRedisClusterIntegrationTest` (Testcontainers — Docker must be running).
 - [ ] `bash scripts/ci/check-test-names.sh` passes; integration classes do not use `*IT.java`.
-- [ ] No over-engineering: features that belong in [Resilience4j](https://resilience4j.readthedocs.io/) (circuit breaking / rate limiting) or [Caffeine](https://github.com/ben-manes/caffeine) (multi-level caching) are **out of scope** — see README "Not in Scope".
-- [ ] Javadoc on public API; Chinese rationale comments are welcome for design decisions (matching the existing codebase style).
+- [ ] `bash scripts/ci/check-docs-contracts.sh` passes when docs, source references, or public contracts changed.
+- [ ] Documentation changes update the canonical owner in [`docs/README.md`](../docs/README.md); no task/date/session document was added as current-state policy.
+- [ ] Public API/configuration/wire changes are checked against [`STABILITY.md`](../STABILITY.md) and [`COMPATIBILITY.md`](../COMPATIBILITY.md).
+- [ ] No over-engineering: features that belong in [Resilience4j](https://resilience4j.readthedocs.io/) (circuit breaking / rate limiting) or [Caffeine](https://github.com/ben-manes/caffeine) (multi-level caching) are out of scope unless the product boundary changes explicitly.
+- [ ] Javadoc on public API; Chinese rationale comments are welcome for design decisions matching the existing codebase style.
 - [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `ci:`, `chore:`.
 
 ## Backward compatibility
 
 <!--
   If this changes default behavior, annotation signatures, resi-cache.*
-  property keys, or the {version,payload} wire format, check STABILITY.md and
-  describe the impact here. Pre-1.0 changes to internals/defaults/metric
-  namespace are allowed but must be noted in CHANGELOG.md (⚠️ BREAKING if
-  user-visible default behavior changes).
+  property keys, or the {version,payload} wire format, describe the impact and
+  update the canonical contract/history source rather than copying a second
+  rule into this PR. Pre-1.0 changes to internals, defaults, or metric
+  namespaces must be recorded in CHANGELOG.md; use a ⚠️ marker for
+  user-visible default behavior changes.
 -->
+
+- [ ] Compatibility impact is described, or this change is documentation/internal-only.
+- [ ] Any pre-1.0 internal/default/metric-namespace change is recorded in [`CHANGELOG.md`](../CHANGELOG.md), with a `⚠️` marker when user-visible.
@@ -39,8 +39,8 @@
 !SECURITY.md
 !PERFORMANCE.md
 !docs/
-!docs/adr/
-
+docs/adr/
+docs/plans/
 # --- 项目配置 ---
 !.editorconfig
 !.cbmignore

@@ -1,10 +1,17 @@
 # Agent Project Instructions
 
 Project conventions live in [CLAUDE.md](./CLAUDE.md), including the
-task-scoped agent workflow. Read the relevant sections for the current task;
-linked documents are references, not a mandatory reading checklist.
+project-scoped workflow and verification commands. Read the relevant sections;
+linked documents are pointers, not a requirement to load the whole repository.
 
-Keep shared project instructions in `CLAUDE.md` and this file as the entry point.
+For documentation or architecture work, start with
+[`docs/README.md`](docs/README.md), then read only the task-relevant core page.
+Keep one canonical owner per topic. Verify current behavior against source,
+configuration, tests, and scripts before changing prose.
+
+Keep shared agent instructions in `CLAUDE.md` and this file as the entry point.
+Do not turn task logs, dated summaries, generated reports, or ignored local
+status files into permanent current-state documentation.
 
 For documentation maintenance, verify commands and versions against `pom.xml`
 and the relevant CI scripts. Preserve existing local edits and update the

@@ -5,13 +5,13 @@ All notable changes to ResiCache are documented here. Format follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) with the
 pre-1.0 caveat below.
 
-## Pre-1.0 caveat
+While the version is `0.x`, behavior and APIs outside the surfaces explicitly
+covered by [`STABILITY.md`](./STABILITY.md) may change in any release,
+including patch releases. Breaking changes are marked with ⚠️ in this
+changelog. The stable 0.x surfaces and their exceptions are defined by
+`STABILITY.md`; do not use this general pre-1.0 caveat to override that
+contract.
 
-While the version is `0.x`, **APIs may change in any release — including
-patch releases.** Breaking changes are marked with ⚠️ in this changelog.
-API stability is only guaranteed from `1.0.0` onward; see
-[`STABILITY.md`](./STABILITY.md) for the contract that defines which
-surfaces are stable in 0.x and which change.
 > No local `v1.0` release tag is treated as an API-stability baseline here.
 > Maven Central publishes `io.github.davidhlp:ResiCache` 0.0.1–0.0.5, 0.0.7,
 > and 3.2.4, but every version (verified 2026-09-05 from the published
@@ -66,9 +66,10 @@ Current milestones:
   `resi-cache.sync-lock.local-only=true` for explicit single-instance
   degradation.
 - ⚠️ **Bloom CLEAN semantics** — ordinary cache eviction no longer clears the
-   Bloom filter or relies on a rebuilding marker/TTL window. Bloom bits describe
-   possible data-source membership, so retained bits can only create
-   false-positives; valid loader calls are not blocked by false-negatives.
+  Bloom filter or relies on a rebuilding marker/TTL window. Bloom bits describe
+  possible data-source membership: false-positives are safe, but a missing
+  membership bit can short-circuit Redis lookup and loader execution. Seed or
+  maintain membership before enabling it for an existing data set.
 - ⚠️ **Read-through is availability-first** — `get(key, loader)` (default and
    sync paths) always returns a successful loader value; a cache write-back
    failure after a successful load is logged (redacted, no raw key) and never
@@ -102,21 +103,21 @@ Current milestones:
   same put metrics as the sync path. Failing write-backs are still logged
   redacted and never override the loaded value.
 - **Key privacy in failure diagnostics** — WARN/ERROR logs and typed exception
-  messages omit the raw key (ADR-0001 §15); where no `cacheName` is available
+  messages omit the raw key; where no `cacheName` is available
   they carry `FailureDiagnostics.keyFingerprint` instead. Covers distributed
   lock acquire/release, `SyncRole` leader/follower failures, the async
   early-expiration retry path, chain post-processing, and the migration
   engine's fingerprint helper (now one implementation).
 - **Redacted diagnostics at every failure site** — the chain’s observer dispatch and
   all six Bloom failure paths now render only the exception type chain at WARN/ERROR
   (`FailureDiagnostics.sanitizedFailure`) and keep the full stack at DEBUG, closing the
-  remaining ADR-0001 §15 gaps. Fail-open behavior and the Bloom failure counters are
+  remaining key-privacy gaps. Fail-open behavior and the Bloom failure counters are
   unchanged.
 - **Sync early-expiration answers with a miss** — a synchronous early-expiration
   skip (`EarlyExpirationMode.SYNC`) now returns `CacheResult.miss()` through the
   chain instead of a null-byte `success`: `EarlyExpirationHandler` advances to
   `ActualCacheHandler`, which consumes the documented `PrefetchDecision` and
-  answers the miss its Javadoc and ADR-0001 §22 describe. Writer and Spring
+  answers the miss its Javadoc and current handler contract describe. Writer and Spring
   behavior is unchanged (null bytes, miss statistics, loader refresh); chain
   observers and SPI callers now receive `Outcome.MISS`.
 - ⚠️ **`@RedisCachePut` metadata now resolves** — the chain used to read only
@@ -150,7 +151,7 @@ Current milestones:
   one evaluation, publishes the typed `PrefetchDecision` (so the value the
   decision read is reused instead of fetched twice) and maps the outcome to
   `SKIP_ALL`/`CONTINUE`. The executor, retry policy and cancellation seam are
-  unchanged (ADR-0001 §11).
+  unchanged (see [`STABILITY.md`](./STABILITY.md)).
 - **Nested chain advancement is explicit (SPI addition, compatible)** —
   `CacheHandler` gains `default HandlerResult handle(CacheContext,
   ChainContinuation next)`; the default ignores `next` and delegates to