@ngockhoale/ukit 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.0.2",
+  "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/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/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