@ngockhoale/ukit 1.6.2 → 1.6.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to UKit are documented here.
 
+## 1.6.4 - 2026-07-27
+
+### Added
+
+- Hard enforcement of the handoff model-tier contract via a new `PreToolUse` hook (`.claude/hooks/handoff-model-guard.sh`), registered for both `Edit|Write` and `Bash`. Previously the plan=opus / implement=sonnet / review=opus split was only a prompt convention the orchestrating model could silently skip.
+  - Blocks writing `docs/AI_HANDOFF/PLAN.md` unless it declares a smart-tier `PLANNER_MODEL` in a new mandatory `## Planner Report` footer.
+  - Blocks creating a fresh `TASK-xxx.md` until `PLAN.md` has a valid smart-tier `PLANNER_MODEL`.
+  - Blocks writing `## Executor Report` unless `EXECUTOR_MODEL` is present and not lite-tier.
+  - Blocks writing `## Reviewer Verdict` unless `REVIEWER_MODEL` is smart-tier and differs from `EXECUTOR_MODEL`.
+  - Blocks `git push` when any reviewed task in the active cycle violates the contract.
+  - Applies identically to the standalone `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review` commands and the combined `/ukit:handoff-fullstack` pipeline, since the gate is keyed on file content, not on which command ran.
+- `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review`, `/ukit:handoff-fullstack`: each phase now carries a mandatory Agent-tool-spawn directive (`ukit-small-task-maintainer`, `handoff-planner`, `feature-implementer`, `code-reviewer`) so the correct model tier is actually invoked, not just suggested.
+- `handoff-planner` agent and `PLAN.md` now require a `## Planner Report` / `PLANNER_MODEL` self-report, mirroring the existing `EXECUTOR_MODEL` / `REVIEWER_MODEL` self-report contract on task files.
+
 ## 1.6.2 - 2026-07-26
 
 ### Added

package/manifests/platform.full.yaml

@@ -914,6 +914,7 @@ items:
       - hook-post-edit-verify
       - hook-auto-allow-bash
       - hook-block-dangerous
+      - hook-handoff-model-guard
       - hook-auto-prune-bash
     mergeStrategy: overwrite_with_backup
     variables: []
@@ -1012,6 +1013,17 @@ items:
     packs:
       - core
 
+  - id: hook-handoff-model-guard
+    type: hook
+    sourceTemplate: .claude/hooks/handoff-model-guard.sh
+    targetPath: .claude/hooks/handoff-model-guard.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-skill-router
     type: hook
     sourceTemplate: .claude/hooks/skill-router.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/templates/.claude/agents/bug-debugger.md

@@ -1,7 +1,7 @@
 ---
 name: bug-debugger
 description: "Debugging specialist for reproducible errors, failing tests, and unexpected behavior. Use proactively when investigation will involve noisy logs, stack traces, or a self-contained reproduce-trace-fix-verify loop. Do not use for trivial obvious fixes or broad architecture ideation."
-model: inherit
+model: sonnet  # unic-code
 color: red
 tools: ["Read", "Grep", "Glob", "Bash", "Edit", "TodoWrite"]
 ---

package/templates/.claude/agents/code-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: code-reviewer
 description: "Independent reviewer for handoff Phase 3. Use after executor reports STATUS: DONE on a handoff task. MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart). Produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL."
-model: inherit
+model: opus  # unic-smart
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
 ---

package/templates/.claude/agents/feature-implementer.md

@@ -1,7 +1,7 @@
 ---
 name: feature-implementer
 description: "Implementation specialist for clear, self-contained coding tasks. Use proactively when the approach is clear and the work can be completed in a bounded pass with a concise summary. Do not use for trivial one-file tweaks or tightly coupled exploratory work."
-model: inherit
+model: sonnet  # unic-code
 color: green
 tools: ["Read", "Edit", "Write", "Grep", "Glob", "Bash", "TodoWrite"]
 ---

