cc-devflow 4.5.8 → 4.5.10

package/bin/cc-devflow-cli.js

@@ -60,6 +60,8 @@ Commands:
   config doctor       Validate config and local ignore safety
   query list          List typed runtime query ids
   query <id>          Run a typed runtime query as JSON
+  task-contract       Compile task contract artifacts
+  review              Record durable review ledger events
   next-change-key     Compute the next REQ/FIX change key
   archive-change      Archive a completed change to devflow/changes/archive/YYYY-MM/
   restore-change      Restore an archived change back to devflow/changes/
@@ -94,6 +96,9 @@ Query options:
   --change <id>        Change id, for example REQ-123
   --change-id <id>     Alias for --change
   --change-key <key>   Full change key, for example REQ-123-my-feature
+  --data-only          Print only the query data payload when the query succeeds
+  --no-trace           Omit trace metadata from the JSON output
+  --compact            Print minified JSON instead of pretty JSON
 
 Next-change-key options:
   --prefix <REQ|FIX>   Change type prefix (required)
@@ -111,7 +116,10 @@ Examples:
   cc-devflow config resolve --cwd /path/to/project --format policy
   cc-devflow query list
   cc-devflow query ship-readiness --cwd /path/to/project --change REQ-123
+  cc-devflow query workflow-context --cwd /path/to/project --change REQ-123 --change-key REQ-123-my-feature --data-only --no-trace --compact
   cc-devflow query progress --change REQ-123 --change-key REQ-123-my-feature
