@cloverleaf/reference-impl 0.11.1 → 0.12.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
   "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge, release).",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/VERSION

@@ -1 +1 @@
-0.11.1
+0.12.0

package/dist/council.mjs

@@ -6,6 +6,7 @@ import { loadTask, saveTask, advanceStatus } from './task.mjs';
 import { writeCouncilResult } from './council-result.mjs';
 import { resolveChairPrompt } from './chair.mjs';
 import { classifyTaskSecurity } from './security-classify.mjs';
+import { writeFeedback } from './feedback.mjs';
 import { loadAffectedRoutesConfig, computeAffectedRoutes } from './affected-routes.mjs';
 import { getPluginRoot } from './plugin-path.mjs';
 export function evaluateWhen(predicate, ctx) {
@@ -56,6 +57,18 @@ const BUILTIN_PROMPTS = {
     ui: 'ui-reviewer.md',
     qa: 'qa.md',
 };
+/**
+ * Council gate → FSM binding (parent-spec §8). The declarative binding layer,
+ * NOT an FSM interpreter: the one decisive gate's transitions remain the lane
+ * logic in applyCouncilVerdict. `advisoryOnly` gates (plan_review's reject,
+ * final_gate's merge/reject are human-only) are forced to advisory regardless
+ * of the binding — a fail-safe honoring "human gates are always advisory".
+ */
+export const GATE_DESCRIPTORS = {
+    'task.review': { state: 'review', advisoryOnly: false },
+    'task.plan_review': { state: 'tactical-plan', advisoryOnly: true },
+    'task.final_gate': { state: 'final-gate', advisoryOnly: true },
+};
 /**
  * Resolve a council member to the absolute path of its prompt. A member with a
  * `prompt` field is a custom role → <repoRoot>/.cloverleaf/prompts/<file> (exist-checked,
@@ -80,7 +93,9 @@ export function resolveMemberPrompt(member, repoRoot) {
 export function resolveCouncilPlan(repoRoot, taskId, gateKey = 'task.review', opts = {}) {
     const { config, source } = loadCouncilConfigWithSource(repoRoot);
     const task = loadTask(repoRoot, taskId);
-    const { profile: profileName, mode } = resolveBinding(config.gates[gateKey], task);
+    const binding = resolveBinding(config.gates[gateKey], task);
+    const profileName = binding.profile;
+    const mode = GATE_DESCRIPTORS[gateKey]?.advisoryOnly ? 'advisory' : binding.mode;
     const empty = {
         gate: gateKey, profile: null, mode, rounds: [],
         aggregation: 'any-veto', on_round_bounce: 'stop', source,
@@ -134,10 +149,14 @@ export function resolveCouncilPlan(repoRoot, taskId, gateKey = 'task.review', op
  * to the result artifact. Walks the minimal legal path to the lane's pre-merge state.
  */
 export function applyCouncilVerdict(repoRoot, taskId, gate, council) {
-    if (gate !== 'task.review') {
-        throw new Error(`apply-council-verdict: gate '${gate}' is not supported yet — the FSM walk is hardcoded for the ` +
-            `task.review → merge lane. Binding other gates needs a gate-aware walk (council Slice 3).`);
+    const desc = GATE_DESCRIPTORS[gate];
+    if (!desc) {
+        throw new Error(`apply-council-verdict: gate '${gate}' is not supported; supported gates: ${Object.keys(GATE_DESCRIPTORS).join(', ')}.`);
     }
+    if (desc.advisoryOnly) {
+        return postAdvisoryVerdict(repoRoot, taskId, gate, desc.state, council);
+    }
+    // Decisive gate (task.review) — the existing lane logic below is unchanged.
     const task = loadTask(repoRoot, taskId);
     if (task.status !== 'review') {
         throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected 'review'`);
@@ -198,3 +217,45 @@ export function applyCouncilVerdict(repoRoot, taskId, gate, council) {
     writeCouncilResult(repoRoot, taskId, result);
     return result;
 }
+/**
+ * Advisory-gate terminal step (Slice 3): record the council verdict + post a
+ * feedback envelope, and drive NO transition — the human owns every transition
+ * at an advisory gate. The verdict (including an escalate) is recorded verbatim;
+ * because nothing is transitioned, the un-lowerable-escalate invariant holds
+ * trivially. Used for task.plan_review (at tactical-plan) and task.final_gate
+ * (at final-gate) — both advisory-only in the current FSM.
+ */
+export function postAdvisoryVerdict(repoRoot, taskId, gate, expectedState, council) {
+    const task = loadTask(repoRoot, taskId);
+    if (task.status !== expectedState) {
+        throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected '${expectedState}' for advisory gate '${gate}'`);
+    }
+    const m = taskId.match(/^(.+)-(\d+)$/);
+    if (!m)
+        throw new Error(`apply-council-verdict: invalid taskId '${taskId}'`);
+    const project = m[1];
+    writeFeedback(repoRoot, {
+        project,
+        taskId,
+        prefix: 'c',
+        envelope: { verdict: council.verdict, summary: council.rationale, findings: [] },
+    });
+    const result = {
+        gate,
+        mode: 'advisory',
+        final_verdict: council.verdict,
+        rule: council.rule,
+        rationale: council.rationale,
+        members: council.members.map((mm) => ({
+            member: mm.member,
+            verdict: mm.verdict,
+            blocking: mm.blocking !== false,
+            weight: mm.weight ?? 1,
+        })),
+        walk: [expectedState],
+        walk_note: 'advisory: verdict posted; human drives the transition',
+        ...(council.forward !== undefined ? { forward: council.forward } : {}),
+    };
+    writeCouncilResult(repoRoot, taskId, result);
+    return result;
+}

package/lib/council-result.ts

@@ -13,14 +13,15 @@ export interface CouncilResultMember {
 
 export interface CouncilResult {
   gate: string;
+  mode?: 'decisive' | 'advisory'; // omitted ⇒ decisive (back-compat); 'advisory' for posted-only gates
   final_verdict: Verdict;
   rule: ThresholdRule | 'chair';
   rationale: string;
   members: CouncilResultMember[];
-  walk: string[]; // states walked, e.g. ["review","automated-gates","qa","final-gate"]
-  walk_note?: string; // set when a state was traversed administratively (e.g. qa with no qa member)
+  walk: string[]; // states walked, e.g. ["review","automated-gates","qa","final-gate"]; [state] for advisory
+  walk_note?: string; // set when a state was traversed administratively, or the advisory note
   forward?: string[]; // chair-curated forwarded member ids (bounce only)
-  security: {
+  security?: { // present for the decisive task.review lane; omitted for advisory gates
     member_verdict: Verdict | 'absent';
     gating_verdict_set: 'pass' | null; // security_review_verdict the council set, if any
     basis: string; // human-readable explanation of the security decision

package/lib/council.ts

@@ -7,6 +7,7 @@ import { loadTask, saveTask, advanceStatus } from './task.js';
 import { writeCouncilResult, type CouncilResult } from './council-result.js';
 import { resolveChairPrompt } from './chair.js';
 import { classifyTaskSecurity } from './security-classify.js';
+import { writeFeedback } from './feedback.js';
 import { loadAffectedRoutesConfig, computeAffectedRoutes } from './affected-routes.js';
 import { getPluginRoot } from './plugin-path.js';
 
@@ -83,6 +84,24 @@ const BUILTIN_PROMPTS: Record<string, string> = {
   qa: 'qa.md',
 };
 
+interface GateDescriptor {
+  state: string; // the task status a gate's council runs at
+  advisoryOnly: boolean; // true when the gate's only legal transitions are human-driven
+}
+
+/**
+ * Council gate → FSM binding (parent-spec §8). The declarative binding layer,
+ * NOT an FSM interpreter: the one decisive gate's transitions remain the lane
+ * logic in applyCouncilVerdict. `advisoryOnly` gates (plan_review's reject,
+ * final_gate's merge/reject are human-only) are forced to advisory regardless
+ * of the binding — a fail-safe honoring "human gates are always advisory".
+ */
+export const GATE_DESCRIPTORS: Record<string, GateDescriptor> = {
+  'task.review': { state: 'review', advisoryOnly: false },
+  'task.plan_review': { state: 'tactical-plan', advisoryOnly: true },
+  'task.final_gate': { state: 'final-gate', advisoryOnly: true },
+};
+
 /**
  * Resolve a council member to the absolute path of its prompt. A member with a
  * `prompt` field is a custom role → <repoRoot>/.cloverleaf/prompts/<file> (exist-checked,
@@ -114,7 +133,10 @@ export function resolveCouncilPlan(
   const { config, source } = loadCouncilConfigWithSource(repoRoot);
   const task = loadTask(repoRoot, taskId) as unknown as Record<string, unknown>;
 
-  const { profile: profileName, mode } = resolveBinding(config.gates[gateKey], task);
+  const binding = resolveBinding(config.gates[gateKey], task);
+  const profileName = binding.profile;
+  const mode: 'decisive' | 'advisory' =
+    GATE_DESCRIPTORS[gateKey]?.advisoryOnly ? 'advisory' : binding.mode;
   const empty: CouncilPlan = {
     gate: gateKey, profile: null, mode, rounds: [],
     aggregation: 'any-veto', on_round_bounce: 'stop', source,
@@ -178,12 +200,16 @@ export function applyCouncilVerdict(
   gate: string,
   council: CouncilVerdict,
 ): CouncilResult {
-  if (gate !== 'task.review') {
+  const desc = GATE_DESCRIPTORS[gate];
+  if (!desc) {
     throw new Error(
-      `apply-council-verdict: gate '${gate}' is not supported yet — the FSM walk is hardcoded for the ` +
-      `task.review → merge lane. Binding other gates needs a gate-aware walk (council Slice 3).`,
+      `apply-council-verdict: gate '${gate}' is not supported; supported gates: ${Object.keys(GATE_DESCRIPTORS).join(', ')}.`,
     );
   }
+  if (desc.advisoryOnly) {
+    return postAdvisoryVerdict(repoRoot, taskId, gate, desc.state, council);
+  }
+  // Decisive gate (task.review) — the existing lane logic below is unchanged.
   const task = loadTask(repoRoot, taskId);
   if (task.status !== 'review') {
     throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected 'review'`);
@@ -246,3 +272,53 @@ export function applyCouncilVerdict(
   writeCouncilResult(repoRoot, taskId, result);
   return result;
 }
+
+/**
+ * Advisory-gate terminal step (Slice 3): record the council verdict + post a
+ * feedback envelope, and drive NO transition — the human owns every transition
+ * at an advisory gate. The verdict (including an escalate) is recorded verbatim;
+ * because nothing is transitioned, the un-lowerable-escalate invariant holds
+ * trivially. Used for task.plan_review (at tactical-plan) and task.final_gate
+ * (at final-gate) — both advisory-only in the current FSM.
+ */
+export function postAdvisoryVerdict(
+  repoRoot: string,
+  taskId: string,
+  gate: string,
+  expectedState: string,
+  council: CouncilVerdict,
+): CouncilResult {
+  const task = loadTask(repoRoot, taskId);
+  if (task.status !== expectedState) {
+    throw new Error(
+      `apply-council-verdict: task ${taskId} is '${task.status}', expected '${expectedState}' for advisory gate '${gate}'`,
+    );
+  }
+  const m = taskId.match(/^(.+)-(\d+)$/);
+  if (!m) throw new Error(`apply-council-verdict: invalid taskId '${taskId}'`);
+  const project = m[1];
+  writeFeedback(repoRoot, {
+    project,
+    taskId,
+    prefix: 'c',
+    envelope: { verdict: council.verdict, summary: council.rationale, findings: [] },
+  });
+  const result: CouncilResult = {
+    gate,
+    mode: 'advisory',
+    final_verdict: council.verdict,
+    rule: council.rule,
+    rationale: council.rationale,
+    members: council.members.map((mm) => ({
+      member: mm.member,
+      verdict: mm.verdict,
+      blocking: mm.blocking !== false,
+      weight: mm.weight ?? 1,
+    })),
+    walk: [expectedState],
+    walk_note: 'advisory: verdict posted; human drives the transition',
+    ...(council.forward !== undefined ? { forward: council.forward } : {}),
+  };
+  writeCouncilResult(repoRoot, taskId, result);
+  return result;
+}

package/package.json

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

package/skills/cloverleaf-run/SKILL.md

@@ -116,7 +116,7 @@ Loop:
   c. If `status === "implementing"`: QA bounced. `qa_bounces += 1`. If `qa_bounces >= MAX_QA_BOUNCES`, escalate. Else return to section 5.1.
   d. Else: unexpected. Report and stop.
 
-5.4. **Final merge:** Inline `/cloverleaf-merge <TASK-ID>` steps (branches to full-pipeline gate per state).
+5.4. **Final merge:** First run the **Advisory `final_gate` council** (§7.6) if a consumer has bound `task.final_gate`. Inline `/cloverleaf-merge <TASK-ID>` steps (branches to full-pipeline gate per state).
 
 ### 6. Escalation
 
@@ -130,7 +130,7 @@ 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`, and (for a chair profile) `plan.chair`. For each round **in order**, for each active member in the round, dispatch its prompt at `plan.rounds[<round>][<member>].promptPath` as a **read-only** subagent and capture its `{verdict, summary, findings}` envelope — do **not** advance state. (Built-in members resolve to the shipped `reviewer`/`security-reviewer`/`ui-reviewer`/`qa` prompts; a custom role resolves to `.cloverleaf/prompts/<file>.md`.)
+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`, and (for a chair profile) `plan.chair`. For each round **in order**: dispatch **all active members in the round concurrently** — issue their Task-tool calls **in a single message** so the harness runs them in parallel — and capture each member's `{verdict, summary, findings}` envelope. Do **not** advance state. Rounds still run in sequence; only members *within* a round are concurrent. (Built-in members resolve to the shipped `reviewer`/`security-reviewer`/`ui-reviewer`/`qa` prompts; a custom role resolves to `.cloverleaf/prompts/<file>.md`.)
 
    **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/'`).
 
@@ -154,6 +154,17 @@ Initialize `council_bounces = 0`.
 
 On a chair **bounce**, the result artifact's `forward` array names the members whose feedback the Implementer should prioritize; the chair `rationale` frames them. The council result artifact at `.cloverleaf/runs/<TASK-ID>/council/task.review.json` records per-member verdicts, the aggregate (or chair) verdict, `forward` (for a chair bounce), 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.
 
+### 7.6 Advisory `final_gate` council (opt-in; full pipeline only)
+
+`final-gate` is reached only in the full pipeline and is already the human merge pause. Before inlining `/cloverleaf-merge <TASK-ID>` at a full-pipeline final gate (both here at 7.5 and at §5.4), check for an advisory council:
+
+1. `cloverleaf-cli council-plan <repo_root> <TASK-ID> task.final_gate`.
+2. If `plan.source !== "consumer"` or `plan.profile === null`, skip — proceed to the plain human merge (today's behavior).
+3. Otherwise dispatch `plan.rounds` per §7.2 (parallel within a round), reviewing `{{diff}}` = `git diff main..cloverleaf/<TASK-ID> -- ':(exclude).cloverleaf/'`, and reach a verdict per §7.3 (chair) or §7.4-style `aggregate-verdicts` (deterministic). Then `cloverleaf-cli apply-council-verdict <repo_root> <TASK-ID> task.final_gate '<council-verdict-json>'`. This **posts** the advisory result to `.cloverleaf/runs/<TASK-ID>/council/task.final_gate.json` + a feedback envelope and **drives no transition** (the task stays at `final-gate`). Commit: `git add .cloverleaf/ && (git diff --cached --quiet || git commit -m "cloverleaf: <TASK-ID> advisory final_gate council (<verdict>)")`.
+4. Surface the council verdict + rationale to the human at the merge confirmation. The human still drives `/cloverleaf-merge` (merge) or reject; the advisory council never merges.
+
+The **fast lane's** `human_merge` (`automated-gates → merged`) is not a council gate. `task.plan_review` (advisory, at `tactical-plan`) is supported at the CLI/library level (`council-plan task.plan_review`, `apply-council-verdict task.plan_review`) for a consumer with a human checkpoint at `tactical-plan`; it is not auto-inserted into this autonomous runner.
+
 ## Rules
 
 - Each agent has its own 3-bounce budget. Bounces from different agents do NOT share counters.