ccgx-workflow 2.4.1 → 2.5.0

package/templates/scripts/invoke-model.mjs

@@ -186,6 +186,28 @@ function lookPath(cmd, opts = {}) {
   return cmd; // let spawn surface ENOENT
 }
 
+// Render one argument for a `cmd.exe /d /s /c "<line>"` invocation spawned with
+// windowsVerbatimArguments:true. Under verbatim mode Node joins args with
+// single spaces and applies NO quoting, so cmd.exe re-parses the line and would
+// act on metacharacters (& | < > ( ) % ") in any unquoted argument. Port of
+// Rust std's append_bat_arg (.bat/.cmd CVE fix), validated against cmd.exe:
+// wrap in literal quotes (metachars inert inside a quoted span + MSVCRT gets one
+// token), MSVCRT-escape inner quotes as \", and emit % as "^%" so %VAR% is not
+// expanded. Doubles backslash runs that precede a quote.
+function cmdEscapeArg(arg) {
+  let out = '"';
+  let backslashes = 0;
+  for (const ch of String(arg)) {
+    if (ch === '%') { out += '"^%"'; backslashes = 0; continue; }
+    if (ch === '"') { out += '\\'.repeat(backslashes) + '\\"'; backslashes = 0; continue; }
+    if (ch === '\\') { backslashes += 1; out += ch; continue; }
+    backslashes = 0;
+    out += ch;
+  }
+  out += '\\'.repeat(backslashes) + '"';
+  return out;
+}
+
 // Resolve `cmd` against PATH (POSIX) or PATH+PATHEXT (Windows).
 // Returns null when the binary is not found, giving callers a chance to emit
 // a friendly install hint before spawn raises ENOENT.