+  cc-devflow task-contract compile --cwd /path/to/project --change REQ-123 --change-key REQ-123-my-feature
+  cc-devflow review start --cwd /path/to/project --change REQ-123 --change-key REQ-123-my-feature --base-sha abc --head-sha def
 `);
 }
 
@@ -456,56 +464,51 @@ function runConfig(args) {
   return 0;
 }
 
-function parseQueryArgs(args) {
+function parseChangeScopedArgs(args, options = {}) {
+  const { allowQueryFlags = false } = options;
   const parsed = {
     cwd: null,
     changeId: null,
     changeKey: null,
+    compact: false,
+    dataOnly: false,
+    noTrace: false,
     rest: []
   };
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 
-    if (arg === '--cwd') {
-      parsed.cwd = args[++i];
-      continue;
-    }
-
-    if (arg.startsWith('--cwd=')) {
-      parsed.cwd = arg.slice('--cwd='.length);
-      continue;
-    }
-
-    if (arg === '--change' || arg === '--change-id') {
-      parsed.changeId = args[++i];
-      continue;
-    }
-
-    if (arg.startsWith('--change=')) {
-      parsed.changeId = arg.slice('--change='.length);
-      continue;
-    }
+    if (arg === '--cwd') { parsed.cwd = args[++i]; continue; }
+    if (arg.startsWith('--cwd=')) { parsed.cwd = arg.slice('--cwd='.length); continue; }
+    if (arg === '--change' || arg === '--change-id') { parsed.changeId = args[++i]; continue; }
+    if (arg.startsWith('--change=')) { parsed.changeId = arg.slice('--change='.length); continue; }
+    if (arg.startsWith('--change-id=')) { parsed.changeId = arg.slice('--change-id='.length); continue; }
+    if (arg === '--change-key') { parsed.changeKey = args[++i]; continue; }
+    if (arg.startsWith('--change-key=')) { parsed.changeKey = arg.slice('--change-key='.length); continue; }
+    if (allowQueryFlags && arg === '--compact') { parsed.compact = true; continue; }
+    if (allowQueryFlags && arg === '--data-only') { parsed.dataOnly = true; continue; }
+    if (allowQueryFlags && arg === '--no-trace') { parsed.noTrace = true; continue; }
 
-    if (arg.startsWith('--change-id=')) {
-      parsed.changeId = arg.slice('--change-id='.length);
-      continue;
-    }
+    parsed.rest.push(arg);
+  }
 
-    if (arg === '--change-key') {
-      parsed.changeKey = args[++i];
-      continue;
-    }
+  return parsed;
+}
 
-    if (arg.startsWith('--change-key=')) {
-      parsed.changeKey = arg.slice('--change-key='.length);
-      continue;
-    }
+function formatQueryResult(result, options) {
+  let output = result;
 
-    parsed.rest.push(arg);
+  if (options.dataOnly && result.ok) {
+    output = result.data;
+  } else if (options.noTrace && output && typeof output === 'object') {
+    const { trace, ...withoutTrace } = output;
+    output = withoutTrace;
   }
 
-  return parsed;
+  return options.compact
+    ? JSON.stringify(output)
+    : JSON.stringify(output, null, 2);
 }
 
 async function runQueryCommand(args) {
@@ -521,7 +524,7 @@ async function runQueryCommand(args) {
     return 0;
   }
 
-  const options = parseQueryArgs(rest);
+  const options = parseChangeScopedArgs(rest, { allowQueryFlags: true });
   if (!options.changeId) {
     console.error('Query --change is required.');
     return 3;
@@ -533,10 +536,256 @@ async function runQueryCommand(args) {
     changeKey: options.changeKey
   });
 
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`${formatQueryResult(result, options)}\n`);
   return result.ok ? 0 : 2;
 }
 
+async function runTaskContractCommand(args) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    console.error('Use: cc-devflow task-contract <compile|validate|migrate> --change <changeId> [--change-key <key>] [--cwd <path>] [--fold-design] [--fold-analysis]');
+    return 3;
+  }
+
+  const options = parseChangeScopedArgs(rest);
+  if (!options.changeId) {
+    console.error('task-contract --change is required.');
+    return 3;
+  }
+
+  if (subcommand === 'compile' || subcommand === 'validate' || subcommand === 'migrate') {
+    const {
+      runCompile,
+      runValidate,
+      runMigrate
+    } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/operations/task-contract.js'));
+    const runners = {
+      compile: runCompile,
+      validate: runValidate,
+      migrate: runMigrate
+    };
+    const runner = runners[subcommand];
+    const result = await runner({
+      repoRoot: path.resolve(options.cwd || process.cwd()),
+      changeId: options.changeId,
+      changeKey: options.changeKey,
+      foldDesign: options.rest.includes('--fold-design'),
+      foldAnalysis: options.rest.includes('--fold-analysis')
+    });
+    if (result.code !== 0) {
+      console.error(result.stderr || result.error || `task-contract ${subcommand} failed`);
+      return result.code;
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result.code;
+  }
+
+  console.error(`Unknown task-contract command: ${subcommand}`);
+  return 3;
+}
+
+function parseReviewStartArgs(args) {
+  const scoped = parseChangeScopedArgs(args);
+  const parsed = {
+    ...scoped,
+    mode: 'implementation',
+    scope: 'current-diff',
+    baseSha: 'unknown',
+    headSha: 'unknown',
+    selectedNodes: [],
+    skippedNodes: [],
+    riskLanes: []
+  };
+
+  for (let i = 0; i < scoped.rest.length; i++) {
+    const arg = scoped.rest[i];
+    if (arg === '--mode') { parsed.mode = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--mode=')) { parsed.mode = arg.slice('--mode='.length); continue; }
+    if (arg === '--scope') { parsed.scope = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--scope=')) { parsed.scope = arg.slice('--scope='.length); continue; }
+    if (arg === '--base-sha') { parsed.baseSha = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--base-sha=')) { parsed.baseSha = arg.slice('--base-sha='.length); continue; }
+    if (arg === '--head-sha') { parsed.headSha = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--head-sha=')) { parsed.headSha = arg.slice('--head-sha='.length); continue; }
+    if (arg === '--selected-node') { parsed.selectedNodes.push(scoped.rest[++i]); continue; }
+    if (arg.startsWith('--selected-node=')) { parsed.selectedNodes.push(arg.slice('--selected-node='.length)); continue; }
+    if (arg === '--skipped-node') { parsed.skippedNodes.push(scoped.rest[++i]); continue; }
+    if (arg.startsWith('--skipped-node=')) { parsed.skippedNodes.push(arg.slice('--skipped-node='.length)); continue; }
+    if (arg === '--risk-lane') { parsed.riskLanes.push(scoped.rest[++i]); continue; }
+    if (arg.startsWith('--risk-lane=')) { parsed.riskLanes.push(arg.slice('--risk-lane='.length)); continue; }
+  }
+
+  return parsed;
+}
+
+function parseReviewEventArgs(args) {
+  const scoped = parseChangeScopedArgs(args);
+  const parsed = {
+    ...scoped,
+    reviewId: null,
+    nodeId: null,
+    mode: 'implementation',
+    target: null,
+    status: null,
+    coverage: [],
+    evidenceRefs: [],
+    findings: [],
+    next: null,
+    findingId: null,
+    severity: null,
+    confidence: null,
+    displayTier: null,
+    fingerprint: null,
+    scope: null,
+    path: null,
+    evidence: null,
+    recommendation: null,
+    route: null,
+    blockingCount: null,
+    warningCount: null,
+    output: null
+  };
+
+  for (let i = 0; i < scoped.rest.length; i++) {
+    const arg = scoped.rest[i];
+    if (arg === '--review-id') { parsed.reviewId = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--review-id=')) { parsed.reviewId = arg.slice('--review-id='.length); continue; }
+    if (arg === '--node-id') { parsed.nodeId = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--node-id=')) { parsed.nodeId = arg.slice('--node-id='.length); continue; }
+    if (arg === '--mode') { parsed.mode = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--mode=')) { parsed.mode = arg.slice('--mode='.length); continue; }
+    if (arg === '--target') { parsed.target = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--target=')) { parsed.target = arg.slice('--target='.length); continue; }
+    if (arg === '--status') { parsed.status = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--status=')) { parsed.status = arg.slice('--status='.length); continue; }
+    if (arg === '--coverage') { parsed.coverage.push(scoped.rest[++i]); continue; }
+    if (arg.startsWith('--coverage=')) { parsed.coverage.push(arg.slice('--coverage='.length)); continue; }
+    if (arg === '--evidence-ref') { parsed.evidenceRefs.push(scoped.rest[++i]); continue; }
+    if (arg.startsWith('--evidence-ref=')) { parsed.evidenceRefs.push(arg.slice('--evidence-ref='.length)); continue; }
+    if (arg === '--finding') { parsed.findings.push(scoped.rest[++i]); continue; }
+    if (arg.startsWith('--finding=')) { parsed.findings.push(arg.slice('--finding='.length)); continue; }
+    if (arg === '--next') { parsed.next = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--next=')) { parsed.next = arg.slice('--next='.length); continue; }
+    if (arg === '--finding-id') { parsed.findingId = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--finding-id=')) { parsed.findingId = arg.slice('--finding-id='.length); continue; }
+    if (arg === '--severity') { parsed.severity = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--severity=')) { parsed.severity = arg.slice('--severity='.length); continue; }
+    if (arg === '--confidence') { parsed.confidence = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--confidence=')) { parsed.confidence = arg.slice('--confidence='.length); continue; }
+    if (arg === '--display-tier') { parsed.displayTier = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--display-tier=')) { parsed.displayTier = arg.slice('--display-tier='.length); continue; }
+    if (arg === '--fingerprint') { parsed.fingerprint = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--fingerprint=')) { parsed.fingerprint = arg.slice('--fingerprint='.length); continue; }
+    if (arg === '--scope') { parsed.scope = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--scope=')) { parsed.scope = arg.slice('--scope='.length); continue; }
+    if (arg === '--path') { parsed.path = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--path=')) { parsed.path = arg.slice('--path='.length); continue; }
+    if (arg === '--evidence') { parsed.evidence = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--evidence=')) { parsed.evidence = arg.slice('--evidence='.length); continue; }
+    if (arg === '--recommendation') { parsed.recommendation = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--recommendation=')) { parsed.recommendation = arg.slice('--recommendation='.length); continue; }
+    if (arg === '--route') { parsed.route = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--route=')) { parsed.route = arg.slice('--route='.length); continue; }
+    if (arg === '--blocking-count') { parsed.blockingCount = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--blocking-count=')) { parsed.blockingCount = arg.slice('--blocking-count='.length); continue; }
+    if (arg === '--warning-count') { parsed.warningCount = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--warning-count=')) { parsed.warningCount = arg.slice('--warning-count='.length); continue; }
+    if (arg === '--output') { parsed.output = scoped.rest[++i]; continue; }
+    if (arg.startsWith('--output=')) { parsed.output = arg.slice('--output='.length); continue; }
+  }
+
+  return parsed;
+}
+
+async function runReviewCommand(args) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    console.error('Use: cc-devflow review start --change <changeId> [--change-key <key>] [--cwd <path>]');
+    return 3;
+  }
+
+  const reviewRunners = {
+    start: null,
+    'record-node': 'runReviewRecordNode',
+    'add-finding': 'runReviewAddFinding',
+    close: 'runReviewClose',
+    render: 'runReviewRender'
+  };
+
+  if (subcommand === 'start') {
+    const options = parseReviewStartArgs(rest);
+    if (!options.changeId) {
+      console.error('review start --change is required.');
+      return 3;
+    }
+
+    const { runReviewStart } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/operations/review-records.js'));
+    const result = await runReviewStart({
+      repoRoot: path.resolve(options.cwd || process.cwd()),
+      changeId: options.changeId,
+      changeKey: options.changeKey,
+      mode: options.mode,
+      scope: options.scope,
+      baseSha: options.baseSha,
+      headSha: options.headSha,
+      selectedNodes: options.selectedNodes,
+      skippedNodes: options.skippedNodes,
+      riskLanes: options.riskLanes
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result.code;
+  }
+
+  if (reviewRunners[subcommand]) {
+    const options = parseReviewEventArgs(rest);
+    if (!options.changeId) {
+      console.error(`review ${subcommand} --change is required.`);
+      return 3;
+    }
+
+    const runnerName = reviewRunners[subcommand];
+    const runners = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/operations/review-records.js'));
+    const result = await runners[runnerName]({
+      repoRoot: path.resolve(options.cwd || process.cwd()),
+      changeId: options.changeId,
+      changeKey: options.changeKey,
+      reviewId: options.reviewId,
+      nodeId: options.nodeId,
+      mode: options.mode,
+      target: options.target,
+      status: options.status,
+      coverage: options.coverage,
+      evidenceRefs: options.evidenceRefs,
+      findings: options.findings,
+      next: options.next,
+      findingId: options.findingId,
+      severity: options.severity,
+      confidence: options.confidence,
+      displayTier: options.displayTier,
+      fingerprint: options.fingerprint,
+      scope: options.scope,
+      path: options.path,
+      evidence: options.evidence,
+      recommendation: options.recommendation,
+      route: options.route,
+      blockingCount: options.blockingCount,
+      warningCount: options.warningCount,
+      output: options.output
+    });
+    if (result.code !== 0) {
+      console.error(result.stderr || result.error || `review ${subcommand} failed`);
+      return result.code;
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result.code;
+  }
+
+  console.error(`Unknown review command: ${subcommand}`);
+  return 3;
+}
+
 function runNextChangeKey(args) {
   const parsed = { prefix: null, description: null, cwd: null };
 
@@ -699,6 +948,14 @@ async function main() {
     return runQueryCommand(rest);
   }
 
+  if (command === 'task-contract') {
+    return runTaskContractCommand(rest);
+  }
+
+  if (command === 'review') {
+    return runReviewCommand(rest);
+  }
+
   if (command === 'next-change-key') {
     return runNextChangeKey(rest);
   }

package/docs/examples/START-HERE.md

@@ -67,8 +67,8 @@ Use this when the only thing you know is the file in front of you.
 | `roadmap.json` | `cc-roadmap` editable machine truth source | [pdca-loop/roadmap.json](./pdca-loop/roadmap.json) |
 | `ROADMAP.md` | `cc-roadmap` generated human view | [pdca-loop/ROADMAP.md](./pdca-loop/ROADMAP.md) |
 | `BACKLOG.md` | deprecated `cc-roadmap` -> `cc-plan` projection | [pdca-loop/BACKLOG.md](./pdca-loop/BACKLOG.md) |
-| `design.md` | `cc-plan` | [pdca-loop/design.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md) or [full-design-blocked/design.md](./full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md) |
-| `tasks.md` | `cc-plan` or `cc-do` | [pdca-loop/tasks.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md) |
+| `tasks.md` | `cc-plan`, `cc-investigate`, or `cc-do` | [pdca-loop/tasks.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md) |
+| `design.md` | legacy `cc-plan` fallback | [pdca-loop/design.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md) or [full-design-blocked/design.md](./full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md) |
 | `task-manifest.json` | `cc-do` | [pdca-loop/task-manifest.json](./pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json) |
 | `report-card.json` | `cc-check` | [pdca-loop/report-card.json](./pdca-loop/changes/REQ-001-copy-invite-link/review/report-card.json), [full-design-blocked/report-card.json](./full-design-blocked/changes/REQ-002-bulk-invite-import/review/report-card.json), or [local-handoff/report-card.json](./local-handoff/changes/REQ-003-audit-log-export/review/report-card.json) |
 | `pr-brief.md` | `cc-act` | [pdca-loop/pr-brief.md](./pdca-loop/changes/REQ-001-copy-invite-link/handoff/pr-brief.md) |
@@ -127,7 +127,7 @@ If both are true, you are usually in `cc-act` local handoff territory, not back
 If you only have one minute, open these files in order:
 
 1. example `README.md`
-2. change `planning/design.md`
+2. change `planning/tasks.md`
 3. `report-card.json` or the single final handoff file
 
 That should already tell you:
@@ -140,7 +140,8 @@ That should already tell you:
 
 `devflow/changes/<change>/` should stay lean.
 
-- Durable truth only: `change-state.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file.
+- Durable truth only: `change-meta.json`, `planning/tasks.md`, CLI-generated `task-manifest.json`, review ledger/findings records, optional CLI logs for debug/failure, `report-card.json`, and one final handoff file. Do not generate task `context.md`, `checkpoint.json`, or AI-written process files.
+- Legacy `planning/design.md`, `planning/analysis.md`, and `cc-review-*.md` are readable fallback inputs for older examples, not new default writes.
 - Runtime scratch belongs in `devflow/workspaces/<change>/`, not beside the durable record.
 
 ## If You Still Want The Split Views

