@ngockhoale/ukit 3.0.0 → 3.0.2

package/src/index/taskRouting.js

@@ -11,6 +11,8 @@ import {
   EXECUTION_CONTRACTS,
   EXECUTION_MODE_ORDER,
   MODEL_TIER_BY_CONTRACT,
+  ROUTE_EFFORTS,
+  resolveModelTier,
 } from '../core/executionContracts.js';
 import { resolveModelRoles, readMergedRuntimeConfig } from '../core/runtimeConfig.js';
 import { resolvePlaybook } from '../core/userPlaybooks.js';
@@ -18,7 +20,7 @@ import { resolvePlaybook } from '../core/userPlaybooks.js';
 // --- v3 route-side advisory blocks (docs/pstack/SPEC-playbook-todo.md, ------------------
 // SPEC-principle-index.md, SPEC-model-roles.md). All three are additive stdout text —
 // they never change mode selection. Static text is byte-stable for prompt-cache reuse.
-// Mirrored literally in templates/.claude/ukit/index/route-task.mjs (parity-locked by
+// Mirrored literally in template_project/.claude/ukit/index/route-task.mjs (parity-locked by
 // tests/consistency/executionContractSync.test.js).
 
 // SPEC-playbook-todo §2.1: numbered step lists the model copies verbatim into its todo