package/templates/.claude/agents/handoff-planner.md

@@ -1,7 +1,7 @@
 ---
 name: handoff-planner
 description: "Handoff planning specialist for Phase 1+2. Use when creating a new handoff cycle: writes PLAN.md with full test plan, splits into TASK-xxx.md files with TDD-embedded test cases, and updates INDEX.md. Always use the strongest available model (Opus/unic-smart)."
-model: inherit
+model: opus  # unic-smart
 color: purple
 tools: ["Read", "Edit", "Write", "Glob", "Bash", "TodoWrite"]
 ---
@@ -34,6 +34,12 @@ Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
 **§4 is non-negotiable.** No test plan = plan not ready.
 If zero testable behavior → write `N/A` + explicit justification in each task's Test Cases.
 
+Append this footer to `PLAN.md` — mandatory, checked by a hook before the write is allowed:
+```
+## Planner Report
+PLANNER_MODEL: <your exact model ID — e.g. claude-opus-4-6>
+```
+
 ## Phase 2 — Split into TASK-xxx.md
 
 Use `_TEMPLATE.md` structure (from pre-read context or file).

package/templates/.claude/agents/ukit-small-task-maintainer.md

@@ -1,7 +1,7 @@
 ---
 name: ukit-small-task-maintainer
 description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
-model: unic-lite
+model: haiku  # unic-lite
 color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---

package/templates/.claude/commands/ukit/handoff-create.md

@@ -16,23 +16,23 @@ $ARGUMENTS
 
 ## Step 1 — Read context (lite model)
 
-Use the lightest model available. Read and summarize:
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask the agent to:
 
-1. `docs/AI_HANDOFF/INDEX.md` → current tasks + statuses (or "empty")
-2. `docs/AI_HANDOFF/ACTIVE.md` → active cycle info (or "no active cycle")
-3. `docs/AI_HANDOFF/RULES.md` → PLAN.md 6-section format + Task Gate required fields
-4. `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
+1. Read `docs/AI_HANDOFF/INDEX.md` → current tasks + statuses (or "empty")
+2. Read `docs/AI_HANDOFF/ACTIVE.md` → active cycle info (or "no active cycle")
+3. Read `docs/AI_HANDOFF/RULES.md` → PLAN.md 6-section format + Task Gate required fields
+4. Read `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
+5. Return a compact summary. Do NOT write anything yet.
 
-Return compact summary. Do NOT write anything yet.
-
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku).
-> Other tools: switch to lite model, run above, keep summary in context.
+> Other tools without subagent support: manually switch to the lite model, run the steps above yourself, keep the summary in context.
 
 ---
 
 ## Step 2 — Write plan + tasks (strong model)
 