package/docs/examples/example-bindings.json

@@ -1,17 +1,17 @@
 {
-  "updatedAt": "2026-05-10",
+  "updatedAt": "2026-05-13",
   "skills": {
-    "cc-roadmap": "5.2.0",
-    "cc-next": "1.0.0",
-    "cc-dev": "1.0.0",
-    "cc-plan": "3.8.2",
-    "cc-investigate": "1.3.0",
-    "cc-do": "1.6.3",
-    "cc-review": "1.3.0",
+    "cc-roadmap": "5.3.0",
+    "cc-next": "1.0.1",
+    "cc-dev": "1.0.1",
+    "cc-plan": "3.9.0",
+    "cc-investigate": "1.5.0",
+    "cc-do": "1.6.7",
+    "cc-review": "2.0.0",
     "cc-pr-review": "1.0.0",
     "cc-pr-land": "1.0.0",
-    "cc-check": "1.10.1",
-    "cc-act": "1.8.3",
+    "cc-check": "1.11.1",
+    "cc-act": "1.8.8",
     "cc-spec-init": "1.1.0"
   },
   "examples": [

package/docs/examples/full-design-blocked/BACKLOG.md

@@ -5,7 +5,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `5.2.0`
+- Skill version: `5.3.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
 - Roadmap state source: `roadmap.json`

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.2.0`, `cc-plan@3.8.2`, `cc-do@1.6.3`, `cc-check@1.10.1`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.9.0`, `cc-do@1.6.7`, `cc-check@1.11.1`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 
@@ -43,8 +43,8 @@ The sample shows what happens when implementation moved before the integration d
 - `roadmap.json` (editable roadmap truth)
 - `ROADMAP.md` (generated view)
 - `BACKLOG.md` (deprecated projection)
-- `changes/REQ-002-bulk-invite-import/planning/design.md`
 - `changes/REQ-002-bulk-invite-import/planning/tasks.md`
+- `changes/REQ-002-bulk-invite-import/planning/design.md` (legacy fallback sample)
 - `changes/REQ-002-bulk-invite-import/planning/task-manifest.json`
 - `changes/REQ-002-bulk-invite-import/review/report-card.json`
 

package/docs/examples/full-design-blocked/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `5.2.0`
+- Skill version: `5.3.0`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md

@@ -4,7 +4,8 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.8.2`
+- CC-Plan skill version: `3.9.0`
+- Work branch: `REQ/002-bulk-invite-import`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`
 - Why not `tiny-design`: the feature crosses import parsing, invite rules, billing limits, duplicate handling, and audit logging