cc-devflow 4.3.0 → 4.5.0

package/.claude/skills/cc-roadmap/scripts/sync-roadmap-progress.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 本地回写器：更新路线图跟踪表中的状态/REQ/进度
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage: sync-roadmap-progress.sh --rm RM-001 [--status Planned] [--req REQ-001] [--progress 50%] [--file devflow/ROADMAP.md]
+       [--item "Add copy action"] [--stage "Stage 1"] [--priority P1] [--depends-on "RM-000"]
+       [--primary-capability cap-example] [--secondary-capabilities "cap-a,cap-b"] [--spec-delta "tighten truth"]
+       [--tracking-file devflow/roadmap-tracking.json] [--backlog-file devflow/BACKLOG.md]
+EOF
+}
+
+RM_ID=""
+ITEM=""
+STAGE=""
+PRIORITY=""
+STATUS=""
+REQ_ID=""
+PROGRESS=""
+DEPENDS_ON=""
+PRIMARY_CAPABILITY=""
+SECONDARY_CAPABILITIES=""
+SPEC_DELTA=""
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+DEFAULT_FILE="$REPO_ROOT/devflow/ROADMAP.md"
+ROOT_FILE="$REPO_ROOT/ROADMAP.md"
+LEGACY_FILE="$REPO_ROOT/devflow/roadmap/roadmap.md"
+FILE="$DEFAULT_FILE"
+TRACKING_FILE=""
+BACKLOG_FILE=""
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --rm) RM_ID="$2"; shift 2 ;;
+    --item) ITEM="$2"; shift 2 ;;
+    --stage) STAGE="$2"; shift 2 ;;
+    --priority) PRIORITY="$2"; shift 2 ;;
+    --status) STATUS="$2"; shift 2 ;;
+    --req) REQ_ID="$2"; shift 2 ;;
+    --progress) PROGRESS="$2"; shift 2 ;;
+    --depends-on) DEPENDS_ON="$2"; shift 2 ;;
+    --primary-capability) PRIMARY_CAPABILITY="$2"; shift 2 ;;
+    --secondary-capabilities) SECONDARY_CAPABILITIES="$2"; shift 2 ;;
+    --spec-delta) SPEC_DELTA="$2"; shift 2 ;;
+    --file) FILE="$2"; shift 2 ;;
+    --tracking-file) TRACKING_FILE="$2"; shift 2 ;;
+    --backlog-file) BACKLOG_FILE="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$FILE" == "$DEFAULT_FILE" && ! -f "$FILE" ]]; then
+  if [[ -f "$ROOT_FILE" ]]; then
+    FILE="$ROOT_FILE"
+  elif [[ -f "$LEGACY_FILE" ]]; then
+    FILE="$LEGACY_FILE"
+  fi
+fi
+
+if [[ -z "$RM_ID" || ! -f "$FILE" ]]; then
+  usage
+  exit 1
+fi
+
+if [[ -z "$TRACKING_FILE" ]]; then
+  TRACKING_FILE="$(cd "$(dirname "$FILE")" && pwd)/roadmap-tracking.json"
+fi
+
+if [[ -z "$BACKLOG_FILE" ]]; then
+  BACKLOG_FILE="$(cd "$(dirname "$FILE")" && pwd)/BACKLOG.md"
+fi
+
+args=(
+  sync
+  --roadmap "$FILE"
+  --backlog "$BACKLOG_FILE"
+  --tracking "$TRACKING_FILE"
+  --rm "$RM_ID"
+)
+
+[[ -n "$ITEM" ]] && args+=(--item "$ITEM")
+[[ -n "$STAGE" ]] && args+=(--stage "$STAGE")
+[[ -n "$PRIORITY" ]] && args+=(--priority "$PRIORITY")
+[[ -n "$STATUS" ]] && args+=(--status "$STATUS")
+[[ -n "$REQ_ID" ]] && args+=(--req "$REQ_ID")
+[[ -n "$PROGRESS" ]] && args+=(--progress "$PROGRESS")
+[[ -n "$DEPENDS_ON" ]] && args+=(--depends-on "$DEPENDS_ON")
+[[ -n "$PRIMARY_CAPABILITY" ]] && args+=(--primary-capability "$PRIMARY_CAPABILITY")
+[[ -n "$SECONDARY_CAPABILITIES" ]] && args+=(--secondary-capabilities "$SECONDARY_CAPABILITIES")
+[[ -n "$SPEC_DELTA" ]] && args+=(--spec-delta "$SPEC_DELTA")
+
+node "$SCRIPT_DIR/roadmap-tracking.js" "${args[@]}"
+echo "Updated $RM_ID in $FILE and $BACKLOG_FILE via $TRACKING_FILE"

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