-Switch to strongest model. Use Step 1 summary — do NOT re-read files.
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "handoff-planner"`, passing it the Step 1 summary and the problem/feature description. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
+
+The planner agent does the following (use Step 1 summary — do NOT re-read files):
 
 1. Check INDEX.md task statuses:
    - All tasks are `ready` (planning only) → **re-run allowed**: overwrite PLAN.md and TASK-xxx.md freely — this is iterative refinement.
@@ -52,6 +52,12 @@ Switch to strongest model. Use Step 1 summary — do NOT re-read files.
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
+   Append a footer — **mandatory, a hook blocks the write without it**:
+   ```
+   ## Planner Report
+   PLANNER_MODEL: <your exact model ID>
+   ```
+
 4. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
    Every task MUST have:
    - Target Files (exact paths — no two tasks in same wave share a file)
@@ -75,8 +81,7 @@ Switch to strongest model. Use Step 1 summary — do NOT re-read files.
 
 7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
-> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem.
-> Other tools: switch to strong model, execute steps 1–7 above.
+> Other tools without subagent support: manually switch to the strong model, execute steps 1–7 above yourself.
 
 ---
 

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -26,7 +26,7 @@ $ARGUMENTS
 
 ### P1 — Read context (lite model)
 
-Use the lightest model available. Read and return a compact summary of:
+**Claude Code — MANDATORY, do this before anything else in P1:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask it to return a compact summary of:
 
 1. `docs/AI_HANDOFF/INDEX.md` — current tasks + statuses (or "empty / no tasks")
 2. `docs/AI_HANDOFF/ACTIVE.md` — active cycle info (or "no active cycle")
@@ -35,11 +35,13 @@ Use the lightest model available. Read and return a compact summary of:
 
 Return a compact summary. Do NOT write any files yet.
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for P1.
+> Other tools without subagent support: manually switch to the lite model and run P1 yourself.
 
 ### P2 — Write PLAN.md + task files (strong model)
 
-Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read files.
+**Claude Code — MANDATORY, do this before anything else in P2:** call the Agent tool with `subagent_type: "handoff-planner"`, passing it the P1 summary and `$ARGUMENTS`. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
+
+The planner agent does the following (use P1 summary — do NOT re-read files):
 
 1. **Guard — check INDEX statuses:**
    - All tasks are `ready` (planning only) → re-run is allowed: overwrite `PLAN.md` and `TASK-xxx.md` freely (iterative refinement).
@@ -59,6 +61,12 @@ Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
+   Append a footer — **mandatory, a hook blocks the write without it**:
+   ```
+   ## Planner Report
+   PLANNER_MODEL: <your exact model ID>
+   ```
+
 4. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
    Every task MUST have:
    - Target Files (exact paths — no two tasks in same wave share a file)
@@ -81,18 +89,16 @@ Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read
 
 7. **Report:** task IDs, dependency graph, any `needs_breakdown` tasks + reason.
 
-> Claude Code: spawn `handoff-planner` (opus) with P1 summary + `$ARGUMENTS` problem.
-
 ### P3 — Commit the plan (lite model)
 
-Use the lightest model. Run:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for this commit step (lite tier — haiku/unic-lite). Run:
 ```bash
 git add docs/AI_HANDOFF/ && git commit -m "handoff: plan — <goal>"
 ```
 
 Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan in git before any implementation begins.
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for P3.
+> Other tools without subagent support: manually switch to the lite model for P2/P3.
 
 ---
 
@@ -100,7 +106,7 @@ Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan
 
 ### I1 — Setup + verify (lite model)
 
-Use the lightest model. Read:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I1. Ask it to read:
 - `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
 - `docs/AI_HANDOFF/INDEX.md` → collect all `ready` tasks
 
@@ -113,8 +119,6 @@ git status   # must be clean — plan commit already done in P3
 
 If working tree is dirty → stop. Ask human to resolve uncommitted changes first.
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for I1.
-
 ### I2 — Infer wave groups
 
 Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
@@ -125,6 +129,8 @@ Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
 
 ### I3 — Execute wave by wave (code model agents)
 
+**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task (in parallel), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+
 For each wave:
 
 **3a — Create worktrees** (one per task, from `$BASE`):
@@ -158,8 +164,6 @@ Executor Report (append to task file — do NOT touch INDEX.md):
   Note: <issues or "none">
 ```
 
-> Claude Code: spawn `feature-implementer` (sonnet) agents in parallel, one per task in the wave.
-
 **3c — Copy changes back + delete worktrees** (orchestrator, after each task reports):
 
 For **PASS + EXECUTOR_MODEL present:**
@@ -200,7 +204,7 @@ Worktrees are **always deleted immediately** — no exceptions.
 
 ### I4 — Consolidate + update INDEX (lite model)
 
-After all waves complete:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I4. After all waves complete, ask it to:
 
 1. Update `docs/AI_HANDOFF/INDEX.md`:
    - PASS tasks → `pending_review`
@@ -214,15 +218,13 @@ After all waves complete:
    git diff --stat             # summary of all uncommitted changes
    ```
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for I4.
-
 ---
 
 ## Phase 4 — Review (strong model)
 
 ### R1 — Setup (lite model)
 