@@ -796,9 +818,14 @@ async function main() {
   // Windows: spawning .cmd/.bat directly throws EINVAL (Node CVE-2024-27980
   // mitigation). Wrap with cmd.exe /c to keep arg array semantics without
   // tripping DEP0190 (`shell:true + args[]` deprecation in Node 24+).
+  // windowsVerbatimArguments hands the line to cmd.exe with no quoting, so each
+  // caller arg must be cmd-escaped and the whole "<prog> <args>" wrapped in one
+  // outer quote pair that /s strips — otherwise cmd.exe would interpret
+  // metacharacters in argv content (command injection).
   if (IS_WINDOWS && /\.(cmd|bat)$/i.test(resolvedCommand)) {
     spawnOpts.windowsVerbatimArguments = true;
-    resolvedArgs = ['/d', '/s', '/c', `"${resolvedCommand}"`, ...args];
+    const line = [`"${resolvedCommand}"`, ...args.map(cmdEscapeArg)].join(' ');
+    resolvedArgs = ['/d', '/s', '/c', `"${line}"`];
     resolvedCommand = process.env.ComSpec || 'cmd.exe';
   }
 

package/templates/scripts/task-store.cjs

@@ -0,0 +1,614 @@
+#!/usr/bin/env node
+// CCG Task Store CLI — P1-4 (.context/tasks container + STATE.json projection).
+//
+// Standalone Node CJS reimplementation of src/utils/task-store.ts. The TS
+// version ships in ccgx-workflow's dist for package consumers; but command
+// templates (/ccg:review 5.4, /ccg:spec-impl Step 10d, future /ccg:autonomous)
+// run in the USER's project, which has no ccgx-workflow npm dependency. The
+// model can't `import` a helper that isn't installed.
+//
+// installer.ts copies this file to ~/.claude/.ccg/scripts/task-store.cjs
+// (alongside spec-suggestion.cjs and friends). Command templates call:
+//
+//   node ~/.claude/.ccg/scripts/task-store.cjs <subcommand> [flags]
+//
+// Subcommands:
+//   create            --id <id> --title <t> [--branch --phase --next --total --done]
+//   get               --id <id>
+//   list
+//   active
+//   update            --id <id> [--title --status --phase --next --branch --total --done]
+//   register-artifact --type <t> --path <p> [--id <id>] [--status --note]
+//   complete          --id <id> [--next <cmd>]
+//                     (--next is archived to task.json only — the completed
+//                      task is terminal, so it is NOT projected into
+//                      STATE.json / the statusline; retrieve via `get --id`)
+//   archive           --id <id>
+//   state
+//
+// All subcommands accept --workdir <dir> (default: process.cwd()).
+//
+// stdout is ALWAYS JSON: TaskRecord / TaskRecord[] / ProjectState /
+// {ok:false, reason}. Exit 0 = success or benign no-op (e.g.
+// register-artifact with no active task → {ok:false,reason:"no-active-task"}).
+// Exit 1 = bad args / IO error / missing task on a mutating subcommand.
+//
+// Logic must stay in lockstep with src/utils/task-store.ts. The shared test
+// cases in __tests__/taskStoreCjs.test.ts pin both implementations against
+// the same fixtures.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// ─────────────────────────────────────────────────────────────────
+// Constants (must mirror task-store.ts)
+// ─────────────────────────────────────────────────────────────────
+
+const TASKS_RELATIVE_PATH = '.context/tasks';
+const STATE_RELATIVE_PATH = '.context/STATE.json';
+
+const TERMINAL_STATUS_SYNONYMS = new Set([
+  'completed', 'complete', 'done', 'finished', 'closed',
+  'archived', 'cancelled', 'canceled', 'abandoned', 'failed',
+]);
+
+const VALID_ARTIFACT_TYPES = new Set([
+  'fix-log', 'spec-evolution', 'review', 'plan', 'summary', 'generic',
+]);
+
+const VALID_TASK_STATUSES = new Set(['in_progress', 'completed', 'archived', 'cancelled']);
+const VALID_ARTIFACT_STATUSES = new Set(['active', 'final', 'stale']);
+
+// ─────────────────────────────────────────────────────────────────
+// Atomic write (mirrors jobs.ts atomicWriteFileSync)
+// ─────────────────────────────────────────────────────────────────
+
+function atomicWriteFileSync(target, content) {
+  const rand = crypto.randomBytes(6).toString('hex');
+  const tmp = `${target}.tmp.${rand}`;
+  try {
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing to clean up */ }
+    throw err;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Path helpers
+// ─────────────────────────────────────────────────────────────────
+
+function tasksRoot(workdir) {
+  return path.join(workdir, '.context', 'tasks');
+}
+
+function taskDir(workdir, taskId) {
+  return path.join(tasksRoot(workdir), sanitizeTaskId(taskId));
+}
+
+function taskJsonPath(workdir, taskId) {
+  return path.join(taskDir(workdir, taskId), 'task.json');
+}
+
+function projectStatePath(workdir) {
+  return path.join(workdir, '.context', 'STATE.json');
+}
+
+function sanitizeTaskId(taskId) {
+  const trimmed = String(taskId == null ? '' : taskId).trim();
+  if (!trimmed) throw new Error('taskId cannot be empty');
+  const cleaned = trimmed.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!cleaned) throw new Error(`taskId sanitizes to empty: ${taskId}`);
+  return cleaned;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Status / progress helpers
+// ─────────────────────────────────────────────────────────────────
+
+function isTerminalStatus(status) {
+  if (typeof status !== 'string') return false;
+  return TERMINAL_STATUS_SYNONYMS.has(status.trim().toLowerCase());
+}
+
+function normalizeProgress(progress) {
+  if (!progress || typeof progress !== 'object') return undefined;
+  const total = progress.total_phases;
+  const done = progress.completed_phases;
+  if (typeof total !== 'number' || typeof done !== 'number') return undefined;
+  const percent = typeof progress.percent === 'number'
+    ? progress.percent
+    : (total > 0 ? Math.round((done / total) * 100) : 0);
+  return { total_phases: total, completed_phases: done, percent };
+}
+
+function normalizeArtifactPath(p) {
+  return p.replace(/\\/g, '/');
+}
+
+function validateTaskRecord(record) {
+  if (record === null || typeof record !== 'object') {
+    throw new Error('TaskRecord must be an object');
+  }
+  if (typeof record.id !== 'string' || !record.id) {
+    throw new Error('TaskRecord missing required field: id');
+  }
+  if (typeof record.status !== 'string' || !record.status) {
+    throw new Error('TaskRecord missing required field: status');
+  }
+  if (typeof record.created_at !== 'string' || !record.created_at) {
+    throw new Error('TaskRecord missing required field: created_at');
+  }
+  if (!Array.isArray(record.artifacts)) {
+    record.artifacts = [];
+  }
+}
+
+function writeTaskRecord(workdir, record) {
+  const dir = taskDir(workdir, record.id);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  atomicWriteFileSync(taskJsonPath(workdir, record.id), JSON.stringify(record, null, 2));
+}
+
+// ─────────────────────────────────────────────────────────────────
+// CRUD (mirrors task-store.ts)
+// ─────────────────────────────────────────────────────────────────
+
+function createTask(workdir, init) {
+  const id = sanitizeTaskId(init.id);
+  if (typeof init.title !== 'string' || !init.title.trim()) {
+    throw new Error('task title cannot be empty');
+  }
+  if (fs.existsSync(taskJsonPath(workdir, id))) {
+    throw new Error(`Task already exists: ${id}`);
+  }
+  const now = new Date().toISOString();
+  const record = {
+    schema_version: 1,
+    id,
+    title: init.title,
+    status: 'in_progress',
+    active_phase: init.active_phase != null ? init.active_phase : null,
+    next_action: init.next_action != null ? init.next_action : null,
+    created_at: now,
+    updated_at: now,
+    artifacts: [],
+  };
+  const progress = normalizeProgress(init.progress);
+  if (progress) record.progress = progress;
+  if (init.branch) record.branch = init.branch;
+  writeTaskRecord(workdir, record);
+  syncProjectState(workdir);
+  return record;
+}
+
+function getTask(workdir, taskId) {
+  const file = taskJsonPath(workdir, taskId);
+  if (!fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, 'utf-8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Task ${taskId}: task.json is not valid JSON (${err.message})`);
+  }
+  validateTaskRecord(parsed);
+  return parsed;
+}
+
+function listTasks(workdir) {
+  const root = tasksRoot(workdir);
+  if (!fs.existsSync(root)) return [];
+  const tasks = [];
+  for (const id of fs.readdirSync(root)) {
+    if (id === 'archive') continue;
+    if (!fs.existsSync(taskJsonPath(workdir, id))) continue;
+    try {
+      const task = getTask(workdir, id);
+      if (task) tasks.push(task);
+    } catch {
+      // corrupt task dir — skip from list view
+    }
+  }
+  tasks.sort((a, b) => b.created_at.localeCompare(a.created_at));
+  return tasks;
+}
+
+function getActiveTask(workdir) {
+  for (const task of listTasks(workdir)) {
+    if (!isTerminalStatus(task.status)) return task;
+  }
+  return null;
+}
+
+function updateTask(workdir, taskId, patch) {
+  const task = getTask(workdir, taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  if ('title' in patch && patch.title !== undefined) task.title = patch.title;
+  if ('status' in patch && patch.status !== undefined) task.status = patch.status;
+  if ('active_phase' in patch) task.active_phase = patch.active_phase != null ? patch.active_phase : null;
+  if ('next_action' in patch) task.next_action = patch.next_action != null ? patch.next_action : null;
+  if ('branch' in patch && patch.branch !== undefined) task.branch = patch.branch;
+  if ('progress' in patch) {
+    const progress = normalizeProgress(patch.progress);
+    if (progress) task.progress = progress;
+    else delete task.progress;
+  }
+  task.updated_at = new Date().toISOString();
+  writeTaskRecord(workdir, task);
+  syncProjectState(workdir);
+  return task;
+}
+
+function registerArtifact(workdir, taskId, artifact) {
+  if (!VALID_ARTIFACT_TYPES.has(artifact.type)) {
+    throw new TypeError(`invalid artifact type: ${String(artifact.type)}`);
+  }
+  if (typeof artifact.path !== 'string' || !artifact.path.trim()) {
+    throw new TypeError('artifact path cannot be empty');
+  }
+  const task = getTask(workdir, taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  const normPath = normalizeArtifactPath(artifact.path.trim());
+  const existing = task.artifacts.find(a => a.type === artifact.type && a.path === normPath);
+  if (existing) {
+    if (artifact.status) existing.status = artifact.status;
+    if (artifact.note !== undefined) existing.note = artifact.note;
+  } else {
+    const entry = {
+      type: artifact.type,
+      path: normPath,
+      status: artifact.status || 'active',
+      registered_at: new Date().toISOString(),
+    };
+    if (artifact.note !== undefined) entry.note = artifact.note;
+    task.artifacts.push(entry);
+  }
+  task.updated_at = new Date().toISOString();
+  writeTaskRecord(workdir, task);
+  syncProjectState(workdir);
+  return task;
+}
+
+function registerArtifactForActiveTask(workdir, artifact) {
+  try {
+    const active = getActiveTask(workdir);
+    if (!active) return null;
+    return registerArtifact(workdir, active.id, artifact);
+  } catch {
+    return null;
+  }
+}
+
+function registerSpecEvolution(workdir, changeId) {
+  return registerArtifactForActiveTask(workdir, {
+    type: 'spec-evolution',
+    path: `openspec/changes/${changeId}/SPEC_EVOLUTION.md`,
+  });
+}
+
+function completeTask(workdir, taskId, opts) {
+  const task = getTask(workdir, taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  task.status = 'completed';
+  task.completed_at = new Date().toISOString();
+  task.active_phase = null;
+  if (opts && 'next_action' in opts) {
+    task.next_action = opts.next_action != null ? opts.next_action : null;
+  }
+  task.updated_at = task.completed_at;
+  writeTaskRecord(workdir, task);
+  syncProjectState(workdir);
+  return task;
+}
+
+function archiveTask(workdir, taskId, now) {
+  const task = getTask(workdir, taskId);
+  if (!task) return null;
+  const ts = now instanceof Date ? now : new Date();
+  task.status = 'archived';
+  task.updated_at = new Date().toISOString();
+  writeTaskRecord(workdir, task);
+  const yearMonth = ts.toISOString().slice(0, 7);
+  const destParent = path.join(tasksRoot(workdir), 'archive', yearMonth);
+  const dest = path.join(destParent, sanitizeTaskId(taskId));
+  try {
+    fs.mkdirSync(destParent, { recursive: true });
+    fs.renameSync(taskDir(workdir, taskId), dest);
+  } catch {
+    syncProjectState(workdir);
+    return null;
+  }
+  syncProjectState(workdir);
+  return dest;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Project state projection
+// ─────────────────────────────────────────────────────────────────
+
+function readProjectState(workdir) {
+  const file = projectStatePath(workdir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeProjectState(workdir, partial) {
+  const state = {
+    schema_version: 1,
+    active_task_id: partial.active_task_id != null ? partial.active_task_id : null,
+    active_phase: partial.active_phase != null ? partial.active_phase : null,
+    next_action: partial.next_action != null ? partial.next_action : null,
+    progress: normalizeProgress(partial.progress) || null,
+    updated_at: new Date().toISOString(),
+  };
+  if (partial.status !== undefined) state.status = partial.status;
+  const file = projectStatePath(workdir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  atomicWriteFileSync(file, JSON.stringify(state, null, 2));
+  return state;
+}
+
+function syncProjectState(workdir) {
+  let active = null;
+  try {
+    active = getActiveTask(workdir);
+  } catch {
+    active = null;
+  }
+  if (!active) {
+    return writeProjectState(workdir, {
+      active_task_id: null, active_phase: null, next_action: null, progress: null,
+    });
+  }
+  return writeProjectState(workdir, {
+    active_task_id: active.id,
+    active_phase: active.active_phase != null ? active.active_phase : null,
+    next_action: active.next_action != null ? active.next_action : null,
+    progress: active.progress || null,
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────────────────────────
+
+const SUBCOMMANDS = new Set([
+  'create', 'get', 'list', 'active', 'update',
+  'register-artifact', 'complete', 'archive', 'state',
+]);
+
+function parseArgs(argv) {
+  // argv = full process.argv (node, script, subcommand, flags...)
+  const out = {
+    command: null,
+    id: null,
+    title: null,
+    branch: null,
+    phase: undefined,
+    next: undefined,
+    status: null,
+    total: null,
+    done: null,
+    type: null,
+    path: null,
+    note: null,
+    workdir: process.cwd(),
+    help: false,
+  };
+  const flagMap = {
+    '--id': 'id',
+    '--title': 'title',
+    '--branch': 'branch',
+    '--phase': 'phase',
+    '--next': 'next',
+    '--status': 'status',
+    '--type': 'type',
+    '--path': 'path',
+    '--note': 'note',
+    '--workdir': 'workdir',
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+    } else if (flagMap[a] && i + 1 < argv.length) {
+      out[flagMap[a]] = argv[++i];
+    } else if ((a === '--total' || a === '--done') && i + 1 < argv.length) {
+      const n = Number.parseInt(argv[++i], 10);
+      if (Number.isNaN(n) || n < 0) {
+        process.stderr.write(`task-store: ${a} must be a non-negative integer\n`);
+        out.help = true;
+      } else {
+        out[a === '--total' ? 'total' : 'done'] = n;
+      }
+    } else if (!a.startsWith('-') && out.command === null) {
+      out.command = a;
+    } else {
+      process.stderr.write(`task-store: unknown arg: ${a}\n`);
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+function printUsage() {
+  process.stderr.write([
+    'Usage: node task-store.cjs <subcommand> [flags]',
+    '',
+    'Subcommands: create | get | list | active | update | register-artifact',
+    '             | complete | archive | state',
+    '',
+    'Flags: --id --title --branch --phase --next --status --total --done',
+    '       --type --path --note --workdir (default: cwd)',
+    '',
+    'Note: complete --next is archived to task.json only — it is NOT projected',
+    'into STATE.json / the statusline (the task is terminal); use `get --id`.',
+    '',
+    'stdout is always JSON. Exit 0 = success or benign no-op',
+    '(e.g. register-artifact with no active task). Exit 1 = bad args / IO error.',
+  ].join('\n') + '\n');
+}
+
+function emit(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+
+function buildProgress(args) {
+  if (args.total === null && args.done === null) return undefined;
+  if (args.total === null || args.done === null) {
+    throw new Error('--total and --done must be provided together');
+  }
+  return { total_phases: args.total, completed_phases: args.done };
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || !args.command || !SUBCOMMANDS.has(args.command)) {
+    printUsage();
+    return 1;
+  }
+  const workdir = args.workdir;
+  try {
+    switch (args.command) {
+      case 'create': {
+        if (!args.id || !args.title) throw new Error('create requires --id and --title');
+        emit(createTask(workdir, {
+          id: args.id,
+          title: args.title,
+          branch: args.branch || undefined,
+          active_phase: args.phase,
+          next_action: args.next,
+          progress: buildProgress(args),
+        }));
+        return 0;
+      }
+      case 'get': {
+        if (!args.id) throw new Error('get requires --id');
+        const task = getTask(workdir, args.id);
+        emit(task || { ok: false, reason: 'not-found' });
+        return 0;
+      }
+      case 'list': {
+        emit(listTasks(workdir));
+        return 0;
+      }
+      case 'active': {
+        const active = getActiveTask(workdir);
+        emit(active || { ok: false, reason: 'no-active-task' });
+        return 0;
+      }
+      case 'update': {
+        if (!args.id) throw new Error('update requires --id');
+        if (args.status !== null && !VALID_TASK_STATUSES.has(args.status)) {
+          throw new Error(`invalid task status: ${args.status} (expected ${[...VALID_TASK_STATUSES].join('|')})`);
+        }
+        const patch = {};
+        if (args.title !== null) patch.title = args.title;
+        if (args.status !== null) patch.status = args.status;
+        if (args.phase !== undefined) patch.active_phase = args.phase;
+        if (args.next !== undefined) patch.next_action = args.next;
+        if (args.branch !== null) patch.branch = args.branch;
+        const progress = buildProgress(args);
+        if (progress) patch.progress = progress;
+        emit(updateTask(workdir, args.id, patch));
+        return 0;
+      }
+      case 'register-artifact': {
+        if (!args.type || !args.path) throw new Error('register-artifact requires --type and --path');
+        // Validate eagerly here: registerArtifactForActiveTask swallows all
+        // errors (advisory contract), but a bad ARGUMENT must still exit 1.
+        if (!VALID_ARTIFACT_TYPES.has(args.type)) {
+          throw new Error(`invalid artifact type: ${args.type} (expected ${[...VALID_ARTIFACT_TYPES].join('|')})`);
+        }
+        if (args.status !== null && !VALID_ARTIFACT_STATUSES.has(args.status)) {
+          throw new Error(`invalid artifact status: ${args.status} (expected ${[...VALID_ARTIFACT_STATUSES].join('|')})`);
+        }
+        const artifact = { type: args.type, path: args.path };
+        if (args.status !== null) artifact.status = args.status;
+        if (args.note !== null) artifact.note = args.note;
+        if (args.id) {
+          emit(registerArtifact(workdir, args.id, artifact));
+          return 0;
+        }
+        const result = registerArtifactForActiveTask(workdir, artifact);
+        // Benign no-op: no active task to pin the pointer on. Exit 0 so
+        // command templates can call this unconditionally without guards.
+        emit(result || { ok: false, reason: 'no-active-task' });
+        return 0;
+      }
+      case 'complete': {
+        if (!args.id) throw new Error('complete requires --id');
+        const opts = args.next !== undefined ? { next_action: args.next } : undefined;
+        emit(completeTask(workdir, args.id, opts));
+        return 0;
+      }
+      case 'archive': {
+        if (!args.id) throw new Error('archive requires --id');
+        const dest = archiveTask(workdir, args.id);
+        emit(dest ? { ok: true, archived_to: dest } : { ok: false, reason: 'not-archived' });
+        return 0;
+      }
+      case 'state': {
+        const state = readProjectState(workdir);
+        emit(state || { ok: false, reason: 'no-state' });
+        return 0;
+      }
+      default: {
+        printUsage();
+        return 1;
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`task-store: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = {
+  // constants
+  TASKS_RELATIVE_PATH,
+  STATE_RELATIVE_PATH,
+  // path helpers
+  tasksRoot,
+  taskDir,
+  taskJsonPath,
+  projectStatePath,
+  sanitizeTaskId,
+  // status helpers
+  isTerminalStatus,
+  // CRUD
+  createTask,
+  getTask,
+  listTasks,
+  getActiveTask,
+  updateTask,
+  // artifacts
+  registerArtifact,
+  registerArtifactForActiveTask,
+  registerSpecEvolution,
+  // lifecycle
+  completeTask,
+  archiveTask,
+  // projection
+  readProjectState,
+  writeProjectState,
+  syncProjectState,
+  // CLI
+  parseArgs,
+  main,
+};

package/templates/skills/tools/verify-change/SKILL.md

@@ -10,10 +10,17 @@ argument-hint: [--mode working|staged|committed]
 deprecated_in: 1.0.0
 replaced_by: /ccg:verify --gate=change
 deprecation_message: 推荐使用 `/ccg:verify --gate=change`。本命令仍可用以保持 BC。详见 .ccg-migration/DEPRECATIONS.md
+gate-type: revision-loop
 ---
 
 # ⚖ 校验关卡 · 变更校验
 
+## Gate 分类与失败路径
+
+- **类型**：revision-loop（maxLoops = 3）
+- **失败路径**：findings 回喂修复 → 重跑本门；3 轮不收敛或连续两轮 issue 数不下降 → escalation 三选（force / guide / abort）
+- **单一真相源**：分类与失败路径以 `/ccg:verify` 的 Gates Taxonomy 段及 `src/utils/verify-orchestrator.ts` 的 `GATE_REGISTRY` 为准
+
 
 ## 核心原则
 

package/templates/skills/tools/verify-module/SKILL.md

@@ -10,10 +10,17 @@ argument-hint: <模块路径>
 deprecated_in: 1.0.0
 replaced_by: /ccg:verify --gate=module
 deprecation_message: 推荐使用 `/ccg:verify --gate=module`。本命令仍可用以保持 BC。详见 .ccg-migration/DEPRECATIONS.md
+gate-type: revision-loop
 ---
 
 # ⚖ 校验关卡 · 模块完整性
 
+## Gate 分类与失败路径
+
+- **类型**：revision-loop（maxLoops = 3）
+- **失败路径**：缺文档/结构 → 补齐后重跑本门；3 轮不收敛 → escalation 三选（force / guide / abort）
+- **单一真相源**：分类与失败路径以 `/ccg:verify` 的 Gates Taxonomy 段及 `src/utils/verify-orchestrator.ts` 的 `GATE_REGISTRY` 为准
+
 
 ## 核心原则