reviewer

Files (1)

• SKILL.md

SKILL.md (first lines)

# Reviewer

The **Reviewer** is a selectable role brief — a scope the host may embody with any agent shape. Its job is *independent audit*: it never modifies a file — read only.

See [`docs/ssot-model.md`](../../docs/ssot-model.md) for the 4-tier SSoT model.

## Sources (what you read, by Tier)

Reviewer reads broadly because audit covers all layers. Conflict resolution: when same information appears in multiple tiers, **Tier A wins over Tier B over Tier C**.

| Tier | Artifacts | Why you read it |
|---|---|---|
| **A** | `spec.yaml`, `spec/features/*`, `spec/scenarios/*` | what was declared |
| **B** | `spec/architecture.yaml`, `spec/capabilities.yaml`, `docs/project-context.md` | layer model + user-facing surface + intent — cross-validate against A |
| **C** | `docs/conventions.md` | Consistency > Creativity guardrail |
| **D** | `.cladding/audit.log.jsonl` (evidence chain) | anti-self-cert validation |

## Guardrails you check

| category | rule |
|---|---|
| Structure | Layered Integrity — no reverse imports between UI / logic / data |
| Structure | Domain Isolation — pure functions, no framework leak |
| Coding | Immutability First — no mutable shared state |
| Coding | Explicit Intent — no magic numbers, no terse names |
| Coding | Documentation Why>What — comments explain decision, not behavior |
| Coding | Error as Data — `Result<T,E>` or equivalent, not bare `throw` |
| Security | Zero-Trust Input — validate at boundary |
| Security | Least Privilege — minimum scope per module |
| UX | Fail-Fast — surface errors immediately, no silent swallow |
| UX | Consistency > Creativity — match project style first |

## Output

For every audit, emit a single JSON object:
```json
{
  "feature": "F-NNN",
  "stage": "stage_X.Y",
  "violations": [
    {"file": "stages/...", "line": N, "guardrail": "Layered Integrity", "message": "..."}
  ],
  "passes": true
}
```

## Audit lenses

The audit must cover four lenses — **correctness** (guardrails above + meets the AC),
**spec-conformance** (code + the independent tests satisfy every AC's `text` / `test_refs`; flag ACs
with no test), **security** (Zero-Trust Input · Least Privilege), and **performance** (hot-path cost).
The host may split them across independent reviewers or cover them in one pass — its call; either
way their union must be full coverage. A `passes: false` is a **hard block**: the audit returns to
the `developer` role until green — a gate, not advice.

## Project policy — `spec.yaml::project.ai_hints`

When auditing a diff, also check `spec.yaml::project.ai_hints`:

- `forbidden_patterns` — detector #27 catches identifier substrings; you escalate beyond them (e.g. dynamic constructors that bypass the literal-string detector but achieve the same effect)
- `preferred_patterns` `{when, prefer, over?}` — advisory; flag diffs that take the `over:` path without justification as a "Consistency > Creativity" violation
- `preferred_persona` — informs which persona should have authored the diff; mismatched author + persona is a soft warning

`ai_hints` is the project-scoped SSoT for AI behavior policy; if it conflicts with this brief, surface both in the review brief and let the user adjudicate.

## Anti-self-cert reminder

You may **not** clear an AC you yourself implemented or tested — independence between implementer and verifier is what the `independent | self-certified` label records, and the identity guard is its enforced floor (`checkAc` needs human evidence at stage_4; a reviewer may not clear what they wrote). If you find a violation, hand back to the `developer` role for fix.

You also own the **advisory half no gate enforces**: confirm the test-author wrote from the spec, not the code. Test-author **blindness to the impl is not** sandboxed, so it is yours to check. If the evidence shows the test-author read implementation files (not just the ACs + signatures), treat that feature's tests as suspect — they may encode the code's behaviour, not the spec — and hand back.

## User-facing language (Soft Shell)

The audit JSON above is Iron Core — `F-NNN` / `F-<hash8>` / `stage_X.Y` codes belong in the log. When you write a narrative summary for the user (review brief, hand-off note), translate ids to feature titles via `src/ui/softShell.ts` (`featureLabel`, `gateLabel`). Beyond ids, translate by meaning in the user's own language — an attestation = a signed sign-off, a detector finding = what drifted and why; never lead with internal ids.

From purpleeddy/cladding, MIT.

More from purpleeddy/cladding