-Use the lightest model. Read:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for the R1 reads. Ask it to read:
 - `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
 - `docs/AI_HANDOFF/INDEX.md` → collect `pending_review` tasks
 
@@ -234,11 +236,13 @@ git diff --stat  # summary of all changes
 
 If `git diff` is empty and `git status` is clean → implement was not completed. Stop and re-run Phase 3.
 
-> Claude Code: `ukit-small-task-maintainer` (haiku) for R1 reads; orchestrator handles R1 guard check.
+> Orchestrator (this session) handles the R1 guard check directly.
 
 ### R2 — Model isolation check (strong model, always first)
 
-Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
+**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each `pending_review` task, call the Agent tool with `subagent_type: "code-reviewer"`. 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.
+
+The spawned reviewer agent reads `EXECUTOR_MODEL` from each task file `## Executor Report`:
 
 | Executor model | Reviewer model | Action |
 |----------------|----------------|--------|
@@ -247,8 +251,6 @@ Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
 | missing / blank | any | **REFUSE** → `changes_requested`: "EXECUTOR_MODEL missing — re-run Phase 3" |
 | "unknown" | present | proceed + flag: "executor model unverified — human confirm" |
 
-> Claude Code: spawn `code-reviewer` (opus) per task for R2–R4.
-
 ### R3 — Re-run Verification Commands (strong model)
 
 ```bash

package/templates/.claude/commands/ukit/handoff-implement.md

@@ -45,7 +45,9 @@ git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
 
 ### 3b — Run tasks in parallel (one agent/session per task)
 
-Each executor works independently in its own worktree — **NO git commit, NO git add**:
+**Claude Code — MANDATORY, do this before anything else in this wave:** call the Agent tool once per task in the wave (in parallel), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+
+Each spawned agent works independently in its own worktree — **NO git commit, NO git add**:
 
 ```
 Read docs/AI_HANDOFF/tasks/TASK-xxx.md
