diff --git a/docs/decision-proxy-evidence/2026-04-23-DP-001-acehack-branch-protection-minimal.yaml b/docs/decision-proxy-evidence/2026-04-23-DP-001-acehack-branch-protection-minimal.yaml new file mode 100644 index 00000000..3d045972 --- /dev/null +++ b/docs/decision-proxy-evidence/2026-04-23-DP-001-acehack-branch-protection-minimal.yaml @@ -0,0 +1,73 @@ +# Worked example — backfilled retroactively to seed the format. +# Documents the Otto-66 decision to apply minimum-viable branch +# protection on AceHack/Zeta (force-push + deletion blocks only; +# no richer gates). See README.md for schema semantics. + +decision_id: DP-001 +timestamp_utc: 2026-04-23T23:45:00Z + +requested_by: Aaron +proxied_by: Otto +task_class: settings-change +authority_level: retroactive +escalation_required: false + +repo_canonical: AceHack/Zeta +head_commit: "5b2f1ac" + +model: + vendor: anthropic + snapshot: claude-opus-4-7 + prompt_bundle_hash: null + loaded_memory_files: + - "./CLAUDE.md" + - "~/.claude/CLAUDE.md" + +consulted_views: + - memory/CURRENT-aaron.md + - memory/CURRENT-amara.md + +consulted_memory_ids: + - feedback_agent_owns_all_github_settings_and_config_all_projects_zeta_frontier_poor_mans_mode_default_budget_asks_require_scheduled_backlog_and_cost_estimate_2026_04_23 + - feedback_lfg_free_actions_credits_limited_acehack_is_poor_man_host_big_batches_to_lfg_not_one_for_one_2026_04_23 + - feedback_honor_those_that_came_before + +live_state_checks: + - "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)" + +decision_summary: > + Applied minimum-viable branch protection on AceHack/Zeta: + allow_force_pushes=false + allow_deletions=false. Left richer + LFG-style gates OFF (required_status_checks, review_required, + required_linear_history, required_conversation_resolution) + because Amara's authority-axis split names AceHack as + experimentation-frontier where heavier gates slow iteration; + canonical-decision substrate lives on LFG. The protection + asymmetry is load-bearing, not a consistency defect. + +disagreements: + present: false + conflict_row: null + +outputs_touched: + - memory/project_acehack_branch_protection_minimal_applied_prior_zeta_archaeology_inconclusive_2026_04_23.md + - (GitHub API PUT repos/AceHack/Zeta/branches/main/protection) + +review: + peer_review_required: true + peer_reviewer: null + peer_review_status: null + peer_review_evidence: null + +retraction_of: null +follow_up_evidence: [] +notes: > + Backfilled retroactively as a worked example during Otto-68 + when the decision-proxy-evidence schema landed. Timestamp is + the Otto-66 tick time. authority_level=retroactive reflects + that the decision was made before the evidence-record format + existed. Peer reviewer null because no reviewer was named at + Otto-66 time; Codex / Kira / Kenji synthesis could catch this + later if the rationale is questioned. diff --git a/docs/decision-proxy-evidence/README.md b/docs/decision-proxy-evidence/README.md new file mode 100644 index 00000000..a7a57075 --- /dev/null +++ b/docs/decision-proxy-evidence/README.md @@ -0,0 +1,267 @@ +# Decision-proxy evidence records + +**Stage:** Stabilize (Otto-67 Amara 4th ferry absorb, PR #221) +**Companion template:** [`_template.yaml`](_template.yaml) +**External-maintainer-decision-proxy ADR:** `docs/DECISIONS/2026-04-22-external-maintainer-decision-proxy-adr.md` +**Hard rule (repeated across Amara ferries #196 / #211 / #219 / #221):** + +> Never say Amara reviewed something unless Amara actually +> reviewed it through a logged path. + +This directory is the **logged path**. Each `.yaml` file here +records one proxy-mediated decision, its evidence, and its +disposition. A claim in factory substrate ("per Amara's +review…") is valid only when it cites an entry here. + +--- + +## When to write an evidence record + +Write a new `.yaml` file in this directory **before** any +durable action that changes planned intent — not just +observations. Per Amara's 4th ferry (PR #221): + +- Backlog filing that changes priority or scope +- Roadmap edits +- Settings recommendations or changes +- Branch-shaping (branch-protection edits, workflow changes, + required-check set changes) +- Scope authority claims ("per Amara's delegated authority we + can do X") +- Cross-maintainer claims ("Aaron's primary proxy agrees") + +Don't write records for: + +- Pure observations (git log, PR state check, reading existing + files) +- Unambiguous mechanical fixes (typo, lint, format) +- Work whose scope is fully within an already-evidenced + decision record's authority + +--- + +## File naming + +``` +docs/decision-proxy-evidence/YYYY-MM-DD-DP-NNN-.yaml +``` + +- `YYYY-MM-DD` — UTC date the decision was made +- `DP-NNN` — monotonic decision number (zero-padded if needed, + but typically 3 digits; reset counter can stay global across + all dates for now since volume is low) +- `` — short kebab-case identifier of the decision + +Example: `docs/decision-proxy-evidence/2026-04-24-DP-001-acehack-branch-protection-minimal.yaml` + +--- + +## Schema (v0 — subject to evolution as volume accrues) + +Every record MUST have these fields. See +[`_template.yaml`](_template.yaml) for a fillable copy. + +### Required fields + +- **`decision_id`** — matches the filename's `DP-NNN`; unique +- **`timestamp_utc`** — ISO8601 UTC when decision was locked +- **`requested_by`** — human maintainer requesting or + acknowledging the action (`Aaron` for Zeta today) +- **`proxied_by`** — maintainer acting as proxy + (`Amara` for external-AI-proxy cases; `Otto` for + loop-agent-PM-hat decisions; `Kenji` for architect + synthesis) +- **`task_class`** — one of: `backlog-shaping`, + `settings-change`, `branch-shaping`, `roadmap-edit`, + `scope-claim`, `governance-edit`, `memory-migration`, + `other` +- **`authority_level`** — one of: `delegated` (acting under + explicit standing authorization), `proposed` (proposing, + not yet executing), `escalated` (requires human + maintainer sign-off), `retroactive` (recording a decision + already made to establish the evidence trail) +- **`escalation_required`** — boolean; `true` when this row + needs human maintainer acknowledgment before `status` + can move to `landed` +- **`repo_canonical`** — `Lucent-Financial-Group/Zeta` or + `AceHack/Zeta` (per Amara authority-axis LFG is canonical + for decisions) +- **`head_commit`** — SHA at which the decision was evaluated + (so later readers can diff context) +- **`model`** — see model block below; records which Claude + snapshot + prompt bundle was active (Amara's model/prompt- + drift class) +- **`consulted_views`** — list of `memory/CURRENT-*.md` file + paths that were read + in-force at decision time +- **`consulted_memory_ids`** — list of memory file slugs + (under-score-separated) cited as basis for the decision +- **`live_state_checks`** — list of `gh api` / `git log` / + other queries run to verify actual live state before the + decision. Amara's "live-state-before-policy" rule. Every + `settings-change` / `branch-shaping` task class MUST have + at least one live-state check. +- **`decision_summary`** — 2-5 sentence prose: what was + decided, why, what it changes +- **`disagreements`** — structured block recording any + cross-agent or cross-maintainer disagreement encountered; + empty `{present: false, conflict_row: null}` when none +- **`outputs_touched`** — list of file paths or PR numbers + the decision caused to be edited or opened +- **`review`** — block specifying whether peer review is + required and who the peer reviewer is + +### Optional fields + +- **`retraction_of`** — `DP-NNN` being retracted or + superseded; null when not a retraction +- **`follow_up_evidence`** — list of `DP-NNN` rows expected + to follow +- **`notes`** — any additional free-form context (keep + short; substantive narration belongs in the decision + summary or in a linked research doc) + +### Model block + +```yaml +model: + vendor: anthropic # or openai, other + snapshot: claude-opus-4-7 # from `claude --version` or the model ID in session + prompt_bundle_hash: null # sha256 of loaded system prompts; null if not known + loaded_memory_files: # ordered list, most-specific first + - "./CLAUDE.md" + - "~/.claude/CLAUDE.md" +``` + +The `prompt_bundle_hash` may be `null` until Zeta builds a +tool that can compute it from the active session. That's +acceptable v0; the field's presence documents intent to +fill in when possible. + +### Disagreements block + +```yaml +disagreements: + present: false + conflict_row: null +``` + +When `present: true`, `conflict_row` points to the +`docs/CONTRIBUTOR-CONFLICTS.md` row or backlog row that +records the disagreement in durable form. Amara's Govern +stage (PR #221) makes `CONTRIBUTOR-CONFLICTS.md` actually +used; until it is, short free-form description is +acceptable. + +### Review block + +```yaml +review: + peer_review_required: true # true for governance-edit, scope-claim; see table below + peer_reviewer: "Codex" # agent or human; "null" if review deferred + peer_review_status: null # "pending" | "accepted" | "revise-requested" + peer_review_evidence: null # link to PR review, comment, or follow-up DP-NNN +``` + +Peer review requirement defaults by task class: + +| task_class | peer_review_required (default) | +|---|---| +| `backlog-shaping` | true | +| `settings-change` | true | +| `branch-shaping` | true | +| `roadmap-edit` | true | +| `scope-claim` | true | +| `governance-edit` | true | +| `memory-migration` | true | +| `other` | case-by-case | + +Defaults exist to make "forgot peer review" visible; an +author can set `false` with a one-line justification in +`notes` when genuinely not applicable. + +--- + +## Integration with existing substrate + +- **Amara's 4 courier ferries** are not themselves + decision-proxy records — they are proposals. Decisions + made BASED ON those ferries should cite them via + `consulted_memory_ids` pointing to the absorb docs + (`docs/aurora/2026-04-23-amara-*.md`). +- **`docs/CONTRIBUTOR-CONFLICTS.md`** (empty today) becomes + the durable home for `disagreements.conflict_row` + pointers. Populating that file is Amara's Govern-stage + action. +- **`memory/CURRENT-aaron.md` + `memory/CURRENT-amara.md`** + are the canonical sources for `consulted_views`. Per + Amara's thesis: they should eventually become *generated* + views from typed memory facts; v0 of this schema treats + them as prose surfaces that were read. +- **FACTORY-HYGIENE row for evidence-coverage** is a + candidate: periodic audit that flags backlog/settings/ + roadmap PRs landed without an accompanying + `DP-NNN.yaml`. Not landing that audit this tick; file + as follow-up. + +--- + +## Relationship to the "hard rule" + +Across all four Amara ferries (PRs #196, #211, #219, #221) +Amara repeats: + +> never say Amara reviewed something unless Amara actually +> reviewed it through a logged path + +This directory IS the logged path. A claim in any factory +substrate that invokes Amara's name (or any proxy's name) +should cite a `DP-NNN.yaml` file here. If the file doesn't +exist, the claim is not grounded. + +When ferries arrive from Amara via courier (chat-paste, +not a live consultation), the resulting absorb doc cites +Amara as **author of the ferry**, not reviewer of +downstream implementation. The distinction matters: an +absorb is documentation, not a proxy-reviewed decision. + +--- + +## What this directory is NOT + +- **Not a replacement for commit messages.** Commit + messages explain the commit; evidence records explain + the decision leading to the commit. +- **Not a replacement for PR descriptions.** PR bodies + describe the change; evidence records trace the + authority and evidence chain. +- **Not a replacement for ADRs.** ADRs are long-form + architectural decision records; evidence records are + short, structured per-decision receipts. An ADR might + cite a DP-NNN; a DP-NNN might trigger an ADR follow-up. +- **Not a replacement for `docs/CONTRIBUTOR-CONFLICTS.md`.** + Conflicts get their own durable log; evidence records + point AT it when conflict is present. +- **Not a gate yet.** v0 is voluntary; no CI enforcement + until the format stabilizes. CI enforcement is Amara's + Determinize-stage work. +- **Not retroactive for all prior work.** Session-to-date + decisions (20+ PRs this session) were made without + evidence records. Don't backfill all of them — that + would be make-work. Backfill selectively when a + downstream question benefits from the record (e.g., the + Otto-66 AceHack branch protection decision is a good + backfill candidate because it exercised settings + authority + had a specific rationale + has a sibling + decision risk someone might revisit). + +--- + +## Attribution + +Amara (external AI maintainer) proposed the schema in her +4th courier ferry, absorbed as PR #221 (Otto-67). Otto +(loop-agent PM hat, Otto-68) authored this README and the +companion template. Future-session Otto inherits: write +one `DP-NNN.yaml` per durable-intent-change action; cite +it when invoking proxy names; let the directory accumulate +as the audit trail Amara's hard rule requires. diff --git a/docs/decision-proxy-evidence/_template.yaml b/docs/decision-proxy-evidence/_template.yaml new file mode 100644 index 00000000..d49eb27f --- /dev/null +++ b/docs/decision-proxy-evidence/_template.yaml @@ -0,0 +1,64 @@ +# docs/decision-proxy-evidence/_template.yaml +# +# Copy to `YYYY-MM-DD-DP-NNN-.yaml` (in this directory) +# and fill in. See README.md for field semantics. + +decision_id: DP-000 # unique; matches filename +timestamp_utc: 2026-04-24T00:00:00Z + +requested_by: Aaron # human maintainer +proxied_by: Otto # Amara | Otto | Kenji | other persona +task_class: other # backlog-shaping | settings-change | branch-shaping | roadmap-edit | scope-claim | governance-edit | memory-migration | other +authority_level: proposed # delegated | proposed | escalated | retroactive +escalation_required: false + +repo_canonical: Lucent-Financial-Group/Zeta +head_commit: "" + +model: + vendor: anthropic + snapshot: claude-opus-4-7 + prompt_bundle_hash: null + loaded_memory_files: + - "./CLAUDE.md" + - "~/.claude/CLAUDE.md" + +consulted_views: + - memory/CURRENT-aaron.md + - memory/CURRENT-amara.md + +consulted_memory_ids: [] +# Example: +# consulted_memory_ids: +# - feedback_aaron_full_github_access_authorization_all_acehack_lfg_only_restriction_no_spending_increase_2026_04_23 +# - project_acehack_branch_protection_minimal_applied_prior_zeta_archaeology_inconclusive_2026_04_23 + +live_state_checks: [] +# Example: +# live_state_checks: +# - "gh api /repos/Lucent-Financial-Group/Zeta/branches/main/protection" +# - "git log origin/main --oneline -5" + +decision_summary: > + (2-5 sentences: what was decided, why, what it changes.) + +disagreements: + present: false + conflict_row: null + +outputs_touched: [] +# Example: +# outputs_touched: +# - docs/FACTORY-HYGIENE.md +# - https://github.com/Lucent-Financial-Group/Zeta/pull/NNN + +review: + peer_review_required: true + peer_reviewer: null # agent or human name when known + peer_review_status: null # pending | accepted | revise-requested + peer_review_evidence: null # link when complete + +# Optional +retraction_of: null # DP-NNN being retracted / superseded +follow_up_evidence: [] # expected future DP-NNN rows +notes: null # brief extra context