@cloverleaf/reference-impl 0.11.1 → 0.13.0

package/lib/cli.ts

@@ -8,7 +8,7 @@
  *   load-task <repoRoot> <taskId>
  *   infer-project <repoRoot>
  *   next-task-id <repoRoot> [--project=<p>]
- *   advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]
+ *   advance-status <repoRoot> <taskId> <toStatus> <actor> [gate]
  *   write-feedback <repoRoot> <taskId> <envelopeJsonPath>
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
@@ -47,6 +47,7 @@
  *   apply-council-verdict <repoRoot> <taskId> <gate> <councilVerdictJson>
  *   chair-context <chairMemberInputsJson>
  *   chair-verdict <chairRawJson> <membersJson>
+ *   validate-council <repoRoot>
  */
 
 import { readFileSync, mkdirSync, copyFileSync, appendFileSync, existsSync } from 'node:fs';
@@ -80,7 +81,9 @@ import type { SiblingScope } from './scope-check.js';
 import { computeRfcTasksView, type RfcTasksView } from './rfc-tasks.js';
 import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.js';
 import { classifyTaskSecurity } from './security-classify.js';
-import { resolveCouncilPlan, applyCouncilVerdict } from './council.js';
+import { resolveCouncilPlan, applyCouncilVerdict, GATE_DESCRIPTORS } from './council.js';
+import { loadCouncilConfigWithSource } from './council-config.js';
+import { validateCouncilConfig } from '@cloverleaf/standard/validators/index.js';
 import { aggregate, type MemberVerdict, type ThresholdRule, type CouncilVerdict } from './aggregation.js';
 import { buildChairContext, finalizeChairVerdict, type ChairMemberInput, type ChairRawVerdict } from './chair.js';
 
@@ -97,7 +100,7 @@ function usage(msg?: string): never {
       '  load-task <repoRoot> <taskId>\n' +
       '  infer-project <repoRoot>\n' +
       '  next-task-id <repoRoot> [--project=<p>]\n' +
-      '  advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]\n' +
+      '  advance-status <repoRoot> <taskId> <toStatus> <actor> [gate]\n' +
       '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
       '  latest-feedback <repoRoot> <taskId>\n' +
       '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
@@ -135,7 +138,8 @@ function usage(msg?: string): never {
       '  apply-council-verdict <repoRoot> <taskId> <gate> <councilVerdictJson>\n' +
       '  chair-context <chairMemberInputsJson>\n' +
       '  chair-verdict <chairRawJson> <membersJson>\n' +
-      '  set-task-field <repoRoot> <taskId> <field> <value>\n'
+      '  set-task-field <repoRoot> <taskId> <field> <value>\n' +
+      '  validate-council <repoRoot>\n'
   );
   process.exit(2);
 }