@@ -71,8 +73,7 @@ Executor Report (append to task file — do NOT touch INDEX.md):
   Note: <issues or "none">
 ```
 
-> Claude Code: spawn `feature-implementer` agents in parallel (one per task).
-> Other tools: open each task in separate session with code model.
+> Other tools without subagent support: open each task in a separate session with the code model.
 
 ### 3c — Orchestrator: copy changes to main + IMMEDIATELY delete worktree
 

package/templates/.claude/commands/ukit/handoff-review.md

@@ -28,6 +28,10 @@ If `git diff` is empty and `git status` is clean → handoff-implement was not c
 
 ## Step 2 — Review the diff
 
+**Claude Code — MANDATORY, do this before anything else:** for each `pending_review` task, call the Agent tool with `subagent_type: "code-reviewer"`. 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.
+
+The spawned reviewer agent performs 2a–2d below per task:
+
 ### 2a — Model isolation check (always first)
 
 Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
@@ -110,5 +114,5 @@ Review summary:
 - All approved → human reviews `git diff` and commits manually.
 - Has fixes → executor re-runs `/ukit:handoff-implement TASK-xxx`
 
-> Claude Code: spawn `code-reviewer` (opus) per task for 2a–2d. Orchestrator handles 1, 2e, 3.
-> Other tools: strong model sequentially per task, same steps.
+> Orchestrator (this session) handles Step 1, 2e, and 3 directly — those are not delegated.
+> Other tools without subagent support: manually switch to the strong model, run 2a–2d sequentially per task.

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# PreToolUse hook: hard-enforce UKit handoff model-tier contract.
+#
+# create (planning) and review must be authored by the strong tier (opus/unic-smart);
+# implement must be authored by at least the code tier (sonnet/unic-code), never lite.
+#
+# Applies identically whether triggered via standalone /ukit:handoff-create,
+# /ukit:handoff-implement, /ukit:handoff-review, or the combined /ukit:handoff-fullstack —
+# the gate is keyed on file content, not on which command was run.
+#
+# Always hard-blocks (exit 2). No advisory/soft mode — the user explicitly asked for
+# strict enforcement of this contract.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+const payload = (() => {
+  try { return JSON.parse(process.env.INPUT || '{}'); } catch { return {}; }
+})();
+const projectRoot = process.env.PROJECT_ROOT;
+const toolName = payload?.tool_name || '';
+const input = payload?.tool_input || {};
+
+function block(message) {
+  process.stderr.write(`BLOCKED (handoff model-tier guard): ${message}\n`);
+  process.exit(2);
+}
+
+function tierOf(model) {
+  if (!model) return null;
+  if (/opus|unic-smart/i.test(model)) return 'smart';
+  if (/sonnet|unic-code/i.test(model)) return 'code';
+  if (/haiku|unic-lite/i.test(model)) return 'lite';
+  return 'unknown';
+}
+
+function extractField(text, name) {
+  const matches = [...text.matchAll(new RegExp(name + ':\\s*(.+)', 'g'))];
+  if (matches.length === 0) return '';
+  return matches[matches.length - 1][1].trim();
+}
+
+if (toolName === 'Write' || toolName === 'Edit') {
+  const filePath = String(input.file_path || '');
+  if (!filePath) process.exit(0);
+
+  const relPath = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+  const isPlan = relPath === 'docs/AI_HANDOFF/PLAN.md';
+  const taskMatch = relPath.match(/^docs\/AI_HANDOFF\/tasks\/(TASK-\d+)\.md$/);
+  if (!isPlan && !taskMatch) process.exit(0);
+
+  const fileExists = fs.existsSync(filePath);
+  const currentContent = fileExists ? fs.readFileSync(filePath, 'utf8') : '';
+
+  function resultingContent() {
+    if (toolName === 'Write') {
+      return typeof input.content === 'string' ? input.content : currentContent;
+    }
+    const oldStr = input.old_string;
+    const newStr = input.new_string;
+    if (typeof oldStr !== 'string' || typeof newStr !== 'string') return currentContent;
+    return input.replace_all
+      ? currentContent.split(oldStr).join(newStr)
+      : currentContent.replace(oldStr, newStr);
+  }
+  const newContent = resultingContent();
+
+  if (isPlan && /## Planner Report/.test(newContent)) {
+    const plannerModel = extractField(newContent, 'PLANNER_MODEL');
+    if (!plannerModel || /^unknown$/i.test(plannerModel)) {
+      block('PLANNER_MODEL missing/unknown in PLAN.md. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) and self-report its model.');
+    }
+    if (tierOf(plannerModel) !== 'smart') {
+      block(`PLANNER_MODEL "${plannerModel}" is not strong/opus tier. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart).`);
+    }
+  }
+
+  if (taskMatch) {
+    const taskId = taskMatch[1];
+    const planPath = path.join(projectRoot, 'docs/AI_HANDOFF/PLAN.md');
+
+    const isFreshTaskFile = !fileExists && !/## Executor Report|## Reviewer Verdict/.test(newContent);
+    if (isFreshTaskFile) {
+      const planContent = fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf8') : '';
+      const plannerModel = extractField(planContent, 'PLANNER_MODEL');
+      if (!plannerModel || tierOf(plannerModel) !== 'smart') {
+        block(`Cannot create ${taskId}.md — PLAN.md has no valid smart-tier PLANNER_MODEL yet. Run planning via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) first.`);
+      }
+    }
+
+    if (/## Executor Report/.test(newContent) && !/## Executor Report/.test(currentContent)) {
+      const executorModel = extractField(newContent, 'EXECUTOR_MODEL');
+      if (!executorModel || /^unknown$/i.test(executorModel)) {
+        block(`${taskId}: EXECUTOR_MODEL missing/unknown. Implementation must run via Agent tool subagent_type: "feature-implementer" (sonnet/unic-code) and self-report its model.`);
+      }
+      if (tierOf(executorModel) === 'lite') {
+        block(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier. Implementation must run on at least sonnet/unic-code, never haiku/unic-lite.`);
+      }
+    }
+
+    if (/## Reviewer Verdict/.test(newContent) && !/## Reviewer Verdict/.test(currentContent)) {
+      const executorModel = extractField(currentContent, 'EXECUTOR_MODEL') || extractField(newContent, 'EXECUTOR_MODEL');
+      const reviewerModel = extractField(newContent, 'REVIEWER_MODEL');
+      if (!reviewerModel || /^unknown$/i.test(reviewerModel)) {
+        block(`${taskId}: REVIEWER_MODEL missing/unknown. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart) and self-report its model.`);
+      }
+      if (tierOf(reviewerModel) !== 'smart') {
+        block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not strong/opus tier. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart).`);
+      }
+      if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
+        block(`${taskId}: REVIEWER_MODEL ("${reviewerModel}") matches EXECUTOR_MODEL — reviewer must differ from executor. Re-run review through a different subagent/model.`);
+      }
+    }
+  }
+  process.exit(0);
+}
+
+if (toolName === 'Bash') {
+  const command = String(input.command || '');
+  if (!/\bgit\s+push\b/.test(command)) process.exit(0);
+
+  const activePath = path.join(projectRoot, 'docs/AI_HANDOFF/ACTIVE.md');
+  const indexPath = path.join(projectRoot, 'docs/AI_HANDOFF/INDEX.md');
+  if (!fs.existsSync(activePath) || !fs.existsSync(indexPath)) process.exit(0); // no handoff cycle here
+
+  const taskIds = [...fs.readFileSync(indexPath, 'utf8').matchAll(/TASK-\d+/g)]
+    .map((m) => m[0])
+    .filter((v, i, a) => a.indexOf(v) === i);
+
+  const problems = [];
+  for (const taskId of taskIds) {
+    const taskPath = path.join(projectRoot, `docs/AI_HANDOFF/tasks/${taskId}.md`);
+    if (!fs.existsSync(taskPath)) continue;
+    const text = fs.readFileSync(taskPath, 'utf8');
+    if (!text.includes('## Reviewer Verdict')) continue; // not yet reviewed, not this push's concern
+
+    const executorModel = extractField(text, 'EXECUTOR_MODEL');
+    const reviewerModel = extractField(text, 'REVIEWER_MODEL');
+
+    if (!executorModel || /^unknown$/i.test(executorModel)) problems.push(`${taskId}: EXECUTOR_MODEL missing/unknown`);
+    else if (tierOf(executorModel) === 'lite') problems.push(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier`);
+
+    if (!reviewerModel || /^unknown$/i.test(reviewerModel)) problems.push(`${taskId}: REVIEWER_MODEL missing/unknown`);
+    else if (tierOf(reviewerModel) !== 'smart') problems.push(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not opus/unic-smart tier`);
+
+    if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
+      problems.push(`${taskId}: REVIEWER_MODEL == EXECUTOR_MODEL`);
+    }
+  }
+
+  if (problems.length > 0) {
+    block(`git push refused — handoff model-tier contract violated:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+  process.exit(0);
+}
+
+process.exit(0);
+NODE
+
+exit $?

package/templates/.claude/settings.json

@@ -1,5 +1,6 @@
 {
-  "fastMode": true,
+  "model": "sonnet",
+  "fastMode": false,
   "fastModePerSessionOptIn": false,
   "alwaysThinkingEnabled": true,
   "effortLevel": "high",
@@ -76,6 +77,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
+            "timeout": 8
           }
         ]
       },
@@ -101,6 +107,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
+            "timeout": 8
           }
         ]
       }