@@ -155,6 +157,29 @@ export const ROUTE_INTENT_KINDS = new Set(['informational', 'delivery', 'mutatio
 export const ROUTE_MUTABILITIES = new Set(['read-only', 'mutating', 'mixed']);
 export const ROUTE_RIGOR_LEVELS = new Set(['R0', 'R1', 'R2', 'R3', 'R4']);
 export const ROUTE_MODEL_TIERS = new Set(['lite', 'code', 'smart']);
+export const ROUTE_RISK_FLOORS = new Set(['none', 'high-risk']);
+// SPEC §5 FR-003: fixed table order — codes are emitted and printed in this order.
+// The first six raise the floor to 'high-risk'; the last two are informational only.
+export const ROUTE_RISK_REASON_CODES = Object.freeze([
+  'security-sensitive',
+  'shared-impact',
+  'public-contract',
+  'schema-change',
+  'destructive-action',
+  'cross-engine',
+  'established-precedent',
+  'explicit-local-target',
+]);
+const ROUTE_RISK_FLOOR_RAISING_CODES = new Set(ROUTE_RISK_REASON_CODES.slice(0, 6));
+const ROUTE_RISK_ENGINES = ['claude code', 'codex', 'omp'];
+
+// FR-004 (M01.3'): Fast Path eligibility vocabulary. The suppressed list is fixed
+// text per SPEC — deliberately not configurable. Reasons are the informational
+// risk codes (the last two ROUTE_RISK_REASON_CODES entries) present on the route.
+const FAST_PATH_MODES = new Set(['tiny-fix', 'local-fix']);
+const FAST_PATH_SUPPRESSED = Object.freeze(['design', 'smart', 'subagents', 'broad-verify']);
+const FAST_PATH_REASON_CODES = new Set(ROUTE_RISK_REASON_CODES.slice(6));
+
 // 'informational' is a real router emission (no completion contract) even though it is
 // not part of the seven-lane EXECUTION_MODE_ORDER ladder.
 export const ROUTE_EXECUTION_MODES = [...EXECUTION_MODE_ORDER, 'informational'];
@@ -169,6 +194,163 @@ export function resolveRouteSchemaStage(config = null) {
   return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
 }
 
+// FR-002: generic stage resolver — every routing.<key>.stage shares the same
+// absent/malformed → 'off' contract. resolveRouteSchemaStage stays as the
+// routeSchema-specific spelling of this helper.
+export function resolveRouteStage(config = null, key) {
+  const stage = config?.routing?.[key]?.stage;
+  return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
+}
+
+// FR-003 (M01.2'): derive the additive riskFloor from hard signals. Codes are
+// collected in ROUTE_RISK_REASON_CODES table order; the floor is 'high-risk' iff
+// any of the first six (floor-raising) codes fired — informational codes never
+// raise it. Detectors read the normalized signal text (same source the mode
+// ladder uses) plus the raw target path and context preview.
+export function deriveRiskFloor({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  executionMode = null,
+  activeSkillIds = [],
+  contextPreview = null,
+} = {}) {
+  const signalText = buildRouteSignalText(promptText, commandText);
+  const target = String(targetFile || '');
+  const skillIds = Array.isArray(activeSkillIds) ? activeSkillIds : [];
+  const codes = [];
+  if (
+    /\b(auth|security|token|permission|secret|credential|password|vulnerab|exploit|xss|injection)\b/i.test(signalText)
+    || skillIds.includes('discover-security')
+  ) {
+    codes.push('security-sensitive');
+  }
+  if (isSharedImpactFile(targetFile) || executionMode === 'shared-edit' || executionMode === 'map-impact') {
+    codes.push('shared-impact');
+  }
+  if (
+    /(^|\/)(package\.json|manifests\/|.*\.d\.ts$|(^|\/)api\/|openapi|swagger)/i.test(target)
+    || /\b(public api|breaking change|api contract|semver)\b/i.test(signalText)
+  ) {
+    codes.push('public-contract');
+  }
+  if (
+    /(^|\/)(migrations?|db|database|prisma|schema)/i.test(target)
+    || /\b(migration|migrate|schema|alter table|add column|drop column)\b/i.test(signalText)
+  ) {
+    codes.push('schema-change');
+  }
+  if (/\b(delete|drop|truncate|destroy|wipe|uninstall|rm -rf|purge)\b/i.test(signalText)) {
+    codes.push('destructive-action');
+  }
+  const engineHits = ROUTE_RISK_ENGINES.filter(
+    (name) => new RegExp(`\\b${name}\\b`, 'i').test(signalText),
+  ).length;
+  if (
+    /\bcross[- ]engine\b|\ball engines\b/i.test(signalText)
+    || engineHits >= 2
+    || /^template_project\/\.(claude|codex|omp)\//i.test(target)
+  ) {
+    codes.push('cross-engine');
+  }
+  if ((contextPreview?.analogFiles?.length ?? 0) > 0 || (contextPreview?.styleFiles?.length ?? 0) > 0) {
+    codes.push('established-precedent');
+  }
+  if (target && !isSharedImpactFile(targetFile)) {
+    codes.push('explicit-local-target');
+  }
+  return {
+    floor: codes.some((code) => ROUTE_RISK_FLOOR_RAISING_CODES.has(code)) ? 'high-risk' : 'none',
+    codes,
+  };
+}
+
+// Route-line segment (FR-003): on 'high-risk' only the floor-raising codes print;
+// on 'none' the informational codes do. Empty list → no segment at all.
+function formatRiskFloorSegment(riskFloor = null) {
+  if (!riskFloor) {
+    return null;
+  }
+  const printed = riskFloor.floor === 'high-risk'
+    ? riskFloor.codes.filter((code) => ROUTE_RISK_FLOOR_RAISING_CODES.has(code))
+    : riskFloor.codes;
+  return printed.length > 0 ? `risk=${riskFloor.floor}(${printed.join(',')})` : null;
+}
+
+// FR-001 (M01.2' limits fragment): compile the contract's numeric budget keys
+// into an advisory map. Only finite numbers survive — a non-numeric or missing
+// key is simply absent. Zero is a real budget ("no read passes"), never
+// filtered. Same key set as the ceremonyBudget.limits builder below.
+export function deriveCeremonyLimits(executionContract = null) {
+  if (executionContract === null || typeof executionContract !== 'object') {
+    return {};
+  }
+  return Object.fromEntries(
+    ['maxReadPasses', 'maxContextPulls', 'maxReadPassesBeforeReassess']
+      .filter((key) => Number.isFinite(executionContract[key]))
+      .map((key) => [key, executionContract[key]]),
+  );
+}
+
+// Route-line segment (FR-002): fixed reads,ctx,reassess order; only present
+// keys print. Empty/absent map → null so the segment never appears.
+export function formatLimitsSegment(limits = null) {
+  if (limits === null || typeof limits !== 'object') {
+    return null;
+  }
+  const parts = [
+    ['reads', 'maxReadPasses'],
+    ['ctx', 'maxContextPulls'],
+    ['reassess', 'maxReadPassesBeforeReassess'],
+  ]
+    .filter(([, key]) => Number.isFinite(limits[key]))
+    .map(([label, key]) => `${label}:${limits[key]}`);
+  return parts.length > 0 ? `limits=${parts.join(',')}` : null;
+}
+
+// FR-004 (M01.3'): Fast Path eligibility predicate. Returns null when no riskFloor
+// was supplied — eligibility must never be derived without the floor check, so a
+// missing floor means "not computed", not "none". Eligible iff the lane is
+// tiny-fix/local-fix, exactly one local target is known, the floor is 'none',
+// a bounded verification path exists (targeted commands or the tiny-fix
+// 'minimal-or-targeted' contract policy), and the target is not shared-impact.
+export function deriveFastPath({
+  executionMode = null,
+  targetFile = null,
+  riskFloor = null,
+  verificationRecommendation = null,
+  contextPreview = null,
+} = {}) {
+  if (!riskFloor) {
+    return null;
+  }
+  const reasons = (riskFloor.codes ?? []).filter((code) => FAST_PATH_REASON_CODES.has(code));
+  const hasLocalTarget = Boolean(targetFile) || contextPreview?.primaryTargets?.length === 1;
+  const hasBoundedVerification = (verificationRecommendation?.commands?.length ?? 0) > 0
+    || buildExecutionContract(executionMode)?.verificationPolicy === 'minimal-or-targeted';
+  const eligible = FAST_PATH_MODES.has(executionMode)
+    && hasLocalTarget
+    && riskFloor.floor === 'none'
+    && hasBoundedVerification
+    && !isSharedImpactFile(targetFile);
+  return {
+    eligible,
+    suppressed: eligible ? [...FAST_PATH_SUPPRESSED] : [],
+    reasons,
+  };
+}
+
+// Route-line segment (FR-004): emitted only for eligible routes — ineligible
+// routes keep the routeSummary.fastPath field for telemetry but stay silent.
+function formatFastPathSegment(fastPath = null) {
+  if (!fastPath?.eligible) {
+    return null;
+  }
+  const reasons = fastPath.reasons?.length ? ` (${fastPath.reasons.join(',')})` : '';
+  return `fastPath=on | suppress: ${FAST_PATH_SUPPRESSED.join(',')}${reasons}`;
+}
+
+
 
 // A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
 // repository mutation the ledger could ever receipt. With no edit/review/debug/build
@@ -232,7 +414,12 @@ function buildResolvedRouteFields({
   executionMode = null,
   executionContract = null,
   completionState = null,
+  riskFloor = null,
 } = {}) {
+  // Decision table v2 (FR-001/FR-002): tier + effort resolve together from the
+  // contract lane and the additive riskFloor. The router cannot observe host
+  // binding capabilities, so the emitted pair is advisory text by definition.
+  const tierDecision = resolveModelTier({ executionMode, riskFloor });
   const signalText = buildRouteSignalText(routingContext.promptText, routingContext.commandText);
   const deliveryOnly = isDeliveryOnlyRequest({
     signalText,
@@ -254,13 +441,15 @@ function buildResolvedRouteFields({
     execution: {
       mode: executionMode,
       rigor: null,
+      riskFloor: riskFloor?.floor ?? null,
       phase: null,
       contractVersion: ROUTE_CONTRACT_VERSION,
-      modelTier: executionContract?.modelTier ?? MODEL_TIER_BY_CONTRACT[executionMode] ?? null,
+      modelTier: tierDecision.tier,
+      effort: tierDecision.effort,
     },
     evidence: {
       observations: [],
-      riskSignals: [],
+      riskSignals: riskFloor?.codes ?? [],
       activationReasons: [],
       suppressionReasons: [],
       completionRequirements: unique(completionState?.missingEvidence ?? []),
@@ -268,7 +457,13 @@ function buildResolvedRouteFields({
     ceremonyBudget: {
       policyVersion: ROUTE_CONTRACT_VERSION,
       rigor: null,
-      limits: {},
+      limits: riskFloor
+        ? Object.fromEntries(
+            ['maxReadPasses', 'maxContextPulls', 'maxReadPassesBeforeReassess']
+              .filter((key) => typeof executionContract?.[key] === 'number')
+              .map((key) => [key, executionContract[key]]),
+          )
+        : {},
       consumed: {},
       exceptions: [],
     },
@@ -324,12 +519,19 @@ export function validateResolvedRoute(route = null) {
     if (route.execution.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.execution.rigor)) {
       errors.push(`execution.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
     }
+    if (route.execution.riskFloor !== null && !ROUTE_RISK_FLOORS.has(route.execution.riskFloor)) {
+      errors.push(`execution.riskFloor must be null or one of: ${[...ROUTE_RISK_FLOORS].join(', ')}.`);
+    }
     if (route.execution.contractVersion !== ROUTE_CONTRACT_VERSION) {
       errors.push(`execution.contractVersion must be ${ROUTE_CONTRACT_VERSION}.`);
     }
     if (route.execution.modelTier !== null && !ROUTE_MODEL_TIERS.has(route.execution.modelTier)) {
       errors.push(`execution.modelTier must be null or one of: ${[...ROUTE_MODEL_TIERS].join(', ')}.`);
     }
+    if (route.execution.effort !== null && route.execution.effort !== undefined
+      && !ROUTE_EFFORTS.has(route.execution.effort)) {
+      errors.push(`execution.effort must be null or one of: ${[...ROUTE_EFFORTS].join(', ')}.`);
+    }
   }
   if (!isObject(route.evidence)) {
     errors.push('evidence must be an object.');
@@ -339,6 +541,12 @@ export function validateResolvedRoute(route = null) {
         errors.push(`evidence.${key} must be an array.`);
       }
     }
+    if (Array.isArray(route.evidence.riskSignals)
+      && route.evidence.riskSignals.some(
+        (code) => typeof code !== 'string' || !ROUTE_RISK_REASON_CODES.includes(code),
+      )) {
+      errors.push(`evidence.riskSignals entries must be one of: ${ROUTE_RISK_REASON_CODES.join(', ')}.`);
+    }
   }
   if (!isObject(route.ceremonyBudget)) {
     errors.push('ceremonyBudget must be an object.');
@@ -667,6 +875,48 @@ export function buildRouteSummary({
     nextActionType: nextAction?.type ?? null,
     completionState,
   });
+  // FR-003 (M01.2'): riskFloor is a top-level additive field emitted whenever ANY
+  // of rigor/fastPath/escalation stages is on — fastPath/escalation consumers read
+  // it even when routeSchema is off. All three off → absent, byte-identical route.
+  const riskStageOn = ['rigor', 'fastPath', 'escalation']
+    .some((key) => resolveRouteStage(runtimeConfig, key) !== 'off');
+  const riskFloor = riskStageOn
+    ? deriveRiskFloor({
+        promptText: routingContext.promptText,
+        commandText: routingContext.commandText,
+        targetFile: routingContext.targetFile ?? null,
+        executionMode,
+        activeSkillIds: activeSkills.map((entry) => entry.id),
+        contextPreview: contextRecommendation?.preview ?? null,
+      })
+    : null;
+  const riskSegment = formatRiskFloorSegment(riskFloor);
+  // FR-003 (M01.2' limits fragment): the rigor advisory — emitted whenever
+  // rigor.stage is on, independent of fastPath/escalation. Stage off → no
+  // segment, byte-identical route.
+  const limitsSegment = resolveRouteStage(runtimeConfig, 'rigor') !== 'off'
+    ? formatLimitsSegment(deriveCeremonyLimits(executionContract))
+    : null;
+  // FR-004 (M01.3'): fastPath is emitted whenever its own stage is on — the field
+  // is always set then (eligible or not) so telemetry/harness can read it; the
+  // route-line segment prints only for eligible routes.
+  const fastPathStage = resolveRouteStage(runtimeConfig, 'fastPath');
+  const fastPath = fastPathStage !== 'off'
+    ? {
+        eligible: false,
+        suppressed: [],
+        reasons: [],
+        ...deriveFastPath({
+          executionMode,
+          targetFile: routingContext.targetFile ?? null,
+          riskFloor,
+          verificationRecommendation,
+          contextPreview: contextRecommendation?.preview ?? null,
+        }),
+        stage: fastPathStage,
+      }
+    : null;
+  const fastPathSegment = formatFastPathSegment(fastPath);
   const resolvedRouteFields = routeSchemaStage !== 'off'
     ? buildResolvedRouteFields({
         routingContext,
@@ -674,6 +924,7 @@ export function buildRouteSummary({
         executionMode,
         executionContract,
         completionState,
+        riskFloor,
       })
     : null;
   const helperHint = compactHelperHint(
@@ -716,6 +967,9 @@ export function buildRouteSummary({
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
     editGuardHint ? `editGuard=${editGuardHint}` : null,
+    riskSegment,
+    limitsSegment,
+    fastPathSegment,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
     workflowPolicyName ? `workflow=${workflowPolicyName}` : null,
@@ -737,6 +991,10 @@ export function buildRouteSummary({
     completionState,
     // M01.1 additive C01 groups — present only when routing.routeSchema.stage != "off".
     ...(resolvedRouteFields ?? {}),
+    // FR-003 additive top-level field — present only when a risk stage is on.
+    ...(riskFloor ? { riskFloor } : {}),
+    // FR-004 additive top-level field — present only when fastPath stage is on.
+    ...(fastPath ? { fastPath } : {}),
     continuationState,
     autonomyLevel,
     continuousExecution,
@@ -864,7 +1122,7 @@ function deriveExecutionScores({
 // asking for an explanation, not a repository change. Routing it to an investigation or
 // edit lane fabricates write/verification debt the completion gate then enforces against an
 // answer turn. Kept byte-equivalent to the shipped copies in
-// templates/.claude/ukit/index/route-task.mjs and templates/.claude/hooks/skill-router.sh;
+// template_project/.claude/ukit/index/route-task.mjs and template_project/.claude/hooks/skill-router.sh;
 // this is the canonical copy those are mirror-tested against. It deliberately ignores
 // targetFile: an edit order phrased as a question is caught by implementWords below, while a
 // pure targeted question ("how does X work?") is still just a question.

package/src/render/instructionRenderer.js

@@ -173,11 +173,11 @@ export function renderAll(layout, sourceTexts, varsByResolve = {}) {
 }
 
 const SOURCE_FILES = {
-  core: 'templates/instructions/core.md',
-  'overlay:claude': 'templates/instructions/overlays/claude.md',
-  'overlay:agents': 'templates/instructions/overlays/agents.md',
-  'overlay:omp-rules': 'templates/instructions/overlays/omp-rules.md',
-  'overlay:repo': 'templates/instructions/overlays/repo.md',
+  core: 'template_project/instructions/core.md',
+  'overlay:claude': 'template_project/instructions/overlays/claude.md',
+  'overlay:agents': 'template_project/instructions/overlays/agents.md',
+  'overlay:omp-rules': 'template_project/instructions/overlays/omp-rules.md',
+  'overlay:repo': 'template_project/instructions/overlays/repo.md',
 };
 
 /**
@@ -187,10 +187,10 @@ const SOURCE_FILES = {
 export async function renderInstructionsFromDisk({ repoRoot, write = true } = {}) {
   const abs = (p) => path.join(repoRoot, p);
   const layout = YAML.parse(
-    fs.readFileSync(abs('templates/instructions/layout.yaml'), 'utf8'),
+    fs.readFileSync(abs('template_project/instructions/layout.yaml'), 'utf8'),
   );
   const repoVars =
-    YAML.parse(fs.readFileSync(abs('templates/instructions/repo-vars.yaml'), 'utf8')) || {};
+    YAML.parse(fs.readFileSync(abs('template_project/instructions/repo-vars.yaml'), 'utf8')) || {};
   const pkg = JSON.parse(fs.readFileSync(abs('package.json'), 'utf8'));
 
   const sourceTexts = {};

package/src/skill/auditSkill.js

@@ -23,7 +23,7 @@ export async function initSkillAudit({ rootDir = process.cwd(), skillName } = {}
   const auditDir = getAuditDir(rootDir, skillName);
   await fs.mkdir(auditDir, { recursive: true });
 
-  const templateSourceDir = path.join(rootDir, 'templates/.claude/skills/skill-quality');
+  const templateSourceDir = path.join(rootDir, 'template_project/.claude/skills/skill-quality');
   const copied = [];
   const skipped = [];
 

package/{templates → template_project}/.claude/agents/code-reviewer.md

@@ -57,6 +57,8 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 VERDICT: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL
 REVIEWER_MODEL: [model name actually used]
 EXECUTOR_MODEL: [from executor report]
+PANEL_MEMBER: [panel tier — `smart`/`code`/`lite`, or `solo` when the panel degenerates; `-` outside panel runs]
+AGREEMENT_MAP: [lead member only — finding → panel members reporting it, from review-panel-aggregate.mjs output; `-` otherwise]
 VERIFICATION_RERUN:
   command: [exact command]
   result: [N pass / M fail]
@@ -121,6 +123,29 @@ Same model is the most common silent failure. Do not skip this check.
 - Keep the verdict block <= 30 lines. Findings are bullet points, not essays.
 - The same-model refusal above is non-negotiable: bypassing it defeats the entire Quality Gate.
 
+## Panel review (diversity review)
+
+When the orchestrator spawns you as one member of the `modelRoles['review-panel']`
+panel (`.ukit/storage/config.json` → `modelRoles`, default `['smart','code','lite']`),
+everything above applies unchanged — same Review order, same severity ladder, same
+verdict block — with these additions:
+
+- Set `PANEL_MEMBER: <tier>` in the verdict to your panel tier (e.g. `smart`,
+  `code`, `lite`). Every member runs the same rubric independently; do not read or
+  wait for other members' verdicts.
+- Leave `AGREEMENT_MAP` as `-` unless you are the **lead member** (the first entry in
+  `modelRoles['review-panel']` = the judgment tier). After the orchestrator runs
+  `node .claude/ukit/index/review-panel-aggregate.mjs <TASK-xxx.md...>` and hands you
+  the output, the lead fills `AGREEMENT_MAP` with the emitted finding → members map
+  and applies the lead-judgment buckets to every finding: **Act on** / **Consider** /
+  **Noted** / **Dismissed**.
+- `consensus≥2 identical findings = high signal`: a finding reported by two or more
+  panel members is high-signal and must not be bucketed below **Consider** without a
+  stated reason.
+- Degenerate panel: if `modelRoles['review-panel']` is empty or has one entry, the
+  panel collapses to a single reviewer — run the normal solo review, set
+  `PANEL_MEMBER: solo`, and note the fallback in `NOTES`.
+
 ## Spec/Plan Review (REVIEW_TARGET_TYPE=spec|plan)
 
 ### Inputs you expect

package/{templates → template_project}/.claude/agents/handoff-planner.md

@@ -76,7 +76,7 @@ verification — link both files' `## Discussion` threads.
 
 ## Phase 0.5 — Write SPEC.md
 
-Write `docs/AI_HANDOFF/SPEC.md` from the template at `templates/docs/AI_HANDOFF/SPEC.md`
+Write `docs/AI_HANDOFF/SPEC.md` from the template at `template_project/docs/AI_HANDOFF/SPEC.md`
 (15 sections). The spec is the contract executors implement against — concrete enough that
 nothing is guessed: exact paths, module and API names, schemas, validation rules,
 permissions, empty/error states, migration behavior, test expectations. Every section is
@@ -135,7 +135,7 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 | Dependencies | `TASK-xxx` or `none` — wave order is inferred from this |
 | Test Cases | Type \| Test Name \| Expected — ≥1 happy + ≥2 edge cases of different kinds |
 | Test Files | Exact test file paths to create/modify |
-| Verification Commands | Runnable shell commands — MUST include the project's lint/typecheck command if one exists (see §5 rule above). Apply the "Test selection" resolution order from docs/AI_HANDOFF/RULES.md: `src/`/`scripts/` targets → the `tests` array in `.cache/index/tests-map.json`; `templates/.claude/**`/`.claude/**` targets → path convention (hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`); if both resolve to fewer than one test file the task MUST fall back to `yarn test:release-core` — never the full suite by default, never an empty selection |
+| Verification Commands | Runnable shell commands — MUST include the project's lint/typecheck command if one exists (see §5 rule above). Apply the "Test selection" resolution order from docs/AI_HANDOFF/RULES.md: `src/`/`scripts/` targets → the `tests` array in `.cache/index/tests-map.json`; `template_project/.claude/**`/`.claude/**` targets → path convention (hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`); if both resolve to fewer than one test file the task MUST fall back to `yarn test:release-core` — never the full suite by default, never an empty selection |
 | Acceptance Criteria | Verifiable checklist |
 
 Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
@@ -196,6 +196,21 @@ Status: planning_done — ready for executor
 ```
 Wave structure is NOT stored here — inferred from task `Dependencies` fields at runtime.
 
+**RUN.md** — write the run's `ExitPredicate:` line before iteration 1 (the orchestrator
+keeps it verbatim on every cursor rewrite):
+
+```
+ExitPredicate: all(index:all-done, git:clean)
+```
+
+Grammar: `all(<term>[,<term>...])` or a single term; terms are `index:all-done`,
+`git:clean`, `file-exists:<relpath>` (repo-relative, no `..` segments). Default to
+`all(index:all-done, git:clean)`; add `file-exists:` terms only for artifacts the plan
+itself must produce. The stop gate evaluates this mechanically when the cursor claims
+`Phase: done` — a `done` claim with failing terms is bounced back with the per-term
+state. **Never relax the predicate mid-run**: if the run cannot satisfy it, the plan is
+wrong — fix the plan, not the gate.
+
 ## Self-Audit — run before reporting, every time
 
 The downstream pipeline is unattended: an incomplete or wrong plan is not caught by a human

package/{templates → template_project}/.claude/commands/ukit/handoff-create.md

@@ -70,7 +70,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    ```
 
 3. Write `docs/AI_HANDOFF/SPEC.md` — the detailed implementation spec (BẮT BUỘC before tasks).
-   Follow `docs/AI_HANDOFF/SPEC.md`'s template sections (or `templates/docs/AI_HANDOFF/SPEC.md`
+   Follow `docs/AI_HANDOFF/SPEC.md`'s template sections (or `template_project/docs/AI_HANDOFF/SPEC.md`
    on a fresh tree): problem/context, goals, non-goals, user journeys, functional requirements
    with Given/When/Then + error cases, fullstack scope (backend, schema/migrations, API
    contract, UI+state, integration, security, performance, observability, deploy/rollback),

package/{templates → template_project}/.claude/commands/ukit/handoff-fullstack.md

@@ -59,7 +59,7 @@ resumable. If compaction does happen, the run resumes from the cursor automatica
 
 ### Run cursor — write after every step
 
-Maintain `docs/AI_HANDOFF/RUN.md`. Rewrite it (whole file, 6 lines) immediately after every
+Maintain `docs/AI_HANDOFF/RUN.md`. Rewrite it (whole file, 7 lines) immediately after every
 numbered step completes:
 
 ```
@@ -69,9 +69,15 @@ Base: <BASE branch>
 Phase: <P0|P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R4.5|R5|F|done|blocked>
 Cursor: wave <N> batch <M> — <what just finished>
 Next: <the exact next step to run>
+ExitPredicate: all(<term>[,<term>...])   # written once at P2; never relaxed
 QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 ```
 
+`ExitPredicate` grammar: `all(<term>[,<term>...])` or a single term; terms are
+`index:all-done`, `git:clean`, `file-exists:<relpath>`. The stop gate evaluates it
+mechanically when the cursor claims `Phase: done` — a `done` claim with failing terms
+is bounced back with the per-term state. Keep the line verbatim on every rewrite.
+
 This file is the resume contract. It costs one small write per step and is what turns an
 interrupted run into a continuable one.
 
@@ -172,9 +178,12 @@ The run must keep itself alive without the human watching.
 
 - **Stop gate (Claude Code, automatic):** while `RUN.md` `Phase:` is not `done`/`blocked`,
   `completion-gate.sh` refuses the stop with the cursor's `Next:` step. Recaps and
-  premature stops cannot park the run. A stalled-cursor breaker
+  premature stops cannot park the run. When RUN.md carries `ExitPredicate:`, a
+  `Phase: done` whose predicate fails is refused too — `done` means the predicate
+  evaluates true. A stalled-cursor breaker
   (`handoff.fullstack.stopGateMaxStalledBlocks`, default 12) releases the session if the
-  cursor has genuinely stopped advancing — the escape hatch, not the norm.
+  cursor has genuinely stopped advancing — the escape hatch, not the norm — and its
+  release advisory reports the predicate state, so a plateau is visible, not silent.
 - **Scheduled wakeup (when the harness offers one):** arm it at run start — Claude Code:
   `CronCreate` a ~`handoff.fullstack.idleWatchdogMin`-minute (default 5) session job with
   prompt `Resume HANDOFF FULLSTACK from docs/AI_HANDOFF/RUN.md — continue the Next: step`;
@@ -222,7 +231,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    ```
 
 3. **Write `docs/AI_HANDOFF/SPEC.md`** — the detailed implementation spec, from
-   `templates/docs/AI_HANDOFF/SPEC.md`'s section list (or RULES.md §Spec). It must be
+   `template_project/docs/AI_HANDOFF/SPEC.md`'s section list (or RULES.md §Spec). It must be
    concrete enough that an executor implements without guessing: exact paths, module and
    API names, schemas, validation rules, permissions, empty/error states, migration
    behavior, and test expectations — every applicable section filled, open questions
@@ -269,7 +278,13 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    ```
    Then **verify the write** (read back the `Status:` line).
 
-8. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
+8. **Write `ExitPredicate:` into `docs/AI_HANDOFF/RUN.md`** — the mechanical definition of
+   done for this run: `all(<term>[,<term>...])` over `index:all-done`, `git:clean`,
+   `file-exists:<relpath>` (default `all(index:all-done, git:clean)`). Written once,
+   before iteration 1, and **never relaxed** — if the run cannot satisfy it, the plan is
+   wrong, not the gate. Then **verify the write** (read back the `ExitPredicate:` line).
+
+9. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
    `needs_breakdown` tasks + reason.
 
 ### P2.5 — Independent plan review (strong model, separate agent)
@@ -455,7 +470,12 @@ Worktrees are **always deleted immediately** — no exceptions.
 A wave boundary is the only safe place to shed context, because everything of value is
 already on disk (task files hold the full logs, git holds the code). Do all four, in order:
 
-1. **Checkpoint the code** — one commit per wave, so every wave is independently revertible:
+1. **Checkpoint the code — commit-if-advanced.** One commit per wave, so every wave is
+   independently revertible — but only when the wave's diff advances the run's
+   `ExitPredicate` (a task moved toward `done`, a required file appeared, the worktree
+   got cleaner). A wave whose diff does not advance the predicate is **discarded**: its
+   copied-back changes are reverted and nothing is committed. A plateau is not a stop —
+   the run continues to the next wave or fix round; the predicate is never relaxed.
    ```bash
    git add -A && git commit -m "handoff: wave <N> — TASK-00x, TASK-00y"
    ```

package/{templates → template_project}/.claude/commands/ukit/handoff-review.md

@@ -54,9 +54,11 @@ If that diff is empty → handoff-implement was not completed. Report which task
 
 **Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
 
-**Claude Code — MANDATORY, do this before anything else:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
+**Spawn the review panel — MANDATORY, do this before anything else:** read `modelRoles['review-panel']` from `.ukit/storage/config.json` → `modelRoles` (default `['smart','code','lite']`; omp tier aliases `@smol`/`@default`/`@slow`). For each `pending_review` task in the batch, call the Agent tool **once per panel entry** (in parallel, bounded by `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per panel entry per task) — each member bound to its panel tier and setting `PANEL_MEMBER: <tier>` in its verdict. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the panel tiers and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
 
-The spawned reviewer agent performs 2a–2d below per task:
+Degenerate panel: if `modelRoles['review-panel']` is empty or has one entry, spawn a single reviewer and require `PANEL_MEMBER: solo` in its verdict.
+
+Each spawned reviewer agent performs 2a–2d below per task:
 
 ### 2a — Model isolation check (always first)
 
@@ -98,6 +100,7 @@ matches the task file's wording.
 VERDICT: approved | approved_minor | changes_requested | critical_block
 REVIEWER_MODEL: <your exact model ID>
 EXECUTOR_MODEL: <from Executor Report>
+PANEL_MEMBER: <panel tier | solo | ->
 VERIFICATION_RERUN: PASS | FAIL
 FINDINGS:
   critical: <file:line — what fails> | none
@@ -116,7 +119,29 @@ BLOCKING: <one line per critical/important finding, or "none">
 ```
 Do not paste the diff, the findings prose, or verification logs back into the orchestrator.
 
-### 2e — Orchestrator updates INDEX.md
+### 2e — Aggregate the panel + lead bucketing
+
+Once every panel member for a task has appended its `## Reviewer Verdict`, run:
+
+```bash
+node .claude/ukit/index/review-panel-aggregate.mjs docs/AI_HANDOFF/tasks/TASK-xxx.md
+```
+
+The script emits an Agreement Map (finding → set of panel members reporting it) and a
+consensus verdict (`approved` when ≥2 members approve and no critical;
+`changes_requested` when ≥1 critical or ≥2 request changes; else `approved_minor`).
+`consensus≥2 identical findings = high signal` — a finding reported by two or more
+members is high-signal. The consensus verdict, not any single member's vote, drives
+`NEXT_STATUS_FOR_INDEX`.
+
+Then the **lead member** (first entry in `modelRoles['review-panel']` = the judgment
+tier) applies the lead-judgment buckets to every finding — **Act on** / **Consider** /
+**Noted** / **Dismissed** — and appends a `## Panel Consensus` block to the task file
+carrying the Agreement Map and the bucketed findings. `Act on` findings feed Step 3's
+auto-fix loop; `Consider`/`Noted`/`Dismissed` are advisory. A high-signal finding must
+not be bucketed below `Consider` without a stated reason.
+
+### 2f — Orchestrator updates INDEX.md
 
 Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewer.
 
@@ -144,7 +169,7 @@ For round in 1..2:
    ```bash
    git add -A && git commit -m "handoff: fix round <N> — TASK-00x"
    ```
-4. Re-review **only the tasks touched this round**, in parallel, per 2a–2e. The reviewer must
+4. Re-review **only the tasks touched this round**, in parallel, per 2a–2f — panel spawn, aggregation, and lead bucketing included. The reviewers must
    still differ from the executor model and still re-runs verification itself.
 5. Update `INDEX.md` and `RUN.md`. Exit when everything is approved.
 
@@ -190,5 +215,5 @@ Then, as the last line:
 This is the only place this command may ask for a compaction. All state lives in git,
 `INDEX.md` and `RUN.md`, so a compacted or fresh session resumes with nothing lost.
 
-> Orchestrator (this session) handles Step 1, 2e, and 3 directly — those are not delegated.
-> **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model, run 2a–2d per task (one session at a time).
+> Orchestrator (this session) handles Step 1, 2e, 2f, and 3 directly — those are not delegated.
+> **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model, run 2a–2d per task (one session at a time, panel members sequentially), then run `review-panel-aggregate.mjs` and apply the lead buckets yourself.