[ACP-HARDEN-140] Solo maintainer + AI-assisted governance profileを追加する

[ootakazuhiko]

Parent: #3655
Depends on: #3657, #3659, #3661
Related: #3656, #3658, #3660
Blocks: #3640 solo-maintainer pilot profile
Codex lane: policy/solo-maintainer-governance

背景

itdojp/ae-frameworkは実質的に「1名の人間maintainer + AI coding/review agents」で運用されている。現行GitHub rulesetは別のwrite権限保有者によるApproving Reviewを要求するため、PR author本人は自分のPRをApproveできず、GitHub Copilot reviewもrequired approvalとして数えられない。結果として、required CI、strict Formal Verify、全review thread解決が完了していてもREVIEW_REQUIREDで自己デッドロックする。

この問題をadmin bypassや一時的なruleset緩和で都度処理せず、ae-frameworkのAssurance Control Planeが、team topologyに応じたtruthful governance profileを提供する必要がある。

目的

次の2つを明確に分離したclosed governance contractを導入する。

1. team-reviewed — 独立した人間reviewerを必要とする通常の複数人運用
2. solo-maintainer-agent-assisted — required human approvalを偽装せず、exact-head Evidence、AI review disposition、会話解決、本人の明示的merge decisionで統制する一人運用

AI reviewを人間approvalとして扱わない。solo profileは独立reviewを達成したと主張せず、「単独maintainerによるEvidence-backed decision」として記録する。

Codex CLI preflight

• AGENTS.md
• docs/integrations/CODEX-ISSUE-RUNBOOK.md
• docs/product/ASSURANCE-CONTROL-PLANE-POLICY.md
• docs/quality/ASSURANCE-MODEL.md
• docs/reference/CONTRACT-CATALOG.md
• docs/spec/context-pack.md
• spec/context-pack/boundary-map.json
• GitHub ruleset／branch protection docs and helpers
• CODEOWNERS
• Policy Gate／Copilot Review Gate／review-completeness scripts
• [ACP-HARDEN-120] GitHub authority snapshotとstale-context検出を追加する #3657 authority snapshot contract
• [ACP-HARDEN-210] human-decision/v1で承認を対象material digestへbindingする #3659 human-decision contract
• [ACP-HARDEN-250] review-disposition/v1とhead-bound review completenessを追加する #3661 review-disposition contract

Context Pack／Boundary Mapと矛盾する場合は変更前に停止する。

Proposed contracts

推奨:

• schema/governance-profile-v1.schema.json
• schema/solo-maintainer-merge-decision-v1.schema.json
• config/governance-profile.json
• scripts/governance/doctor.mjs
• scripts/governance/validate-merge-decision.mjs
• scripts/governance/render-ruleset-guidance.mjs
• fixtures／tests／Contract Catalog entry

Governance profile

最低限:

schemaVersion
profileId
mode:
  team-reviewed
  solo-maintainer-agent-assisted
humanMaintainerCount
independentHumanApprovalRequired
aiReviewRole:
  advisory-only
requiredAuthoritySnapshot
requiredChecks
requiredReviewThreadResolution
requiredReviewDisposition
requiredHumanDecision
riskProfiles
rulesetExpectations
profileDigest

Solo merge decision

最低限:

schemaVersion
decisionId
repository
pullRequestNumber
baseSha
headSha
riskClass
authoritySnapshotDigest
requiredCheckSnapshotDigest
reviewThreadSnapshotDigest
reviewDispositionDigest
aiReviewEvidenceRefs
humanDecision:
  actorRole: authorized-maintainer
  decision: approve-merge | reject | defer
  issuedAt
  rationale
limitations
supersedes
artifactStatus: real | test-only
decisionDigest

GitHub ruleset semantics

solo-maintainer-agent-assisted

Repository rulesetは少なくとも次を満たす。

• Pull Request必須: ON
• required approving review count: 0
• code owner review必須: OFF
• latest pushを別人がApprove: OFF
• review conversation resolution: ON
• required exact-head status checks: ON
• force push／branch deletion: OFF
• bypassを通常運用の前提にしない
• AI／Copilot reviewはadvisory Evidenceでありapprovalではない
• merge操作はauthorized human maintainerのみ

CODEOWNERSはownership/routing文書として維持可能だが、solo profileではcode-owner approval ruleを有効にしない。

team-reviewed

• required approval count >= 1
• code owner／last-push approvalはteam policyに従う
• solo decision artifactだけで独立reviewを代替しない

Governance deadlock detection

governance doctorは最低限次をfail closedで検出する。

