[Governance Gap] Establish an observable independent-review and CODEOWNERS route

[seonghobae]

Buyer / acquisition outcome

Make Clearfolio's protected-branch review governance deterministic and auditable instead of relying on an implicit or manually discovered reviewer path. A buyer, maintainer, or automation must be able to determine who is eligible to provide a qualifying independent review, how that reviewer is requested, and which exact-head review evidence satisfies the repository's live merge policy without manufacturing approval.

Fresh evidence — 2026-08-10

Protected main is 83ec6f7fe2b04bdcd28bf98ec350e41e55730a18.

Current protected-main docs/repository-metadata.md still records Explicit CODEOWNERS set to transfer team as incomplete. Repository code search does not expose a current CODEOWNERS file.

Three independent Ready/mergeable lanes illustrate the operational gap:

• fix(security): harden audit pseudonymization and refresh Netty evidence #270 exact head 63cdc36b926af8fd03a1ec689a1a6d5d800b8248: exact-head CI, Security Scan, SAST Semgrep, and fuzz successful; review threads resolved/outdated; no qualifying approval.
• docs: establish canonical product, architecture, and acquisition spine #305 exact head 5bbe979a256f4f19ba8a416a3f5fdd3e01305dd5: exact-head CI, Security Scan, and SAST Semgrep successful; review threads resolved; no qualifying approval.
• fix(openapi): align buyer contract license metadata #316 exact head b6d79bce1cbbcc34e2743891788d96d40ab42d87: exact-head CI, Security Scan, SAST Semgrep, and fuzz successful; review threads resolved/outdated; no qualifying approval.

Auto-merge is enabled on all three through ordinary repository protection so no branch-protection requirement is bypassed.

Empirical protection proof

After revalidating #316's unchanged exact head and exact-head gates, the normal GitHub merge endpoint was invoked with expected_head_sha=b6d79bce1cbbcc34e2743891788d96d40ab42d87. GitHub rejected the merge with HTTP 405:

At least 1 approving review is required by reviewers with write access.

This proves one approving review from a reviewer GitHub counts as write-authorized is a live protected-merge requirement.

Current reviewer eligibility — central authority resolves the ambiguity

The ordinary request-reviewers API for opencode-agent returned HTTP 422 because it is not an ordinary collaborator. A fresh repository permission probe independently reports collaborator permission none for opencode-agent; the cwl-noema-review mention identity does not expose qualifying repository write permission.

More importantly, the organization-owned governance authority ContextualWisdomLab/.github#772 explicitly records the current CWL separation-of-duties contract:

• opencode-agent, cwl-noema-review, and coderabbitai are advisory reviewers and do not have repository write permission that GitHub counts for protected-branch approval;
• author self-review is non-independent;
• the durable target design is an independent-reviewers human team with at least two non-author maintainers and the minimum permission GitHub counts, plus CODEOWNERS/reviewer assignment and reviewer-availability evidence;
• automated reviewers must remain read-only/advisory and must not receive broad contents-write authority merely to manufacture approval.

Therefore the earlier hypothesis that a central OpenCode/Noema formal APPROVED review might itself satisfy Clearfolio's write-authorized review rule is now falsified by the central governance contract. Historical PR #107 proves OpenCode can submit a formal review object, but that object is advisory for the protected-review separation-of-duties gate.

Review-delivery control plane is also currently under repair

The central trusted-comment mention route remains useful for advisory exact-head source review, but it is not the counted human-approval route. Fresh central state also shows .github PR #911 repairing a separate live delivery defect: GitHub repository_dispatch.client_payload permits at most ten top-level properties, while the protected-main OpenCode router→wrapper hop carried fourteen. #911 rebuilds that repair on current central main and remains Draft pending its own gates. Thus absence of a current OpenCode queue receipt must not be misclassified as a Clearfolio source defect.

Current exact-head @opencode-agent / @cwl-noema-review invocations on #270/#305/#316 remain advisory review probes only. They do not substitute for the counted human review required by the merge rule.

Required governance contract

1. Preserve the observed Clearfolio merge rule: at least one approving review from a reviewer with permission GitHub counts as write-authorized.
2. Adopt the organization-level solution from .github#772 rather than granting write authority to advisory bots: an eligible independent human team with backup coverage and minimum counted permission.
3. Add/update CODEOWNERS or another explicit reviewer-assignment route using verified eligible human/team identities. Do not invent a team slug or reviewer before organization governance creates/verifies it.
4. Keep OpenCode, Noema, CodeRabbit, GHAS and other automation evidence separate and advisory; they may discover defects but cannot satisfy the counted-human gate by inference.
5. Keep exact-head review identity separate from source-head checks, statuses, model judgments, synthetic-merge evidence, and protected-main runtime evidence.
6. Preserve stale-review/dismissal behavior and revalidate approving permission/head immediately before merge.
7. Keep expected-head-safe auto-merge enabled only through normal protection; no bypass or review-count reduction.

