@ngockhoale/ukit 3.4.15 → 3.4.17

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.17 - 2026-10-06
+
+**Planners can revise an unimplemented task that still carries the skeleton Executor Report.**
+`handoff-model-guard.sh` blocked every Edit/Write to an existing `TASK-xxx.md` whose
+`## Executor Report` (or `## Reviewer Verdict`) was still the Phase-2 skeleton, demanding
+`EXECUTOR_MODEL` — so `/ukit:handoff-create` could create a task but never amend it after
+plan review. The model gate now fires only when the phase section itself changes to real
+content; edits elsewhere, unchanged skeletons and inert placeholders (`Not started.`,
+`KEY: -`) pass. Real executor/reviewer reports without a valid model, lite-tier models and
+real-model demotion stay blocked. Regression: `tests/hooks/taskSkeletonAmendment.test.js`.
+
+## 3.4.16 - 2026-10-05
+
+**Create-scope guard no longer blocks planner subagents running in a git worktree.**
+`handoff-model-guard.sh` classified write targets against the main project root, so a
+`handoff-planner` isolated in a worktree (`.claude/worktrees/<n>/`, `.worktrees/<n>/`, or a
+sibling checkout of the same repo) writing `docs/AI_HANDOFF/*` read as `deny-.claude` /
+`outside-root` — an unfixable block the agent retried blind. Targets are now scoped against
+that worktree's own root (same-repo verified via git common dir); source/config stay denied
+inside the worktree and unrelated outside paths stay denied. Test: `tests/hooks/createScopeGuard.test.js` #13.
+
 ## 3.4.15 - 2026-10-05
 
 **Hook chain no longer masks a real gate block (stops blind-retry token burn).**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.15",
+  "version": "3.4.17",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

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

@@ -197,6 +197,31 @@ function isPlaceholderValue(value) {
   if (!raw || /^[<(]/.test(raw)) return true;
   return ['-','--','tbd','todo','n/a','na','none','unknown','pending'].includes(raw.toLowerCase());
 }
+
+// Planning amendments (handoff-create revising an unimplemented task) re-submit a task whose
+// `## Executor Report` / `## Reviewer Verdict` is still the Phase-2 skeleton. The model gate
+// exists to stop a skeleton being promoted into a "real" report without a validated model, so it
+// must only fire when the phase section itself is touched with real content — not when the edit
+// leaves the skeleton unchanged or keeps it inert (headings/"Not started."/placeholder fields).
+function phaseSection(text, heading) {
+  const m = new RegExp('^##[ \\t]+' + heading + '[ \\t]*$', 'm').exec(text);
+  if (!m) return null;
+  const rest = text.slice(m.index + m[0].length);
+  const next = rest.search(/^##[ \t]+\S/m);
+  return (next === -1 ? rest : rest.slice(0, next)).trim();
+}
+function phaseSectionInert(section) {
+  if (section === null) return true;
+  return section.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).every((line) => {
+    if (/^(?:[-*]\s*)?(?:not started|n\/a|tbd|todo|pending|none)\.?$/i.test(line)) return true;
+    const kv = line.match(/^(?:[-*]\s*)?\**[A-Za-z_ ]+\**\s*:\s*(.*)$/);
+    return Boolean(kv) && isPlaceholderValue(kv[1].replace(/\*+/g, '').trim());
+  });
+}
+function phaseSectionUntouched(currentVisible, newVisible, heading) {
+  const next = phaseSection(newVisible, heading);
+  return phaseSection(currentVisible, heading) === next || phaseSectionInert(next);
+}
   // W2-D07 fix: `OVERRIDE_APPROVED_BY: human` was plain text inside gated files —
   // self-authorizable by the gated model. The in-file `## Model-Tier Guard Override`
   // declaration stays (it is the audit trail), but it only counts when a marker file
@@ -302,9 +327,33 @@ async function resolveReal(p, depth = 0) {
 
 const SCOPE_DENY_CLASSES_OUTSIDE = 'outside-root';
 // -> { block:boolean, cls:string, rel?:string }
-async function classifyTarget(filePath, projectDir) {
+// A subagent isolated in a git worktree writes under THAT worktree's tree: inside the project
+// (`.claude/worktrees/<n>/`, `.worktrees/<n>/`) or a sibling checkout of the same repo. Scope
+// must be judged against that worktree's root — against the main root the same `docs/…` file
+// reads as deny-.claude / outside-root, a block the agent cannot fix and retries blind.
+async function worktreeBaseFor(abs, projectDir) {
+  try {
+    const root = path.resolve(projectDir);
+    const rel = path.relative(root, abs).replace(/\\/g, '/');
+    const m = rel.match(/^(?:\.claude\/worktrees|\.worktrees)\/[^/]+(?=\/|$)/);
+    if (m) return path.join(root, m[0]);
+    if (!(rel === '..' || rel.startsWith('../') || path.isAbsolute(rel))) return null;
+    const { execFileSync } = require('child_process');
+    let dir = path.dirname(abs);
+    for (let i = 0; i < 64; i += 1) {
+      try { await fsp.access(dir); break; } catch { const up = path.dirname(dir); if (up === dir) return null; dir = up; }
+    }
+    const git = (cwd, ...a) => execFileSync('git', ['-C', cwd, ...a], { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const common = (cwd) => fsp.realpath(path.resolve(cwd, git(cwd, 'rev-parse', '--git-common-dir')));
+    if ((await common(dir)) !== (await common(root))) return null;
+    return git(dir, 'rev-parse', '--show-toplevel') || null;
+  } catch { return null; }
+}
+
+async function classifyTarget(filePath, projectDirArg) {
   try {
-    const abs = path.resolve(projectDir, filePath); // collapses `..`
+    const abs = path.resolve(projectDirArg, filePath); // collapses `..`
+    const projectDir = (await worktreeBaseFor(abs, projectDirArg)) || projectDirArg;
     const rootReal = await fsp.realpath(projectDir);
     const relTo = (root, p) => path.relative(root, p).replace(/\\/g, '/');
     const outside = (r) => r === '..' || r.startsWith('../') || path.isAbsolute(r);
@@ -553,7 +602,7 @@ if (toolName === 'Write' || toolName === 'Edit') {
     if (hasExecutorReport && !currentExecutorReal) {
       const executorModel = extractField(newVisible, 'EXECUTOR_MODEL');
       if (isPlaceholderValue(executorModel) || /^unknown$/i.test(executorModel)) {
-        if (!isFreshTaskFile) {
+        if (!isFreshTaskFile && !phaseSectionUntouched(currentVisible, newVisible, 'Executor Report')) {
           block(`${taskId}: EXECUTOR_MODEL missing/placeholder. Implementation must run via Agent tool subagent_type: "feature-implementer" (sonnet/unic-code) and self-report its model.`);
         }
         // Else: skeleton sections copied from a task template at creation time — the
@@ -595,7 +644,7 @@ if (toolName === 'Write' || toolName === 'Edit') {
       const reviewOverride = await taskHasHumanOverride(newVisible, taskId)
         || await planHasHumanOverride(stripHtmlComments(planContentForReview));
       if (isPlaceholderValue(reviewerModel) || /^unknown$/i.test(reviewerModel)) {
-        if (!isFreshTaskFile) {
+        if (!isFreshTaskFile && !phaseSectionUntouched(currentVisible, newVisible, 'Reviewer Verdict')) {
           block(`${taskId}: REVIEWER_MODEL missing/placeholder. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart) and self-report its model.`);
         }
         // Else: skeleton Reviewer Verdict on a freshly created task file — Phase 4