• humanMaintainerCount = 1 かつ required approvals > 0
• humanMaintainerCount = 1 かつ require_code_owner_review = true で唯一のCODEOWNERがPR author
• humanMaintainerCount = 1 かつ require_last_push_approval = true
• AI reviewをhuman approvalとして数える設定／文言
• required checkが別head
• unresolved review threadあり
• exact-head merge decisionなし
• test-only decision artifactでreal PRをmergeしようとする
• current GitHub rulesetとdeclared governance profileのdrift

Finding例:

governance-deadlock
ruleset-profile-drift
independent-review-unavailable
ai-review-not-human-approval
merge-decision-stale-head

Risk profiles

最低限:

normal

• required checks success
• review threads resolved
• AI review completed or explicit unavailable reason
• exact-head human merge decision

high

• normal要件
• extended CI
• security／testing／artifacts／assurance gates
• applicable formal gate
• all actionable AI comments dispositioned
• explicit limitations

critical

Profile policyで次のいずれかを選べる。

• external human review required
• explicit exceptional solo decision with stronger Evidence and recorded risk acceptance

独立reviewがない場合に「two-person review済み」と表現しない。

Policy Gate integration

solo modeではGitHub reviewDecision=REVIEW_REQUIREDを成功条件にしない代わりに、次を必須化する。

• [ACP-HARDEN-120] GitHub authority snapshotとstale-context検出を追加する #3657 exact-head authority snapshot
• required checksがcurrent headでsuccess
• unresolved actionable review threads 0
• [ACP-HARDEN-250] review-disposition/v1とhead-bound review completenessを追加する #3661 review dispositions complete
• AI reviewはadvisoryとして記録
• [ACP-HARDEN-210] human-decision/v1で承認を対象material digestへbindingする #3659 subject-bound human decision
• merge decision head/baseがcurrent PRと一致
• risk profileの追加gateが完了

team modeでは従来どおりindependent approvalを要求する。

CLI／UX

推奨commands:

ae governance init --mode solo-maintainer-agent-assisted
ae governance doctor
ae governance snapshot --pr <number>
ae governance attest --pr <number> --decision approve-merge
ae governance check --pr <number>
ae governance ruleset-guidance

--applyでGitHub rulesetを変更する機能を追加する場合は、default dry-run、人間による明示確認、変更前後snapshot、rollback guidanceを必須にする。

Acceptance criteria

• solo profileでrequired human approvalを0としても、PR、checks、conversation resolution、exact-head human decisionが必須。
• AI/Copilot reviewをhuman approvalとして数えない。
• solo + required approvals > 0をgovernance-deadlockとして検出する。
• CODEOWNERSが一人だけの場合のcode-owner review deadlockを検出する。
• last-push approvalのsolo deadlockを検出する。
• GitHub rulesetとprofileのdriftをoffline fixtureで検出する。
• human decisionがPR exact head/baseとauthority snapshotへbindingされる。
• stale decision、wrong-head CI、unresolved thread、test-only decisionを拒否する。
• team profileではsolo attestationだけでrequired approvalを代替できない。
• normal/high/critical risk profileの差異がmachine-readable。
• repository設定変更はdefault dry-runで、直接自動変更しない。

Validation

• Schema self-validation
• solo/team profile fixtures
• one-maintainer deadlock fixtures
• CODEOWNERS deadlock fixtures
• last-push approval deadlock fixtures
• exact-head／wrong-head decision tests
• AI review advisory-only tests
• ruleset drift tests
• risk profile tests
• deterministic decision digest x2
• pnpm -s run build
• pnpm -s run api:check
• pnpm -s run check:schemas
• pnpm -s run check:doc-consistency
• pnpm -s run verify:lite
• Context Pack／Boundary Map
• actionlint
• git diff --check
• exact-head required CI

Documentation

• solo maintainerの保証境界
• AI reviewとhuman approvalの違い
• GitHub ruleset推奨値
• CODEOWNERSの扱い
• emergency bypassと通常運用の違い
• independent reviewが存在しないというresidual risk
• teamへ移行した際のprofile migration

非目標

• AIを法的／人間reviewerとして扱うこと
• independent reviewがないのにあると主張すること
• auto-mergeをdefault化すること
• GitHub Appを人間approvalとして偽装すること
• repository admin bypassを通常merge経路にすること
• GitHub以外のSCM対応

HUMAN DECISION REQUIRED

• critical riskでexternal reviewを必須とするか、exceptional solo decisionを許可するか
• ruleset自動適用を提供するか、guidanceのみとするか
• solo decisionのauthorized maintainer authority source
• public release／security disclosure／irreversible migrationの追加gate

Stop condition

• 1 Draft PR
• exact-head required CI success
• actionable review threads resolved
• governance doctor fixture evidence
• worktree clean
• merge／Issue closeは人間判断