thanh-kit 2.5.0 → 2.5.2

package/templates/hooks/skill-dedup.cjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * Skill Dedup Hook - Prevents local skills from shadowing global versions
+ *
+ * @deprecated DISABLED in v2.9.1 due to race condition with parallel sessions.
+ * See issue #422: concurrent sessions overwrite manifest, orphaning skills.
+ * Hook file kept for reference; will be redesigned in future release.
+ *
+ * Original design:
+ *   SessionStart: move overlapping local skills to .claude/skills/.shadowed/
+ *   SessionEnd:   restore .shadowed/ skills back to .claude/skills/
+ *
+ * Problem: Non-atomic file operations + shared manifest = race condition
+ * when multiple Claude Code sessions run in the same directory.
+ */
+
+// Crash wrapper
+try {
+  const fs = require('fs');
+  const path = require('path');
+  const os = require('os');
+
+// Directories to never shadow (internal infrastructure, not real skills)
+const SKIP_DIRS = new Set(['.shadowed', '.venv', 'node_modules', '__pycache__']);
+
+// -- Helpers -----------------------------------------------------------------
+
+/**
+ * List skill directory names in a given skills root
+ * Only returns directories that contain a SKILL.md (valid skills)
+ */
+function listSkillNames(skillsRoot) {
+  if (!fs.existsSync(skillsRoot)) return [];
+  try {
+    return fs.readdirSync(skillsRoot, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !SKIP_DIRS.has(d.name))
+      .filter(d => fs.existsSync(path.join(skillsRoot, d.name, 'SKILL.md')))
+      .map(d => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Find overlapping skill names between global and local installations
+ */
+function findOverlaps(globalSkills, localSkills) {
+  const globalSet = new Set(globalSkills);
+  return localSkills.filter(name => globalSet.has(name));
+}
+
+/**
+ * Move a skill directory from source to destination
+ */
+function moveSkillDir(src, dest) {
+  fs.renameSync(src, dest);
+}
+
+/**
+ * Resolve paths for a given context (injectable for testing)
+ */
+function resolvePaths(globalDir, localDir) {
+  const shadowedDir = path.join(localDir, '.shadowed');
+  const manifestFile = path.join(shadowedDir, '.dedup-manifest.json');
+  return { globalDir, localDir, shadowedDir, manifestFile };
+}
+
+/**
+ * Get default paths based on environment
+ */
+function getDefaultPaths() {
+  const globalDir = path.join(os.homedir(), '.claude', 'skills');
+  const localDir = path.join(process.cwd(), '.claude', 'skills');
+  return resolvePaths(globalDir, localDir);
+}
+
+// -- SessionStart: Shadow local duplicates -----------------------------------
+
+function handleSessionStart(paths) {
+  const { globalDir, localDir, shadowedDir } = paths;
+
+  const globalSkills = listSkillNames(globalDir);
+  const localSkills = listSkillNames(localDir);
+
+  if (globalSkills.length === 0 || localSkills.length === 0) return { shadowed: [] };
+
+  const overlaps = findOverlaps(globalSkills, localSkills);
+  if (overlaps.length === 0) return { shadowed: [] };
+
+  // If .shadowed/ already exists from a crashed previous session, restore first
+  if (fs.existsSync(shadowedDir)) {
+    handleSessionEnd(paths);
+    // Re-evaluate overlaps after restoration
+    const freshLocal = listSkillNames(localDir);
+    const freshOverlaps = findOverlaps(globalSkills, freshLocal);
+    if (freshOverlaps.length === 0) return { shadowed: [] };
+    return doShadow(freshOverlaps, paths);
+  }
+
+  return doShadow(overlaps, paths);
+}
+
+function doShadow(overlaps, paths) {
+  const { localDir, shadowedDir, manifestFile } = paths;
+
+  // Create .shadowed directory
+  fs.mkdirSync(shadowedDir, { recursive: true });
+
+  const shadowed = [];
+  for (const name of overlaps) {
+    try {
+      moveSkillDir(path.join(localDir, name), path.join(shadowedDir, name));
+      shadowed.push(name);
+    } catch (err) {
+      process.stderr.write(`[skill-dedup] Failed to shadow "${name}": ${err.message}\n`);
+    }
+  }
+
+  if (shadowed.length === 0) return { shadowed: [] };
+
+  // Write manifest so SessionEnd knows what to restore
+  const manifest = {
+    shadowedAt: new Date().toISOString(),
+    skills: shadowed,
+    globalDir: paths.globalDir,
+    localDir: paths.localDir
+  };
+  fs.writeFileSync(manifestFile, JSON.stringify(manifest, null, 2));
+
+  console.log(`Skill dedup: ${shadowed.length} local skill(s) shadowed — global versions active: ${shadowed.join(', ')}`);
+  return { shadowed };
+}
+
+// -- SessionEnd: Restore shadowed skills -------------------------------------
+
+function handleSessionEnd(paths) {
+  const { shadowedDir, manifestFile } = paths;
+
+  if (!fs.existsSync(manifestFile)) {
+    if (fs.existsSync(shadowedDir)) {
+      return restoreOrphanedSkills(paths);
+    }
+    return { restored: [] };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  } catch {
+    return restoreOrphanedSkills(paths);
+  }
+
+  const restored = [];
+  for (const name of manifest.skills || []) {
+    try {
+      const src = path.join(shadowedDir, name);
+      const dest = path.join(paths.localDir, name);
+      if (fs.existsSync(src) && !fs.existsSync(dest)) {
+        moveSkillDir(src, dest);
+        restored.push(name);
+      }
+    } catch (err) {
+      process.stderr.write(`[skill-dedup] Failed to restore "${name}": ${err.message}\n`);
+    }
+  }
+
+  cleanupShadowedDir(paths);
+
+  if (restored.length > 0) {
+    console.log(`Skill dedup: restored ${restored.length} local skill(s): ${restored.join(', ')}`);
+  }
+  return { restored };
+}
+
+/**
+ * Restore any skill directories found in .shadowed/ without a manifest
+ * Safety net for crashed sessions or corrupt manifests
+ */
+function restoreOrphanedSkills(paths) {
+  const { shadowedDir, localDir } = paths;
+  const restored = [];
+  try {
+    const entries = fs.readdirSync(shadowedDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const src = path.join(shadowedDir, entry.name);
+        const dest = path.join(localDir, entry.name);
+        if (fs.existsSync(src) && !fs.existsSync(dest)) {
+          moveSkillDir(src, dest);
+          restored.push(entry.name);
+        }
+      }
+    }
+  } catch {
+    // Best effort
+  }
+  cleanupShadowedDir(paths);
+  return { restored };
+}
+
+/**
+ * Remove the .shadowed directory and manifest
+ */
+function cleanupShadowedDir(paths) {
+  const { shadowedDir, manifestFile } = paths;
+  try {
+    if (fs.existsSync(manifestFile)) fs.unlinkSync(manifestFile);
+    if (fs.existsSync(shadowedDir)) fs.rmdirSync(shadowedDir);
+  } catch {
+    // Non-fatal: leftover empty dir is harmless
+  }
+}
+
+  // -- Main --------------------------------------------------------------------
+
+  function main() {
+    try {
+      let payload = {};
+      try {
+        const input = fs.readFileSync('/dev/stdin', 'utf8').trim();
+        if (input) payload = JSON.parse(input);
+      } catch {
+        // No stdin or invalid JSON
+      }
+
+      const paths = getDefaultPaths();
+      const event = payload.hook_event_name || '';
+
+      if (event === 'SessionEnd' || event === 'Stop') {
+        handleSessionEnd(paths);
+      } else {
+        handleSessionStart(paths);
+      }
+    } catch (err) {
+      process.stderr.write(`[skill-dedup] Error: ${err.message}\n`);
+    }
+
+    process.exit(0);
+  }
+
+  // Export for testing
+  if (require.main === module) {
+    main();
+  }
+
+  module.exports = {
+    listSkillNames,
+    findOverlaps,
+    resolvePaths,
+    handleSessionStart,
+    handleSessionEnd,
+    doShadow,
+    restoreOrphanedSkills,
+    cleanupShadowedDir,
+    SKIP_DIRS
+  };
+} catch (e) {
+  // Minimal crash logging (zero deps — only Node builtins)
+  try {
+    const fs = require('fs');
+    const p = require('path');
+    const logDir = p.join(__dirname, '.logs');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(p.join(logDir, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: p.basename(__filename, '.cjs'), status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0); // fail-open
+}

package/templates/hooks/subagent-init.cjs

@@ -10,15 +10,27 @@
  *   0 - Success (non-blocking, allows continuation)
  */
 
-const fs = require('fs');
-const {
-  loadConfig,
-  resolveNamingPattern,
-  getGitBranch,
-  resolvePlanPath,
-  getReportsPath,
-  normalizePath
-} = require('./lib/ck-config-utils.cjs');
+// Crash wrapper
+try {
+  const fs = require('fs');
+  const path = require('path');
+  const {
+    loadConfig,
+    resolveNamingPattern,
+    getGitBranch,
+    getGitRoot,
+    resolvePlanPath,
+    getReportsPath,
+    normalizePath,
+    extractTaskListId,
+    isHookEnabled
+  } = require('./lib/ck-config-utils.cjs');
+  const { resolveSkillsVenv } = require('./lib/context-builder.cjs');
+
+  // Early exit if hook disabled in config
+  if (!isHookEnabled('subagent-init')) {
+    process.exit(0);
+  }
 
 /**
  * Get agent-specific context from config
@@ -56,17 +68,37 @@ async function main() {
     // Load config for trust verification, naming, and agent-specific context
     const config = loadConfig({ includeProject: false, includeAssertions: false });
 
+    // Use payload.cwd if provided for git operations (monorepo support)
+    // This ensures subagent resolves paths relative to its own CWD, not process.cwd()
+    // Issue #327: Use trim() to handle empty string edge case
+    const effectiveCwd = payload.cwd?.trim() || process.cwd();
+
     // Compute naming pattern directly (don't rely on env vars which may not propagate)
-    const gitBranch = getGitBranch();
+    // Pass effectiveCwd to git commands to support monorepo/submodule scenarios
+    const gitBranch = getGitBranch(effectiveCwd);
+    const gitRoot = getGitRoot(effectiveCwd);
+    // Issue #327: Use CWD as base for subdirectory workflow support
+    // Git root is kept for reference but CWD determines where files are created
+    const baseDir = effectiveCwd;
+
+    // Debug logging for path resolution troubleshooting
+    if (process.env.CK_DEBUG) {
+      console.error(`[subagent-init] effectiveCwd=${effectiveCwd}, gitRoot=${gitRoot}, baseDir=${baseDir}`);
+    }
     const namePattern = resolveNamingPattern(config.plan, gitBranch);
 
-    // Resolve plan and reports path
-    const resolved = resolvePlanPath(null, config);
-    const reportsPath = getReportsPath(resolved.path, resolved.resolvedBy, config.plan, config.paths);
+    // Resolve plan and reports path - use absolute paths based on CWD (Issue #327)
+    // Use session_id from payload to resolve active plan context (Issue #321)
+    const sessionId = payload.session_id || process.env.CK_SESSION_ID || null;
+    const resolved = resolvePlanPath(sessionId, config);
+    const reportsPath = getReportsPath(resolved.path, resolved.resolvedBy, config.plan, config.paths, baseDir);
     const activePlan = resolved.resolvedBy === 'session' ? resolved.path : '';
     const suggestedPlan = resolved.resolvedBy === 'branch' ? resolved.path : '';
-    const plansPath = normalizePath(config.paths?.plans) || 'plans';
-    const docsPath = normalizePath(config.paths?.docs) || 'docs';
+
+    // Extract task list ID for Claude Code Tasks coordination (shared helper, DRY)
+    const taskListId = extractTaskListId(resolved);
+    const plansPath = path.join(baseDir, normalizePath(config.paths?.plans) || 'plans');
+    const docsPath = path.join(baseDir, normalizePath(config.paths?.docs) || 'docs');
     const thinkingLanguage = config.locale?.thinkingLanguage || '';
     const responseLanguage = config.locale?.responseLanguage || '';
     // Auto-default thinkingLanguage to 'en' when only responseLanguage is set
@@ -77,13 +109,16 @@ async function main() {
 
     // Subagent identification
     lines.push(`## Subagent: ${agentType}`);
-    lines.push(`ID: ${agentId} | CWD: ${payload.cwd || process.cwd()}`);
+    lines.push(`ID: ${agentId} | CWD: ${effectiveCwd}`);
     lines.push(``);
 
     // Plan context (from env vars)
     lines.push(`## Context`);
     if (activePlan) {
       lines.push(`- Plan: ${activePlan}`);
+      if (taskListId) {
+        lines.push(`- Task List: ${taskListId} (shared with session)`);
+      }
     } else if (suggestedPlan) {
       lines.push(`- Plan: none | Suggested: ${suggestedPlan}`);
     } else {
@@ -106,19 +141,25 @@ async function main() {
       lines.push(``);
     }
 
+    // Resolve Python venv path for subagent instructions
+    const skillsVenv = resolveSkillsVenv();
+
     // Core rules (minimal)
     lines.push(`## Rules`);
-    lines.push(`- Follow: .claude/workflows/development-rules.md`);
     lines.push(`- Reports → ${reportsPath}`);
     lines.push(`- YAGNI / KISS / DRY`);
-    lines.push(`- **Class Responsibility:** Logic in LOWEST layer (Model > Service > Component). Mapping → Command/DTO. Constants → Model.`);
     lines.push(`- Concise, list unresolved Qs at end`);
+    // Python venv rules (if venv exists)
+    if (skillsVenv) {
+      lines.push(`- Python scripts in .claude/skills/: Use \`${skillsVenv}\``);
+      lines.push(`- Never use global pip install`);
+    }
 
     // Naming templates (computed directly for reliable injection)
     lines.push(``);
     lines.push(`## Naming`);
-    lines.push(`- Report: ${reportsPath}${agentType}-${namePattern}.md`);
-    lines.push(`- Plan dir: ${plansPath}/${namePattern}/`);
+    lines.push(`- Report: ${path.join(reportsPath, `${agentType}-${namePattern}.md`)}`);
+    lines.push(`- Plan dir: ${path.join(plansPath, namePattern)}/`);
 
     // Trust verification (if enabled)
     lines.push(...buildTrustVerification(config));
@@ -145,6 +186,18 @@ async function main() {
     console.error(`SubagentStart hook error: ${error.message}`);
     process.exit(0); // Fail-open
   }
-}
+  }
 
-main();
+  main();
+} catch (e) {
+  // Minimal crash logging (zero deps — only Node builtins)
+  try {
+    const fs = require('fs');
+    const p = require('path');
+    const logDir = p.join(__dirname, '.logs');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(p.join(logDir, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: p.basename(__filename, '.cjs'), status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0); // fail-open
+}

package/templates/hooks/task-completed-handler.cjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * TaskCompleted Hook - Logs task completions and injects progress context
+ *
+ * Fires: When any agent marks a task as completed (TaskUpdate with status: completed),
+ *        or when a teammate finishes its turn with in-progress tasks.
+ * Official docs: https://code.claude.com/docs/en/hooks#taskcompleted
+ * Decision control: Exit code only (exit 2 blocks completion, stderr fed as feedback)
+ * Note: additionalContext output is informational — may be ignored by CC for this event.
+ * Input: { task_id, task_subject, task_description, teammate_name, team_name, ... }
+ * Output: additionalContext with progress summary for lead
+ * Design: Non-blocking, fail-open (exit 0 always), no external deps
+ */
+
+// Crash wrapper
+try {
+  const fs = require('fs');
+  const path = require('path');
+  const os = require('os');
+  const { isHookEnabled } = require('./lib/ck-config-utils.cjs');
+
+  if (!isHookEnabled('task-completed-handler')) {
+    process.exit(0);
+  }
+
+const TASKS_DIR = path.join(os.homedir(), '.claude', 'tasks');
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch { return null; }
+}
+
+function countTasks(teamName) {
+  const taskDir = path.join(TASKS_DIR, teamName);
+  try {
+    if (!fs.existsSync(taskDir)) return null;
+    const files = fs.readdirSync(taskDir).filter(f => f.endsWith('.json'));
+    let pending = 0, inProgress = 0, completed = 0;
+    for (const file of files) {
+      const task = readJson(path.join(taskDir, file));
+      if (!task?.status) continue;
+      if (task.status === 'pending') pending++;
+      else if (task.status === 'in_progress') inProgress++;
+      else if (task.status === 'completed') completed++;
+    }
+    return { pending, inProgress, completed, total: pending + inProgress + completed };
+  } catch { return null; }
+}
+
+function logCompletion(teamName, taskId, taskSubject, teammateName) {
+  const reportsPath = process.env.CK_REPORTS_PATH;
+  if (!reportsPath) return;
+  const logFile = path.join(reportsPath, `team-${teamName}-completions.md`);
+  try {
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    const timestamp = new Date().toISOString().slice(0, 19).replace('T', ' ');
+    const line = `- [${timestamp}] Task #${taskId} "${taskSubject}" completed by ${teammateName}\n`;
+    fs.appendFileSync(logFile, line);
+  } catch { /* fail-open */ }
+}
+
+function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    const { task_id, task_subject, teammate_name, team_name } = payload;
+    if (!team_name) process.exit(0);
+
+    // Log completion to report file
+    logCompletion(team_name, task_id, task_subject, teammate_name);
+
+    // Count task progress
+    const counts = countTasks(team_name);
+    const lines = [];
+    lines.push(`## Task Completed`);
+    lines.push(`Task #${task_id} "${task_subject}" completed by ${teammate_name}.`);
+
+    if (counts) {
+      const remaining = counts.pending + counts.inProgress;
+      lines.push(`Progress: ${counts.completed}/${counts.total} done. ${counts.pending} pending, ${counts.inProgress} in progress.`);
+      if (remaining === 0) {
+        lines.push('');
+        lines.push('**All tasks completed.** Consider shutting down teammates and synthesizing results.');
+      }
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'TaskCompleted',
+        additionalContext: lines.join('\n')
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  } catch (error) {
+    if (process.env.CK_DEBUG) {
+      console.error(`[task-completed-handler] Error: ${error.message}`);
+    }
+    process.exit(0);
+  }
+  }
+
+  main();
+} catch (e) {
+  // Minimal crash logging (zero deps — only Node builtins)
+  try {
+    const fs = require('fs');
+    const p = require('path');
+    const logDir = p.join(__dirname, '.logs');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(p.join(logDir, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: p.basename(__filename, '.cjs'), status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0); // fail-open
+}