docs(contracts): land update-principles meta-contract from operator exemplar

Codifies five properties every commit must demonstrate: single concern,
drift-blocking test, sibling-pattern citation, fitness delta, clean
branch point. Source exemplar: commit 1b9d139c (cherry-picked to main
as f62295f7); the supergate compile-health SKIP fix demonstrated the
shape and this contract names what made it a teaching commit.

The five principles are the floor, not the ceiling. Each principle's
mechanical enforcer (single-concern lint, drift-test detector, sibling-
citation regex, fitness-delta regex, branch-point check) ships as its
own commit per BC3 epic — itself an application of principle 1.

Matches the existing factory-claim-ledger / finding-registry contract
shape: top-level heading, frontmatter consumers list, body > 200 chars,
catalogued in docs/documentation-index.md. Structural-floor gate
auto-validates on push.

Code-driven fitness: 39 → 40 contracts catalogued.

Cycle 52 / wave 1 of the 2026-05-12 rescope:
.agents/plans/2026-05-12-rescope-evolve-and-architecture.md

docs/contracts/update-principles.md

@@ -0,0 +1,99 @@
+# Update Principles Contract
+
+> **Status:** Draft
+> **Decision:** Every commit demonstrates five operator-exemplar properties or is rejected at review.
+> **Consumers:** every contributor; `scripts/check-update-principles.sh` (future); commit-review-gate hook.
+> **Source exemplar:** commit `1b9d139c` (operator-pushed to `nightly/2026-05-12`, cherry-picked to main as `f62295f7` on 2026-05-12).
+
+Source for these principles is observation, not abstraction. Cycles 44-51 demonstrated the inverse — text-only patches, multi-concern commits, no drift tests, narrative quality claims, dirty branch points — and produced 32 commits of red CI invisible to the operator. The exemplar commit `1b9d139c` demonstrated the inverse-inverse: a single 2-file change with 4 bats tests, sibling-pattern citation, and a measured fitness delta. The five principles below codify what made the exemplar a teaching moment.
+
+## The five principles
+
+Every commit MUST demonstrate ALL FIVE:
+
+### 1. Single concern
+
+One bug or feature per commit. If the commit message body has more than one bullet describing what changed at the code level, split the commit.
+
+**Counter-example (cycle 48):** "Fix 3 CI failures (markdownlint, supergate, registry)." Even though the failures were related (all surfaced by the same operator audit), they should have landed as three commits. Composite commits mask which fix caused which gate result.
+
+**Exemplar (`1b9d139c`):** "three-gap-supergate SKIPs compile-health on greenfield." One concern. One gate. One commit.
+
+### 2. Drift-blocking test included
+
+If the commit fixes behavior, a test in the same commit must fail when that behavior regresses. A one-shot operator probe (`AGENTS_DIR=/tmp/no-such-dir bash …`) is verification, not a drift-block. A bats test that runs on every push is.
+
+**Counter-example (cycle 48 supergate fix):** verified locally with one probe. No regression test. Subsequent cycles couldn't tell if the SKIP path still worked.
+
+**Exemplar (`1b9d139c`):** four bats tests covering all paths (greenfield SKIP, overnight PASS, canonical PASS, empty-tree SKIP). Any future change that breaks the SKIP semantic fires a CI failure.
+
+### 3. Sibling-pattern citation
+
+Every fix names the precedent it follows. New shapes need explicit rationale; copying an existing shape needs the citation to be explicit.
+
+**Counter-example (cycle 51 Step 1.5 healing-first classifier):** added as new text in SKILL.md with no reference to similar gating in other skills.
+
+**Exemplar (`1b9d139c`):** commit message says "matching the Gap 1 council-coverage SKIP shape." Reviewers can verify the pattern is reused, not reinvented.
+
+### 4. Fitness delta in the commit message
+
+Measured outcome, not narrated outcome. If the change can't be measured, it's suspect. The fitness delta is one or two numbers, paired (before → after).
+
+**Counter-example (cycle 46 PG4 promotion):** "promotes claim to PG4 strong-verify." No measurement. Was the claim previously verified by 0 gates, 1, 5? Reader cannot tell.
+
+**Exemplar (`1b9d139c`):** "Code-driven fitness: 134/139 → 139/139." Reader sees exactly what improved.
+
+Acceptable fitness delta forms:
+- Gate count: `N/M → M/M`
+- Test count: `X passing → X+Y passing`
+- Coverage: `A% → B%`
+- Bead count: `K open → K-N open`
+- Goals score: `S → S+1`
+- Any other numerical pair the change actually moves
+
+If the change is unmeasurable, that itself is a signal: it's either a structural change with no observable consequence (suspect) or a refactor that needs to be paired with a behavioral test (back to principle 2).
+
+### 5. Branched from a clean point
+
+Even a single-commit fix should not carry unrelated context. If main is red or noisy, branch from the most recent clean commit and apply the fix in isolation.
+
+**Counter-example (cycles 46-47 PG4 promotions):** shipped onto a CI-red branch (had been red for ~30 commits). The promotion evidence files cited gates that were running red at write time.
+
+**Exemplar (`1b9d139c`):** branched from `dcdb016b` (the commit immediately before the cycle 44 noise). The fix shipped on a clean base; readers see the change without unrelated cycle-44-51 noise.
+
+## Enforcement plan
+
+The five principles are voluntary until codified. Codification path:
+
+| Principle | Enforcer | Status |
+|---|---|---|
+| 1. Single concern | `scripts/check-single-concern.sh` reads commit diff, fails if > N files touched without explicit `[multi-concern]` tag | TODO (BC3 epic, separate cycle) |
+| 2. Drift-blocking test | commit-review-gate hook checks for added `*_test.go` / `*.bats` paired with modified `*.go` / `*.sh` | TODO (BC3 epic, separate cycle) |
+| 3. Sibling-pattern citation | lint commit body for `matching … pattern` / `sibling …` / `following the … shape` phrasing | TODO (BC3 epic, separate cycle) |
+| 4. Fitness delta | regex `/[0-9]+\/[0-9]+ → [0-9]+\/[0-9]+/` or similar numerical-pair pattern in commit body | TODO (BC3 epic, separate cycle) |
+| 5. Clean branch point | `git log --since` check on the commit's first-parent base — already partially enforced by `pre-push-gate.sh` worktree-disposition lane | partial |
+
+Each principle's enforcer ships as its own commit (each cycle demonstrates principle 1).
+
+## Sibling contracts and consumers
+
+- **Pattern follows:** existing contract shape in `docs/contracts/factory-claim-ledger.md`, `docs/contracts/finding-registry.md`, etc.
+- **Catalog entry:** `docs/documentation-index.md` (this contract is added there in the same commit).
+- **Validates against:** `scripts/check-contracts-structural-floor.sh` — minimum-bar gate that every contract has a top-level heading, frontmatter consumers list, and body ≥ 200 chars.
+- **Future strong-enforcement gates:** see the table above.
+
+## Anti-claim
+
+Not claiming these principles are exhaustive. The five are the minimum bar. Repo-specific principles (e.g., "every skill edit produces a hypotheses.jsonl entry," soc-z8rt.6 → BC3.3) layer on top, contract-by-contract. The five here are the floor.
+
+Not claiming the exemplar commit is the only valid shape. A bug fix can be one file (no bats if there's nothing to bats); a refactor can omit fitness delta if it's truly behavior-preserving (but then principle 2's drift-blocking test becomes mandatory to prove behavior preservation). The principles compose; they aren't a literal template.
+
+## Companion artifacts
+
+- Rescope plan: `.agents/plans/2026-05-12-rescope-evolve-and-architecture.md` (operator review pending; tracked outside `.agents/` once filed under bd epics).
+- Bounded-context inventory: `.agents/research/2026-05-12-bounded-contexts-and-ports.md`.
+- Source post-mortem: `.agents/post-mortems/2026-05-12-evolve-session-improvement-postmortem.md`.
+
+## Cycle log
+
+- 2026-05-12 cycle 52: contract written as the first concrete output of rescope Wave 1.

docs/documentation-index.md

@@ -260,6 +260,7 @@ Bridge / framing docs:
 - [Factory Claim Ledger Contract](contracts/factory-claim-ledger.md) — Public claim posture ledger mapping software-factory claims to evidence level, owner issue, closure gate, and safe wording
 - [Factory Claim Ledger Schema](contracts/factory-claim-ledger.schema.json) — Contract-local JSON Schema for claim-ledger rows and posture enums
 - [Factory Claim Ledger Example](contracts/factory-claim-ledger.example.json) — Current claim ledger fixture covering README, PRODUCT, GOALS, docs index, assurance, contracts, and comparison claims
+- [Update Principles Contract](contracts/update-principles.md) — Five operator-exemplar properties every commit must demonstrate (single concern, drift-blocking test, sibling citation, fitness delta, clean branch point); sourced from commit 1b9d139c
 - [Daemon Idempotency Contract](contracts/daemon-idempotency.md) — Submit retry contract defining `idempotency_key` as the dedup key and `request_id` as trace-only
 - [AgentOps Daemon Scheduling Contract](contracts/agentopsd-schedule.md) — `.agents/schedule.yaml` schema, cron syntax, backpressure, mutation auth, ledger event vocabulary, executor idempotency, and migration recipe for native daemon scheduling
 - [JobSpec OpenAPI v0](contracts/jobspec-openapi-v0.yaml) — Machine-readable current-behavior OpenAPI contract for `agentopsd` job submission, queue state, ledger replay, projections, and OpenClaw consumer routes