cc-devflow 4.2.0 → 4.4.1

package/.claude/skills/cc-roadmap/scripts/lib/roadmap-tracking/schema.js

@@ -0,0 +1,245 @@
+const ROADMAP_COLUMNS = [
+  ['RM-ID', 'rmId'],
+  ['Item', 'item'],
+  ['Stage', 'stage'],
+  ['Priority', 'priority'],
+  ['Primary Capability', 'primaryCapability'],
+  ['Secondary Capabilities', 'secondaryCapabilities'],
+  ['Expected Spec Delta', 'expectedSpecDelta'],
+  ['Depends On', 'dependsOn'],
+  ['Status', 'status'],
+  ['REQ', 'req'],
+  ['Progress', 'progress']
+];
+
+const BACKLOG_QUEUE_COLUMNS = [
+  ['RM-ID', 'rmId'],
+  ['Title', 'item'],
+  ['Source Stage', 'stage'],
+  ['Priority', 'priority'],
+  ['Primary Capability', 'primaryCapability'],
+  ['Secondary Capabilities', 'secondaryCapabilities'],
+  ['Capability Gap', 'capabilityGap'],
+  ['Expected Spec Delta', 'expectedSpecDelta'],
+  ['Evidence', 'evidence'],
+  ['Depends On', 'dependsOn'],
+  ['Parallel With', 'parallelWith'],
+  ['Unknowns', 'unknowns'],
+  ['Next Decision', 'nextDecision'],
+  ['Ready', 'ready']
+];
+
+const DEFAULT_BACKLOG = {
+  capabilityGap: '',
+  evidence: '',
+  parallelWith: [],
+  unknowns: '',
+  nextDecision: '',
+  ready: false,
+  whyNow: '',
+  successSignal: '',
+  entryConstraints: '',
+  openRisks: '',
+  firstPlanningQuestion: '',
+  requiredContextToLoad: '',
+  whyReadyNow: '',
+  parked: false,
+  parkedReason: '',
+  triggerToReopen: '',
+  missingEvidence: ''
+};
+
+const DEFAULT_TRACKING = {
+  version: 2,
+  lastSyncedAt: '',
+  backlogMeta: {
+    roadmapVersion: '',
+    skillVersion: '',
+    currentFocusStage: ''
+  },
+  dependencyHandoff: {
+    serialSpine: '',
+    parallelReadyNextWave: '',
+    notesOnBlockers: ''
+  },
+  items: []
+};
+
+function normalizeHeader(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ');
+}
+
+function normalizeCell(value) {
+  const trimmed = String(value || '').trim();
+  return trimmed === '-' ? '' : trimmed;
+}
+
+function parseList(value) {
+  const cleaned = normalizeCell(value);
+  if (!cleaned) {
+    return [];
+  }
+
+  return cleaned
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function formatList(items) {
+  return items.length ? items.join(', ') : '-';
+}
+
+function formatCell(value) {
+  const cleaned = String(value || '').trim();
+  return cleaned || '-';
+}
+
+function formatBacklogValue(value) {
+  return formatCell(value);
+}
+
+function formatBoolean(value) {
+  return value ? 'Yes' : 'No';
+}
+
+function formatInlineCode(value) {
+  const cleaned = String(value || '').trim();
+  return cleaned ? `\`${cleaned}\`` : '';
+}
+
+function normalizeBoolean(value) {
+  const normalized = normalizeCell(value).toLowerCase();
+  return normalized === 'yes' || normalized === 'true';
+}
+
+function emptyBacklog() {
+  return {
+    ...DEFAULT_BACKLOG,
+    parallelWith: []
+  };
+}
+
+function normalizeItem(raw) {
+  const backlog = raw.backlog || {};
+
+  return {
+    rmId: String(raw.rmId || '').trim(),
+    item: String(raw.item || '').trim(),
+    stage: String(raw.stage || '').trim(),
+    priority: String(raw.priority || '').trim(),
+    primaryCapability: String(raw.primaryCapability || '').trim(),
+    secondaryCapabilities: Array.isArray(raw.secondaryCapabilities)
+      ? raw.secondaryCapabilities.map((entry) => String(entry).trim()).filter(Boolean)
+      : parseList(raw.secondaryCapabilities),
+    expectedSpecDelta: String(raw.expectedSpecDelta || '').trim(),
+    dependsOn: Array.isArray(raw.dependsOn)
+      ? raw.dependsOn.map((entry) => String(entry).trim()).filter(Boolean)
+      : parseList(raw.dependsOn),
+    status: String(raw.status || '').trim(),
+    req: String(raw.req || '').trim(),
+    progress: String(raw.progress || '').trim(),
+    backlog: {
+      capabilityGap: String(backlog.capabilityGap || '').trim(),
+      evidence: String(backlog.evidence || '').trim(),
+      parallelWith: Array.isArray(backlog.parallelWith)
+        ? backlog.parallelWith.map((entry) => String(entry).trim()).filter(Boolean)
+        : parseList(backlog.parallelWith),
+      unknowns: String(backlog.unknowns || '').trim(),
+      nextDecision: String(backlog.nextDecision || '').trim(),
+      ready: Boolean(backlog.ready),
+      whyNow: String(backlog.whyNow || '').trim(),
+      successSignal: String(backlog.successSignal || '').trim(),
+      entryConstraints: String(backlog.entryConstraints || '').trim(),
+      openRisks: String(backlog.openRisks || '').trim(),
+      firstPlanningQuestion: String(backlog.firstPlanningQuestion || '').trim(),
+      requiredContextToLoad: String(backlog.requiredContextToLoad || '').trim(),
+      whyReadyNow: String(backlog.whyReadyNow || '').trim(),
+      parked: Boolean(backlog.parked),
+      parkedReason: String(backlog.parkedReason || '').trim(),
+      triggerToReopen: String(backlog.triggerToReopen || '').trim(),
+      missingEvidence: String(backlog.missingEvidence || '').trim()
+    }
+  };
+}
+
+function normalizeTracking(raw) {
+  const backlogMeta = raw.backlogMeta || {};
+  const dependencyHandoff = raw.dependencyHandoff || {};
+  const items = Array.isArray(raw.items) ? raw.items.map(normalizeItem) : [];
+
+  return {
+    version: 2,
+    lastSyncedAt: String(raw.lastSyncedAt || '').trim(),
+    backlogMeta: {
+      roadmapVersion: String(backlogMeta.roadmapVersion || '').trim(),
+      skillVersion: String(backlogMeta.skillVersion || '').trim(),
+      currentFocusStage: String(backlogMeta.currentFocusStage || '').trim()
+    },
+    dependencyHandoff: {
+      serialSpine: String(dependencyHandoff.serialSpine || '').trim(),
+      parallelReadyNextWave: String(dependencyHandoff.parallelReadyNextWave || '').trim(),
+      notesOnBlockers: String(dependencyHandoff.notesOnBlockers || '').trim()
+    },
+    items
+  };
+}
+
+const ROADMAP_HEADER_TO_KEY = new Map(
+  ROADMAP_COLUMNS.map(([header, key]) => [normalizeHeader(header), key])
+);
+
+const BACKLOG_QUEUE_HEADER_TO_KEY = new Map(
+  BACKLOG_QUEUE_COLUMNS.map(([header, key]) => [normalizeHeader(header), key])
+);
+
+const READY_FIELD_MAP = new Map(
+  [
+    ['Primary Capability', 'primaryCapability'],
+    ['Secondary Capabilities', 'secondaryCapabilities'],
+    ['Why now', 'whyNow'],
+    ['Success signal', 'successSignal'],
+    ['Entry constraints', 'entryConstraints'],
+    ['Capability gap', 'capabilityGap'],
+    ['Expected spec delta', 'expectedSpecDelta'],
+    ['Open risks', 'openRisks'],
+    ['First planning question', 'firstPlanningQuestion'],
+    ['Required context to load', 'requiredContextToLoad'],
+    ['Depends On', 'dependsOn'],
+    ['Parallel With', 'parallelWith'],
+    ['Why this is ready now', 'whyReadyNow']
+  ].map(([label, key]) => [normalizeHeader(label), key])
+);
+
+const PARKED_FIELD_MAP = new Map(
+  [
+    ['Reason parked', 'parkedReason'],
+    ['Trigger to reopen', 'triggerToReopen'],
+    ['Missing evidence', 'missingEvidence']
+  ].map(([label, key]) => [normalizeHeader(label), key])
+);
+
+module.exports = {
+  BACKLOG_QUEUE_COLUMNS,
+  BACKLOG_QUEUE_HEADER_TO_KEY,
+  DEFAULT_TRACKING,
+  PARKED_FIELD_MAP,
+  READY_FIELD_MAP,
+  ROADMAP_COLUMNS,
+  ROADMAP_HEADER_TO_KEY,
+  emptyBacklog,
+  formatBacklogValue,
+  formatBoolean,
+  formatCell,
+  formatInlineCode,
+  formatList,
+  normalizeBoolean,
+  normalizeCell,
+  normalizeHeader,
+  normalizeItem,
+  normalizeTracking,
+  parseList
+};

package/.claude/skills/cc-roadmap/scripts/lib/roadmap-tracking/store.js

@@ -0,0 +1,139 @@
+const fs = require('fs');
+
+const {
+  emptyBacklog,
+  normalizeItem,
+  normalizeTracking,
+  parseList
+} = require('./schema');
+const {
+  renderBacklogDocument,
+  renderRoadmapDocument,
+  trackingFromMarkdown
+} = require('./markdown');
+
+function ensureDir(filePath) {
+  fs.mkdirSync(require('path').dirname(filePath), { recursive: true });
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, data) {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function readFileIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return '';
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function upgradeLegacyTracking(parsed) {
+  if (parsed.version === 2 || parsed.backlogMeta || parsed.dependencyHandoff) {
+    return normalizeTracking(parsed);
+  }
+
+  return normalizeTracking({
+    version: 2,
+    lastSyncedAt: parsed.lastSyncedAt || '',
+    backlogMeta: {
+      roadmapVersion: '',
+      skillVersion: '',
+      currentFocusStage: ''
+    },
+    dependencyHandoff: {
+      serialSpine: '',
+      parallelReadyNextWave: '',
+      notesOnBlockers: ''
+    },
+    items: Array.isArray(parsed.items)
+      ? parsed.items.map((item) => ({
+          ...item,
+          backlog: {
+            ...emptyBacklog(),
+            ...(item.backlog || {})
+          }
+        }))
+      : []
+  });
+}
+
+function loadTracking({ trackingFile, roadmapFile = '', backlogFile = '' }) {
+  if (trackingFile && fs.existsSync(trackingFile)) {
+    return upgradeLegacyTracking(readJson(trackingFile));
+  }
+
+  return trackingFromMarkdown(readFileIfExists(roadmapFile), readFileIfExists(backlogFile));
+}
+
+function applySyncArgs(tracking, args) {
+  const index = tracking.items.findIndex((item) => item.rmId === args.rm);
+  const item = index === -1 ? normalizeItem({ rmId: args.rm }) : tracking.items[index];
+
+  const scalarUpdates = [
+    ['item', 'item'],
+    ['stage', 'stage'],
+    ['priority', 'priority'],
+    ['primary-capability', 'primaryCapability'],
+    ['spec-delta', 'expectedSpecDelta'],
+    ['status', 'status'],
+    ['req', 'req'],
+    ['progress', 'progress']
+  ];
+
+  scalarUpdates.forEach(([argName, key]) => {
+    if (args[argName] != null) {
+      item[key] = String(args[argName]).trim();
+    }
+  });
+
+  if (args['secondary-capabilities'] != null) {
+    item.secondaryCapabilities = parseList(args['secondary-capabilities']);
+  }
+
+  if (args['depends-on'] != null) {
+    item.dependsOn = parseList(args['depends-on']);
+  }
+
+  const normalized = normalizeItem(item);
+  if (index === -1) {
+    tracking.items.push(normalized);
+  } else {
+    tracking.items[index] = normalized;
+  }
+
+  tracking.lastSyncedAt = new Date().toISOString().slice(0, 10);
+  return tracking;
+}
+
+function persistTrackingFiles({ trackingFile, roadmapFile, backlogFile, tracking }) {
+  writeJson(trackingFile, tracking);
+
+  const roadmapOutput = renderRoadmapDocument({
+    original: readFileIfExists(roadmapFile) || '# ROADMAP\n',
+    roadmapFile,
+    trackingFile,
+    tracking
+  });
+  const backlogOutput = renderBacklogDocument({
+    backlogFile,
+    trackingFile,
+    tracking
+  });
+
+  ensureDir(roadmapFile);
+  fs.writeFileSync(roadmapFile, roadmapOutput);
+  ensureDir(backlogFile);
+  fs.writeFileSync(backlogFile, backlogOutput);
+}
+
+module.exports = {
+  applySyncArgs,
+  loadTracking,
+  persistTrackingFiles
+};

package/.claude/skills/cc-roadmap/scripts/locate-roadmap-item.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 本地定位器：优先从 tracking 真相源定位 RM / REQ
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage: locate-roadmap-item.sh <ID> [--roadmap devflow/ROADMAP.md] [--backlog devflow/BACKLOG.md] [--tracking-file devflow/roadmap-tracking.json]
+
+ID can be RM-xxx or REQ-xxx.
+EOF
+}
+
+TARGET="${1:-}"
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+DEFAULT_ROADMAP_FILE="$REPO_ROOT/devflow/ROADMAP.md"
+ROOT_ROADMAP_FILE="$REPO_ROOT/ROADMAP.md"
+LEGACY_ROADMAP_FILE="$REPO_ROOT/devflow/roadmap/roadmap.md"
+DEFAULT_BACKLOG_FILE="$REPO_ROOT/devflow/BACKLOG.md"
+ROOT_BACKLOG_FILE="$REPO_ROOT/BACKLOG.md"
+LEGACY_BACKLOG_FILE="$REPO_ROOT/devflow/roadmap/backlog.md"
+DEFAULT_TRACKING_FILE="$REPO_ROOT/devflow/roadmap-tracking.json"
+ROOT_TRACKING_FILE="$REPO_ROOT/roadmap-tracking.json"
+LEGACY_TRACKING_FILE="$REPO_ROOT/devflow/roadmap/roadmap-tracking.json"
+ROADMAP_FILE="$DEFAULT_ROADMAP_FILE"
+BACKLOG_FILE="$DEFAULT_BACKLOG_FILE"
+TRACKING_FILE="$DEFAULT_TRACKING_FILE"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ -z "$TARGET" ]]; then
+  usage
+  exit 1
+fi
+shift || true
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --roadmap) ROADMAP_FILE="$2"; shift 2 ;;
+    --backlog) BACKLOG_FILE="$2"; shift 2 ;;
+    --tracking-file) TRACKING_FILE="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$ROADMAP_FILE" == "$DEFAULT_ROADMAP_FILE" && ! -f "$ROADMAP_FILE" ]]; then
+  if [[ -f "$ROOT_ROADMAP_FILE" ]]; then
+    ROADMAP_FILE="$ROOT_ROADMAP_FILE"
+  elif [[ -f "$LEGACY_ROADMAP_FILE" ]]; then
+    ROADMAP_FILE="$LEGACY_ROADMAP_FILE"
+  fi
+fi
+
+if [[ "$BACKLOG_FILE" == "$DEFAULT_BACKLOG_FILE" && ! -f "$BACKLOG_FILE" ]]; then
+  if [[ -f "$ROOT_BACKLOG_FILE" ]]; then
+    BACKLOG_FILE="$ROOT_BACKLOG_FILE"
+  elif [[ -f "$LEGACY_BACKLOG_FILE" ]]; then
+    BACKLOG_FILE="$LEGACY_BACKLOG_FILE"
+  fi
+fi
+
+if [[ "$TRACKING_FILE" == "$DEFAULT_TRACKING_FILE" && ! -f "$TRACKING_FILE" ]]; then
+  roadmap_dir="$(cd "$(dirname "$ROADMAP_FILE")" 2>/dev/null && pwd || true)"
+  if [[ -n "$roadmap_dir" && -f "$roadmap_dir/roadmap-tracking.json" ]]; then
+    TRACKING_FILE="$roadmap_dir/roadmap-tracking.json"
+  elif [[ -f "$ROOT_TRACKING_FILE" ]]; then
+    TRACKING_FILE="$ROOT_TRACKING_FILE"
+  elif [[ -f "$LEGACY_TRACKING_FILE" ]]; then
+    TRACKING_FILE="$LEGACY_TRACKING_FILE"
+  fi
+fi
+
+found=false
+
+print_tracking_matches() {
+  local tracking_file="$1"
+  local target="$2"
+  node "$SCRIPT_DIR/roadmap-tracking.js" find --tracking "$tracking_file" --id "$target"
+}
+
+if [[ -f "$TRACKING_FILE" ]]; then
+  if print_tracking_matches "$TRACKING_FILE" "$TARGET"; then
+    found=true
+  fi
+fi
+
+if [[ -f "$ROADMAP_FILE" ]]; then
+  if rg -n --fixed-strings "$TARGET" "$ROADMAP_FILE" >/dev/null 2>&1; then
+    echo "[ROADMAP]"
+    rg -n --fixed-strings "$TARGET" "$ROADMAP_FILE"
+    found=true
+  fi
+fi
+
+if [[ -f "$BACKLOG_FILE" ]]; then
+  if rg -n --fixed-strings "$TARGET" "$BACKLOG_FILE" >/dev/null 2>&1; then
+    echo "[BACKLOG]"
+    rg -n --fixed-strings "$TARGET" "$BACKLOG_FILE"
+    found=true
+  fi
+fi
+
+if [[ "$found" == false ]]; then
+  echo "Not found: $TARGET" >&2
+  exit 1
+fi

