@ngockhoale/ukit 2.0.1 → 2.0.3

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to UKit are documented here.
 
+## 2.0.3 - 2026-08-11
+
+### Added
+
+- **`ukit memory propose "<text>" [--category <name>] [--project <id>]`** — the missing first step of the Project Pattern Learning loop. Wires the existing `proposePatternCandidate()` to the CLI so a candidate can actually be created; duplicate proposals of the same text return the existing pending entry instead of stacking.
+
+### Fixed
+
+- **Project Pattern Learning was unreachable in every real install.** v2.0.0 shipped `ukit memory list --pending` / `approve` / `reject`, but nothing could create a candidate: `proposePatternCandidate()` had zero production callers, and the `project-learning` skill told the AI to import it from `src/core/memory/store.js` — a path that only exists inside the UKit repo, never in an installed project. The skill now points at the new CLI subcommand, and `tests/cli/memoryCommand.test.js` drives the loop through the CLI only, so a fix that works solely via a direct function import cannot make those tests pass.
+- **The v2.0.0 handoff Interfaces block never shipped.** `Consumes`/`Produces` were added to the repo's own `docs/AI_HANDOFF/RULES.md` and `tasks/_TEMPLATE.md` but not to the `templates/docs/AI_HANDOFF/` copies that `ukit install` actually delivers, so installed projects got handoff docs without the feature the 2.0.0 changelog claims. Same dev-mirror divergence class as the 2.0.2 hard-cap hooks.
+
+## 2.0.2 - 2026-08-11
+
+### Added
+
+- **Absolute context hard cap** — new `compact.hardCapTokens` (default `220000`) and `compact.hardCapBlock` (default `true`). Crossing the cap makes `context-hardcap-gate.sh` refuse `Edit`/`Write`/`Bash` outright until real compaction happens, instead of only printing a suggestion. `Read`/`Grep`/`Glob` stay open so the agent can still explain the block — only a human can invoke compaction. This is a new, separate ceiling: the existing soft/hard advisory phases (`compact.tokenThreshold` 50k, derived hard 80k) are unchanged.
+- **`reset-compact-pressure.sh`** (SessionStart) — zeroes the compact pressure tracker at session start, so the cap measures the current session rather than accumulating over a project's lifetime.
+
+### Fixed
+
+- **The hard cap would have shipped dead.** Both new hooks were wired into `settings.json` but had no entry in `manifests/platform.full.yaml`, so `ukit install` never copied them: real installs got `settings.json` pointing at scripts that do not exist. Found by a scratch-project install, not by the test suite. Added a `tests/manifest/settingsHookCoverage.test.js` regression guard that fails whenever a hook is wired without a manifest entry, or a manifest hook's `sourceTemplate` is missing, or the dev mirror and template `settings.json` disagree.
+- **Permanent-block deadlock.** `compact-pressure.json` accumulated forever, so the cap would eventually block `Edit`/`Write`/`Bash` in every future session even with tiny context — and because the gate covers `Bash`, the documented remedies could not run. Fixed by the SessionStart reset plus a PreCompact reset.
+- **Reset skipped on cache hit.** The PreCompact reset sat after `reinject-context.mjs`'s prompt-cache early return, so a cache hit left the gate tripped permanently. Moved ahead of the return.
+- **Gate bypass via `NotebookEdit`/`MultiEdit`.** The gate compared `tool_name` exactly while the `settings.json` matcher is a regex (`Edit|Write` also matches both), so those tools fired the hook and passed through it. Now matched against an explicit tool set.
+- Prompt cache in `reinject-context.mjs` no longer keys on the live pressure value when the threshold plan is inactive (where it cannot affect output), which had turned every run into a cache miss.
+- `compact.hardCapTokens` reads straight from config instead of deriving from the advisory hard threshold, so raising `tokenThreshold` can never silently raise the ceiling.
+
+## 2.0.1 - 2026-08-10
+
+### Fixed
+
+- `ukit memory approve` / `reject` accept an optional `--project <id>` flag, so a pattern candidate belonging to a non-current project (surfaced by `list --pending`'s cross-project scan) can actually be resolved instead of failing "not found".
+- `ukit memory list` reports a conventions count alongside decisions, so an approval's effect is visible.
+
 ## 2.0.0 - 2026-08-10
 
 ### Added

package/manifests/platform.full.yaml

@@ -1098,6 +1098,29 @@ items:
     packs:
       - core
 
+  - id: hook-context-hardcap-gate
+    type: hook
+    sourceTemplate: .claude/hooks/context-hardcap-gate.sh
+    targetPath: .claude/hooks/context-hardcap-gate.sh
+    requires:
+      - ukit-runtime-compact-threshold-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-reset-compact-pressure
+    type: hook
+    sourceTemplate: .claude/hooks/reset-compact-pressure.sh
+    targetPath: .claude/hooks/reset-compact-pressure.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-compress-output
     type: hook
     sourceTemplate: .claude/hooks/compress-output.sh

package/package.json

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

package/src/cli/commands/memory.js

@@ -3,6 +3,7 @@ import {
   forgetMemoryItem,
   listMemoryItems,
   listPendingPatternCandidates,
+  proposePatternCandidate,
   resolvePatternCandidate,
   runProjectHygiene,
 } from '../../core/memory/store.js';
@@ -15,6 +16,15 @@ import fs from 'node:fs/promises';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 
+function extractFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index < 0) return { value: null, rest: args };
+  return {
+    value: args[index + 1] ?? null,
+    rest: [...args.slice(0, index), ...args.slice(index + 2)],
+  };
+}
+
 async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
   let entries = [];
   try {
@@ -75,6 +85,26 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'propose') {
+    const projectFlag = extractFlag(rest, '--project');
+    const categoryFlag = extractFlag(projectFlag.rest, '--category');
+    const text = categoryFlag.rest.join(' ').trim();
+    if (!text) {
+      throw new Error('Missing pattern text. Usage: ukit memory propose "<text>" [--category <name>] [--project <id>]');
+    }
+
+    const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot)).project.name;
+    const candidate = await proposePatternCandidate(projectRoot, projectId, {
+      text,
+      category: categoryFlag.value,
+      detectedFrom: 'cli',
+    });
+
+    console.log(`[UKit] Proposed ${candidate.id} (${candidate.status}) for project ${projectId}.`);
+    console.log('[UKit] Review with `ukit memory list --pending`, then `ukit memory approve <id>`.');
+    return;
+  }
+
   if (subcommand === 'approve' || subcommand === 'reject') {
     const projectFlagIndex = rest.indexOf('--project');
     const explicitProjectId = projectFlagIndex >= 0 ? rest[projectFlagIndex + 1] : null;
@@ -186,7 +216,7 @@ export async function runMemory({ projectRoot, argv = [] }) {
 
 export function printMemoryHelp() {
   console.log('UKit Memory Commands');
-  console.log('Usage: ukit memory <list|search|recall|forget|export|approve|reject|hygiene> [args]');
+  console.log('Usage: ukit memory <list|search|recall|forget|export|propose|approve|reject|hygiene> [args]');
   console.log('');
   console.log('Subcommands:');
   console.log('  list               List memory items in shared .ukit/storage/memory');
@@ -195,6 +225,7 @@ export function printMemoryHelp() {
   console.log('  recall <task>      Print a compact previous-context block for the current task');
   console.log('  forget <id>        Remove one memory item by id');
   console.log('  export             Print all memory as JSON');
+  console.log('  propose "<text>" [--category <name>] [--project <id>]  Propose a project convention for human approval');
   console.log('  approve <id> [--project <id>]  Approve a pending pattern candidate into project conventions');
   console.log('  reject <id> [--project <id>]   Reject a pending pattern candidate');
   console.log('  hygiene [--project <id>]  Run decision-conflict resolution + session archiving now');

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/project-learning/SKILL.md

@@ -18,7 +18,7 @@ One-off patterns are not conventions. Skip this for anything seen only once.
 
 ## What NOT to do
 
-Never write directly into `conventions`, and never mention this to the human as if it's already decided. Always propose through Task 10's storage path — call `proposePatternCandidate(projectRoot, projectId, candidate)` from `src/core/memory/store.js` (or, from a plain conversation, tell the human to check `ukit memory list --pending`). Phrase the candidate as one falsifiable sentence:
+Never write directly into `conventions`, and never mention this to the human as if it's already decided. Always propose through the CLI — run `ukit memory propose "<text>" [--category <name>]`, then tell the human to check `ukit memory list --pending`. Phrase the candidate as one falsifiable sentence:
 
 - Good: "Use `ControlInput` from `src/components/` instead of raw `<input>` for form fields."
 - Bad: "This project seems to like custom inputs."

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -437,14 +437,42 @@ export function buildCompactThresholds(config = {}) {
   const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
+  // Deliberately NOT coupled to hardThreshold: this is an absolute ceiling, so raising
+  // the advisory tokenThreshold must never silently raise the cap along with it.
+  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 220_000));
 
   return {
     softThreshold,
     hardThreshold,
     baselineTokens,
+    hardCapTokens,
   };
 }
 
+// Absolute, non-negotiable ceiling — separate from the soft/hard advisory phases above.
+// Crossing this means the advisory nudges were not followed; real compaction is mandatory.
+export function isHardCapExceeded(estimatedTotalTokens, config = {}) {
+  const { hardCapTokens } = buildCompactThresholds(config);
+  return finiteNumber(estimatedTotalTokens, 0) >= hardCapTokens;
+}
+
+// Called from the PreCompact hook path once real compaction has happened, so the
+// hard-cap gate unblocks on the next tool call instead of staying tripped forever.
+export function resetCompactPressureState(rawState = {}, config = {}) {
+  const current = buildCompactPressureState(rawState, config);
+  return buildCompactPressureState({
+    ...current,
+    updatedAt: Date.now(),
+    sessionTokens: 0,
+    estimatedContextTokens: 0,
+    estimatedTotalTokens: 0,
+    recentPrompts: [],
+    recentOutputs: [],
+    cooldownUntil: 0,
+    latestPlan: null,
+  }, config);
+}
+
 function buildReleaseThresholds(thresholds = buildCompactThresholds()) {
   const softReleaseThreshold = Math.max(
     Math.min(thresholds.softThreshold, Math.round(thresholds.softThreshold * SOFT_RELEASE_RATIO)),

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -14,6 +14,8 @@ import {
 import {
   buildThresholdCompactPlan,
   readCompactPressureState,
+  resetCompactPressureState,
+  writeCompactPressureState,
   writeThresholdCompactPlan,
 } from './compact-threshold.mjs';
 
@@ -62,6 +64,14 @@ async function main() {
   const rawBodyLines = [...rawStaticLines, ...dynamicLines];
   const bodyLines = [...staticLines, ...dynamicLines];
   const pressureState = await readCompactPressureState(projectRoot, config);
+
+  // Reset the hard-cap tracker as early as possible: this hook fires on every real
+  // compaction, and it is the only signal that context actually shrank. It must happen
+  // before the promptCache early-return below, otherwise a cache hit would skip it and
+  // leave context-hardcap-gate.sh permanently tripped. Downstream writes
+  // (writeThresholdCompactPlan) re-read from disk, so they build on the zeroed state and
+  // keep their own stats increments intact.
+  await writeCompactPressureState(projectRoot, resetCompactPressureState(pressureState, config), config);
   const anchorLines = dynamicLines.filter((line) => (
     line.startsWith('- Recent routed lane:')
     || line.startsWith('- Current approach:')
@@ -93,7 +103,10 @@ async function main() {
     activeSkills: Array.isArray(state?.activeSkills) ? state.activeSkills.map((item) => getActiveSkillPath(item)) : [],
     bodyLines: thresholdPlan.active ? thresholdPlan.lines : bodyLines,
     thresholdPhase: thresholdPlan.active ? thresholdPlan.phase : 'monitor',
-    estimatedTotalTokens: thresholdPlan.active ? thresholdPlan.estimatedTotalTokens : pressureState.estimatedTotalTokens,
+    // Only key on the token count when the threshold plan is active — that is the only case
+    // where it changes the rendered output. Keying on the live pressure value while inactive
+    // would miss the cache on every run, since the reset above zeroes it between runs.
+    estimatedTotalTokens: thresholdPlan.active ? thresholdPlan.estimatedTotalTokens : 0,
   });
 
   if (config.tokenPipeline?.promptCache) {

package/templates/docs/AI_HANDOFF/RULES.md

@@ -106,6 +106,8 @@ A task is `ready` only when it has:
 - Clear target files
 - Clear action
 - Dependencies stated
+- **Interfaces** — Consumes/Produces với chữ ký thật (function/endpoint/type), không placeholder;
+  `(none)` hợp lệ nếu task không có input/output liên task
 - **Test Plan** (PLAN.md §4) — happy path + ≥1 edge case (+ regression test nếu fix bug); hoặc `N/A` kèm lý do
 - Verification command (lệnh executor sẽ chạy)
 - Acceptance criteria

package/templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md

@@ -2,7 +2,7 @@
 
 <!--
 Template cho mỗi task. Planner copy file này khi split PLAN.md sang task riêng.
-File này BẮT BUỘC giữ structure: Goal + Test Cases + Test Files + Verification + Acceptance.
+File này BẮT BUỘC giữ structure: Goal + Test Cases + Test Files + Verification + Acceptance + Interfaces.
 Mọi AI (planner / executor / reviewer) đọc và ghi vào file NÀY. Không trao đổi ngoài file.
 -->
 
@@ -48,6 +48,17 @@ yarn test tests/path/to/file.test.js
 
 - (none) <!-- hoặc TASK-xxx phải done trước -->
 
+## Interfaces
+
+<!--
+Executor thường CHỈ thấy task file này, không thấy task khác. Block này là cách nó biết đúng
+tên/kiểu mà task khác kỳ vọng — tránh lỗi kiểu "TASK-3 gọi clearLayers() nhưng TASK-7 lại gọi
+clearFullLayers()". Ghi chữ ký thật (function/endpoint/type), không ghi placeholder.
+-->
+
+- Consumes: `<what this task uses from earlier tasks — exact function/endpoint signatures, types>` <!-- hoặc (none) -->
+- Produces: `<what later tasks rely on from this task — exact function/endpoint signatures, types>` <!-- hoặc (none) -->
+
 ---
 
 ## Discussion

package/templates/ukit/storage/config.json

@@ -9,6 +9,8 @@
   "compact": {
     "enabled": true,
     "tokenThreshold": 50000,
+    "hardCapTokens": 220000,
+    "hardCapBlock": true,
     "contextRotDetection": true,
     "askBeforeDrop": true,
     "codexContext": {
@@ -367,6 +369,8 @@
     "compact": {
       "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
       "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
+      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 220000 token ước lượng). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc.",
+      "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm. Không có ngoại lệ.",
       "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
       "askBeforeDrop": "Giữ thái độ thận trọng trước khi bỏ context quan trọng. Nếu rủi ro thì hand back cho main model.",
       "agentContext": {