@cloverleaf/reference-impl 0.8.6 → 0.10.0

package/lib/prep-worktree.ts

@@ -95,48 +95,69 @@ function buildMissingNodeModulesError(mainRoot: string): Error {
 }
 
 export function prepWorktree(mainRoot: string, worktreePath: string): void {
-  const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
-  const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
+  const embedded =
+    existsSync(join(worktreePath, 'standard', 'package.json')) &&
+    existsSync(join(worktreePath, 'reference-impl', 'package.json'));
 
-  if (!existsSync(wtStandardPkg)) {
-    throw new Error(`worktree missing standard/package.json at ${wtStandardPkg}`);
-  }
-  if (!existsSync(wtRefImplPkg)) {
-    throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
+  // configRoot is where .cloverleaf/config/discovery.json is read from. Embedded mode
+  // walks up to the primary repo (which holds node_modules + the config); a non-monorepo
+  // consumer uses mainRoot directly.
+  let configRoot: string;
+  if (embedded) {
+    const resolvedMain = findPrimaryRoot(mainRoot);
+    if (resolvedMain === null) {
+      throw buildMissingNodeModulesError(mainRoot);
+    }
+    configRoot = resolvedMain;
+  } else {
+    configRoot = mainRoot;
   }
 
-  // Resolve the actual primary repo root: start from mainRoot and walk up until we find a
-  // directory containing both standard/node_modules and reference-impl/node_modules.
-  const resolvedMain = findPrimaryRoot(mainRoot);
-  if (resolvedMain === null) {
-    throw buildMissingNodeModulesError(mainRoot);
+  const config = loadDiscoveryConfig(configRoot);
+
+  if (embedded) {
+    // Embedded / monorepo mode: prime the cloverleaf TS tooling (unchanged behavior).
+    copyEmbeddedArtifacts(configRoot, worktreePath);
   }
 
-  const mainStandardNm = join(resolvedMain, 'standard', 'node_modules');
-  const mainRefImplNm = join(resolvedMain, 'reference-impl', 'node_modules');
+  // Both modes: copy any gitignored dirs the consumer's tests/briefs reference.
+  copyPrepDirs(configRoot, config.prep_copy_dirs, worktreePath);
 
-  const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
-  const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
+  if (embedded) {
+    // Build standard/ fresh from the worktree's own sources.
+    execSync('npm run build', {
+      cwd: join(worktreePath, 'standard'),
+      stdio: 'pipe',
+    });
+  }
+
+  // Both modes: run the consumer's worktree setup command, if configured.
+  if (config.worktree_setup_command.trim() !== '') {
+    execSync(config.worktree_setup_command, {
+      cwd: worktreePath,
+      stdio: 'pipe',
+    });
+  }
+}
 
-  // verbatimSymlinks keeps relative symlink targets byte-identical, so the @cloverleaf/standard
-  // link in reference-impl/node_modules/ resolves against the worktree after copy.
-  //
-  // primeCopy wipes the destination before cpSync. Two reasons:
-  //   1. Idempotence: a partial prior run (or a re-invocation after a test failure) may
-  //      leave partial state; we must not trip on it.
-  //   2. cpSync with verbatimSymlinks: true does not reliably overwrite an existing
-  //      symlink at the destination even with force: true (CLV-20 Reviewer repro was
-  //      EEXIST on vite/node_modules/.bin on second invocation).
-  primeCopy(mainStandardNm, wtStandardNm);
-  primeCopy(mainRefImplNm, wtRefImplNm);
+/**
+ * Embedded / monorepo mode: copy the primary repo's installed cloverleaf TS deps + built
+ * dist into the worktree, preserving the @cloverleaf/standard relative symlink. (See the
+ * file header for the CLV-16/17/37/52 history.)
+ */
+function copyEmbeddedArtifacts(resolvedMain: string, worktreePath: string): void {
+  primeCopy(join(resolvedMain, 'standard', 'node_modules'), join(worktreePath, 'standard', 'node_modules'));
+  primeCopy(join(resolvedMain, 'reference-impl', 'node_modules'), join(worktreePath, 'reference-impl', 'node_modules'));
   primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
+}
 
-  // Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory
-  // (e.g., docs/superpowers) from mainRoot into the worktree. Walker briefs reference
-  // these paths but git checkouts of main don't carry gitignored content.
-  const discoveryConfig = loadDiscoveryConfig(resolvedMain);
-  for (const dir of discoveryConfig.prep_copy_dirs) {
-    const srcPath = join(resolvedMain, dir);
+/**
+ * Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory from
+ * configRoot into the worktree. Missing entries warn and are skipped.
+ */
+function copyPrepDirs(configRoot: string, dirs: string[], worktreePath: string): void {
+  for (const dir of dirs) {
+    const srcPath = join(configRoot, dir);
     const dstPath = join(worktreePath, dir);
     if (!existsSync(srcPath)) {
       process.stderr.write(`prep-worktree: prep_copy_dirs entry '${dir}' not found at ${srcPath} — skipping.\n`);
@@ -144,11 +165,6 @@ export function prepWorktree(mainRoot: string, worktreePath: string): void {
     }
     primeCopy(srcPath, dstPath);
   }
-
-  execSync('npm run build', {
-    cwd: join(worktreePath, 'standard'),
-    stdio: 'pipe',
-  });
 }
 
 function primeCopy(src: string, dst: string): void {

package/lib/qa-report.ts

@@ -1,3 +1,6 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
 export interface QaRunResult {
   ruleId: string;
   command: string;
@@ -39,6 +42,18 @@ function renderRow(r: QaRunResult): string {
   `;
 }
 
+/**
+ * Read a QA runs JSON file (array of QaRunResult), render the HTML report, and write it to
+ * outHtmlPath, creating the parent directory if needed. Lets QA write its report via the
+ * cloverleaf-cli bin instead of importing a monorepo dist path.
+ */
+export function writeQaReportFromFile(runsJsonPath: string, outHtmlPath: string): void {
+  const runs = JSON.parse(readFileSync(runsJsonPath, 'utf-8')) as QaRunResult[];
+  const html = renderQaReport(runs);
+  mkdirSync(dirname(outHtmlPath), { recursive: true });
+  writeFileSync(outHtmlPath, html, 'utf-8');
+}
+
 export function renderQaReport(runs: QaRunResult[]): string {
   const empty = runs.length === 0
     ? `<p class="empty">No runs / results.</p>`

package/lib/rfc-tasks.ts

@@ -6,8 +6,7 @@ import type { PlanDoc } from './plan.js';
 
 /**
  * A task is "standalone" (RFC-direct) iff it has no parent (absent or null)
- * AND it has a non-empty context.rfc.id. See
- * docs/superpowers/specs/2026-05-12-rfc-direct-tasks-design.md §"Discriminator".
+ * AND it has a non-empty context.rfc.id.
  */
 export function isStandaloneTask(task: TaskDoc): boolean {
   const parent = (task as Record<string, unknown>).parent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.8.6",
+  "version": "0.10.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/implementer.md

@@ -8,6 +8,7 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
 - `feedback`: optional — the most recent feedback envelope from a prior Reviewer bounce. If present, address every finding before re-submitting.
 - `repo_root`: absolute path to the consumer repo.
 - `base_branch`: the branch to branch off (default: `main`).
+- `test_rules`: a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries (from `qa-rules.json`).
 
 ## Your process
 
@@ -26,7 +27,7 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
 2. If `feedback` is present, re-read each finding; plan how to address them.
 3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.
 4. Implement the code + tests needed to satisfy every acceptance criterion.
-5. Run the project's test command (typically `npm test` — check package.json `scripts.test`). All tests must pass.
+5. Run the project's tests. Your test rules are provided as `{{test_rules}}` — a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries; each `match` is a list of glob patterns. For each rule whose `match` covers a file you changed, run its `command` in its `cwd`. All must pass. (If no rule matches your changes, there is nothing to run.)
 6. Stage and commit your changes with message `feat: <task.title> [<task.id>]`.
 7. Return a structured JSON result to stdout:
 
@@ -54,5 +55,5 @@ If you cannot complete the task:
 - Do NOT open a PR.
 - Do NOT modify `.cloverleaf/` — state transitions are the skill's job.
 - Do NOT skip tests or write placeholder tests. Every acceptance criterion must be covered by a real, meaningful test.
-- Work within the existing project patterns. If the repo has a tsconfig, package.json scripts, or test conventions, follow them.
+- Work within the existing project patterns. Follow the repo's existing conventions — its configuration, scripts, and test layout.
 - Small, focused commits are preferred but a single well-scoped commit is acceptable for this task.

package/prompts/qa.md

@@ -25,11 +25,11 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
    Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
 
-1. Set up isolated worktree and prepare its node_modules + standard/dist. The `prep-worktree`
-   helper copies main's `standard/node_modules` and `reference-impl/node_modules` into the
-   worktree and runs the standard build script so the @cloverleaf/standard symlink resolves
-   correctly inside the worktree. (Without this, `tsc` fails with `Cannot find module
-   '@cloverleaf/standard/validators/index.js'` because git worktrees don't inherit node_modules.)
+1. Set up an isolated worktree and prime it so the project's tests can run. The
+   `prep-worktree` helper prepares the worktree's dependencies (for a TypeScript monorepo it
+   copies the built tooling; for other projects it runs the configured `worktree_setup_command`
+   and copies any `prep_copy_dirs`). Without it, a fresh worktree may lack the dependencies the
+   tests need.
    ```bash
    TMPDIR=$(mktemp -d)
    SHA=$(git rev-parse {{branch}})
@@ -50,8 +50,8 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
    - Run it in `"$TMPDIR/<cwd>"`
    - Capture stdout, stderr, exit code
    - Parse test output to extract `passed`, `failed`, `total`:
-     - Vitest: `Tests  N passed | M failed (T)` or similar
-     - npm build: treat exit 0 as `{passed: 1, failed: 0, total: 1}`, non-zero as `{passed: 0, failed: 1, total: 1}`
+     - Exit code is the universal signal: exit 0 = the command's checks passed; non-zero = failed.
+     - When the output format is recognized, also extract counts, e.g. Vitest (`Tests N passed | M failed`), pytest (`N passed, M failed`), or a plain build/lint (exit 0 → `{passed: 1, failed: 0, total: 1}`).
    - On failure, collect up to 10 failure names/messages as findings with `severity: "error"` and `rule: "qa.<suite>.<test-name>"`
 
 5. Aggregate results: sum `passed`, `failed`, `total` across all runs.
@@ -59,7 +59,7 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 6. Compute verdict:
    - `pass` — every command exited 0 AND aggregated `failed === 0`
    - `bounce` — any command exited non-zero OR `failed > 0`; findings list the first ~10 failures
-   - `escalate` — any command failed deterministically on 3 consecutive retries (attempt the rerun yourself), OR `npm ci` itself failed (infrastructure problem)
+   - `escalate` — any command failed deterministically on 3 consecutive retries (attempt the rerun yourself), OR the worktree setup itself failed (infrastructure problem)
 
 7. Teardown:
    ```bash
@@ -72,17 +72,25 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 - Read-only. Do NOT edit source files.
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the worktree, even on error.
-- **Loading or running a module directly.** Do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither and fails with `ERR_MODULE_NOT_FOUND`. Use `npx tsx` instead (already in the worktree's `node_modules`): it resolves `.ts` sources **and** the project's `.js`-style import specifiers, so the natural import works. Run it from the worktree's `reference-impl/` directory; for anything the test suite already covers, prefer `npm test`.
+- **Loading or running a module directly (TypeScript projects).** If your project is TypeScript, do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither. Use `npx tsx` instead (resolves `.ts` sources and `.js`-style import specifiers):
 
   ```bash
   npx tsx -e "import('./lib/<module>.js').then(m => console.log(Object.keys(m)))"
   ```
 
+  For other ecosystems, use your language's module-load or REPL equivalent. For anything the test suite already covers, prefer running the tests.
+
 ## QA Report (v0.4)
 
 After executing all matched QA rules, write an HTML report summarizing each run to `<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html` (substitute `{taskId}` with the `id` field from the task input, e.g., `{{task.id}}`).
 
-Use `renderQaReport(runs)` from `lib/qa-report.ts` to produce the HTML. The compiled artifact is at `<repoRoot>/reference-impl/dist/qa-report.mjs` — invoke via `node --input-type=module` or import from there. Ensure the output directory exists first (`mkdir -p`).
+Write the runs array (one `{ruleId, command, cwd, durationMs, passed, stdoutTail, stderrTail}` object per executed command) to a temp JSON file, then generate the report via the CLI:
+
+```bash
+cloverleaf-cli qa-report /tmp/cl-qa-runs-{taskId}.json "<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html"
+```
+
+The CLI creates the output directory.
 
 In the feedback you emit, include the report as an attachment on a single info-level finding (or on whichever summary finding you already emit):
 

package/prompts/reviewer.md

@@ -8,6 +8,7 @@ You are the Cloverleaf Reviewer agent. Your job: perform a fresh-eyes review of
 - `branch`: the branch name the Implementer produced (e.g., `cloverleaf/DEMO-001`).
 - `base_branch`: the branch to diff against (default: `main`).
 - `repo_root`: absolute path to the consumer repo.
+- `test_rules`: a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries (from `qa-rules.json`).
 
 ## Your process
 
@@ -49,15 +50,16 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
 - You are a fresh pair of eyes. Do not rubber-stamp. If you have substantive doubts, bounce.
 - Check that tests actually cover the AC; a passing test suite with no AC coverage is a bounce.
 - Do NOT modify any files. You are read-only.
-- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree and prime it with `cloverleaf-cli prep-worktree` (copies main's node_modules + builds standard/dist inside the worktree — without this, `tsc` fails with `Cannot find module '@cloverleaf/standard/validators/index.js'`):
+- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree and prime it with `cloverleaf-cli prep-worktree` (prepares the worktree so the project's tests can run):
 
   ```bash
   MAIN=$(pwd)
   SHA=$(git rev-parse cloverleaf/<task-id>)
   git worktree add --detach /tmp/cl-review-<task-id> "$SHA"
   cloverleaf-cli prep-worktree "$MAIN" /tmp/cl-review-<task-id>
-  cd /tmp/cl-review-<task-id>/reference-impl
-  npm test
+  # Run the project's tests. Your rules are in {{test_rules}} (JSON object { rules: [{cwd, match, command}, ...] }).
+  # For each rule whose match globs cover a changed file, run its command in
+  # /tmp/cl-review-<task-id>/<cwd>.
   cd -
   git worktree remove /tmp/cl-review-<task-id>
   ```
@@ -65,10 +67,12 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
   Use `--detach` with a SHA rather than a branch name: when running inside a walker worktree, the feature branch (and main) may already be checked out in another worktree, causing `git worktree add` to fail with "fatal: branch … is already checked out". Detaching at a SHA bypasses this constraint entirely.
 
   This keeps `.cloverleaf/` on main intact.
-- **Loading or running a module directly.** Do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither and fails with `ERR_MODULE_NOT_FOUND`. Use `npx tsx` instead (already in the worktree's `node_modules`): it resolves `.ts` sources **and** the project's `.js`-style import specifiers, so the natural import works. Run it from the worktree's `reference-impl/` directory; for anything the test suite already covers, prefer `npm test`.
+- **Loading or running a module directly (TypeScript projects).** If your project is TypeScript, do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither. Use `npx tsx` instead (resolves `.ts` sources and `.js`-style import specifiers):
 
   ```bash
   npx tsx -e "import('./lib/<module>.js').then(m => console.log(Object.keys(m)))"
   ```
+
+  For other ecosystems, use your language's module-load or REPL equivalent. For anything the test suite already covers, prefer running the tests.
 - Severities (per the Cloverleaf feedback schema): `blocker` = wrong behavior / missing AC / broken tests; `error` = notable defect that should be fixed but doesn't break AC; `warning` = should fix; `info` = nit / style. Use `blocker` and `error` for bounces.
 - If a criterion is subjective, lean toward pass — the task author chose those words deliberately.

package/skills/cloverleaf-implement/SKILL.md

@@ -23,6 +23,16 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
    ```
    Capture the output. If present and the latest verdict is `bounce`, pass it into the subagent.
 
+3b. Load the project's test rules (consumer override or shipped default):
+   ```bash
+   if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
+     cat "<repo_root>/.cloverleaf/config/qa-rules.json"
+   else
+     cat "$(cloverleaf-cli plugin-root)/config/qa-rules.json"
+   fi
+   ```
+   Capture the output as `test_rules`.
+
 4. Dispatch the Implementer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
@@ -31,6 +41,7 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
      - `{{feedback}}` → the feedback JSON if present, else the literal string `null`
      - `{{repo_root}}` → absolute path to the current repo
      - `{{base_branch}}` → `main` (or the current default branch)
+     - `{{test_rules}}` → the test rules JSON captured in step 3b
 
    **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
 

package/skills/cloverleaf-review/SKILL.md

@@ -37,10 +37,20 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
    ```
    Capture this output for the subagent.
 
+4b. Load the project's test rules (consumer override or shipped default):
+   ```bash
+   if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
+     cat "<repo_root>/.cloverleaf/config/qa-rules.json"
+   else
+     cat "$(cloverleaf-cli plugin-root)/config/qa-rules.json"
+   fi
+   ```
+   Capture the output as `test_rules`.
+
 5. Dispatch the Reviewer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
-   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`, `{{test_rules}}`.
 
    **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
 

package/skills/cloverleaf-run/SKILL.md

@@ -57,9 +57,11 @@ Recovery sequence:
 
 2. Load task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "pending"`. If not, report and stop.
 
-3. Read `task.risk_class`:
-   - `"low"` → go to section 4 (Fast Lane)
-   - `"high"` → go to section 5 (Full Pipeline)
+3. **Council gate detection (opt-in).** Run `cloverleaf-cli council-plan <repo_root> <TASK-ID> task.review` and parse the JSON plan. If `plan.source === "consumer"` **and** `plan.profile !== null`, the project has opted into a configured review council — drive the review phase via **section 7 (Council review path)** instead of the hardcoded reviewer/security/ui/qa steps in sections 4/5. Otherwise (`source: "default"`, or no `task.review` binding) proceed exactly as today:
+   - `task.risk_class === "low"` → section 4 (Fast Lane)
+   - `task.risk_class === "high"` → section 5 (Full Pipeline)
+
+   When the council path is active it still uses the Implementer (and, for the full pipeline, the Documenter) to produce the branch; only the review→merge portion is council-driven.
 
 ### 4. Fast Lane
 
@@ -122,6 +124,35 @@ Loop:
 - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> escalated (bounce budget exhausted)"`.
 - Report: "✗ Escalated `<TASK-ID>`. Review `.cloverleaf/feedback/` and either refine the task or take over manually. Counters: reviewer=<N>, ui_reviewer=<N>, qa=<N>, security=<N>."
 
+### 7. Council review path (opt-in; active when council-plan source is "consumer")
+
+Initialize `council_bounces = 0`.
+
+7.1 **Produce the branch.** Run the Implementer (`/cloverleaf-implement <TASK-ID>` steps); for `risk_class: "high"` also run the Documenter (`/cloverleaf-document <TASK-ID>` steps). The task reaches `review`.
+
+7.2 **Run the council members (verdict-only).** Re-run `cloverleaf-cli council-plan <repo_root> <TASK-ID> task.review` to get `plan.rounds`, `plan.aggregation`, `plan.on_round_bounce`. For each round **in order**, for each member in the round, dispatch the member's prompt as a **read-only** subagent and capture its `{verdict, summary, findings}` envelope — do **not** advance state:
+   - `reviewer` → `prompts/reviewer.md`, feedback prefix `r`
+   - `security` → `prompts/security-reviewer.md`, prefix `s`
+   - `ui` → `prompts/ui-reviewer.md`, prefix `u`
+   - `qa` → `prompts/qa.md`, prefix `q`
+
+   **Dispatch conventions:** invoke the Task tool in foreground (default — never `run_in_background`); do not poll with foreground `sleep`. Substitute `{{task}}`, `{{branch}}` (`cloverleaf/<TASK-ID>`), `{{base_branch}}` (`main`), `{{repo_root}}`, `{{diff}}` (`git diff main..cloverleaf/<TASK-ID> -- ':(exclude).cloverleaf/'`).
+
+   Persist each member's envelope: `echo '<envelope>' > /tmp/clv-council-<member>.json && cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/clv-council-<member>.json --prefix=<r|s|u|q>`. Collect a members array `[{ "member": "<id>", "verdict": "<pass|bounce|escalate>", "blocking": <plan member blocking>, "weight": <plan member weight> }]`.
+
+   **Short-circuit:** if any member returns `escalate`, stop immediately. Otherwise, after each round, if `plan.on_round_bounce === "stop"` and any **blocking** member in that round returned `bounce`, stop before the next round. Always finish the members already running in the current round (batched).
+
+7.3 **Aggregate.** Map `plan.aggregation` to the CLI rule argument: a string passes through; `{ "quorum": k }` → `quorum:k`. Run `cloverleaf-cli aggregate-verdicts '<members-json>' <rule>` and capture the council verdict JSON.
+
+7.4 **Apply.** Run `cloverleaf-cli apply-council-verdict <repo_root> <TASK-ID> task.review '<council-verdict-json>'`. The FSM walk may self-commit some transitions (e.g. `security_class → high`, the rework verdict-reset), so the wrap-up commit can find nothing staged — that is expected. Commit the remainder: `git add .cloverleaf/ && (git diff --cached --quiet || git commit -m "cloverleaf: <TASK-ID> council review (<verdict>)")`.
+
+7.5 **Branch on the task's new status (reload with `load-task`):**
+   - `automated-gates` (fast lane pass) or `final-gate` (full pipeline pass) → proceed to the merge: inline `/cloverleaf-merge <TASK-ID>`.
+   - `implementing` (bounce) → `council_bounces += 1`. If `council_bounces >= 3`, escalate (section 6). Else return to 7.1.
+   - `escalated` → stop and surface to the user (review `.cloverleaf/feedback/` and `.cloverleaf/runs/<TASK-ID>/council/task.review.json`).
+
+The council result artifact at `.cloverleaf/runs/<TASK-ID>/council/task.review.json` records per-member verdicts, the aggregate, and the security basis (incl. an omitted or out-voted `security` member). On any member-dispatch failure or unparseable envelope, stop and report — never treat a failed member as a pass.
+
 ## Rules
 
 - Each agent has its own 3-bounce budget. Bounces from different agents do NOT share counters.