harness-judge

Files (1)

• SKILL.md

SKILL.md (first lines)

## Purpose

Orchestrate the judge phase: delegate a single focused review to `archon-judge`, optionally run mutation testing and Playwright E2E tests as quality gates, and automatically re-run `sdd-apply` with structured feedback on failure (up to 3 retries).

## Activation Contract

Load when the orchestrator reaches the `judge` phase after `sdd-verify` passes. This skill wraps existing skills — it does NOT reimplement review or apply logic.

The FIRST action on activation is Step 0: compute the full-track risk tier, then read the judge flag. If the judge phase is disabled, or the computed tier is skip-eligible and not lightened, this skill returns `skipped` immediately and the orchestrator advances to `archive`, then, after archive stages its commit on the branch, the PR is opened (single-PR flow).

## Hard Rules

- The judge phase is configurable. ALWAYS read `.archon/config.yaml` → `judge.enabled` as part of Step 0, before delegating any review. Default: `true` (run when the section is absent). When `judge.enabled: false`, SKIP the entire judge phase regardless of the computed risk tier — do NOT invoke `archon-judge`, mutation testing, or Playwright — and return `skipped` so the orchestrator advances from verify straight to archive.
- The judge phase only runs on the `full` track; a computed risk tier that is skip-eligible (full track, size small) MAY also skip or lighten it even when `judge.enabled` is not explicitly false. `bugfix` and `fast` never run judge regardless of tier.
- ALWAYS delegate a single focused review to the archon-judge subagent. Do NOT invoke judgment-day inline on the orchestrator's model. Do NOT run a dual or blind review.
- ALWAYS invoke `sdd-apply` for re-fixes. Do NOT apply fixes inline.
- ALWAYS invoke `sdd-verify` after each re-apply before re-judging.
- Mutation testing is OPT-IN. Read `.archon/config.yaml` → `mutation_testing.enabled`. Default: `false`. Skip entirely when disabled.
- Playwright E2E is OPT-IN and runs only for web projects. ALWAYS read `.archon/config.yaml` → `playwright.enabled` to decide whether to run it. Default: `false`. Skip entirely when disabled. These tests run AFTER verify and after the single judge review passes.
- Security gate is OPT-IN. Read `.archon/config.yaml` → `security.enabled`. Default: `false`. When `security.enabled` is true, treat any unresolved `@security` CRITICAL coverage gap (reported by `sdd-verify`) as a failing gate — do NOT advance to archive. When `security.enabled` is false, skip this check entirely and count it as `pass`.
- Maximum 3 retry cycles. The 4th failure returns `blocked` with `max_retries_exceeded: true`.
- NEVER skip the re-verify step between re-apply and re-judge.
- Accumulate all issues across retry cycles in the feedback block.

## Execution Steps

### Step 0: Judge Flag Gate (HARD GATE)

#### Step 0a: Compute the Risk Tier (full track only)

Before reading the `judge.enabled` flag, compute the per-change risk tier so the
flag check below has it available. This tiering applies to the `full` track only —
[[harness-fast-track]] and `[[harness-bugfix-track]]` never run judge regardless of
tier, which in practice means the orchestrator never invokes this skill for them at
all (neither track has a judge phase in its sequence — see [[harness-workflow]]).

1. Run `archon workflow status --change {change-name} --json` and read its `track`
   and `size` keys.
2. Resolve `track` using the SAME back-compat rule as `trackOrder()`
   (`internal/workflow/workflow.go`) and `harness-workflow/SKILL.md`'s Step 1:
   absent or empty `track` resolves as `full`. Do NOT compare the raw string to
   `"full"` literally — an empty string is `full`, not "some other track".
3. With the resolved track:
   - Resolved track != `full` (i.e. `bugfix` or `fast`) → this skill should never
     have been invoked for it at all (neither track has a judge phase in its
     sequence). Do not silently skip and do not guess a tier: STOP and report
     `blocked` with reason `harness-judge invoked on a non-full track — orchestrator
     routing bug` (same handling as Step 0b's parenthetical below; there is only
     one rule for this case, stated once here).
   - Resolved track == `full` and `size` is `substantial` or `unknown` (including
     absent/empty, which reads as `unknown`) → tier **requires judge**.
   - Resolved track == `full` and `size: small` → tier is **skip-eligible**.

#### Step 0b: Judge Flag Gate

Read `.archon/config.yaml` → `judge.enabled`:

```yaml
judge:
  enabled: true
```

By this point Step 0a has already exited (`blocked`) for any non-full track, so
everything below is scoped to the `full` track only. On the `full` track,
`judge.enabled: false` ALWAYS wins and short-circuits everything else, regardless of
the tier computed in Step 0a — this override is unchanged from before tiering
existed:

- `judge.enabled: false`: STOP. Do NOT invoke `archon-judge` or any gate — not even
  when the Step 0a tier would have required judge. Return the report below with
  **Verdict: `skipped`**, and exit — the orchestrator then runs
  `archon workflow complete --change {name}` to mark this `judge` phase completed
  (skipped, not reviewed) BEFORE `archon workflow advance --to archive`, exactly
  like any other phase's completion; then, after archive stages its commit on the
  branch, the PR is opened (single-PR flow).

  ```markdown
  ## Judge Phase Report

  **Change**: {change-name}
  **Verdict**: skipped
  **Reason**: judge phase disabled via `.archon/config.yaml` → `judge.enabled: false`
  ```

- `judge.enabled: true` (or the `judge` section is absent → default `true`): Step 0a
  already routed a non-full track to `blocked` before computing a tier, so by this
  point the resolved track is always `full`. The tier now decides:
  - Tier **requires judge** (full + substantial/unknown) → proceed to Step 1.
  - Tier **skip-eligible** (full + small) → the single judge review MAY be skipped or
    lightened; report `skipped` (mirroring the format above, with Reason:
    `skip-eligible risk tier (track: full, size: small)`) — the orchestrator then
    runs `archon workflow complete --change {name}` to mark `judge` completed before
    `archon workflow advance --to archive`, same as the `judge.enabled: false` path
    above — OR proceed to Step 1 with a lightened review — either is acceptable, but
    do NOT silently fall through without recording which path was taken in the
    report.

### Step 1: Read Configuration

Read `.archon/config.yaml` for the judge flag and the gate settings:

```yaml
judge:
  enabled: true
mutation_testing:
  enabled: false
  tool: gremlins
  threshold: 0.80
playwright:
  enabled: false
  test_dir: e2e
  base_url: http://localhost:3000
```

- `judge.enabled` controls whether the whole phase runs (see Step 0). Default: `true`.
- If the file or a gate section is missing, default that gate to `enabled: false`.

### Step 2: Delegate Single Review to archon-judge

From AlexCas/archon-ai, MIT.

More from AlexCas/archon-ai