diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index da2157efb0..fee0acf36d 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -6883,6 +6883,33 @@ Keeping them adjacent preserves the directive cluster. schema for adversarial-training-corpus risks; Kenji synthesizes the dual-use deliverable. +## P2 — BP-25 promotion candidate — live-state-before-policy + +- [ ] **Promote "live-state-before-policy" to BP-25 via ADR.** + Amara's 4th ferry (PR #221 absorb) named the rule; Otto-72 + landed schema-enforcement of it via the `live_state_checks:` + field in `docs/decision-proxy-evidence/` records (documented + in the `README.md` "Live-state-before-policy" section + after PR ). BP-NN promotion is Aarav's call per the + BP-NN-promotion-cadence FACTORY-HYGIENE row; this row + queues the promotion consideration. Rule text candidate: + *"Never recommend a repository settings change, required- + check change, merge policy change, or branch-rule change + unless the current live state has been queried in the same + work unit."* **Scope:** draft ADR under + `docs/DECISIONS/YYYY-MM-DD-bp-25-live-state-before-policy.md` + citing the Amara ferry + the schema-enforcement in + `docs/decision-proxy-evidence/README.md` + the HB-004 + failure-mode evidence Amara sampled. If adopted, promote + to BP-25 in `docs/AGENT-BEST-PRACTICES.md` (current max + is BP-24). **Effort:** S (ADR drafting + policy + inclusion). **Owner:** Aarav drives the promotion call; + Kenji integrates; Rune readability. **Source of truth:** + `docs/aurora/2026-04-23-amara-memory-drift-alignment- + claude-to-memories-drift.md` (PR #221 absorb) + + `docs/decision-proxy-evidence/README.md` (PR #222 + this + PR's addendum). + ## P1 — Principle-adherence review cadence (Otto-58 new hygiene class) - [ ] **Principle-adherence review — cadenced agent judgment on diff --git a/docs/decision-proxy-evidence/README.md b/docs/decision-proxy-evidence/README.md index a7a570750c..065f61d7ea 100644 --- a/docs/decision-proxy-evidence/README.md +++ b/docs/decision-proxy-evidence/README.md @@ -205,6 +205,71 @@ author can set `false` with a one-line justification in --- +## Live-state-before-policy — the principle behind `live_state_checks:` + +Amara's 4th ferry (PR #221) named this as a Determinize- +stage rule, paired with the evidence-record format: + +> Never recommend a repository settings change, required- +> check change, merge policy change, or branch-rule change +> unless the current live state has been queried in the +> same work unit. + +**Why it exists:** Amara's commit-sample HB-004 arc shows +the failure mode — same-day propose-from-symptoms → policy- +stance → empirical-correction. The pattern generalizes +whenever an agent proposes substrate changes from inferred +state rather than verified state. The fix is mechanical: +run the `gh api` / `git log` / equivalent check **first**, +propose **second**. + +**How the schema enforces it:** + +The `live_state_checks:` field is required for every +`settings-change` and `branch-shaping` task class. At least +one entry must name an actual command that was executed to +verify the state the decision operates on. Examples from +the DP-001 worked example: + +- `gh api repos/Lucent-Financial-Group/Zeta/branches/main/protection` +- `gh api repos/AceHack/Zeta --jq '.fork // .parent.full_name'` +- `gh api users/AceHack/events (repo-level create/delete scan)` + +An evidence record with an empty `live_state_checks:` array +for those task classes is a flag: either the rule was +skipped (fix the record), or the task class was +misclassified (change the field). + +**Scope:** + +Applies whenever a durable change to state-with-public- +consequences is proposed: + +- Settings changes (repo, org, branch, workflow, + required-checks, rulesets) +- Branch-shaping (branch-protection, policy flips, merge + method changes) +- Scope / authority claims that assume repo state + ("I'll merge this because branch protection allows it") +- Roadmap edits that assume current capability state + ("this works because test X passes" — verify test X + actually passes) + +Does NOT apply to: + +- Pure read / observation work (research docs, memory + absorbs, BACKLOG row filings that don't assert state) +- Mechanical fixes where the state is self-evident in + the change (typo, lint, format) + +**Future BP-NN promotion candidate:** this rule meets the +bar for a stable BP rule per `docs/AGENT-BEST-PRACTICES.md` +(multiple occurrences + cross-agent applicability). Aarav +considers for BP-25 promotion via ADR; until then it lives +here as schema-enforced practice. + +--- + ## Relationship to the "hard rule" Across all four Amara ferries (PRs #196, #211, #219, #221)