review

name	review
description	Orchestrate β review in phases — contract integrity, then implementation, then verdict. Each phase loads its own sub-skill.
artifact_class	skill
kata_surface	external
governing_question	Is the branch coherent enough to merge, or what specific incoherence must be named and fixed?
visibility	internal
parent	cdd
triggers	["review","pr","approve","request changes"]
scope	task-local
inputs	["branch","issue","diff",".cdd/unreleased/{N}/ artifacts"]
outputs	["beta-review.md"]
requires	["β completed intake and skill loading","canonical CDD.md loaded"]
calls	["review/contract/SKILL.md","review/issue-contract/SKILL.md","review/diff-context/SKILL.md","review/architecture/SKILL.md"]
calls_dynamic	[{"source":"project design constraints"}]
kata_ref	src/packages/cnos.cdd.kata/katas/M2-review/

Review — Orchestrator

Core Principle

A review is a witnessed judgment, not a rubber stamp. The reviewer owes the same honesty discipline as the implementer: name what is wrong, trace it to evidence, and state what must change.

Review = tri(contract truth, implementation/projection evidence, witnessed verdict)

The review proceeds in three phases. Each phase loads its own sub-skill. Do not attempt all phases from memory — the sub-skills contain the detail.

---

Phases

Phase 1: Contract integrity

Load: review/contract/SKILL.md

Before reading the diff for implementation correctness, verify that the work contract (issue + PR body + branch summary) is internally consistent, truthful about status, and non-contradictory.

Complete the Contract Integrity table. If any row is "no," the review cannot approve unless the row is explicitly out of scope and the reviewer names why.

Phase 2: Implementation review

Phase 2 runs three sub-skills sequentially. Load each in order:

1. review/issue-contract/SKILL.md — issue contract walk (AC coverage, named doc updates, CDD artifact contract, active skill consistency)
2. review/diff-context/SKILL.md — diff and context inspection (structural closure, multi-format parity, snapshot consistency, stale paths, authority conflicts, architecture leverage, design constraints)
3. review/architecture/SKILL.md — architecture and design check (7 questions A–G; load cnos.core/skills/design/SKILL.md when active)

Walk the issue contract (ACs, named docs, CDD artifacts). Read the diff and its neighbors. Apply mechanical scans, architecture checks, and evidence-bound findings.

Phase 3: Verdict

Return to this file for verdict rules and output format.

---

Verdict Rules

3.1. Every claim traces to evidence

• No "seems wrong." Point to a line, commit, file, artifact, or behavior.

3.2. Name the severity

• D — blocker, demonstrable incoherence
• C — significant incoherence, non-blocking
• B — improvement opportunity
• A — polish

3.3. All findings must be resolved before merge

• APPROVED is a conjunction: APPROVED means (a) all issue ACs are met and (b) zero findings at any severity remain unresolved. A verdict with unresolved C, B, or A findings is internally contradictory — the Severity table declares all of C/B/A "not merge-ready until fixed." APPROVED+unresolved-finding is not a valid verdict form.
• There is no "approved with follow-up."
• D findings block merge. C/B/A findings must be fixed on-branch before merge.
• Only exception: finding requires a design decision outside issue scope → "deferred by design scope," author files issue before merge.

3.4. Verdict before details

• Lead with APPROVED / REQUEST CHANGES.

3.4a. Verdict-shape lint

Three invalid verdict shapes — each auto-RC:

• APPROVED + unresolved findings at any severity — contradicts 3.3 (all D/C/B/A must be fixed on-branch).
• APPROVED + conditional qualifier — conditional, pending, modulo, subject to, assuming, provisional on, with follow-up smuggle in an unresolved finding 3.3 forbids.
• Split verdicts — two terminal verdicts in one round (e.g. APPROVED for scope X, REQUEST CHANGES for scope Y). One round, one decision.

Recovery: any conditional or split shape becomes REQUEST CHANGES; each named condition is reformatted as a required-fix finding at its severity. The reviewer re-emits a single terminal verdict in the next round once findings clear.

Derives from: tsc #53 β@S4 — "APPROVED with 3 unresolved C findings + conditional language." Rules 3.3/3.4 banned the shape implicitly; no explicit lint enumerated the conditional qualifiers or the split-verdict form.

3.5. No phantom blockers

• Only block on incoherence you can demonstrate.

3.6. Approve when coherent, not when perfect

