Skip to content

v0.16.0 — Clarify rule line, reviewers always get their criteria, protects-only blockers

Latest

Choose a tag to compare

@dsifry dsifry released this 12 Nov 02:04
4bbb10a

Highlights: reviews stop and ask when the requirement is the problem (Clarify rule line, misunderstanding analysis, brainstorming assumption ledger); reviewers get their rubric and role criteria whatever the orchestrator writes; rubric BLOCKING rows block only with a protects that points outside the rubric.

Update: claude plugin marketplace update metaswarm-marketplace && claude plugin update metaswarm@metaswarm-marketplace, then restart Claude Code.

Added

  • Reviews now stop and ask when the requirement is the problem (#103). The review iteration rule gains a Clarify line (line 2, after the clean pass). It fires on four signals:
    • C1: a blocker needs the user (needs_user) or rests on an unconfirmed assumption;
    • C2: blocker totals are not converging over three rounds, or reviewers diverge (the total did not fall, one reviewer dropped to no blockers and another rose; a falling total never counts);
    • C3: fixes keep causing new blockers;
    • C4: the same theme recurs across rounds.
      Instead of a plain escalation, the gate writes a Clarification report with a misunderstanding analysis and five options. There is no approve or override option. "Keep going" never defaults a needs_user question. The escalation lines (3-5) gain a "Clarify the requirement / re-brainstorm" option, and the rule lines are now numbered 1 to 7 (they ran 1 to 6).
  • A deterministic helper applies the rule (#103). lib/review-rule.js reads a per-gate review-history file under .beads/context/review-history/ and prints the rule line, action and signals, so the orchestrator no longer does the signal arithmetic by hand. In the metaswarm repo it runs the working copy, elsewhere the installed plugin's copy.
  • Reviewers report signal fields (#103). Every finding carries theme. Blockers also carry needs_user, origin (implementation, requirement or assumption) and, when the blocker rests on an assumption, the ledger id. Only blockers feed the signals.
  • Brainstorming keeps an assumption ledger (#103). brainstorming-extension loads at the start of every brainstorming session with an assumption ledger, a confirmation rule and a Common misreadings checklist. The no-superpowers /brainstorm fallback applies them too.
  • Misreadings are learned per project (#103). A confirmed misunderstanding is stored in the project's knowledge base as a gotcha tagged misunderstanding, with an opt-in upstream issue.
  • Review history is recovered on resume (#103). /prime, /start-task, /start and /handoff read .beads/context/review-history/ so a clarify-pending gate re-asks its questions after compaction or in a new session, and the handoff names the open history files.

Fixed

  • Reviewers get their criteria even when the orchestrator paraphrases the prompt (#105). Orchestrators often summarise the gate templates, or send "read this brief and follow it exactly", and reviewers then skipped their rubric. In one session only 1 of 73 design reviewers opened theirs.
    • design-reviewer now carries every role's Review Criteria checklist and fills in a ### Criteria check table, one row per item.
    • plan-reviewer carries the adversarial plan rubric's Review Categories and fills in the same kind of table over its category's checks.
    • adversarial-reviewer now starts with the receipt and reads its mode's rubric file, because the rubric's classification tables set severity.
    • All three reviewer types put a Criteria applied: line right after the verdict heading, naming the rubric they applied. A review without it is re-requested once, then accepted with a follow-up, so it never blocks a gate.
    • A test fails when an embedded checklist drifts from its source.
    • evals/reviewer-rubric/ holds the eval behind the change. It runs by hand, never in CI. With planted defects, the missing test plan went from 0/3 to 3/3 caught, the missing API contract from 0/3 to 3/3, and the any type rated as the rubric requires from 0/3 to 3/3.
  • A rubric entry is not itself a requirement (#112). A "BLOCKING" row sets severity; the finding blocks only when protects names a DoD item, the spec, a credible user scenario, or a written project standard (CLAUDE.md, coding standards, lint or tsconfig settings). The adversarial, plan, external-tool and UX rubrics state this in their mapping line, so Codex and Gemini reviewers, which get the rubric but not the guide, see it too. The no-any row now blocks only when the project states the rule, and is advisory otherwise. Before, reviewers split on any in projects with no such rule.
  • The reviewer eval scores replies with a Haiku judge (#109). Regex scoring got cells wrong in both directions; a tool-less Haiku call now judges whether each planted defect is reported, for about $0.001 a trial. Calibration against 282 hand labels agreed on 279. Three published cells were corrected (see evals/reviewer-rubric/README.md).

Changed

  • The overengineering check now comes before the "two or more reviewers, so iterate" line (#103). The rule is: pass, clarify, cap, recurring or disputed, overengineering, then iterate (line 6 for a fixed critical/major finding or two or more reviewers, line 7 otherwise). Before, a round with blockers from two or more reviewers iterated before the overengineering check could run. This is a behaviour change: a round flagged overengineering now gets the check first.

Upgrading

/setup skips instruction files (CLAUDE.md, AGENTS.md, GEMINI.md) that already have a metaswarm section, and /update does not rewrite them. Re-running /setup will not do it either. Existing projects must update their instruction file by hand from the new templates (templates/CLAUDE.md, templates/AGENTS.md and templates/GEMINI.md in the metaswarm plugin):

  1. Replace "Delivery Scope & Review Iteration": the new bullet order, with Clarify after the clean pass.
  2. Add the new "During Brainstorming" section: it loads the brainstorming extension at the start of every session.
  3. CLAUDE.md only: replace the Context Recovery line, which now names the review history and clarify-pending.

Projects that generated phase agents (.claude/agents/metaswarm-*.md, from /setup or metaswarm-agents.sh generate) must run /update, or metaswarm-agents.sh generate, to pick up the reviewer criteria and the Criteria applied: receipt (#105). Role-type resolution uses those local copies first. Until they are regenerated, each review is re-requested once for the missing receipt. metaswarm-agents.sh check reports the copies as stale.