Test / acceptance

• Repository governance docs/tests reflect the observed 1 approving review by a reviewer with write access rule.
• Negative evidence is preserved: author self-review does not qualify; opencode-agent ordinary review request is 422/non-collaborator; advisory bots do not have counted write permission.
• Organization governance provides at least two non-author human identities with minimum counted repository permission through an independent-reviewer team or equivalent reviewed mechanism.
• A dry-run/current clean PR proves an eligible independent human approval changes the live protection decision while advisory bot review alone does not.
• A post-approval commit proves stale approval is dismissed/invalidated according to live policy.
• Reviewer permission removal/loss fails closed with an actionable governance blocker.
• CODEOWNERS/reviewer assignment, backup/leave/offboarding, exact-head identity and permission snapshot are documented and auditable.
• docs/repository-metadata.md, canonical traceability/governance, and operator guidance are reconciled after the organization route is actually provisioned.
• No branch protection, required check, security gate, or review count is weakened merely to merge work.

Dependency / scope

This issue is the Clearfolio leaf view of organization governance issue ContextualWisdomLab/.github#772. .github is read-only to the Clearfolio writer loop. Do not duplicate the central human-team provisioning or grant bots write permission here.

#270/#305/#316 are technically clean candidates whose merges remain locally deferred on the counted-human gate; their auto-merge configuration preserves every normal protection requirement. While organization governance is unresolved, continue every other safe Clearfolio product/security/reliability lane.

[seonghobae]

Additional reviewer-route evidence from fresh central-control-plane inspection:

• get_repo_collaborator_permission reports opencode-agent permission=none for Clearfolio, consistent with the ordinary request-reviewers 422. Do not retry that collaborator API route unless eligibility changes.
• protected central .github exact head 6eb06cdd08c79a06f7b390069d4ffa49e2eb7dba contains scripts/ci/opencode_existing_approval_gate.py. The gate explicitly recognizes only opencode-agent / opencode-agent[bot] as OpenCode approval publication actors and accepts reuse only when the GitHub review is APPROVED, its commit_id equals the exact current head, the body contains the real-model approval marker/result/head/run/attempt, and structured adversarial validation passes. Deterministic/model-unavailable fallbacks are explicitly rejected.
• This proves the central architecture intentionally distinguishes a real exact-head OpenCode formal approval from generic bot comments/checks. It does not yet prove GitHub's current Clearfolio protected-branch rule will count a newly delivered App approval as the required write-authorized review; that remains the live acceptance test after one of the fresh fix(security): harden audit pseudonymization and refresh Netty evidence #270/docs: establish canonical product, architecture, and acquisition spine #305/fix(openapi): align buyer contract license metadata #316 invocations completes.

The next governance proof therefore stays narrow: central trusted-comment dispatch -> exact-head formal OpenCode review -> ordinary protected merge/auto-merge acceptance, with no branch mutation or policy weakening.

[seonghobae]

Fresh counted-review route probe — 2026-08-10

Revalidated the organization-governance candidate route against a new technically clean Clearfolio PR rather than relying on predecessor evidence.

• Probe PR: chore: superseded by current-base KPI ledger PR #339 #330 fix(analytics): reject invalid persisted KPI numerics
• Exact head: 66c7afc6eeb1e5862e414d14e7d236e275536082
• Protected main observed for this PR: 83ec6f7fe2b04bdcd28bf98ec350e41e55730a18
• Exact-head CI, Security Scan, SAST Semgrep, and fuzz are all successful.
• Formal reviews: none; unresolved inline review threads: none.
• Auto-merge is enabled through ordinary protection.

A fresh ordinary GitHub reviewer request to team independent-reviewers returned HTTP 422:

Reviews may only be requested from collaborators. One or more of the teams you specified is not a collaborator of the ContextualWisdomLab/clearfolio repository.

This confirms that the organization-level target team is still not provisioned as a counted collaborator on Clearfolio. No review rule was weakened and no bot/author identity was substituted. The executable external prerequisite remains the one already defined by .github#772: provision a genuinely independent human reviewer team with the minimum permission GitHub counts, then request an exact-head approval. Until that happens, clean PRs may remain auto-merge armed but policy-blocked while other product work continues.