@@ -0,0 +1,10 @@
+# CC-Simplify Skill Changelog
+
+## v1.1.0 - 2026-04-19
+
+- expand `cc-simplify` review scope to catch spec drift alongside reuse, quality, and efficiency issues
+- require the cleanup pass to flag missing `change-meta.json` or capability spec sync when behavior changes outrun the spec chain
+
+## v1.0.0 - 2026-04-17
+
+- initial distributed `cc-simplify` maintenance skill for pre-ship cleanup

package/.claude/skills/cc-simplify/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: cc-simplify
+version: 1.1.0
+description: Review changed code for reuse, quality, efficiency, and spec drift, then fix any issues found or flag the drift for the user.
+---
+Simplify: Code Review and Cleanup
+
+Review all changed files for reuse, quality, and efficiency. Fix any issues found.
+
+## Phase 1: Identify Changes
+
+Run \`git diff\` (or \`git diff HEAD\` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
+
+## Phase 2: Launch Three Review Agents in Parallel
+
+Use the ${AGENT_TOOL_NAME} tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+
+### Agent 1: Code Reuse Review
+
+For each change:
+
+1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones.
+2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead.
+3. **Flag any inline logic that could use an existing utility** — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.
+
+### Agent 2: Code Quality Review
+
+Review the same changes for hacky patterns:
+
+1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
+2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones
+3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction
+4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
+5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
+6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value — check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior
+7. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)
+8. **Spec drift**: behavior, boundary, or invariant changed but no matching `change-meta.json` / capability spec delta was updated — flag it explicitly and propose the missing spec sync
+
+### Agent 3: Efficiency Review
+
+Review the same changes for efficiency:
+
+1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
+2. **Missed concurrency**: independent operations run sequentially when they could run in parallel
+3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths
+4. **Recurring no-op updates**: state/store updates inside polling loops, intervals, or event handlers that fire unconditionally — add a change-detection guard so downstream consumers aren't notified when nothing changed. Also: if a wrapper function takes an updater/reducer callback, verify it honors same-reference returns (or whatever the "no change" signal is) — otherwise callers' early-return no-ops are silently defeated
+5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
+6. **Memory**: unbounded data structures, missing cleanup, event listener leaks
+7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one
+
+## Phase 3: Fix Issues
+
+Wait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on — do not argue with the finding, just skip it.
+
+When done, briefly summarize what was fixed (or confirm the code was already clean).

package/.claude/skills/cc-spec-init/CHANGELOG.md

@@ -0,0 +1,12 @@
+# CC-Spec-Init Skill Changelog
+
+## v1.0.1 - 2026-04-27
+
+- require capability specs, spec indexes, and change metadata to resolve the runtime output policy before writing durable artifacts
+- record `Output language` as the machine-enforced language contract while treating `agent_preferences` as advisory style input
+
+## v1.0.0 - 2026-04-19
+
+- 初始版 `cc-spec-init`，用于 capability-centered spec 初始化、能力真相源维护和 `change-meta.json` 链路收口。
+- 新增 `INDEX.md`、capability spec、`change-meta.json` 三类模板。
+- 新增 bootstrap 与链接校验脚本，供 `cc-roadmap`、`cc-plan`、`cc-act` 前后复用。

package/.claude/skills/cc-spec-init/PLAYBOOK.md

@@ -0,0 +1,55 @@
+# CC-Spec-Init Playbook
+
+## Core Rules
+
+1. 先定 capability 边界，再写 spec 文本。
+2. `spec` 记录现状，`roadmap` 记录未来，`change-meta` 记录桥接。
+3. 同一个 change 可以多挂 capability，但只能有一个 primary capability。
+4. 正常演化优先 `deprecated` / `merged` / `split`，不要直接物理删除。
+5. 每次变更结束都跑链接校验，别把断链留到下轮执行。
+
+## Standard Modes
+
+### Bootstrap
+
+- 建 `devflow/specs/INDEX.md`
+- 建 `devflow/specs/capabilities/`
+- 为当前最重要的 capability 建最小 truth source
+
+### Create
+
+- 新 capability spec
+- 回写 `INDEX.md`
+- 为当前 change 生成 `change-meta.json`
+
+### Update Links
+
+- 修 roadmap / backlog / change / spec 的 capability 引用
+- 重建 `INDEX.md`
+
+### Split / Merge / Deprecate
+
+- 在原 capability spec 标明状态变化
+- 补 `splitInto` / `mergedInto` / `supersededBy`
+- 确认历史 change 仍然可追踪
+
+## Command Kit
+
+```bash
+# 初始化 specs 目录
+bash .claude/skills/cc-spec-init/scripts/bootstrap-specs.sh
+
+# 校验 spec 链路
+bash .claude/skills/cc-spec-init/scripts/validate-spec-links.sh
+
+# 看哪些 change 已缺 change-meta
+find devflow/changes -maxdepth 2 -name change-meta.json | sort
+```
+
+## Review Questions
+
+1. capability 的边界是否清楚到 AI 不会把别的系统能力写进来？
+2. `Current Truth` 是否只写当前成立的承诺？
+3. `Missing` 和 `Intentional Gaps` 是否被保留下来？
+4. roadmap item 和 change 是否都能指向 capability？
+5. 这次是该 `update`，还是其实应该 `split` / `merge`？

package/.claude/skills/cc-spec-init/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: cc-spec-init
+version: 1.0.1
+description: Use when you need to initialize capability specs under `devflow/specs/`, create or evolve capability truth sources, generate `change-meta.json`, or validate roadmap/change/spec links before roadmap, planning, or closeout work continues.
+---
+
+# CC-Spec-Init
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、相关模板/脚本引用，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-spec-init` 是 capability-centered spec 的收口器。
+
+它只做一件事：把系统“当前承诺什么”收成稳定 truth source，并把 `roadmap -> change -> spec` 的链接补齐。
+
+它不是主 workflow 的一环。
+
+主 workflow 仍然是：
+
+- `cc-roadmap`
+- `cc-plan` 或 `cc-investigate`
+- `cc-do`
+- `cc-check`
+- `cc-act`
+
+`cc-spec-init` 负责这些动作：
+
+- 初始化 `devflow/specs/`
+- 新建 capability spec
+- 对 capability 做 `split` / `merge` / `deprecate`
+- 生成或修复 `devflow/changes/<change-key>/change-meta.json`
+- 重建 `devflow/specs/INDEX.md`
+- 校验 capability、roadmap item、change 之间的链接完整性
+
+## Runtime Output Policy
+
+写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
+
+- `Output language` 是机器约束，capability spec、`devflow/specs/INDEX.md` 和 `change-meta.json` 必须记录并遵守它。
+- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
+- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
+
+## Read First
+
+1. `PLAYBOOK.md`
+2. `CHANGELOG.md`
+3. `references/spec-contract.md`
+4. `assets/INDEX_TEMPLATE.md`
+5. `assets/CAPABILITY_TEMPLATE.md`
+6. `assets/CHANGE_META_TEMPLATE.json`
+
+## Use This Skill When
+
+- 你第一次把仓库升级到 capability-centered spec 模型
+- 需要创建新 capability spec
+- 需要把 change 绑定到 primary / secondary capability
+- 需要做 capability 的 `split` / `merge` / `deprecate`
+- `cc-roadmap`、`cc-plan`、`cc-act` 发现 spec 链路断了
+- 需要在 closeout 前确认 spec/roadmap/change 仍然同构
+
+如果当前工作只是执行一个已冻结任务，不要停在这里，回主 workflow。
+
+## Entry Gate
+
+1. 先读现有 `devflow/specs/INDEX.md`、相关 capability spec、相关 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`、相关 `change-meta.json`。
+2. 先判断你是在做 `bootstrap`、`create`、`update-links`、`split`、`merge` 还是 `deprecate`。
+3. 先锁定 capability 边界，再写模板；不要先写 prose 再猜结构。
+4. 先明确 primary capability，再允许 secondary capabilities 存在。
+
+## Session Protocol
+
+1. 先判断现状：
+   - `devflow/specs/` 是否已存在
+   - capability 是否已存在
+   - 相关 change 是否已有 `change-meta.json`
+2. 如果是首次初始化：
+   - 创建 `devflow/specs/INDEX.md`
+   - 创建 `devflow/specs/capabilities/`
+   - 为当前已知 capability 写最小 spec
+3. 如果是新 capability：
+   - 先写 capability 边界、约束、当前 truth、gaps
+   - 再登记到 `INDEX.md`
+4. 如果是 change 绑定：
+   - 生成或更新 `change-meta.json`
+   - 填入 `primaryCapability`、`secondaryCapabilities`、`expectedDelta`、`affectedInvariants`、`gapsClosed`、`newGaps`
+5. 如果是 capability 结构调整：
+   - 优先 `deprecated` / `mergedInto` / `splitInto`
+   - 不要直接物理删除，除非确认没有 roadmap/change 仍在引用
+6. 结束前运行链接校验，确认：
+   - `INDEX.md` 引到的 capability 文件都存在
+   - `change-meta.json` 里的 capability 都能落到 spec
+   - roadmap / backlog 里的 capability 引用仍可追踪
+
+## Output
+
+- `devflow/specs/INDEX.md`
+- `devflow/specs/capabilities/<capability>.md`
+- `devflow/changes/<change-key>/change-meta.json`
+- 链接校验结果
+
+## Working Rules
+
+1. `spec` 写现状，不写一次性推导过程。
+2. `roadmap` 写未来推进，不写当前 truth。
+3. `change-meta.json` 是机器真相源；capability markdown 是人机共读的长期约束源。
+4. 一个 change 可以挂多个 capability，但必须有一个 `primaryCapability`。
+5. capability 不直接硬删除；优先用状态表达历史连续性。
+6. `INDEX.md` 只做目录和状态总览，不复制各 spec 正文。
+
+## Bundled Resources
+
+- 变更记录：`CHANGELOG.md`
+- 使用剧本：`PLAYBOOK.md`
+- 契约：`references/spec-contract.md`
+- 模板：`assets/INDEX_TEMPLATE.md`
+- 模板：`assets/CAPABILITY_TEMPLATE.md`
+- 模板：`assets/CHANGE_META_TEMPLATE.json`
+- 初始化：`scripts/bootstrap-specs.sh`
+- 校验：`scripts/validate-spec-links.sh`
+
+## Exit Criteria
+
+- `devflow/specs/` 已建立或已修复
+- 相关 capability spec 有明确边界、约束、truth、gaps
+- 相关 change 已有 `change-meta.json`
+- `INDEX.md`、roadmap、change、spec 之间的链接可追踪
+- 下一步可以安心回到 `cc-roadmap`、`cc-plan` 或 `cc-act`
+
+## Do Not
+
+- 不把 roadmap 写回 spec
+- 不把执行细节写成 capability truth
+- 不允许没有 primary capability 的多 capability change
+- 不直接删 capability 文件导致链路断裂

package/.claude/skills/cc-spec-init/assets/CAPABILITY_TEMPLATE.md

@@ -0,0 +1,64 @@
+---
+id: cap-example
+title: Example Capability
+type: user-visible
+status: partial
+primary_owner: ""
+output_language: ""
+last_verified_at: 2026-04-19
+roadmap_links:
+  - RM-001
+related_changes:
+  - REQ-001-example
+superseded_by: []
+split_into: []
+merged_into: ""
+---
+
+# Purpose
+
+一句话说明这个 capability 为谁解决什么问题。
+
+# Boundary
+
+In:
+- 属于这个 capability 的行为
+
+Out:
+- 明确不属于这个 capability 的行为
+
+# Invariants
+
+- 后续 change 不能破坏的约束
+- AI 改代码前必须先满足这些约束
+
+# Current Truth
+
+- 当前已成立的用户可见行为
+- 当前已成立的系统承诺
+- 当前异常与失败边界
+
+# Completion
+
+Delivered:
+- 已完成部分
+
+Missing:
+- 尚未完成但预期要做的部分
+
+Intentional Gaps:
+- 有意不做、暂时不做的部分
+
+# Roadmap Links
+
+- RM-001: 未来推进什么
+
+# Change Ledger
+
+- REQ-001-example: 这次 change 对 capability 做了什么
+
+# Evidence
+
+- Code:
+- Tests:
+- Docs:

package/.claude/skills/cc-spec-init/assets/CHANGE_META_TEMPLATE.json

@@ -0,0 +1,28 @@
+{
+  "changeId": "REQ-001",
+  "requirementId": "REQ-001",
+  "outputPolicy": {
+    "documentLanguage": ""
+  },
+  "sourceRoadmap": {
+    "itemId": "RM-001",
+    "roadmapVersion": "roadmap.v1",
+    "roadmapSkillVersion": "4.1.0"
+  },
+  "spec": {
+    "primaryCapability": "cap-example",
+    "secondaryCapabilities": [],
+    "changeType": "update",
+    "specFiles": [
+      "devflow/specs/capabilities/cap-example.md"
+    ],
+    "expectedDelta": [
+      "Describe the new truth the change should add or tighten"
+    ],
+    "affectedInvariants": [],
+    "gapsClosed": [],
+    "newGaps": [],
+    "syncStatus": "planned",
+    "notes": []
+  }
+}

package/.claude/skills/cc-spec-init/assets/INDEX_TEMPLATE.md

@@ -0,0 +1,35 @@
+# Capability Index
+
+## Index Meta
+
+- Spec system version: `spec.v1`
+- Output language:
+- Last updated:
+- Maintainer:
+- Notes:
+
+## Capability Map
+
+| Capability ID | Title | Type | Status | Primary Owner | Roadmap Links | Open Gaps | Last Verified |
+|---------------|-------|------|--------|---------------|---------------|-----------|---------------|
+| cap-example | Example Capability | user-visible | partial | team | RM-001 | 2 | 2026-04-19 |
+
+## Active Change Links
+
+| Change | Primary Capability | Secondary Capabilities | Expected Delta | Sync Status |
+|--------|--------------------|------------------------|----------------|-------------|
+| REQ-001-example | cap-example | - | Add copy action | planned |
+
+## Status Legend
+
+- `proposed`: capability exists as a planned truth source but current truth is not yet verified
+- `partial`: some truth is delivered, gaps remain
+- `stable`: current truth is verified and considered reliable
+- `deprecated`: do not build net-new work here; follow `Superseded By`
+
+## Index Review
+
+- Missing capability files:
+- Dangling roadmap links:
+- Dangling change links:
+- Next cleanup:

package/.claude/skills/cc-spec-init/references/spec-contract.md

@@ -0,0 +1,22 @@
+# Spec Contract
+
+## Truth Layers
+
+- `devflow/ROADMAP.md` / `devflow/BACKLOG.md`: 未来推进什么 capability
+- `devflow/specs/INDEX.md`: capability 总目录与当前状态快照
+- `devflow/specs/capabilities/*.md`: 某个 capability 当前承诺什么
+- `devflow/changes/<change>/change-meta.json`: 某次 change 如何影响 capability
+
+## Capability Rules
+
+1. 以用户可感知能力为主，内部系统能力为辅。
+2. `Boundary`、`Invariants`、`Current Truth` 是核心，不要被 narrative 淹没。
+3. `Missing` 与 `Intentional Gaps` 必须长期保留。
+4. capability 名称要稳定、可重用，不要按一次需求命名。
+
+## Change Meta Rules
+
+1. `primaryCapability` 必填。
+2. `secondaryCapabilities` 可空，但必须有明确原因。
+3. `changeType` 只使用：`create`、`update`、`split`、`merge`、`deprecate`。
+4. `syncStatus` 生命周期：`planned -> verified -> synced`。

package/.claude/skills/cc-spec-init/scripts/bootstrap-specs.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 初始化 capability-centered spec 目录骨架
+# ------------------------------------------------------------
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+BASE="$ROOT/devflow/specs"
+CAP_DIR="$BASE/capabilities"
+SKILL_DIR="$ROOT/.claude/skills/cc-spec-init"
+
+mkdir -p "$CAP_DIR"
+
+copy_if_missing() {
+  local src="$1"
+  local dest="$2"
+
+  if [[ ! -f "$dest" ]]; then
+    cp "$src" "$dest"
+    echo "Created ${dest#$ROOT/}"
+  else
+    echo "Kept ${dest#$ROOT/}"
+  fi
+}
+
+copy_if_missing "$SKILL_DIR/assets/INDEX_TEMPLATE.md" "$BASE/INDEX.md"
+copy_if_missing "$SKILL_DIR/assets/CAPABILITY_TEMPLATE.md" "$CAP_DIR/cap-example.md"
+
+echo "Spec bootstrap complete"

package/.claude/skills/cc-spec-init/scripts/validate-spec-links.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 校验 spec / roadmap / change 链路是否断裂
+# ------------------------------------------------------------
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+INDEX_FILE="$ROOT/devflow/specs/INDEX.md"
+CAP_DIR="$ROOT/devflow/specs/capabilities"
+FAILED=0
+
+if [[ ! -f "$INDEX_FILE" ]]; then
+  echo "Missing devflow/specs/INDEX.md" >&2
+  exit 1
+fi
+
+if [[ ! -d "$CAP_DIR" ]]; then
+  echo "Missing devflow/specs/capabilities/" >&2
+  exit 1
+fi
+
+while IFS= read -r capability; do
+  [[ -z "$capability" ]] && continue
+  if [[ ! -f "$CAP_DIR/$capability.md" ]]; then
+    echo "Dangling capability in INDEX.md: $capability" >&2
+    FAILED=1
+  fi
+done < <(awk -F'|' '/^\|/ {id=$2; gsub(/^[[:space:]]+|[[:space:]]+$/, "", id); if (id != "" && id != "Capability ID" && id !~ /^-+$/) print id}' "$INDEX_FILE")
+
+while IFS= read -r meta; do
+  primary="$(jq -r '.spec.primaryCapability // empty' "$meta" 2>/dev/null || true)"
+  [[ -z "$primary" ]] && continue
+  if [[ ! -f "$CAP_DIR/$primary.md" ]]; then
+    echo "Dangling primary capability in ${meta#$ROOT/}: $primary" >&2
+    FAILED=1
+  fi
+done < <(find "$ROOT/devflow/changes" -maxdepth 2 -name change-meta.json -type f 2>/dev/null | sort)
+
+if [[ "$FAILED" -ne 0 ]]; then
+  exit 1
+fi
+
+echo "Spec links are valid"