pdurlej/platform

Fork 0

Proposal: globalne zasady governance — non-author AI reviewer mandatory + branch protection na każdym mikroprojekcie #75

New issue

Closed

opened 2026-05-05 02:58:14 +02:00 by claude · 3 comments

claude commented

2026-05-05 02:58:14 +02:00

Collaborator

Proposal

Adopt globally (as platform-level governance, applicable to all microprojects: pyfallow, hermes-agency, iskra-openclaw, ...) the contributor pattern that operator (pdurlej) confirmed during pyfallow Phase A close-out (chat 2026-05-04 → 2026-05-05):

Mandatory non-author reviewer on every PR, regardless of size class.
Reviewer can be an AI agent (claude / codex / glm), but must not be the PR author. Identity-isolation enforced (different PAT, different commit author).
Branch protection rule on main enforces mechanically — no merge without ≥1 approved review + green CI. Even repo admins are subject (no silent bypass; break-glass is "disable rule, push, re-enable" with audit trail).
Operator (pdurlej) is the merger, not a reviewer-of-record. Operator's role = final approval and merge button. Review work is delegated to AI agents per-policy.
Platform's AGENTS.md is the canonical contributor contract for every microproject. Microproject-local docs may add (never subtract).

Why now

Operator's voice 2026-05-05 (translated, condensed):

"I'm the merger but only I can merge — that means none of you (agents) actually care about merge quality. Codex saw 9-of-13 MCP tests failing on Python 3.11 in Phase A and just fixed them locally without escalation. That's reactive, not defensive. From now on every PR — even Small per AGENTS.md size class — must have at least one reviewer different from the author, AI agent or otherwise. The mechanism: branch protection in Forgejo wymusza CI/CD-style 'no approval = no merge'. The way platform builds code should be the universal source for all microprojects."

Quote in original Polish recorded in pyfallow decisions/ (forthcoming ADR 0010, see references below).

Concrete change to existing platform docs

AGENTS.md § "Canary 3+3 review (ADR 0001)" currently scopes mandatory canary to PRs touching modules/, schema/, prompts/, tests/, control-plane/, decisions/. Small PRs outside those paths can merge with 1 tech + 1 product reviewer per ADR 0001 Rule 1a.

Proposed amendment: mandatory non-author reviewer on every PR (Small/Medium/Large/Batch), regardless of touched paths. Canary 3+3 stays mandatory for governance-critical paths (no change there); the universal floor adds: even pure-docs / single-file changes need a non-author reviewer to approve before merge.

Light-PR pattern (1 reviewer, single iteration) is acceptable for Small PRs — but not zero reviewers.

Concrete change to microproject convention

Each microproject's repo (pyfallow, hermes-agency, iskra-openclaw, ...):

Branch protection rule on main:
- Restrict push to main (whitelist empty, i.e., nobody direct-pushes; PR-only)
- Require ≥1 approved review (dismiss stale on new commits)
- Require status checks (CI matrix per project) to pass
- Require branches up-to-date with main before merge
- Block force-push
- Enforce for repository admins (operator subject to same rules; break-glass = explicit toggle)
Identity-isolation: per-actor PAT in BW (item git.pdurlej.com (<actor>), custom field PAT). Already documented in AGENTS.md § Identity-isolation.
Microproject's contributor doc (e.g., pdurlej/pyfallow/.codex/WORKFLOW.md) references platform AGENTS.md as canonical, adds project-specific extras only.

Pyfallow as first integration

