cc-devflow 4.3.0 → 4.4.1

package/.claude/skills/cc-check/scripts/render-report-card.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+
+function usage() {
+  console.error(
+    'Usage: render-report-card.js --change-id REQ-123 --manifest task-manifest.json --quick quick.json --strict strict.json --review review.json'
+  );
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function parseArgs(argv) {
+  const args = {
+    changeId: '',
+    manifest: '',
+    quick: '',
+    strict: '',
+    review: '',
+    timestamp: ''
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--change-id') {
+      args.changeId = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (arg === '--manifest') {
+      args.manifest = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (arg === '--quick') {
+      args.quick = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (arg === '--strict') {
+      args.strict = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (arg === '--review') {
+      args.review = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (arg === '--timestamp') {
+      args.timestamp = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+  }
+
+  return args;
+}
+
+function deriveVerdict(manifest, quickGates, strictGates, review) {
+  if ((manifest.tasks || []).some((task) => task.status === 'failed')) {
+    return 'fail';
+  }
+
+  if ([...quickGates, ...strictGates].some((gate) => gate.status === 'fail')) {
+    return 'fail';
+  }
+
+  if (review.status === 'blocked') {
+    return 'blocked';
+  }
+
+  if (review.status === 'fail') {
+    return 'fail';
+  }
+
+  return 'pass';
+}
+
+function deriveReroute({ verdict, review, manifest, blockingFindings }) {
+  if (verdict === 'pass') {
+    return 'none';
+  }
+
+  const taskFailures = (manifest.tasks || []).some((task) => task.status === 'failed');
+  if (taskFailures) {
+    return 'cc-do';
+  }
+
+  const rerouteSignals = [
+    review.summary || '',
+    review.details || '',
+    ...(blockingFindings || [])
+  ].join(' ').toLowerCase();
+
+  if (/(root cause|repro|debug|investigat|regression)/.test(rerouteSignals)) {
+    return 'cc-investigate';
+  }
+
+  if (/(design|scope|plan|planning|requirement|contract)/.test(rerouteSignals)) {
+    return 'cc-plan';
+  }
+
+  return 'cc-do';
+}
+
+function buildSummary({ quickGates, strictGates, review, verdict }) {
+  const gateSummary = (gates) => `${gates.filter((gate) => gate.status === 'pass').length}/${gates.length}`;
+  return [
+    `verdict=${verdict}`,
+    `quick=${gateSummary(quickGates)}`,
+    `strict=${gateSummary(strictGates)}`,
+    `review=${review.status}`
+  ].join(' ');
+}
+
+function summarizeOpenReviewFindings(findings = []) {
+  return findings
+    .filter((item) => item.status !== 'resolved' && item.status !== 'accepted' && item.status !== 'informational')
+    .map((item) => `${item.source}: ${item.summary}`);
+}
+
+function collectBlockingFindings({ manifest, quickGates, strictGates, review }) {
+  const findings = [];
+
+  for (const task of manifest.tasks || []) {
+    if (task.status === 'failed') {
+      findings.push(`${task.id}: ${task.lastError || 'task failed'}`);
+    }
+  }
+
+  for (const gate of [...quickGates, ...strictGates]) {
+    if (gate.status === 'fail') {
+      findings.push(`${gate.name}: ${gate.details}`);
+    }
+  }
+
+  if (review.status === 'blocked' || review.status === 'fail') {
+    findings.push(`review: ${review.summary || review.details || review.status}`);
+  }
+
+  return findings.concat(summarizeOpenReviewFindings(review.findings || []));
+}
+
+function deriveSpecSignals(manifest, verdict, review) {
+  const spec = manifest.spec || {};
+  const hasSpec =
+    Boolean(spec.primaryCapability) ||
+    (Array.isArray(spec.secondaryCapabilities) && spec.secondaryCapabilities.length > 0) ||
+    (Array.isArray(spec.specFiles) && spec.specFiles.length > 0);
+
+  if (!hasSpec || review.status === 'blocked') {
+    return {
+      specAlignment: 'blocked',
+      specDeltaVerified: false,
+      specSyncReady: false
+    };
+  }
+
+  if (verdict === 'fail') {
+    return {
+      specAlignment: 'fail',
+      specDeltaVerified: false,
+      specSyncReady: false
+    };
+  }
+
+  return {
+    specAlignment: 'pass',
+    specDeltaVerified: true,
+    specSyncReady: true
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.changeId || !args.manifest || !args.quick || !args.strict || !args.review) {
+    usage();
+    process.exit(1);
+  }
+
+  const manifest = readJson(args.manifest);
+  const quickGates = readJson(args.quick);
+  const strictGates = readJson(args.strict);
+  const review = readJson(args.review);
+
+  const blockingFindings = collectBlockingFindings({
+    manifest,
+    quickGates,
+    strictGates,
+    review
+  });
+  const verdict = deriveVerdict(manifest, quickGates, strictGates, review);
+  const reroute = deriveReroute({
+    verdict,
+    review,
+    manifest,
+    blockingFindings
+  });
+  const specSignals = deriveSpecSignals(manifest, verdict, review);
+
+  const report = {
+    changeId: args.changeId,
+    verdict,
+    overall: verdict === 'pass' ? 'pass' : 'fail',
+    summary: buildSummary({
+      quickGates,
+      strictGates,
+      review,
+      verdict
+    }),
+    specAlignment: specSignals.specAlignment,
+    specDeltaVerified: specSignals.specDeltaVerified,
+    specSyncReady: specSignals.specSyncReady,
+    quickGates,
+    strictGates,
+    review,
+    blockingFindings,
+    gaps: manifest.spec?.newGaps || [],
+    reroute,
+    timestamp: args.timestamp || new Date().toISOString()
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();

package/.claude/skills/cc-check/scripts/run-quality-gates.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 执行验证命令，输出结构化结果
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage:
+  run-quality-gates.sh --gate "test::npm test" [--gate "lint::npm run lint"]
+  run-quality-gates.sh --cmd "npm test" [--cmd "npm run lint"]
+EOF
+}
+
+cmds=()
+gates=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --gate) gates+=("$2"); shift 2 ;;
+    --cmd) cmds+=("$2"); shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ ${#cmds[@]} -eq 0 && ${#gates[@]} -eq 0 ]]; then
+  usage
+  exit 1
+fi
+
+if [[ ${#gates[@]} -eq 0 ]]; then
+  for cmd in "${cmds[@]}"; do
+    gates+=("$cmd::$cmd")
+  done
+fi
+
+printf '['
+first=true
+for gate in "${gates[@]}"; do
+  name="${gate%%::*}"
+  cmd="${gate#*::}"
+  stdout_file="$(mktemp)"
+  stderr_file="$(mktemp)"
+  start_ms="$(node -e 'console.log(Date.now())')"
+
+  if eval "$cmd" >"$stdout_file" 2>"$stderr_file"; then
+    status="pass"
+    code=0
+  else
+    status="fail"
+    code=$?
+  fi
+  end_ms="$(node -e 'console.log(Date.now())')"
+  duration_ms=$((end_ms - start_ms))
+  stdout_text="$(cat "$stdout_file" 2>/dev/null || true)"
+  stderr_text="$(cat "$stderr_file" 2>/dev/null || true)"
+  details="ok"
+  if [[ "$stdout_text" == __CC_DEVFLOW_SKIP__* || "$stderr_text" == __CC_DEVFLOW_SKIP__* ]]; then
+    status="skipped"
+    code=0
+    details="${stdout_text#__CC_DEVFLOW_SKIP__ }"
+    if [[ "$details" == "$stdout_text" ]]; then
+      details="${stderr_text#__CC_DEVFLOW_SKIP__ }"
+    fi
+  elif [[ "$status" != "pass" ]]; then
+    details="$(cat "$stderr_file" 2>/dev/null || true)"
+    if [[ -z "$details" ]]; then
+      details="$(cat "$stdout_file" 2>/dev/null || true)"
+    fi
+    details="${details//$'\n'/ }"
+  fi
+  $first || printf ','
+  first=false
+  jq -nc \
+    --arg name "$name" \
+    --arg command "$cmd" \
+    --arg status "$status" \
+    --arg details "${details:0:400}" \
+    --argjson durationMs "$duration_ms" \
+    --argjson exitCode "$code" \
+    '{name:$name,command:$command,status:$status,durationMs:$durationMs,details:$details,exitCode:$exitCode}'
+  rm -f "$stdout_file" "$stderr_file"
+done
+printf ']\n'

package/.claude/skills/cc-check/scripts/verify-gate.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 检查验证产物和 report-card 是否齐全
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage: verify-gate.sh --report report-card.json [--require FILE...]
+EOF
+}
+
+REPORT=""
+requires=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --report) REPORT="$2"; shift 2 ;;
+    --require) requires+=("$2"); shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$REPORT" || ! -f "$REPORT" ]]; then
+  usage
+  exit 1
+fi
+
+jq -e '
+  .changeId and
+  .overall and
+  .verdict and
+  .summary and
+  .review and
+  .blockingFindings and
+  (.specAlignment? // "blocked") and
+  ((.specDeltaVerified? // false) | type == "boolean") and
+  ((.specSyncReady? // false) | type == "boolean") and
+  .reroute and
+  .timestamp and
+  (.verdict | IN("pass", "fail", "blocked")) and
+  (.overall | IN("pass", "fail")) and
+  (.reroute | IN("none", "cc-do", "cc-investigate", "cc-plan")) and
+  (.review.status | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.verdict == "pass" and .reroute == "none") or (.verdict != "pass" and .reroute != "none"))
+' "$REPORT" >/dev/null
+
+if (( ${#requires[@]} > 0 )); then
+  for file in "${requires[@]}"; do
+    [[ -f "$file" ]] || { echo "Missing required file: $file" >&2; exit 1; }
+  done
+fi
+
+echo "Gate report is structurally valid"

package/.claude/skills/cc-do/CHANGELOG.md

@@ -0,0 +1,49 @@
+# CC-Do Skill Changelog
+
+## v1.5.1 - 2026-04-25
+
+- remove external tool provenance from the public skill contract so test-first execution reads as native `cc-do` behavior
+- keep the Red/Green/Refactor iron law and exception checkpoint contract unchanged
+
+## v1.5.0 - 2026-04-24
+
+- add test-first execution to the `cc-do` contract with an explicit `NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST` rule
+- require Red failure reason verification, post-refactor Green evidence, and checkpoint fields that make TDD proof resumable
+- add a narrow TDD exception contract so prototypes, generated files, and config-only changes cannot silently bypass test-first execution
+
+Migration note:
+
+- new task checkpoints should record `red`, `green`, `refactor`, and optional `tddException` fields before `cc-check` verifies the task
+
+## v1.4.0 - 2026-04-19
+
+- require `cc-do` to load `change-meta.json` and related capability specs before coding so execution stops guessing long-term constraints
+- extend `build-task-context.sh` with primary capability, spec files, expected spec delta, and sync status
+- make the execution contract explicit that `cc-do` validates spec alignment but does not mutate long-term spec truth
+
+Migration note:
+
+- new execution contexts should include `change-meta.json` beside `design.md` / `analysis.md`
+
+## v1.3.1 - 2026-04-18
+
+- replace GNU `sed` usage in `scripts/mark-task-complete.sh` with a portable `awk` implementation so task completion works on macOS BSD userlands
+
+## v1.3.0 - 2026-04-17
+
+- split root-cause investigation out of `cc-do` so bug execution now expects a frozen `ANALYSIS.md` handoff from `cc-investigate`
+- teach `cc-do` to accept either `DESIGN.md` or `ANALYSIS.md` as the upstream contract
+- clarify reroutes so repeated failed bug repairs return to `cc-investigate`, while true scope drift still returns to `cc-plan`
+
+## v1.2.0 - 2026-04-17
+
+- add structured frontmatter contract fields for reads, writes, reroutes, recovery, and tool budget
+- add `Harness Contract` and `Visible State Machine` so execution boundaries are visible in the skill pack itself
+- strengthen context reset and local recovery guidance to prefer checkpoint reload over chat-memory continuation
+
+## v1.1.0 - 2026-04-15
+
+- add `version` frontmatter and semver tracking
+- add stronger trigger phrases in frontmatter
+- add `Quick Start` to classify execution into implement / resume / cc-investigate-first / review-fix
+- add `Good Output` so execution leaves clear recovery and verification evidence

package/.claude/skills/cc-do/PLAYBOOK.md

@@ -0,0 +1,119 @@
+# CC-Do Playbook
+
+## Visible State Machine
+
+`cc-plan | cc-investigate -> cc-do -> cc-check`
+
+- Enter from: an approved `planning/design.md` or `planning/analysis.md` with frozen tasks.
+- Stay in: `cc-do` while there are ready tasks, valid checkpoints, and the design contract still holds.
+- Exit to: `cc-check` once the current task set has red/green/review evidence and no hidden execution gaps remain.
+- Reroute to: `cc-investigate` if repeated failures prove the root-cause contract is wrong, or `cc-plan` if the requirement design itself is wrong.
+
+## Quick Triage
+
+开始前先把当前执行局面归到 4 类之一：
+
+- `implement`: 已有 ready task，可直接进入 TDD
+- `resume`: task 已有 runtime / checkpoint，需要续做
+- `repair-from-investigation`: `planning/analysis.md` 已冻结，可直接修
+- `reroute-cc-investigate`: bug 根因未明，回调查入口
+- `review-fix`: scope 不变，只修 review 指向的问题
+
+如果这一步归不清，说明当前上下文还没组装好，不准开始实现。
+
+## Execution Loop
+
+1. 读取 `task-manifest.json`，先用 `scripts/select-ready-tasks.sh` 找出当前 ready tasks。
+2. 如果有多于一个 ready task，要先跑 `scripts/detect-file-conflicts.sh`；有共享触点或依赖关系就退回串行。
+3. 对每个要执行的 task，先用 `scripts/build-task-context.sh` 从 `planning/design.md`、`planning/tasks.md`、`planning/task-manifest.json` 组装上下文，再开始编码。
+4. 如果当前任务来自 `cc-investigate`，把 `planning/analysis.md` 当成上游合同，不准一边做一边重开调查。
+5. 进入 TDD 闭环：先红，再绿，再重构。
+6. 每个关键节点都写 runtime：失败测试、Green 通过、Refactor、Review 结论、阻塞原因。
+7. 任务实现后，先过 `spec review`，再过 `code review`，review 不通过就回到实现。
+8. 两道 review 门都通过后，才能把任务标成完成，并把结果留给 `cc-check`。
+
+## Local Kit
+
+- 恢复时看 `references/execution-recovery.md`
+- 并行分配时看 `references/parallel-dispatch.md`
+- 需要判断当前任务时用 `scripts/check-task-status.sh`
+- 需要找 ready task 时用 `scripts/select-ready-tasks.sh`
+- 需要组装任务上下文时用 `scripts/build-task-context.sh`
+- 需要写 checkpoint 时用 `scripts/write-task-checkpoint.sh`
+- 需要写 review 门结果时用 `scripts/record-review-decision.sh`
+- 需要校验任务闭环时用 `scripts/verify-task-gates.sh`
+- 需要勾选任务时用 `scripts/mark-task-complete.sh`
+- 需要确认并行安全时用 `scripts/detect-file-conflicts.sh`
+- bug 根因没冻结时，退出当前执行并回 `cc-investigate`
+
+## TDD Standard
+
+1. 先写失败测试，再运行到红。
+2. 确认红灯是预期失败，不是测试写错、fixture 缺失或环境没接上。
+3. 只写让当前测试转绿的最小实现。
+4. 绿后才允许重构。
+5. 重构后必须保持绿。
+6. 测试没先红过，就不能宣称这次变更受 TDD 保护。
+
+## TDD Exception Rule
+
+只有这些场景允许跳过 fail-first：
+
+- throwaway prototype
+- 纯生成文件
+- 纯配置变更
+- 上游明确禁止写测试的探索步骤
+
+每个例外都要写入 checkpoint：
+
+- `tddException.reason`
+- `tddException.risk`
+- `tddException.alternativeEvidence`
+
+没有例外记录，就按违规处理，回到 Red。
+
+## Task Gates
+
+任务只有在下面顺序全部成立后，才算完成：
+
+1. `red_failed`: 已观察到预期失败
+2. `red_reason_verified`: 红灯原因与目标行为缺失一致
+3. `green_passed`: 当前任务实现转绿
+4. `refactor_done` 或 `refactor_not_needed`
+5. `refactor_green`: 重构后相关测试仍绿
+6. `spec_review_pass`
+7. `code_review_pass`
+
+任何一门失败，都回到实现，不准直接跨过去。
+
+## Parallel Dispatch Rule
+
+只有满足全部条件，才能并行：
+
+1. 任务处于当前 active phase
+2. `dependsOn` 已全部满足
+3. 任务显式允许并行，例如 `[P]`
+4. `touches` / `files` 不冲突
+5. 每个 subagent 都拿到了自己的 task context
+
+少一条，都按顺序执行。
+
+## Root Cause Protocol
+
+- 先复现，再猜原因
+- 先读 `planning/analysis.md`，再改代码
+- 先守住修复边界，再做最小实现
+- 两次失败后回看证据
+- 三次失败后先回 `cc-investigate`，再决定是否需要 `cc-plan`
+
+## Recovery Standard
+
+至少留下这些恢复信息：
+
+- 当前任务 ID
+- 当前 active phase / ready tasks
+- 已完成什么
+- 卡在哪里
+- 下一步唯一动作
+- 相关文件 / 命令 / 观察
+- 最近一次 Red/Green/Review 到了哪一站