@@ -182,16 +186,15 @@ try {
     }
 
     case 'advance-status': {
-      const [repoRoot, taskId, toStatus, actorArg, gate, path] = rest;
+      const [repoRoot, taskId, toStatus, actorArg, gate] = rest;
       if (!repoRoot || !taskId || !toStatus || !actorArg)
-        usage('advance-status requires <repoRoot> <taskId> <toStatus> <actor> [gate] [path]');
+        usage('advance-status requires <repoRoot> <taskId> <toStatus> <actor> [gate]');
       if (actorArg !== 'agent' && actorArg !== 'human') {
         die(`actor must be 'agent' or 'human' (got '${actorArg}')`, 2);
       }
       const actor: 'agent' | 'human' = actorArg;
-      const opts: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {};
+      const opts: { gate?: string } = {};
       if (gate) opts.gate = gate;
-      if (path === 'fast_lane' || path === 'full_pipeline') opts.path = path;
       const updated = advanceStatus(repoRoot, taskId, toStatus, actor, opts);
       process.stdout.write(updated.status + '\n');
       break;
@@ -923,6 +926,23 @@ try {
       break;
     }
 
+    case 'validate-council': {
+      const [repoRoot] = rest;
+      if (!repoRoot) usage('validate-council requires <repoRoot>');
+      const { config } = loadCouncilConfigWithSource(repoRoot);
+      const gd = Object.fromEntries(
+        Object.entries(GATE_DESCRIPTORS).map(([k, d]) => [k, { kind: d.kind ?? 'code' }]),
+      );
+      const result = validateCouncilConfig(config as never, gd);
+      if (result.ok) {
+        process.stdout.write('council config OK\n');
+      } else {
+        for (const v of result.violations) process.stderr.write(`${v.rule}: ${v.message}\n`);
+        process.exit(1);
+      }
+      break;
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/council-config.ts

@@ -11,6 +11,7 @@ export type WhenPredicate = 'always' | 'security_class:high' | 'ui_changes';
 export interface CouncilMember {
   member: string; // built-in id ('reviewer' | 'security' | 'ui' | 'qa') or a custom role id
   prompt?: string; // custom-role prompt filename, resolved under .cloverleaf/prompts/
+  kind?: 'code' | 'rfc' | 'plan'; // artifact kind this member reviews; default 'code'. A profile must be kind-homogeneous.
   when?: WhenPredicate; // default 'always'
   blocking?: boolean; // default true
   weight?: number; // default 1

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

@@ -4,10 +4,15 @@ import { join } from 'node:path';
 import { loadCouncilConfigWithSource, type CouncilConfig, type GateBinding, type WhenPredicate, type CouncilMember } from './council-config.js';
 import type { ThresholdRule, CouncilVerdict } from './aggregation.js';
 import { loadTask, saveTask, advanceStatus } from './task.js';
+import { loadPlan } from './plan.js';
+import { loadRfc } from './rfc.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 { loadQaRulesDocument } from './qa-rules.js';
+import { loadUiReviewConfig } from './ui-review-config.js';
 import { getPluginRoot } from './plugin-path.js';
 
 export interface ResolvedMember {
@@ -15,6 +20,14 @@ export interface ResolvedMember {
   blocking: boolean;
   weight: number;
   promptPath: string;
+  /**
+   * Tokens this member's prompt declares beyond the five the runner always supplies
+   * (task, branch, base_branch, repo_root, diff), resolved here rather than described
+   * in skill prose. Values are the literal strings to substitute. Empty for members
+   * whose prompt needs nothing extra, and for any token planning cannot resolve
+   * without side effects (see MEMBER_TOKENS).
+   */
+  substitutions: Record<string, string>;
 }
 
 export interface CouncilPlan {
@@ -76,13 +89,52 @@ export function resolveChangedFiles(repoRoot: string, taskId: string, opts: { ch
   }
 }
 
-const BUILTIN_PROMPTS: Record<string, string> = {
+/**
+ * The built-in council members and the shipped prompt each one resolves to.
+ * Exported as the single source of truth for "which members are built in":
+ * `tests/council.test.ts` walks it to assert every built-in prompt's declared
+ * tokens are covered by BASE_TOKENS ∪ MEMBER_TOKENS, so a prompt cannot gain a
+ * token that no one resolves.
+ */
+export const BUILTIN_PROMPTS: Record<string, string> = {
   reviewer: 'reviewer.md',
   security: 'security-reviewer.md',
   ui: 'ui-reviewer.md',
   qa: 'qa.md',
 };
 
+interface GateDescriptor {
+  state: string; // the work-item status a gate's council runs at
+  advisoryOnly: boolean; // true when the gate's only legal transitions are human-driven
+  kind?: 'code' | 'rfc' | 'plan'; // artifact kind the gate reviews; default 'code'
+}
+
+/**
+ * Council gate → FSM binding. `task.review` is the collapsed delivery council
+ * (decisive); `task.plan_review` is decisive-capable (agent bounce to pending);
+ * `task.final_gate` and the two discovery gates are advisory (post-only, human
+ * drives the transition). Advisory-only gates route to postAdvisoryVerdict.
+ */
+export const GATE_DESCRIPTORS: Record<string, GateDescriptor> = {
+  'task.review': { state: 'council', advisoryOnly: false },
+  'task.plan_review': { state: 'tactical-plan', advisoryOnly: false },
+  'task.final_gate': { state: 'final-gate', advisoryOnly: true },
+  'plan.task_batch': { state: 'task_batch_gate', advisoryOnly: true, kind: 'plan' },
+  'rfc.strategy_gate': { state: 'rfc_strategy_gate', advisoryOnly: true, kind: 'rfc' },
+};
+
+// Load any work item's status/doc by the gate's "type." prefix (task | plan | rfc).
+function workItemTypeOf(gate: string): 'task' | 'plan' | 'rfc' {
+  const t = gate.split('.')[0];
+  if (t === 'task' || t === 'plan' || t === 'rfc') return t;
+  throw new Error(`council: gate '${gate}' has no task/plan/rfc type prefix`);
+}
+function loadWorkItemDoc(repoRoot: string, type: 'task' | 'plan' | 'rfc', id: string): Record<string, unknown> {
+  if (type === 'plan') return loadPlan(repoRoot, id) as unknown as Record<string, unknown>;
+  if (type === 'rfc') return loadRfc(repoRoot, id) as unknown as Record<string, unknown>;
+  return loadTask(repoRoot, id) as unknown as Record<string, unknown>;
+}
+
 /**
  * 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,
@@ -105,16 +157,127 @@ export function resolveMemberPrompt(member: CouncilMember, repoRoot: string): st
   return join(getPluginRoot(), 'prompts', builtin);
 }
 
+/**
+ * Every extra token a built-in member's prompt may declare, beyond the five the
+ * runner always supplies. A union rather than `string` so `resolveSubstitutions`'s
+ * `default:` can be an exhaustiveness check: adding a token to MEMBER_TOKENS
+ * without a matching `case` is a typecheck failure, not a silently dropped key.
+ */
+export type MemberToken =
+  | 'test_rules'
+  | 'qa_rules'
+  | 'affected_routes'
+  | 'preview_port'
+  | 'ui_review_config'
+  | 'taskId';
+
+/**
+ * Extra tokens each built-in member's prompt declares, beyond the five the runner
+ * always supplies. Kept adjacent to the resolver so a prompt gaining a token is a
+ * one-line change in TS with a test behind it, rather than silent drift in skill prose.
+ *
+ * `preview_port` is listed because `ui-reviewer.md` genuinely declares it — but it is
+ * deliberately not resolved (see `resolveSubstitutions`). This map is the prompts'
+ * contract; the resolver is the subset planning can answer honestly.
+ *
+ * `tests/council.test.ts` pins this map against the prompts themselves: every
+ * `{{token}}` a built-in prompt declares must appear here or in BASE_TOKENS. That
+ * completeness check is what makes `cloverleaf-run` §7.2's "never dispatch with an
+ * unresolved token" rule safe — otherwise a prompt-only token stalls its member.
+ */
+export const MEMBER_TOKENS: Record<string, readonly MemberToken[]> = {
+  reviewer: ['test_rules'],
+  security: [],
+  qa: ['qa_rules'],
+  ui: ['affected_routes', 'preview_port', 'ui_review_config', 'taskId'],
+};
+
+interface SubstitutionContext {
+  /**
+   * Id of the work item under review. Always known at planning time, so
+   * `{{taskId}}` — `ui-reviewer.md`'s run-artifact directory
+   * (`.cloverleaf/runs/<id>/ui-review/`) — is always resolvable.
+   */
+  workItemId: string;
+  /**
+   * Routes this work item's diff affects, in the same `string[] | 'all'` encoding
+   * `cloverleaf-cli affected-routes` prints. Undefined for the discovery gates
+   * (plan/rfc), where no code diff is in scope.
+   */
+  affectedRoutes?: string[] | 'all';
+}
+
+/**
+ * Resolve a member's extra prompt tokens. Side-effect free by contract: it reads
+ * config and reuses values the plan already computed, and never allocates, writes,
+ * or starts anything — `council-plan` is a query, and callers re-run it freely.
+ *
+ * A token that cannot be answered honestly at planning time is **omitted** rather
+ * than filled with a placeholder. An absent key leaves a visible `{{token}}` for
+ * whoever dispatches the member; a fabricated value is silently wrong, which is the
+ * exact failure mode this map exists to prevent.
+ */
+function resolveSubstitutions(
+  memberId: string,
+  repoRoot: string,
+  ctx: SubstitutionContext,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const token of MEMBER_TOKENS[memberId] ?? []) {
+    switch (token) {
+      // Both carry the qa-rules *document* (`{ rules: [...] }`) — the shape
+      // reviewer.md and qa.md document — not loadQaRulesConfig()'s bare array.
+      case 'test_rules':
+      case 'qa_rules':
+        out[token] = JSON.stringify(loadQaRulesDocument(repoRoot));
+        break;
+      case 'ui_review_config':
+        out[token] = JSON.stringify(loadUiReviewConfig(repoRoot));
+        break;
+      case 'affected_routes':
+        // Diff-dependent, so available only on a code gate; the plan already
+        // computed it to evaluate the `ui_changes` predicate.
+        if (ctx.affectedRoutes !== undefined) out[token] = JSON.stringify(ctx.affectedRoutes);
+        break;
+      case 'taskId':
+        // The run-artifact directory ui-reviewer.md writes its state.json sidecar
+        // into. A pure value already in hand, so it is always resolved: leaving it
+        // literal makes lib/ui-review-state.ts read a path that cannot exist, and
+        // the baselines-hold then fails open.
+        out[token] = ctx.workItemId;
+        break;
+      case 'preview_port':
+        // Deliberately unresolved: there is no configured preview port and no
+        // side-effect-free way to derive one — lib/ports.ts offers only
+        // getFreePort(), which *allocates*. Whoever dispatches the ui member
+        // allocates it there, as the standalone ui-review skill does.
+        break;
+      default: {
+        // Exhaustiveness guard. A token added to MEMBER_TOKENS with no case above
+        // would otherwise be dropped silently — the exact drift this map exists to
+        // prevent — so make it a compile error instead.
+        const unhandled: never = token;
+        throw new Error(`council: no resolver for member token '${String(unhandled)}'`);
+      }
+    }
+  }
+  return out;
+}
+
 export function resolveCouncilPlan(
   repoRoot: string,
-  taskId: string,
+  workItemId: string,
   gateKey = 'task.review',
   opts: { changedFiles?: string[] } = {},
 ): CouncilPlan {
   const { config, source } = loadCouncilConfigWithSource(repoRoot);
-  const task = loadTask(repoRoot, taskId) as unknown as Record<string, unknown>;
+  const type = workItemTypeOf(gateKey);
+  const doc = loadWorkItemDoc(repoRoot, type, workItemId);
 
-  const { profile: profileName, mode } = resolveBinding(config.gates[gateKey], task);
+  const binding = resolveBinding(config.gates[gateKey], doc);
+  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,
@@ -131,11 +294,17 @@ export function resolveCouncilPlan(
     return empty; // unknown profile → fail toward today's behavior
   }
 
-  const changed = resolveChangedFiles(repoRoot, taskId, opts);
-  const securityHigh = classifyTaskSecurity(repoRoot, taskId, { changedFiles: changed }).effective === 'high';
-  const affected = computeAffectedRoutes(changed, loadAffectedRoutesConfig(repoRoot));
-  const uiChanges = affected === 'all' || affected.length > 0;
-  const ctx: WhenContext = { securityHigh, uiChanges };
+  // The when-context (security/ui) is a code-kind (task delivery) concern only.
+  // `affectedRoutes` outlives the predicate: the ui member's {{affected_routes}}
+  // token is the same value, so it is computed once and threaded to both.
+  let ctx: WhenContext = { securityHigh: false, uiChanges: false };
+  let affectedRoutes: string[] | 'all' | undefined;
+  if (type === 'task') {
+    const changed = resolveChangedFiles(repoRoot, workItemId, opts);
+    const securityHigh = classifyTaskSecurity(repoRoot, workItemId, { changedFiles: changed }).effective === 'high';
+    affectedRoutes = computeAffectedRoutes(changed, loadAffectedRoutesConfig(repoRoot));
+    ctx = { securityHigh, uiChanges: affectedRoutes === 'all' || affectedRoutes.length > 0 };
+  }
 
   const rounds: ResolvedMember[][] = [];
   for (const round of profile.rounds) {
@@ -146,6 +315,7 @@ export function resolveCouncilPlan(
         blocking: member.blocking !== false,
         weight: member.weight ?? 1,
         promptPath: resolveMemberPrompt(member, repoRoot),
+        substitutions: resolveSubstitutions(member.member, repoRoot, { workItemId, affectedRoutes }),
       }));
     if (active.length > 0) rounds.push(active);
   }
@@ -167,30 +337,44 @@ export function resolveCouncilPlan(
 
 /**
  * Drive the FSM transition implied by a council verdict (the runner's terminal step).
- * Council-authoritative: on a pass it records the council's gating verdict so the
- * v0.8.1 security precondition is satisfied for any high-security gated transition;
- * the per-member basis (incl. an omitted or out-voted `security` member) is written
- * to the result artifact. Walks the minimal legal path to the lane's pre-merge state.
+ * Routes by gate: `task.review` → the collapsed decisive delivery council; the
+ * decisive `task.plan_review` → the plan-review council; advisory-only gates
+ * (task.final_gate and the two discovery gates) → postAdvisoryVerdict, which
+ * records the verdict and drives no transition.
  */
 export function applyCouncilVerdict(
   repoRoot: string,
-  taskId: string,
+  workItemId: string,
   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, workItemId, gate, desc.state, council);
+  }
+  if (gate === 'task.plan_review') {
+    return applyDecisivePlanReview(repoRoot, workItemId, gate, council);
+  }
+  return applyDeliveryCouncil(repoRoot, workItemId, gate, council); // task.review — collapsed council phase
+}
+
+/** Decisive delivery council (task.review at the collapsed `council` state). */
+function applyDeliveryCouncil(repoRoot: string, taskId: string, gate: string, council: CouncilVerdict): CouncilResult {
   const task = loadTask(repoRoot, taskId);
-  if (task.status !== 'review') {
-    throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected 'review'`);
+  if (task.status !== 'council') {
+    throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected 'council'`);
   }
-  const lane: 'fast' | 'full' = task.risk_class === 'high' ? 'full' : 'fast';
   const securityMember = council.members.find((m) => m.member === 'security');
-  const walk: string[] = ['review'];
+  const highSecurity = task.security_class === 'high';
+  // No security verdict to report? Ask the profile what it intended — before any
+  // transition mutates the task the gate binding selects a profile from.
+  const plannedSecurity = securityMember === undefined ? resolvePlannedSecurity(repoRoot, taskId, gate) : null;
+  const walk: string[] = ['council'];
 
   if (council.verdict === 'escalate') {
     advanceStatus(repoRoot, taskId, 'escalated', 'agent');
@@ -199,45 +383,30 @@ export function applyCouncilVerdict(
     advanceStatus(repoRoot, taskId, 'implementing', 'agent');
     walk.push('implementing');
   } else {
-    // pass — minimal legal walk; review→automated-gates resets the security verdict,
-    // so set the council's gating verdict AFTER that transition.
-    advanceStatus(repoRoot, taskId, 'automated-gates', 'agent');
-    walk.push('automated-gates');
-    const atGates = loadTask(repoRoot, taskId);
-    atGates.security_review_verdict = 'pass';
-    saveTask(repoRoot, atGates);
-    if (lane === 'full') {
-      advanceStatus(repoRoot, taskId, 'qa', 'agent', { path: 'full_pipeline' });
-      walk.push('qa');
-      advanceStatus(repoRoot, taskId, 'final-gate', 'agent', { path: 'full_pipeline' });
-      walk.push('final-gate');
+    // pass → council → final-gate; record the council's authoritative security verdict for high tasks
+    // (the v0.8.1 guarantee's backstop, now that the FSM no longer enforces it mechanically).
+    advanceStatus(repoRoot, taskId, 'final-gate', 'agent');
+    walk.push('final-gate');
+    if (highSecurity) {
+      const atGate = loadTask(repoRoot, taskId);
+      atGate.security_review_verdict = 'pass';
+      saveTask(repoRoot, atGate);
     }
   }
 
-  const qaTraversedAdministratively =
-    lane === 'full' && walk.includes('qa') && !council.members.some((m) => m.member === 'qa');
-
   const result: CouncilResult = {
     gate,
     final_verdict: council.verdict,
     rule: council.rule,
     rationale: council.rationale,
-    members: council.members.map((m) => ({
-      member: m.member,
-      verdict: m.verdict,
-      blocking: m.blocking !== false,
-      weight: m.weight ?? 1,
-    })),
+    members: council.members.map((m) => ({ member: m.member, verdict: m.verdict, blocking: m.blocking !== false, weight: m.weight ?? 1 })),
     walk,
-    ...(qaTraversedAdministratively
-      ? { walk_note: 'qa state traversed administratively; no qa member ran' }
-      : {}),
     ...(council.forward !== undefined ? { forward: council.forward } : {}),
     security: {
       member_verdict: securityMember ? securityMember.verdict : 'absent',
-      gating_verdict_set: council.verdict === 'pass' ? 'pass' : null,
+      gating_verdict_set: council.verdict === 'pass' && highSecurity ? 'pass' : null,
       basis: !securityMember
-        ? 'no security member configured; advanced under council authority'
+        ? securityBasisWhenAbsent(plannedSecurity, council)
         : securityMember.verdict === 'pass'
           ? 'security member passed'
           : `security member returned '${securityMember.verdict}'; council ${council.verdict} by rule ${JSON.stringify(council.rule)}`,
@@ -246,3 +415,186 @@ export function applyCouncilVerdict(
   writeCouncilResult(repoRoot, taskId, result);
   return result;
 }
+
+/** What this gate's profile planned for the `security` member, for basis classification. */
+interface PlannedSecurity {
+  /** Round the `security` member is planned in, or null when it is not in the plan at all. */
+  securityRound: number | null;
+  /**
+   * Earliest planned round per member id. A stop rule explains security's absence only if
+   * it fired in a round that could actually have preceded security's own, so the round
+   * ordering — not merely the presence of a bouncing member — is what the basis checks.
+   */
+  memberRounds: Map<string, number>;
+  stopsOnRoundBounce: boolean;
+}
+
+/**
+ * Resolve what the profile bound to `gate` planned for the `security` member on this task.
+ *
+ * `council.members` names only the members that actually *ran*, so a missing security
+ * verdict is ambiguous on its own. The resolved plan disambiguates it — with one honest
+ * limitation: `resolveCouncilPlan` filters `when`-inactive members out, so a member
+ * excluded by its `when` predicate and a profile that never listed one both come back
+ * `planned: false`. Both are truthfully "no security member for this task", so they share
+ * one basis string rather than a distinction this cannot actually make.
+ *
+ * Two deliberate properties:
+ * - Returns null rather than throwing. Plan resolution reads consumer config and can fail
+ *   on, say, a mistyped member id; an audit string is not worth failing a terminal apply
+ *   step over, and a run whose plan will not resolve says exactly that.
+ * - Called only when there is no security verdict to explain: for a task-kind gate
+ *   `resolveCouncilPlan` runs a `git diff`, so this adds one git invocation to the apply
+ *   path, and it should stay at most one.
+ */
+function resolvePlannedSecurity(repoRoot: string, taskId: string, gate: string): PlannedSecurity | null {
+  try {
+    const plan = resolveCouncilPlan(repoRoot, taskId, gate);
+    // Earliest occurrence wins: if a member is planned twice, the first round is the
+    // earliest point the council could have run it.
+    const memberRounds = new Map<string, number>();
+    plan.rounds.forEach((round, index) => {
+      for (const m of round) if (!memberRounds.has(m.member)) memberRounds.set(m.member, index);
+    });
+    return {
+      securityRound: memberRounds.get('security') ?? null,
+      memberRounds,
+      stopsOnRoundBounce: plan.on_round_bounce === 'stop',
+    };
+  } catch (err) {
+    process.stderr.write(
+      `apply-council-verdict: could not resolve the council plan for gate '${gate}' on ${taskId} (${err instanceof Error ? err.message : String(err)}); the result artifact will record the security basis as unknown.\n`,
+    );
+    return null;
+  }
+}
+
+/**
+ * The `security.basis` for a run that recorded no security verdict. Each string states only
+ * what that run can prove, so a cause is named only when the run satisfies one of the
+ * council's two stop rules *in a round that could have preceded security's own*:
+ *
+ * - an `escalate` from any member stops the council immediately, so an escalator in an
+ *   earlier round — or in security's own round, cutting off a concurrently dispatched
+ *   member — explains the absence; one in a *later* round cannot, since that round ran only
+ *   because security's round completed;
+ * - a **blocking** `bounce` stops the council "before the next round" under
+ *   `on_round_bounce: stop`, so it explains the absence only from a *strictly earlier*
+ *   round. A same-round bounce cannot un-dispatch a member already running alongside it.
+ *
+ * Anything else — a non-blocking bounce, a stop rule that fired too late, a member the
+ * runner never dispatched or whose envelope was lost — leaves the absence unexplained, and
+ * the artifact says so rather than naming a cause that would point the auditor away from
+ * the real anomaly.
+ */
+function securityBasisWhenAbsent(planned: PlannedSecurity | null, council: CouncilVerdict): string {
+  if (planned === null) {
+    return 'no security member ran; the council plan could not be resolved, so whether one was configured is unknown';
+  }
+  const securityRound = planned.securityRound;
+  if (securityRound === null) {
+    // Covers both a profile with no security member and one excluded by its `when`
+    // predicate — indistinguishable here, and the wording claims no more than that.
+    const outcome =
+      council.verdict === 'bounce' ? 'council bounced to implementing'
+      : council.verdict === 'escalate' ? 'council escalated'
+      : 'advanced under council authority';
+    return `no security member in this task's resolved council plan; ${outcome}`;
+  }
+  // Did a stop rule fire in a round at/before `latestRound`? A member the plan does not
+  // name cannot be ordered against security's round, so it never explains the absence.
+  const stoppedBy = (verdict: CouncilVerdict['verdict'], latestRound: number, blockingOnly: boolean): boolean =>
+    council.members.some((m) => {
+      const round = planned.memberRounds.get(m.member);
+      return m.verdict === verdict && round !== undefined && round <= latestRound && (!blockingOnly || m.blocking !== false);
+    });
+  if (stoppedBy('escalate', securityRound, false)) {
+    return 'security member configured for this task but not reached: another member escalated and the council short-circuited; no security verdict recorded';
+  }
+  if (planned.stopsOnRoundBounce && stoppedBy('bounce', securityRound - 1, true)) {
+    return "security member configured for this task but not reached: an earlier round's blocking member bounced and the profile stops on a round bounce; no security verdict recorded";
+  }
+  return 'security member configured for this task but did not run; no security verdict recorded';
+}
+
+/** Decisive plan-review council (task.plan_review at tactical-plan). */
+function applyDecisivePlanReview(repoRoot: string, taskId: string, gate: string, council: CouncilVerdict): CouncilResult {
+  const task = loadTask(repoRoot, taskId);
+  if (task.status !== 'tactical-plan') {
+    throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected 'tactical-plan' for gate '${gate}'`);
+  }
+  const walk: string[] = ['tactical-plan'];
+  if (council.verdict === 'escalate') {
+    advanceStatus(repoRoot, taskId, 'escalated', 'agent');
+    walk.push('escalated');
+  } else if (council.verdict === 'bounce') {
+    advanceStatus(repoRoot, taskId, 'pending', 'agent', { gate: 'per_task_plan_review' });
+    walk.push('pending');
+  } else {
+    advanceStatus(repoRoot, taskId, 'implementing', 'agent');
+    walk.push('implementing');
+  }
+  const result: CouncilResult = {
+    gate,
+    final_verdict: council.verdict,
+    rule: council.rule,
+    rationale: council.rationale,
+    members: council.members.map((m) => ({ member: m.member, verdict: m.verdict, blocking: m.blocking !== false, weight: m.weight ?? 1 })),
+    walk,
+    ...(council.forward !== undefined ? { forward: council.forward } : {}),
+  };
+  writeCouncilResult(repoRoot, taskId, result);
+  return result;
+}
+
+/**
+ * Advisory-gate terminal step: 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. Generalized over work-item kind: the gate's `type.` prefix selects
+ * task | plan | rfc. Used for task.final_gate (final-gate) and the discovery
+ * gates plan.task_batch (task_batch_gate) / rfc.strategy_gate (rfc_strategy_gate).
+ */
+export function postAdvisoryVerdict(
+  repoRoot: string,
+  workItemId: string,
+  gate: string,
+  expectedState: string,
+  council: CouncilVerdict,
+): CouncilResult {
+  const type = workItemTypeOf(gate);
+  const status = String(loadWorkItemDoc(repoRoot, type, workItemId).status ?? '');
+  if (status !== expectedState) {
+    throw new Error(
+      `apply-council-verdict: ${type} ${workItemId} is '${status}', expected '${expectedState}' for advisory gate '${gate}'`,
+    );
+  }
+  const m = workItemId.match(/^(.+)-(\d+)$/);
+  if (!m) throw new Error(`apply-council-verdict: invalid work-item id '${workItemId}'`);
+  const project = m[1];
+  writeFeedback(repoRoot, {
+    project,
+    taskId: workItemId,
+    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, workItemId, result);
+  return result;
+}