@ngockhoale/ukit 1.6.8 → 2.0.2

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Independent reviewer for handoff Phase 3, and for spec/plan documents. For code (default): 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. For spec/plan documents (set REVIEW_TARGET_TYPE=spec or plan): reviews a docs/plans/*.md file for completeness/consistency/clarity/scope/YAGNI, produces Status: Approved | Issues Found."
 model: opus  # unic-smart
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
@@ -10,7 +10,14 @@ You are the independent reviewer for UKit's handoff Quality Gate. Your model is
 
 **Do not invent issues. Do not rubber-stamp.** Every finding must point at a specific file + line + concrete failure mode.
 
-## Inputs you expect
+## REVIEW_TARGET_TYPE
+
+- `code` (default, if not specified) — reviewing a handoff task diff. Follow **Code Review** below, unchanged.
+- `spec` | `plan` — reviewing a document (e.g. `docs/plans/*.md`), no diff/task file/executor report involved. Skip straight to **Spec/Plan Review** at the end of this file instead.
+
+## Code Review (REVIEW_TARGET_TYPE=code)
+
+### Inputs you expect
 
 - Path to task file: `docs/AI_HANDOFF/tasks/TASK-xxx.md` (has Test Plan §4 + Verification Commands + Executor Report at bottom).
 - The executor's `STATUS: DONE` report with FILES_CHANGED + VERIFICATION block.
@@ -18,7 +25,7 @@ You are the independent reviewer for UKit's handoff Quality Gate. Your model is
 
 If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete handoff package".
 
-## Review order
+### Review order
 
 1. **Test Plan adherence** — Were all tests in §4 actually implemented? Run them yourself: `<task Verification Commands>`. Fresh PASS required, no trusting executor's output blindly.
 2. **Correctness** — Does the diff implement the requested behavior? Any obvious wrong assumptions, stale refs, missing cases?
@@ -27,14 +34,14 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 5. **Performance / scale** — Accidental N+1, repeated I/O, large scans inside hot paths.
 6. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
 
-## Severity ladder
+### Severity ladder
 
 - **CRITICAL** — security hole, data loss risk, broken core behavior, test was faked (no real assertion), or verification command does NOT actually pass when you re-run it. Blocks handoff cứng.
 - **CHANGES-REQUESTED** — Important issues: missing edge-case test, regression risk in shared code, wrong abstraction at scope boundary. Executor must fix and re-submit.
 - **APPROVED-WITH-MINOR** — Minor naming / doc / style issues. Logged on task file but handoff allowed.
 - **APPROVED** — Clean.
 
-## Output (append to task file as `## Reviewer Verdict`)
+### Output (append to task file as `## Reviewer Verdict`)
 
 ```
 ## Reviewer Verdict
@@ -59,7 +66,7 @@ NOTES: [1-2 sentences for human reviewer if needed]
 
 After writing the verdict, update `docs/AI_HANDOFF/INDEX.md` row for this task: set Status = NEXT_STATUS_FOR_INDEX, set Reviewer = your model name.
 
-## Model isolation check (FIRST thing you do)
+### Model isolation check (FIRST thing you do)
 
 UKit cannot force any tool to use a specific model. The contract is enforced HERE, by you, via self-report comparison.
 
@@ -77,10 +84,47 @@ UKit cannot force any tool to use a specific model. The contract is enforced HER
 
 Same model is the most common silent failure. Do not skip this check.
 
-## Rules
+### Rules
 
 - **Always re-run** the task's Verification Commands. If they fail, VERDICT = CRITICAL regardless of executor claims.
 - If executor said `TEST_PLAN_FOLLOWED: N/A` without a real justification, downgrade to at minimum CHANGES-REQUESTED.
 - Never approve when test file has no real `expect`/`assert` - that is a fake test -> CRITICAL.
 - 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.
+
+## Spec/Plan Review (REVIEW_TARGET_TYPE=spec|plan)
+
+### Inputs you expect
+
+- Path to the spec/plan document (e.g. `docs/plans/*.md`). No diff, no task file, no executor report — review the document itself.
+
+### Review order
+
+| Category | What to look for |
+|---|---|
+| Completeness | TODO/TBD/placeholders, incomplete sections |
+| Consistency | internal contradictions, conflicting requirements |
+| Clarity | requirements ambiguous enough to cause a wrong build |
+| Scope | focused enough for one plan, not silently covering multiple subsystems |
+| YAGNI | unrequested features, over-engineering |
+
+Only flag issues that would cause real problems during implementation planning. Approve unless there are serious gaps that would lead to a flawed plan.
+
+### Output
+
+```
+Status: Approved | Issues Found
+
+COMPLETENESS:
+  - <finding, or "none">
+CONSISTENCY:
+  - <finding, or "none">
+CLARITY:
+  - <finding, or "none">
+SCOPE:
+  - <finding, or "none">
+YAGNI:
+  - <finding, or "none">
+
+NOTES: [1-2 sentences if needed]
+```

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

@@ -15,9 +15,21 @@ Use the strongest model available — planning with a weak model produces weak t
 - **Pre-read context** (if provided): compact summary of INDEX.md, ACTIVE.md, RULES.md, _TEMPLATE.md. Use it directly — do NOT re-read those files.
 - If no pre-read context → read the files yourself (fallback for direct invocation).
 
+## Scope Check (before Phase 1)
+
+Before refining the request into `PLAN.md`, check whether it describes multiple independent subsystems (e.g. "CRM + AI + billing + analytics + mobile app"). If yes, stop and output a decomposition table instead of planning the mega-spec:
+
+```
+Scope complexity: HIGH
+Detected systems: [...]
+Recommended decomposition: N modules — plan each as a separate PLAN.md
+```
+
+Wait for human confirmation before writing `PLAN.md`.
+
 ## Phase 1 — Write PLAN.md
 
-Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
+Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
 
 ```
 §1 Intent       — what problem, what success looks like
@@ -29,6 +41,9 @@ Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
                   table: | Type | Test Name | Expected |
 §5 Verification — exact shell commands executor will run
 §6 Acceptance   — checklist of done criteria (prefer verifiable/command-based criteria)
+§7 Global Constraints — one line each: version floors, dependency limits, naming/copy
+                  rules, platform requirements. Every TASK-xxx.md inherits this section
+                  by reference — do not repeat these constraints inside each task.
 ```
 
 **§4 is non-negotiable.** No test plan = plan not ready.
@@ -42,6 +57,8 @@ PLANNER_MODEL: <your exact model ID — e.g. claude-opus-4-6>
 
 ## Phase 2 — Split into TASK-xxx.md
 
+**Right-sizing rule:** A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. Split only where a reviewer could meaningfully approve one task while rejecting its neighbor. Each task ends with an independently testable deliverable.
+
 Use `_TEMPLATE.md` structure (from pre-read context or file).
 
 **Every task MUST have all fields:**
@@ -87,5 +104,4 @@ Wave structure is NOT stored here — inferred from task `Dependencies` fields a
 
 - Do NOT implement. Job ends when all tasks are `ready` or `needs_breakdown`.
 - Undone tasks in INDEX.md → warn human: continue old cycle or start fresh?
-- Prefer smaller tasks. Each task = one executor session.
 - Cannot determine test cases → `needs_breakdown` + Discussion thread note.

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# PreToolUse hook: hard-enforce an absolute context token cap (compact.hardCapTokens,
+# default 220000), separate from the soft/hard advisory pressure phases in
+# compact-threshold.mjs (default soft=50000/hard=80000, which only print a suggestion).
+#
+# Those advisory phases are just injected text — nothing stops the agent from ignoring
+# them and letting a session run to hundreds of thousands of tokens with no compaction.
+# This gate is the backstop: once estimatedTotalTokens >= hardCapTokens, Edit/Write/Bash
+# are refused (exit 2) until a real compaction happens. Real compaction is detected via
+# the PreCompact hook (reinject-context.mjs), which resets the tracked counter — see
+# resetCompactPressureState in compact-threshold.mjs. No advisory bypass, no exceptions.
+#
+# Matcher is Edit|Write|Bash only. Read/Grep/Glob stay open so the agent can still
+# investigate, report status, and tell the user to run /compact — gating those too would
+# just brick the session with no way out, since only the user (not the agent) can invoke
+# real compaction.
+#
+# Config toggle: compact.hardCapBlock (default true). Set to false only to debug this
+# gate itself; it must not become a normal escape hatch.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const payload = (() => {
+  try {
+    const parsed = JSON.parse(process.env.INPUT || '');
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+})();
+
+const projectRoot = process.env.PROJECT_ROOT;
+const hookDir = process.env.HOOK_DIR;
+const toolName = payload?.tool_name || '';
+
+// Gate only mutating/costly tools. Everything else (Read, Grep, Glob, TodoWrite, ...)
+// stays free so the agent can still respond and tell the user to compact.
+// Listed explicitly because the settings.json matcher is a regex ("Edit|Write") that also
+// matches NotebookEdit/MultiEdit -- an exact !== comparison would let those slip through
+// the gate while still firing the hook.
+const GATED_TOOLS = new Set(['Edit', 'Write', 'Bash', 'NotebookEdit', 'MultiEdit']);
+if (!GATED_TOOLS.has(toolName)) {
+  process.exit(0);
+}
+
+function readJsonSafe(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+(async () => {
+  const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
+  if (config?.compact?.hardCapBlock === false) {
+    process.exit(0);
+    return;
+  }
+
+  const thresholdModulePath = path.join(hookDir, '..', 'ukit', 'runtime', 'compact-threshold.mjs');
+  if (!fs.existsSync(thresholdModulePath)) {
+    process.exit(0);
+    return;
+  }
+
+  const mod = await import(pathToFileURL(thresholdModulePath).href);
+  const pressurePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'compact-pressure.json');
+  const rawState = readJsonSafe(pressurePath, null);
+  const state = mod.buildCompactPressureState(rawState, config);
+  const thresholds = mod.buildCompactThresholds(config);
+
+  if (state.estimatedTotalTokens < thresholds.hardCapTokens) {
+    process.exit(0);
+    return;
+  }
+
+  const lines = [
+    `BLOCKED (context hard cap): estimated context ~${state.estimatedTotalTokens} tokens >= hard cap ${thresholds.hardCapTokens}.`,
+    'This is an absolute ceiling (compact.hardCapTokens), separate from the soft/hard advisory phases — those were apparently not followed.',
+    `Edit/Write/Bash refused (tool_name=${toolName}) until real compaction happens.`,
+    'Remedy (any one): run /compact, or start a new session (SessionStart resets the counter), or delete .ukit/storage/cache/compact-pressure.json.',
+    'Do not work around this by summarizing inline and continuing, and do not reach for a non-gated write tool.',
+  ];
+  process.stderr.write(`${lines.join('\n')}\n`);
+  process.exit(2);
+})().catch((err) => {
+  // Unlike vision-gate.sh, a logic error here fails OPEN: this is a backstop on top of
+  // advisory nudges, not a correctness gate — a broken gate must not brick every session.
+  process.stderr.write(`context-hardcap-gate: internal error, failing open: ${err?.message ?? err}\n`);
+  process.exit(0);
+});
+NODE
+
+exit $?

package/templates/.claude/hooks/reset-compact-pressure.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# SessionStart hook: zero the compact pressure tracker at the start of every session.
+#
+# compact-pressure.json is a single per-project file whose sessionTokens counter only ever
+# accumulates (see registerPromptPressure/registerOutputPressure in compact-threshold.mjs).
+# Without this reset it sums every prompt and every command output across the entire
+# lifetime of the project, so it eventually crosses compact.hardCapTokens and permanently
+# blocks Edit/Write/Bash in every future session -- even when actual context is tiny.
+# That is a deadlock: the gate blocks Bash, so the documented remedies (ukit install,
+# ukit doctor) cannot run, and compaction never fires because real context is small.
+#
+# Resetting here makes the counter measure THIS session only, which is what the hard cap
+# is actually trying to approximate. It also gives the gate a guaranteed escape hatch:
+# restarting the session always clears a stuck gate, with no manual file surgery.
+#
+# Always exits 0 -- a failure here must never prevent a session from starting.
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+PRESSURE_FILE="$PROJECT_ROOT/.ukit/storage/cache/compact-pressure.json"
+
+if [ -f "$PRESSURE_FILE" ]; then
+  rm -f "$PRESSURE_FILE" 2>/dev/null || true
+fi
+
+exit 0

package/templates/.claude/settings.json

@@ -87,6 +87,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-gate.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\"",
+            "timeout": 8
           }
         ]
       },
@@ -117,6 +122,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\"",
+            "timeout": 8
           }
         ]
       }
@@ -177,6 +187,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\"",
+            "timeout": 8
           }
         ]
       }

package/templates/.claude/skills/canvas-design/SKILL.md

@@ -52,27 +52,9 @@ The philosophy must guide the next version to express ideas VISUALLY, not throug
 
 ### PHILOSOPHY EXAMPLES
 
-**"Concrete Poetry"**
-Philosophy: Communication through monumental form and bold geometry.
-Visual expression: Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions, Polish poster energy meets Le Corbusier. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.
+Five condensed reference examples ("Concrete Poetry", "Chromatic Language", "Analog Meditation", "Organic Systems", "Geometric Silence") showing the philosophy → visual-expression pattern are in [`philosophy-examples.md`](philosophy-examples.md).
 
-**"Chromatic Language"**
-Philosophy: Color as the primary information system.
-Visual expression: Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.
-
-**"Analog Meditation"**
-Philosophy: Quiet visual contemplation through texture and breathing room.
-Visual expression: Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.
-
-**"Organic Systems"**
-Philosophy: Natural clustering and modular growth patterns.
-Visual expression: Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.
-
-**"Geometric Silence"**
-Philosophy: Pure order and restraint.
-Visual expression: Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.
-
-*These are condensed examples. The actual design philosophy should be 4-6 substantial paragraphs.*
+*The actual design philosophy should be 4-6 substantial paragraphs.*
 
 ### ESSENTIAL PRINCIPLES
 - **VISUAL PHILOSOPHY**: Create an aesthetic worldview to be expressed through design

package/templates/.claude/skills/canvas-design/philosophy-examples.md

@@ -0,0 +1,23 @@
+# Canvas Design Philosophy Examples
+
+Condensed reference examples showing the philosophy → visual-expression pattern described in `SKILL.md`. Use these to spark creativity, not as a fixed catalog — the actual design philosophy for a piece should be 4-6 substantial paragraphs.
+
+**"Concrete Poetry"**
+Philosophy: Communication through monumental form and bold geometry.
+Visual expression: Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions, Polish poster energy meets Le Corbusier. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.
+
+**"Chromatic Language"**
+Philosophy: Color as the primary information system.
+Visual expression: Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.
+
+**"Analog Meditation"**
+Philosophy: Quiet visual contemplation through texture and breathing room.
+Visual expression: Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.
+
+**"Organic Systems"**
+Philosophy: Natural clustering and modular growth patterns.
+Visual expression: Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.
+
+**"Geometric Silence"**
+Philosophy: Pure order and restraint.
+Visual expression: Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.

package/templates/.claude/skills/debugging-toolkit/SKILL.md

@@ -53,28 +53,7 @@ You MUST complete each phase before proceeding to the next.
    - Git diff, recent commits
    - New dependencies, config changes
 
-4. **Root Cause Tracing (Deep Dive)**
-
-   **Use when error is deep in call stack:**
-
-   **The Tracing Process:**
-   1. **Observe Symptom:** `Error: git init failed in /packages/core`
-   2. **Find Immediate Cause:** `execFile('git', ['init'], { cwd: '' })`
-   3. **Trace Upwards:**
-      - Who called this? `WorktreeManager`
-      - With what arguments? `projectDir = ''`
-   4. **Find Original Trigger:**
-      - Where did empty string come from? `setupCoreTest()` returned empty `tempDir`
-   5. **Fix at Source:** Fix `setupCoreTest`, NOT the immediate caller.
-
-   **Instrumentation:**
-   If manual tracing fails, add logging *before* the failure:
-   ```js
-   console.error('DEBUG context:', {
-     arg: someArg,
-     stack: new Error().stack // crucial!
-   });
-   ```
+4. **Root Cause Tracing (Deep Dive)** — use when error is deep in call stack: trace upwards from symptom to original trigger, fix at source. Worked example + instrumentation snippet: [`reference-tables.md`](reference-tables.md#root-cause-tracing-deep-dive).
 
 5. **Gather Evidence in Multi-Component Systems**
    - Log what enters/exits each component boundary
@@ -146,11 +125,4 @@ If you catch yourself thinking:
 
 **ALL of these mean: STOP. Return to Phase 1.**
 
-## Quick Reference
-
-| Phase | Key Activities | Success Criteria |
-|-------|---------------|------------------|
-| **1. Root Cause** | Read errors, reproduce, trace stack backwards | Understand WHAT and WHY |
-| **2. Pattern** | Find working examples, compare | Identify differences |
-| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
-| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+Compact per-phase quick-reference table: [`reference-tables.md`](reference-tables.md).

package/templates/.claude/skills/debugging-toolkit/reference-tables.md

@@ -0,0 +1,33 @@
+# Debugging Toolkit — Quick Reference
+
+Compact restatement of the four phases in `SKILL.md`. Read the phases first; this table is for quick lookup during a session.
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, trace stack backwards | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## Root Cause Tracing (Deep Dive)
+
+**The Tracing Process:**
+1. **Observe Symptom:** `Error: git init failed in /packages/core`
+2. **Find Immediate Cause:** `execFile('git', ['init'], { cwd: '' })`
+3. **Trace Upwards:**
+   - Who called this? `WorktreeManager`
+   - With what arguments? `projectDir = ''`
+4. **Find Original Trigger:**
+   - Where did empty string come from? `setupCoreTest()` returned empty `tempDir`
+5. **Fix at Source:** Fix `setupCoreTest`, NOT the immediate caller.
+
+**Instrumentation:**
+If manual tracing fails, add logging *before* the failure:
+```js
+console.error('DEBUG context:', {
+  arg: someArg,
+  stack: new Error().stack // crucial!
+});
+```