package/.claude/skills/cc-roadmap/scripts/roadmap-tracking.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+const { loadTracking, applySyncArgs, persistTrackingFiles } = require('./lib/roadmap-tracking/store');
+const { findTrackingMatches, formatTrackingMatches } = require('./lib/roadmap-tracking/query');
+
+function usage() {
+  process.stderr.write(
+    [
+      'Usage:',
+      '  roadmap-tracking.js sync --roadmap <ROADMAP.md> --backlog <BACKLOG.md> --tracking <roadmap-tracking.json> --rm <RM-ID> [field updates]',
+      '  roadmap-tracking.js render --roadmap <ROADMAP.md> --backlog <BACKLOG.md> --tracking <roadmap-tracking.json>',
+      '  roadmap-tracking.js find --tracking <roadmap-tracking.json> --id <RM-ID|REQ-ID>',
+      '',
+      'Fields:',
+      '  --item <title>',
+      '  --stage <Stage 1>',
+      '  --priority <P1>',
+      '  --primary-capability <cap-id>',
+      '  --secondary-capabilities "cap-a,cap-b"',
+      '  --spec-delta "delta summary"',
+      '  --depends-on "RM-001,RM-002"',
+      '  --status <Planned>',
+      '  --req <REQ-001>',
+      '  --progress <50%>'
+    ].join('\n')
+  );
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const args = { command };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const key = rest[index];
+    const value = rest[index + 1];
+
+    if (!key.startsWith('--')) {
+      throw createError(`Unknown arg: ${key}`);
+    }
+
+    if (value == null || value.startsWith('--')) {
+      throw createError(`Missing value for ${key}`);
+    }
+
+    args[key.slice(2)] = value;
+    index += 1;
+  }
+
+  return args;
+}
+
+function createError(message, showUsage = true) {
+  const error = new Error(message);
+  error.showUsage = showUsage;
+  return error;
+}
+
+function normalizePathArg(filePath) {
+  return path.resolve(filePath);
+}
+
+function requireArgs(args, names, message) {
+  const missing = names.filter((name) => !args[name]);
+  if (missing.length) {
+    throw createError(message);
+  }
+}
+
+function syncTracking(args) {
+  requireArgs(
+    args,
+    ['roadmap', 'backlog', 'tracking', 'rm'],
+    'sync requires --roadmap, --backlog, --tracking, and --rm'
+  );
+
+  const files = {
+    roadmapFile: normalizePathArg(args.roadmap),
+    backlogFile: normalizePathArg(args.backlog),
+    trackingFile: normalizePathArg(args.tracking)
+  };
+  const tracking = loadTracking(files);
+  applySyncArgs(tracking, args);
+  persistTrackingFiles({
+    ...files,
+    tracking
+  });
+}
+
+function renderOnly(args) {
+  requireArgs(
+    args,
+    ['roadmap', 'backlog', 'tracking'],
+    'render requires --roadmap, --backlog, and --tracking'
+  );
+
+  const files = {
+    roadmapFile: normalizePathArg(args.roadmap),
+    backlogFile: normalizePathArg(args.backlog),
+    trackingFile: normalizePathArg(args.tracking)
+  };
+  const tracking = loadTracking(files);
+  persistTrackingFiles({
+    ...files,
+    tracking
+  });
+}
+
+function findTracking(args) {
+  requireArgs(args, ['tracking', 'id'], 'find requires --tracking and --id');
+
+  const tracking = loadTracking({
+    trackingFile: normalizePathArg(args.tracking)
+  });
+  const matches = findTrackingMatches(tracking, args.id);
+  if (!matches.length) {
+    throw createError(`Not found in tracking: ${args.id}`, false);
+  }
+
+  process.stdout.write(formatTrackingMatches(matches));
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+
+    if (args.command === 'sync') {
+      syncTracking(args);
+      return;
+    }
+
+    if (args.command === 'render') {
+      renderOnly(args);
+      return;
+    }
+
+    if (args.command === 'find') {
+      findTracking(args);
+      return;
+    }
+
+    throw createError(`Unknown command: ${args.command || '<missing>'}`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    if (error.showUsage !== false) {
+      usage();
+    }
+    process.exitCode = 1;
+  }
+}
+
+main();