• The bar is coherence, not taste.

3.7. Close the search space on approval

• Approval explicitly states that no remaining blocker was found in the relevant contract.

3.8. Evidence depth matches claim strength

• structural claim → unit/schema proof may suffice
• runtime behavior claim → path/integration proof required
• operator contract claim → output/projection/state artifact required

3.9. Specify regression pairs for D-level findings

• Every D-level finding includes positive case + negative case.

3.10. CI-green gate (binding)

• β must verify required CI/build checks are green on review SHA before emitting verdict APPROVED.
• Run gh run list --branch <review-SHA> --json status,conclusion,workflow_name (or equivalent) and verify every required workflow has conclusion == "success".
• If any required workflow is red/pending/missing on review SHA → verdict is RC, finding B-severity, classification ci-status.
• Document the check in beta-review.md §CI status: one-line citation of run + conclusion.
• Required workflows determined by GitHub branch protection rules; fallback to "every workflow that runs on cycle branch" if no protection rules configured.

3.11. Merge instruction is explicit

• Names the exact branch and merge action with Closes #N in the merge commit.

3.11b. γ artifact completeness gate (binding)

• β must verify .cdd/unreleased/{N}/gamma-scaffold.md exists on the cycle branch before emitting verdict APPROVED.
• If gamma-scaffold.md is missing → verdict is RC, finding D-severity, classification protocol-compliance.
• Rationale: Prevents protocol bypass where δ dispatches α→β directly without γ coordination. Missing γ artifacts indicate the cycle did not follow the canonical triadic protocol (cnos.cds/skills/cds/CDS.md §"Field 6: Actor collapse rule").
• Scope: This gate applies to all cycles except explicit protocol exemptions.
• Exemption discoverability: An exemption satisfies 3.11b only if it appears in one of the following auditable surfaces:
  • (i) Sub-issue body (canonical §5.1 dispatch) — the body of the cycle's own issue, or the body of any issue γ links from the dispatch prompt as authority for the cycle. A comment on a parent / master / tracking issue does NOT satisfy exemption discoverability on this path: β reviews the sub-issue β was dispatched against, not the parent tree, and master comments are not part of the cycle's load surface. Derives from: tsc #49 F2 — four β subagents diverged on a cycle where the exemption lived as a parent-issue comment; β@S1 read 3.11b literally (D-severity RC), β@S2/S3/S4 accepted the master comment (B non-blocker). The rule did not specify which issue body counts, so divergence was structural, not careless.
  • (ii) Wave manifest under §5.2 wave-mode — for any cycle running as a sub of a wave under operator/SKILL.md §5.2 wave-mode (γ=δ collapse permitted; per cnos.cds/skills/cds/CDS.md §"Field 6: Actor collapse rule" with γ-coordinator and δ-operator fused), the canonical γ-artifact-of-record is the wave manifest at .cdd/waves/{wave-id}/manifest.md plus the wave status (per operator/SKILL.md §10.2). β recognizes the wave manifest as discharging the same γ-artifact-of-record duty .cdd/unreleased/{N}/gamma-scaffold.md discharges under §5.1 — provided the discoverability link from sub-issue to wave manifest is itself auditable: either (a) the sub-issue body cites the wave by id (e.g. names .cdd/waves/{wave-id}/manifest.md or the wave title in ## Wave / ## Source / ## Related prose), OR (b) the master tracking issue named by the wave manifest links to the sub-issue (e.g. via GitHub sub-issue relations, a wave-tracking comment thread, or an explicit Issues: table in the manifest itself naming the sub). When (a) or (b) holds, the wave manifest's γ = δ permitted declaration (or equivalent wave-mode exemption text), pinned file-paths forward-reference contract, standing permissions, and timeout budgets satisfy the γ-artifact-of-record duty for every sub of that wave. Derives from: cph cdr-refactor wave 2026-05-18 (master usurobor/cph#11; subs cph#12, #13, #14, #15) — four-of-four sub-uniform §5.2 configuration with zero per-sub gamma-scaffold.md; β produced three distinct substantive-read justifications across the four subs (cph#12 beta-review.md §3.11b L133–158: wave-manifest-as-γ-artifact; cph#13 §Contract Integrity row 11: sub-issue-body exemption line; cph#14 §2.5 L187–195: cph-canonical-model three-part justification; cph#15 §2.0.0 row L29: uniform §5.2 wave-exempt). Three distinct β reads of the same wave-uniform configuration is a discoverability gap, not a β skill issue. cph#15 β-closeout L55 names the patch axis explicitly; wave-iteration F1 at usurobor/cph:.cdd/iterations/wave-2026-05-18.md consolidates the pattern.
• Recovery paths when 3.11b RC fires: either (a) γ (or δ-as-γ) authors the missing .cdd/unreleased/{N}/gamma-scaffold.md on the cycle branch before β re-dispatch, OR (b) γ amends the sub-issue body to add an explicit ## Protocol exemption section naming the reason (e.g. emergency patch, infrastructure-only change with operator override) and β re-dispatches against the amended body, OR (c) under §5.2 wave-mode, γ ensures the wave manifest at .cdd/waves/{wave-id}/manifest.md exists with a wave-mode exemption declaration AND establishes the sub-issue ↔ wave-manifest discoverability link per (ii) above. Path (a) is canonical for §5.1 dispatch; path (b) is the escape valve for cycles that legitimately bypass γ scaffolding; path (c) is canonical for §5.2 wave-mode dispatch and does not require per-sub scaffolds.
• Document the check in beta-review.md §Artifact completeness: citation of gamma-scaffold.md presence/absence under §5.1, OR — under §5.2 wave-mode — citation of the wave manifest path AND the discoverability-link surface (sub-issue body wave-id cite OR master-tracking-issue link to sub); if a 3.11b exemption is claimed via sub-issue body §Protocol exemption section, cite that section.

3.12. Review divergence is a skill gap

• When two reviewers diverge, the fix is a patch to the review skill, not "be more careful."

3.13. Honest-claim verification

Documents claim things; β verifies the claims are backed by code, data, or canonical source. Three sub-checks, all binding:

• (a) Reproducibility — Every measurement quoted in a doc must be reproducible from artifacts in this commit. If the doc says "engine output = 0.83", the run that produced 0.83 must be runnable from the diff with provenance attached. A measurement with no reproduction path is a D-level finding.
• (b) Source-of-truth alignment — Every term used in a non-spec doc must trace to its canonical definition. Drift between informal and normative usage is a D-level finding (e.g. "W2 spread" used inconsistently with cnos.cdd/skills/.../W2 spec definition).
• (c) Wiring claims — If a module documents "X is wired into Y", β grep-checks that X actually appears in Y's call graph. A doc lying about wiring is the most expensive class of bug to find late, because consumers trust the doc and stop reading the code.
• (d) Gap claims — γ peer-enumeration rule applies symmetrically to α honest-claim verification. When β finds an existing surface that the cycle's §Gap claimed didn't exist, the finding is binding (B-severity minimum) and attributes to γ axis, not α. Gap-side claims ("X does not exist") must be backed by grep-evidence per gamma/SKILL.md §2.2a peer-enumeration discipline.

Failure mode this rule catches: α produces a narrative document (release note, self-coherence report, post-release assessment, runtime spec) whose prose is internally consistent but whose claims are not backed by what the cycle actually shipped. The supercycle in cnos-tsc surfaced this pattern across multiple cycles — three of four findings on the v3.2.0 self-coherence report cycle were honest-claim violations (undeclared artifact, score discrepancy, missing provenance attachment).

---

Finding Taxonomy

Type	Definition	Examples
mechanical	Caught by grep/diff/script	stale path, wrong branch name, broken link
judgment	Requires design/coherence assessment	missing AC, authority conflict, design trade-off
contract	Work contract is incoherent	issue contradiction, PR overclaim, draft-as-current, exception contradicts hard gate, proof plan missing
honest-claim	Doc claims something code/data doesn't back (rule 3.13)	non-reproducible measurement, term used inconsistently with spec, wiring claim that grep disproves

Contract and honest-claim findings may overlap with mechanical or judgment — tag both when applicable.

Mechanical findings reaching review are process bugs. If >20% of findings in a cycle are mechanical, file a process issue.

---

Severity

Sev	Meaning	Merge readiness
D	Demonstrable incoherence	not merge-ready
C	Real incoherence, locally non-blocking	not merge-ready until fixed
B	Improvement opportunity	not merge-ready until fixed
A	Polish	not merge-ready until fixed

---

Output Format

Written to .cdd/unreleased/{N}/beta-review.md incrementally. Each review pass (contract, implementation, verdict) is a separate commit+push to the cycle branch. Do not write the entire review in one generation — stream timeouts will discard partial work.

Incremental write discipline:

1. Write each pass as a separate operation (§2.0.0 Contract → §2.1 Implementation → Verdict)
2. Commit and push after each pass
3. If resuming after a failure, read what exists on the branch and continue from the last committed pass

Each round appends a new section.

**Verdict:** APPROVED / REQUEST CHANGES

**Round:** N
**Fixed this round:** {commit hashes} closes {prior findings}
**Branch CI state:** green / provisional
**Merge instruction:** `git merge {branch}` into main with `Closes #{issue}`

## §2.0.0 Contract Integrity

| Check | Result | Notes |
|---|---|---|
| Status truth preserved | yes / no / n/a | |
| Canonical sources/paths verified | yes / no / n/a | |
| Scope/non-goals consistent | yes / no / n/a | |
| Constraint strata consistent | yes / no / n/a | |
| Exceptions field-specific/reasoned | yes / no / n/a | |
| Path resolution base explicit | yes / no / n/a | |
| Proof shape adequate | yes / no / n/a | |
| Cross-surface projections updated | yes / no / n/a | |
| No witness theater / false closure | yes / no / n/a | |
| PR body matches branch files | yes / no / n/a | |
| γ artifacts present (gamma-scaffold.md) | yes / no / n/a | rule 3.11b compliance |

## §2.0 Issue Contract

### AC Coverage
| # | AC | In diff? | Status | Notes |
|---|----|----------|--------|-------|

### Named Doc Updates
| Doc / File | In diff? | Status | Notes |
|------------|----------|--------|-------|

### CDD Artifact Contract
| Artifact | Required? | Present? | Notes |
|----------|-----------|----------|-------|

### Active Skill Consistency
| Skill | Required by | Loaded? | Applied? | Notes |
|-------|-------------|---------|----------|-------|

## Findings

| # | Finding | Evidence | Severity | Type |
|---|---------|----------|----------|------|

## Regressions Required (D-level only)

## Notes

---

Checklist

Before submitting a review:

• Phase 1 (contract integrity) completed before Phase 2
• §2.0.0 Contract integrity table filled
• Status truth checked: shipped/current/draft/planned/non-goal not conflated
• Source-of-truth paths resolve and match canonical docs
• Issue/PR examples obey their own rules
• Hard gates do not appear in exception examples
• Path resolution base verified where paths are validated
• Proof plan includes oracle, positive, negative where required
• New CI/check/status surfaces update operator-visible projections
• PR body matches corrected branch files
• No witness theater: structure backed by rejection mechanism or honest caveat
• Every issue AC verified (met, partial, missing, deferred)
• Required named docs/files checked
• CDD artifacts exist and are internally consistent
• Mechanical diff scan: duplicates, branch names, snapshot plausibility
• Every claim traces to evidence
• Honest-claim verification (3.13a): every quoted measurement reproducible from this commit
• Honest-claim verification (3.13b): every term used in a non-spec doc traces to canonical source
• Honest-claim verification (3.13c): every wiring claim grep-verified
• Severity assigned to every finding
• Type assigned to every finding (mechanical / judgment / contract / honest-claim)
• D-level findings include regression test pairs
• CI/build checks green on review SHA (binding gate per rule 3.10)
• Approval explicitly closes the search space
• Merge instruction names branch and merge action
• Verdict stated first
• Verdict-shape lint passed (no APPROVED + unresolved findings; no conditional qualifier; no split verdict) per rule 3.4a

---

After Review

• Approved: β merges branch into main with Closes #N, pushes, proceeds to release per release/SKILL.md.
• Changes requested: α fixes on branch, appends to self-coherence.md; β narrows on next round.

Review identity

β uses a different git identity than α — different role names in the email local part. The canonical form is {role}@{project}.cdd.cnos (or the cnos elision {role}@cdd.cnos); see operator/SKILL.md §Git identity for role actors for the full prescription, rationale, and worked examples. The role separation is git-observable. The two-level form from cycle #287 is deprecated as of cycle #343.

---

External kata

Practice and evaluation for this review skill live in:

src/packages/cnos.cdd.kata/katas/M2-review/

That kata exercises the contract-integrity preflight, implementation review, architecture check, finding taxonomy, active-skill consistency, and evidence-depth rules. The frontmatter kata_ref field above carries the same path for machine-readable linkage.