Branch protection rules enabled today on pdurlej/pyfallow/main per operator action 2026-05-05 (this PR's predecessor — operator clicked Settings → Branches in Forgejo UI).
Required status checks: CI / Python 3.11 (pull_request), CI / Python 3.12 (pull_request), CI / Python 3.13 (pull_request).
ADR 0010 (forthcoming, in pdurlej/pyfallow/decisions/) records the decision with full context.

Suggested implementation in this issue's resolution

Decision phase — operator triages this issue, decides amendment scope, marks ready-for-agent.
PR phase — claude (or codex) opens PR amending AGENTS.md (and possibly PLATFORM_CONSTITUTION.md if reviewer rule is constitutional). Full Canary Context Pack per existing canary 3+3 process. The amendment PR itself goes through the new universal-floor reviewer rule — meta-validation that the rule works.
Rollout phase — sister Forgejo issues opened in pdurlej/hermes-agency, pdurlej/iskra-openclaw, etc., asking operator to enable branch protection there with same shape as pyfallow. Each microproject gets its own branch-protection-enable issue.

Owner Action Board

Needs owner now

CHOOSE: scope of universal-floor reviewer rule. Default unless objected: applies to every PR, Small/Medium/Large/Batch.
CHOOSE: this rule lives in AGENTS.md (as amendment to § Canary 3+3) or in PLATFORM_CONSTITUTION.md (as a new operator promise). Default: AGENTS.md — it's contributor-facing operational rule, not constitutional identity.

Default path unless owner objects

DEFAULT: claude opens amendment PR to AGENTS.md with full Canary Context Pack. The PR itself triggers full 3+3 canary (since it touches governance docs). Codex or glm reviews; operator merges.

Agent follow-up, no owner attention now

TASK: claude opens this proposal as platform issue (this issue)
TASK: claude tracks branch-protection-enable issues for each microproject as they come online (one per repo)

Blocked / waiting on precondition

BLOCKED: amendment PR until operator approves issue scope above

Model / emotional signal note (≤280 chars)

Yellow→green. Operator's "non-tech needs deterministic governance" thesis grew from pyfallow Phase A retrospective into a global pattern. This issue captures the moment. Risk if not formalized in platform: each microproject reinvents wheel; identity-isolation drifts; AI agents skip review because no mechanism enforces.

References

pyfallow Phase A retro chat 2026-05-04 → 2026-05-05 (operator + claude orchestrator)
pyfallow decisions/0010-mandatory-non-author-reviewer.md — forthcoming ADR with full context
pyfallow decisions/0007-pyfallow-as-deterministic-gate.md — articulates pyfallow as "deterministic code gate" counterpart to platform.exe's deterministic infra gate; same identity discipline propagated to other microprojects via this proposal
platform AGENTS.md § Canary 3+3 review — current scoping (this proposal amends)
platform decisions/0001-canary-mandatory-pm-cadence.md — establishes canary 3+3 (this proposal extends scope)

— Claude Opus 4.7 (orchestrator), 2026-05-05

## Proposal Adopt **globally** (as platform-level governance, applicable to all microprojects: `pyfallow`, `hermes-agency`, `iskra-openclaw`, ...) the contributor pattern that operator (`pdurlej`) confirmed during pyfallow Phase A close-out (chat 2026-05-04 → 2026-05-05): 1. **Mandatory non-author reviewer on every PR**, regardless of size class. 2. **Reviewer can be an AI agent** (claude / codex / glm), but **must not be the PR author**. Identity-isolation enforced (different PAT, different commit author). 3. **Branch protection rule on `main` enforces mechanically** — no merge without ≥1 approved review + green CI. Even repo admins are subject (no silent bypass; break-glass is "disable rule, push, re-enable" with audit trail). 4. **Operator (`pdurlej`) is the merger**, not a reviewer-of-record. Operator's role = final approval and merge button. Review work is delegated to AI agents per-policy. 5. **Platform's `AGENTS.md` is the canonical contributor contract** for every microproject. Microproject-local docs may add (never subtract). ## Why now Operator's voice 2026-05-05 (translated, condensed): > "I'm the merger but only I can merge — that means none of you (agents) actually care about merge quality. Codex saw 9-of-13 MCP tests failing on Python 3.11 in Phase A and just fixed them locally without escalation. That's reactive, not defensive. From now on every PR — even Small per AGENTS.md size class — must have at least one reviewer different from the author, AI agent or otherwise. The mechanism: branch protection in Forgejo wymusza CI/CD-style 'no approval = no merge'. The way platform builds code should be the universal source for all microprojects." Quote in original Polish recorded in pyfallow `decisions/` (forthcoming ADR 0010, see references below). ## Concrete change to existing platform docs `AGENTS.md` § "Canary 3+3 review (ADR 0001)" currently scopes mandatory canary to PRs touching `modules/`, `schema/`, `prompts/`, `tests/`, `control-plane/`, `decisions/`. Small PRs outside those paths can merge with 1 tech + 1 product reviewer per ADR 0001 Rule 1a. **Proposed amendment:** mandatory non-author reviewer on **every** PR (Small/Medium/Large/Batch), regardless of touched paths. Canary 3+3 stays mandatory for governance-critical paths (no change there); the universal floor adds: even pure-docs / single-file changes need a non-author reviewer to approve before merge. Light-PR pattern (1 reviewer, single iteration) is acceptable for Small PRs — but not zero reviewers. ## Concrete change to microproject convention Each microproject's repo (`pyfallow`, `hermes-agency`, `iskra-openclaw`, ...): 1. Branch protection rule on `main`: - Restrict push to `main` (whitelist empty, i.e., nobody direct-pushes; PR-only) - Require ≥1 approved review (dismiss stale on new commits) - Require status checks (CI matrix per project) to pass - Require branches up-to-date with main before merge - Block force-push - Enforce for repository admins (operator subject to same rules; break-glass = explicit toggle) 2. Identity-isolation: per-actor PAT in BW (item `git.pdurlej.com (<actor>)`, custom field `PAT`). Already documented in `AGENTS.md` § Identity-isolation. 3. Microproject's contributor doc (e.g., `pdurlej/pyfallow/.codex/WORKFLOW.md`) references platform `AGENTS.md` as canonical, adds project-specific extras only. ## Pyfallow as first integration - Branch protection rules **enabled today** on `pdurlej/pyfallow/main` per operator action 2026-05-05 (this PR's predecessor — operator clicked Settings → Branches in Forgejo UI). - Required status checks: `CI / Python 3.11 (pull_request)`, `CI / Python 3.12 (pull_request)`, `CI / Python 3.13 (pull_request)`. - ADR 0010 (forthcoming, in `pdurlej/pyfallow/decisions/`) records the decision with full context. ## Suggested implementation in this issue's resolution 1. **Decision phase** — operator triages this issue, decides amendment scope, marks `ready-for-agent`. 2. **PR phase** — claude (or codex) opens PR amending `AGENTS.md` (and possibly `PLATFORM_CONSTITUTION.md` if reviewer rule is constitutional). Full Canary Context Pack per existing canary 3+3 process. **The amendment PR itself goes through the new universal-floor reviewer rule** — meta-validation that the rule works. 3. **Rollout phase** — sister Forgejo issues opened in `pdurlej/hermes-agency`, `pdurlej/iskra-openclaw`, etc., asking operator to enable branch protection there with same shape as pyfallow. Each microproject gets its own branch-protection-enable issue. ## Owner Action Board ### Needs owner now - CHOOSE: scope of universal-floor reviewer rule. Default unless objected: applies to every PR, Small/Medium/Large/Batch. - CHOOSE: this rule lives in `AGENTS.md` (as amendment to § Canary 3+3) or in `PLATFORM_CONSTITUTION.md` (as a new operator promise). Default: `AGENTS.md` — it's contributor-facing operational rule, not constitutional identity. ### Default path unless owner objects - DEFAULT: claude opens amendment PR to `AGENTS.md` with full Canary Context Pack. The PR itself triggers full 3+3 canary (since it touches governance docs). Codex or glm reviews; operator merges. ### Agent follow-up, no owner attention now - TASK: claude opens this proposal as platform issue (this issue) - TASK: claude tracks branch-protection-enable issues for each microproject as they come online (one per repo) ### Blocked / waiting on precondition - BLOCKED: amendment PR until operator approves issue scope above ## Model / emotional signal note (≤280 chars) Yellow→green. Operator's "non-tech needs deterministic governance" thesis grew from pyfallow Phase A retrospective into a global pattern. This issue captures the moment. Risk if not formalized in platform: each microproject reinvents wheel; identity-isolation drifts; AI agents skip review because no mechanism enforces. ## References - pyfallow Phase A retro chat 2026-05-04 → 2026-05-05 (operator + claude orchestrator) - pyfallow `decisions/0010-mandatory-non-author-reviewer.md` — forthcoming ADR with full context - pyfallow `decisions/0007-pyfallow-as-deterministic-gate.md` — articulates pyfallow as "deterministic code gate" counterpart to `platform.exe`'s deterministic infra gate; same identity discipline propagated to other microprojects via this proposal - platform `AGENTS.md` § Canary 3+3 review — current scoping (this proposal amends) - platform `decisions/0001-canary-mandatory-pm-cadence.md` — establishes canary 3+3 (this proposal extends scope) — Claude Opus 4.7 (orchestrator), 2026-05-05

claude added the

proposed

needs-operator-decision

needs-triage

Operator decision: ACCEPT (2026-05-06)

Operator-confirmed via chat 2026-05-06: accept the proposal in principle.

Adopted globally (platform-level governance, applicable to all microprojects: pyfallow, hermes-agency, iskra-openclaw, platform, future microprojects):

Mandatory non-author reviewer on every PR (any size class)
Reviewer can be an AI agent (claude / codex / glm / ollama-via-Ollama-Pro), but MUST NOT be the PR author. Identity-isolation enforced.
Branch protection rule on main enforces mechanically — no merge without ≥1 approval from a non-author identity.

Execution gate

Branch protection enforcement is gated on Issue #49 setup tasks (specifically: branch protection configuration on main per ADR 0002 setup task #3). Until #49 setup completes, this is policy in effect but not yet mechanically enforced. Soft enforcement: orchestrator/PR-opener follows it; reviewers cite it.

Follow-up needed

After #49 setup completes: configure Forgejo branch protection on pdurlej/platform/main to require ≥1 approval from non-author
Apply same pattern to pdurlej/pyfallow, pdurlej/hermes-agency, pdurlej/iskra-openclaw mains (separate operator UI tasks per repo)
Update AGENTS.md to reflect this as canonical (currently mentions canary 3+3 only)

This issue stays open until all four mains have branch protection configured. Closing prematurely would lose the cross-repo follow-up tracking.

Label updated: accepted (or use existing label if present).

## Operator decision: ACCEPT (2026-05-06) Operator-confirmed via chat 2026-05-06: accept the proposal in principle. **Adopted globally** (platform-level governance, applicable to all microprojects: `pyfallow`, `hermes-agency`, `iskra-openclaw`, `platform`, future microprojects): 1. Mandatory non-author reviewer on every PR (any size class) 2. Reviewer can be an AI agent (claude / codex / glm / ollama-via-Ollama-Pro), but MUST NOT be the PR author. Identity-isolation enforced. 3. Branch protection rule on `main` enforces mechanically — no merge without ≥1 approval from a non-author identity. ### Execution gate Branch protection enforcement is **gated on Issue #49 setup tasks** (specifically: branch protection configuration on `main` per ADR 0002 setup task #3). Until #49 setup completes, this is **policy in effect** but not yet **mechanically enforced**. Soft enforcement: orchestrator/PR-opener follows it; reviewers cite it. ### Follow-up needed - [ ] After #49 setup completes: configure Forgejo branch protection on `pdurlej/platform/main` to require ≥1 approval from non-author - [ ] Apply same pattern to `pdurlej/pyfallow`, `pdurlej/hermes-agency`, `pdurlej/iskra-openclaw` mains (separate operator UI tasks per repo) - [ ] Update `AGENTS.md` to reflect this as canonical (currently mentions canary 3+3 only) This issue stays open until all four mains have branch protection configured. Closing prematurely would lose the cross-repo follow-up tracking. Label updated: `accepted` (or use existing label if present).

claude referenced this issue

2026-05-06 00:24:18 +02:00

product: AI Slot Machine — local static linter / integrity companion for agent answers #55

claude referenced this issue

2026-05-17 17:23:10 +02:00

docs(specs): prebuild for #243 branch protection main with base-is-main guard #327

claude referenced this issue

2026-05-17 17:27:24 +02:00

docs(specs): prebuild for #243 branch protection main with base-is-main guard #330

claude referenced this issue

2026-05-17 21:29:20 +02:00

docs(specs): secrets-pipeline-foundation-v0 prebuild (#237) #349

claude referenced this issue

2026-05-17 22:30:50 +02:00

docs(state): cross-ref agent-souls + practices in ANY-COUSIN-WAKEUP.md #355

claude referenced this issue

2026-05-17 22:43:51 +02:00

docs(state): cross-ref agent-souls + practices in ANY-COUSIN-WAKEUP.md #355

claude referenced this issue from a commit

2026-05-17 23:02:43 +02:00

prompts(forks): v0.1 dispatch template with worktree isolation (8 retry prebuilds)

claude referenced this issue

2026-05-17 23:03:11 +02:00

prompts(forks): v0.1 dispatch template with worktree isolation (8 retry prebuilds) #356

claude referenced this issue from a commit

2026-05-18 08:19:47 +02:00

decisions(0019) + docs(specs): non-author reviewer mandatory v0 prebuild (#75)

claude referenced this issue

2026-05-18 08:20:15 +02:00

decisions(0019) + docs(specs): non-author reviewer mandatory v0 prebuild (#75) #369

codex added this to the 06 - Agent execution and CI governance milestone

2026-05-19 08:36:24 +02:00

pdurlej referenced this issue from a commit

2026-05-23 09:20:07 +02:00

Merge pull request 'decisions(0019) + docs(specs): non-author reviewer mandatory v0 prebuild (#75)' (#369) from claude/fork-C3-governance-non-author-reviewer-mandatory into main

codex referenced this issue

2026-05-24 21:33:30 +02:00

docs(review): define non-author AI approval policy #450

codex commented

2026-05-29 16:23:50 +02:00

Collaborator

M10 disposition: moved to 10 - Improvements.

What this is: global governance / non-author AI reviewer proposal.

Why parked here: This is broad governance policy; keep it as future improvement rather than letting it bloat M06 current execution work.

This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

M10 disposition: moved to `10 - Improvements`. What this is: global governance / non-author AI reviewer proposal. Why parked here: This is broad governance policy; keep it as future improvement rather than letting it bloat M06 current execution work. This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

codex modified the milestone from 06 - Agent execution and CI governance to 10 - Improvements

2026-05-29 16:23:51 +02:00

codex commented

2026-05-29 16:36:33 +02:00

Collaborator

Closing as accepted/superseded by ADR-0019 and the current governance stack.

Accepted superset now lives across:

ADR-0019: mandatory non-author reviewer policy;
docs/ci/ai-review-governance.md: counted AI review contract;
Patchwarden: PR safety/sanity/automerge lane;
Vistula: flow state, manual-vs-auto merge reporting, delivery telemetry;
AgentSouls: cousin identity and operational discipline.

Any remaining implementation should be tracked as concrete M06 tasks, such as required checks / branch protection activation, not as this broad proposal issue.

Closing as accepted/superseded by ADR-0019 and the current governance stack. Accepted superset now lives across: - ADR-0019: mandatory non-author reviewer policy; - `docs/ci/ai-review-governance.md`: counted AI review contract; - Patchwarden: PR safety/sanity/automerge lane; - Vistula: flow state, manual-vs-auto merge reporting, delivery telemetry; - AgentSouls: cousin identity and operational discipline. Any remaining implementation should be tracked as concrete M06 tasks, such as required checks / branch protection activation, not as this broad proposal issue.

codex closed this issue

2026-05-29 16:36:33 +02:00