@walwal-harness/cli 5.9.5 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.9.5",
-  "description": "Production harness for AI agent engineering — Solo/Team mode, Planner, Generator(BE/FE), Evaluator chain (Code-Quality → Functional → Visual), optional Brainstormer. Supports React, Next.js, and Flutter FE stacks.",
+  "version": "6.0.0",
+  "description": "Production harness for AI agent engineering — NEXUS-adapted company metaphor (Dispatcher/CEO + Conductor + Meeting-Manager + COO/Planner + CTO + CQO + Service-Ops). Solo/Team mode, Brainstormer, Planner, Generator(BE/FE/Designer/DevOps), Evaluator chain (Code-Quality → Functional → Visual + Architecture/Security). Supports React, Next.js, and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"
   },
@@ -24,6 +24,13 @@
     "planner",
     "generator",
     "evaluator",
+    "nexus",
+    "ceo",
+    "cto",
+    "cqo",
+    "conductor",
+    "meeting-manager",
+    "service-ops",
     "nestjs",
     "react",
     "flutter",
@@ -45,6 +52,7 @@
     "scripts/",
     "commands/",
     "assets/",
-    "gotchas/"
+    "gotchas/",
+    "CHANGELOG.md"
   ]
 }

package/scripts/harness-dashboard-up.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# walwal-harness — Brick Office dashboard launcher
+#
+# 처음 쓰는 사용자도 한 줄로 대시보드를 띄워볼 수 있게 만든 helper.
+# walwal-harness CLI 패키지에는 R3F + Next.js 무게 때문에 dashboard 가 미포함이고,
+# 본 스크립트가 git sparse-checkout 으로 apps/harness-dashboard/ 만 가져와서
+# 사용자 프로젝트 외부 (~/.walwal-harness/dashboard) 에 격리 설치 후 dev 실행한다.
+#
+# Usage:
+#   bash scripts/harness-dashboard-up.sh                 # install + dev (port 3001)
+#   bash scripts/harness-dashboard-up.sh --port 3050     # override port
+#   HARNESS_ROOT=/path/to/project bash ...               # explicit harness root
+set -euo pipefail
+
+REPO_URL="${WALWAL_HARNESS_REPO:-https://github.com/30eggis/walwal-harness.git}"
+DASHBOARD_PATH="apps/harness-dashboard"
+LOCAL_DIR="${HOME}/.walwal-harness/dashboard"
+PORT="${PORT:-3001}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port) PORT="$2"; shift 2 ;;
+    --reinstall) rm -rf "$LOCAL_DIR"; shift ;;
+    --help|-h)
+      sed -n '2,16p' "$0"
+      exit 0 ;;
+    *) echo "[brick-office] unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [[ -z "${HARNESS_ROOT:-}" ]]; then
+  HARNESS_ROOT="$(pwd)"
+fi
+if [[ ! -d "${HARNESS_ROOT}/.harness" ]]; then
+  echo "[brick-office] FAIL: ${HARNESS_ROOT} 에 .harness/ 가 없습니다."
+  echo "                먼저 'npx walwal-harness' 로 초기화하세요."
+  exit 3
+fi
+
+echo "[brick-office] HARNESS_ROOT = ${HARNESS_ROOT}"
+echo "[brick-office] dashboard 격리 경로 = ${LOCAL_DIR}"
+
+if [[ ! -d "${LOCAL_DIR}/${DASHBOARD_PATH}" ]]; then
+  echo "[brick-office] 첫 실행 — git sparse-checkout 으로 dashboard 만 가져옵니다 (~5MB)."
+  mkdir -p "${LOCAL_DIR}"
+  cd "${LOCAL_DIR}"
+  git init -q
+  git remote add origin "${REPO_URL}" 2>/dev/null || true
+  git config core.sparseCheckout true
+  echo "${DASHBOARD_PATH}/" > .git/info/sparse-checkout
+  git fetch --depth=1 origin main -q
+  git checkout main -q
+  echo "[brick-office] 다운로드 완료."
+fi
+
+cd "${LOCAL_DIR}/${DASHBOARD_PATH}"
+
+if [[ ! -d node_modules ]]; then
+  echo "[brick-office] npm install (한 번만 실행, ~30s)..."
+  npm install --no-audit --no-fund --loglevel=error
+fi
+
+echo ""
+echo "╔══════════════════════════════════════════════════════════╗"
+echo "║  Brick Office — http://localhost:${PORT}"
+echo "║                                                          ║"
+echo "║  HARNESS_ROOT 이 가리키는 프로젝트의 .harness/ 상태를     ║"
+echo "║  실시간 (SSE) 시각화합니다. Ctrl+C 로 종료.              ║"
+echo "╚══════════════════════════════════════════════════════════╝"
+echo ""
+
+HARNESS_ROOT="${HARNESS_ROOT}" npm run dev:dashboard -- -p "${PORT}"

package/scripts/harness-dashboard.sh

@@ -236,14 +236,23 @@ render_team_queue_summary() {
   failed=$(jq '.queue.failed | length' "$QUEUE" 2>/dev/null || echo 0)
 
   # passed 는 queue.passed ∪ feature-list.json 의 self-passed 를 dedup 합집합으로 계산
-  # (과거 sprint 에서 PASS 되어 queue 에서 빠진 feature 도 카운트)
+  # total 도 feature-list IDs ∪ queue 전체 IDs 합집합으로 계산 — 새 sprint feature 가
+  # queue 에만 추가되고 feature-list 에 누락되어도 누락 없이 카운트 (예: F-800+ Sprint 8)
   if [ -f "$FEATURES" ]; then
     passed=$(jq -r --slurpfile q "$QUEUE" '
       ($q[0].queue.passed // []) as $qp |
       ([.features[] | select((.passes // []) | any(. == "evaluator-functional" or . == "evaluator-visual" or . == "evaluator-code-quality")) | .id]) as $sp |
       ($qp + $sp | unique | length)
     ' "$FEATURES" 2>/dev/null || echo 0)
-    total=$(jq '.features | length' "$FEATURES" 2>/dev/null || echo 0)
+    total=$(jq -r --slurpfile q "$QUEUE" '
+      ([.features[].id]) as $fl |
+      (($q[0].queue.ready // []) +
+       ($q[0].queue.passed // []) +
+       (($q[0].queue.failed // []) | if type == "object" then keys else . end) +
+       (($q[0].queue.in_progress // {}) | keys) +
+       (($q[0].queue.blocked // {}) | keys)) as $qids |
+      ($fl + $qids | unique | length)
+    ' "$FEATURES" 2>/dev/null || echo 0)
   else
     passed=$(jq '.queue.passed | length' "$QUEUE" 2>/dev/null || echo 0)
     total=$((ready + blocked + in_prog + passed + failed))
@@ -260,6 +269,24 @@ render_team_queue_summary() {
   for ((i=0; i<empty; i++)); do bar+="░"; done
 
   echo -e "  ${bar} ${passed}/${total} (${pct}%)  R:${GREEN}${ready}${RESET} B:${YELLOW}${blocked}${RESET} P:${CYAN}${in_prog}${RESET} ${GREEN}✓${passed}${RESET} ${RED}✗${failed}${RESET}"
+
+  # Integrity warn — 큐에 있지만 feature-list 에 없는 orphan feature 가 있으면 경고.
+  # 발생 원인: Lead 가 jq 로 큐 직접 편집 (canonical path = enqueue 명령 사용).
+  if [ -f "$FEATURES" ]; then
+    local orphan_count
+    orphan_count=$(jq -r --slurpfile q "$QUEUE" '
+      ([.features[].id]) as $fl |
+      (($q[0].queue.ready // []) +
+       ($q[0].queue.passed // []) +
+       (($q[0].queue.failed // []) | if type == "object" then keys else . end) +
+       (($q[0].queue.in_progress // {}) | keys) +
+       (($q[0].queue.blocked // {}) | keys)) as $qids |
+      ($qids - $fl) | unique | length
+    ' "$FEATURES" 2>/dev/null || echo 0)
+    if [ "${orphan_count:-0}" -gt 0 ]; then
+      echo -e "  ${YELLOW}⚠ ${orphan_count} feature(s) in queue but not in feature-list.json${RESET} ${DIM}(use: queue-manager enqueue)${RESET}"
+    fi
+  fi
 }
 
 render_team_status() {
@@ -313,19 +340,23 @@ render_team_features() {
   echo ""
   echo -e "${BOLD}Features${RESET}"
 
+  # feature-list IDs ∪ queue 전체 IDs 합집합을 iterate.
+  # feature-list 에 등록 안 된 queue-only feature 는 name="(queue)" 로 표시.
   jq -r --slurpfile q "$QUEUE" '
     ($q[0].queue.passed // []) as $passed |
-    ($q[0].queue.failed // []) as $failed |
+    ($q[0].queue.failed // []) as $failed_raw |
+    (if ($failed_raw | type) == "object" then ($failed_raw | keys) else $failed_raw end) as $failed |
     ($q[0].queue.ready // []) as $ready |
     ($q[0].queue.in_progress // {}) as $prog |
     ($q[0].queue.blocked // {}) as $blocked |
-    .features[] |
-    .id as $fid |
-    (.name // .title // .description // "?" | if length > 18 then .[0:16] + ".." else . end) as $fname |
-    # passed 판정: queue.passed 또는 feature.passes 에 evaluator-functional/visual/code-quality 가 있으면 PASS.
-    # 과거 sprint 에서 PASS 된 feature 가 새 sprint queue 재생성 시 queue.passed 에서 누락되어도
-    # feature-list.json 의 passes 배열은 이력으로 남아있으므로, 거기서도 검사한다.
-    ((.passes // []) | any(. == "evaluator-functional" or . == "evaluator-visual" or . == "evaluator-code-quality")) as $self_passed |
+    ([.features[] | {id: .id, name: (.name // .title // .description // "?"), passes: (.passes // [])}]) as $fl |
+    ([$fl[] | {(.id): .}] | add // {}) as $fl_map |
+    (([$fl[].id]) + $ready + $passed + $failed + ($prog | keys) + ($blocked | keys) | unique) as $all_ids |
+    $all_ids[] |
+    . as $fid |
+    ($fl_map[$fid] // {name: "(queue)", passes: []}) as $f |
+    ($f.name | if length > 18 then .[0:16] + ".." else . end) as $fname |
+    (($f.passes // []) | any(. == "evaluator-functional" or . == "evaluator-visual" or . == "evaluator-code-quality")) as $self_passed |
     (if ($fid | IN($passed[])) or $self_passed then "P"
      elif $prog[$fid] then "I|\($prog[$fid].team)|\($prog[$fid].phase)"
      elif ($fid | IN($failed[])) then "F"

package/scripts/harness-goal-init.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# harness-goal-init.sh — 새 GOAL 발급 (CEO=Dispatcher 전용)
+# 사용법: bash scripts/harness-goal-init.sh "<title>"
+#
+# 동작:
+#   1. .harness/actions/goals.md 가 없으면 template로 생성
+#   2. 다음 GOAL ID(G-N) 발급 → progress.json.goals.list 에 등록
+#   3. progress.json.goals.active_id 갱신
+#   4. CTO 협의 미완료 상태(cto_feasibility=null, owner_confirmed=false)
+#
+# 후속:
+#   - CTO는 cto_feasibility 의견을 협의 후 같은 항목에 채워줌
+#   - Owner 최종 확인 시 dispatcher 가 owner_confirmed=true 로 갱신
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+GOAL_FILE="$ROOT/.harness/actions/goals.md"
+TEMPLATE="$ROOT/.harness/actions/goals.md.template"
+PROGRESS="$ROOT/.harness/progress.json"
+
+TITLE="${1:-}"
+if [ -z "$TITLE" ]; then
+  echo "usage: $0 \"<title>\"" >&2
+  exit 1
+fi
+
+mkdir -p "$ROOT/.harness/actions"
+
+# 1. 파일이 없으면 template 복사 후 ISO 시각 채움
+if [ ! -f "$GOAL_FILE" ]; then
+  if [ ! -f "$TEMPLATE" ]; then
+    echo "template missing: $TEMPLATE" >&2; exit 1
+  fi
+  ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  sed "s|<ISO>|$ISO|g" "$TEMPLATE" > "$GOAL_FILE"
+fi
+
+# 2. 다음 GOAL ID 계산
+LAST_N=$(jq -r '.goals.list | map(.id // "G-0") | map(sub("G-"; "")) | map(tonumber? // 0) | max // 0' "$PROGRESS" 2>/dev/null || echo 0)
+NEXT_N=$((LAST_N + 1))
+GOAL_ID="G-${NEXT_N}"
+ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# 3. progress.json 에 등록 (partial update)
+jq --arg id "$GOAL_ID" --arg title "$TITLE" --arg iso "$ISO" '
+  .goals.list += [{
+    "id": $id,
+    "title": $title,
+    "status": "draft",
+    "owner_confirmed": false,
+    "cto_feasibility": null,
+    "created_at": $iso
+  }] |
+  .goals.active_id = $id |
+  .updated_at = $iso
+' "$PROGRESS" > "$PROGRESS.tmp" && mv "$PROGRESS.tmp" "$PROGRESS"
+
+# 4. goals.md 에 GOAL 섹션 append (CEO가 이후 본문 채움)
+cat >> "$GOAL_FILE" <<EOF
+
+## $GOAL_ID — $TITLE
+status: draft
+owner_confirmed: false
+cto_feasibility: null
+created_at: $ISO
+
+(CEO가 success_metrics·deadline·kpis·runbook 채움)
+EOF
+
+echo "$GOAL_ID 발급 완료: $TITLE"
+echo "→ $GOAL_FILE 에서 본문 작성"
+echo "→ CTO 협의 후 owner 확정 시 owner_confirmed=true"

package/scripts/harness-goal-show.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# harness-goal-show.sh — 현재 active GOAL + 적합도 요약 출력
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PROGRESS="$ROOT/.harness/progress.json"
+GOAL_FILE="$ROOT/.harness/actions/goals.md"
+
+if [ ! -f "$PROGRESS" ]; then
+  echo "progress.json 없음. bash init.sh 먼저 실행." >&2; exit 1
+fi
+
+ACTIVE_ID=$(jq -r '.goals.active_id // ""' "$PROGRESS")
+ADHERENCE=$(jq -r '.goals.current_adherence // "n/a"' "$PROGRESS")
+
+if [ -z "$ACTIVE_ID" ]; then
+  echo "Active GOAL 없음. CEO(Dispatcher)가 첫 발화에서 발급."
+  echo "  bash scripts/harness-goal-init.sh \"<title>\""
+  exit 0
+fi
+
+echo "Active GOAL: $ACTIVE_ID"
+echo "Adherence:   $ADHERENCE"
+echo ""
+
+# progress.json 의 GOAL 메타 출력
+jq -r --arg id "$ACTIVE_ID" '
+  .goals.list[] | select(.id == $id) |
+  "title:           \(.title)",
+  "status:          \(.status)",
+  "owner_confirmed: \(.owner_confirmed)",
+  "cto_feasibility: \(.cto_feasibility // "pending")",
+  "created_at:      \(.created_at // "?")"
+' "$PROGRESS"
+
+echo ""
+echo "본문: $GOAL_FILE 에서 ## $ACTIVE_ID 섹션 참조"

package/scripts/harness-next.sh

@@ -415,25 +415,24 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
   # ── Collect artifacts ──
   FEATURE_LIST="$PROJECT_ROOT/.harness/actions/feature-list.json"
 
-  local -a artifacts_ready=()
+  artifacts_ready=()
   for f in plan.md feature-list.json api-contract.json sprint-contract.md evaluation-functional.md evaluation-visual.md; do
     if [ -f "$PROJECT_ROOT/.harness/actions/$f" ]; then
       artifacts_ready+=("$f")
     fi
   done
-  local artifacts_json
   artifacts_json=$(printf '%s\n' "${artifacts_ready[@]}" | jq -R . | jq -s .)
 
   # Collect focus features (incomplete ones)
-  local focus_features="[]"
+  focus_features="[]"
   if [ -f "$FEATURE_LIST" ]; then
     focus_features=$(jq '[.features[]? | select(.passes == null or (.passes | length) == 0 or ((.passes // []) | map(select(. == "evaluator-functional")) | length == 0)) | .id] | .[0:5]' "$FEATURE_LIST" 2>/dev/null || echo "[]")
   fi
 
   # ── Regression data ──
-  local regression_source="null"
-  local prev_sprint=$((sprint_num - 1))
-  local prev_archive="$PROJECT_ROOT/.harness/archive/sprint-$(printf '%03d' $prev_sprint)"
+  regression_source="null"
+  prev_sprint=$((sprint_num - 1))
+  prev_archive="$PROJECT_ROOT/.harness/archive/sprint-$(printf '%03d' $prev_sprint)"
   if [ "$prev_sprint" -ge 1 ] && [ -d "$prev_archive" ]; then
     if [ -f "$prev_archive/feature-list.json" ]; then
       regression_source=$(jq '{
@@ -445,8 +444,8 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
   fi
 
   # ── Eval-specific config ──
-  local eval_config="null"
-  local cross_validation_data="null"
+  eval_config="null"
+  cross_validation_data="null"
   case "$next_agent" in
     evaluator-*)
       eval_config=$(jq '{
@@ -462,15 +461,15 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
   esac
 
   # ── Cross-Validation (chain: code-quality → functional → visual) ──
-  local cross_validation_from_code_quality="null"
+  cross_validation_from_code_quality="null"
   if [ "$next_agent" = "evaluator-functional" ] || [ "$next_agent" = "evaluator-visual" ]; then
-    local cq_eval="$PROJECT_ROOT/.harness/actions/evaluation-code-quality.md"
+    cq_eval="$PROJECT_ROOT/.harness/actions/evaluation-code-quality.md"
     if [ -f "$cq_eval" ]; then
       cross_validation_from_code_quality=$(sed -n '/```json/,/```/p' "$cq_eval" | tail -n +2 | head -n -1 | jq 'select(.evaluator == "code-quality" or .cross_validation_from_code_quality)' 2>/dev/null || echo "null")
     fi
   fi
   if [ "$next_agent" = "evaluator-visual" ]; then
-    local func_eval="$PROJECT_ROOT/.harness/actions/evaluation-functional.md"
+    func_eval="$PROJECT_ROOT/.harness/actions/evaluation-functional.md"
     if [ -f "$func_eval" ]; then
       cross_validation_data=$(sed -n '/```json/,/```/p' "$func_eval" | tail -n +2 | head -n -1 | jq 'select(.evaluator == "functional")' 2>/dev/null || echo "null")
     fi

package/scripts/harness-queue-manager.sh

@@ -541,6 +541,126 @@ cmd_resume_probe() {
   exit 1
 }
 
+# ══════════════════════════════════════════
+# enqueue — Append feature to feature-list.json AND insert into queue (canonical path).
+#
+# Lead 가 ad-hoc 핫픽스 / 새 sprint feature 를 추가할 때 jq 로 큐를 직접 편집하면
+# feature-list.json 과 큐가 갈라진다 (실제 사고: F-716, F-800~F-806 이 큐에만 등록).
+# 이 명령은 feature-list append → queue insert (deps 미해소면 blocked) 를 한 트랜잭션으로 처리.
+#
+# Usage: enqueue <feature-json-file>   # 파일 경로
+#        enqueue -                     # stdin 으로 JSON
+#
+# 입력 JSON 최소 필드: {id, title, sprint, depends_on?, layer?, service?, acceptance_criteria?}
+# ══════════════════════════════════════════
+cmd_enqueue() {
+  local input="${1:-}"
+  if [ -z "$input" ]; then
+    echo "[queue] enqueue: feature JSON 파일 경로 또는 '-' (stdin) 필요" >&2
+    exit 1
+  fi
+  if [ ! -f "$FEATURES" ]; then echo "[queue] feature-list.json not found." >&2; exit 1; fi
+  if [ ! -f "$QUEUE" ]; then echo "[queue] feature-queue.json not found. init 먼저." >&2; exit 1; fi
+
+  local feat_json
+  if [ "$input" = "-" ]; then
+    feat_json=$(cat)
+  else
+    feat_json=$(cat "$input")
+  fi
+
+  if ! echo "$feat_json" | jq -e '.id and .title and .sprint' >/dev/null 2>&1; then
+    echo "[queue] enqueue: id/title/sprint 필수 필드 누락" >&2
+    exit 1
+  fi
+
+  local fid
+  fid=$(echo "$feat_json" | jq -r '.id')
+
+  acquire_queue_lock
+
+  if jq -e --arg id "$fid" '.features[] | select(.id == $id)' "$FEATURES" >/dev/null 2>&1; then
+    release_queue_lock
+    echo "[queue] enqueue: $fid 이 feature-list.json 에 이미 존재" >&2
+    exit 1
+  fi
+
+  if jq -e --arg id "$fid" '
+    ($id | IN(.queue.ready[]?,.queue.passed[]?)) or
+    (.queue.in_progress[$id]?) or (.queue.blocked[$id]?) or
+    (.queue.failed[$id]? // (.queue.failed | type == "array" and ($id | IN(.queue.failed[]?))))
+  ' "$QUEUE" >/dev/null 2>&1; then
+    release_queue_lock
+    echo "[queue] enqueue: $fid 이 큐에 이미 존재" >&2
+    exit 1
+  fi
+
+  local tmp_features="${FEATURES}.tmp.$$"
+  if ! jq --argjson new "$feat_json" '.features += [$new]' "$FEATURES" > "$tmp_features" 2>/dev/null; then
+    rm -f "$tmp_features"; release_queue_lock
+    echo "[queue] enqueue: feature-list.json 업데이트 실패" >&2; exit 1
+  fi
+  mv "$tmp_features" "$FEATURES"
+
+  local deps unmet
+  deps=$(echo "$feat_json" | jq -c '.depends_on // []')
+  unmet=$(jq --argjson d "$deps" '
+    ($d - (.queue.passed // [])) | length
+  ' "$QUEUE" 2>/dev/null || echo 0)
+
+  local tmp_queue="${QUEUE}.tmp.$$"
+  if [ "${unmet:-0}" -gt 0 ]; then
+    jq --arg id "$fid" --argjson deps "$deps" '.queue.blocked[$id] = $deps' "$QUEUE" > "$tmp_queue" 2>/dev/null
+  else
+    jq --arg id "$fid" '.queue.ready += [$id]' "$QUEUE" > "$tmp_queue" 2>/dev/null
+  fi
+  if [ ! -s "$tmp_queue" ]; then
+    rm -f "$tmp_queue"; release_queue_lock
+    echo "[queue] enqueue: feature-queue.json 업데이트 실패" >&2; exit 1
+  fi
+  mv "$tmp_queue" "$QUEUE"
+
+  release_queue_lock
+
+  if [ "${unmet:-0}" -gt 0 ]; then
+    echo "[queue] enqueue: $fid → blocked (unmet deps: ${unmet})"
+  else
+    echo "[queue] enqueue: $fid → ready"
+  fi
+}
+
+# ══════════════════════════════════════════
+# integrity — feature-list ↔ queue divergence 검사.
+# 큐에 있지만 feature-list 에 없는 feature ID 를 출력. 0건이면 종료코드 0.
+# ══════════════════════════════════════════
+cmd_integrity() {
+  if [ ! -f "$FEATURES" ] || [ ! -f "$QUEUE" ]; then
+    echo "[integrity] feature-list 또는 feature-queue 없음"
+    exit 0
+  fi
+  local orphans
+  orphans=$(jq -r --slurpfile q "$QUEUE" '
+    ([.features[].id]) as $fl |
+    (($q[0].queue.ready // []) +
+     ($q[0].queue.passed // []) +
+     (($q[0].queue.failed // []) | if type == "object" then keys else . end) +
+     (($q[0].queue.in_progress // {}) | keys) +
+     (($q[0].queue.blocked // {}) | keys)) as $qids |
+    ($qids - $fl) | unique | .[]
+  ' "$FEATURES" 2>/dev/null)
+
+  if [ -z "$orphans" ]; then
+    echo "[integrity] OK — feature-list ↔ queue 동기화됨"
+    exit 0
+  fi
+  echo "[integrity] ⚠ feature-list 에 없는 queue-only feature 발견:"
+  echo "$orphans" | sed 's/^/  - /'
+  echo "[integrity] 복구 방법:"
+  echo "  1) Planner 가 해당 feature 를 feature-list.json 에 sprint 지정해서 추가하거나"
+  echo "  2) bash scripts/harness-queue-manager.sh enqueue <feature.json>  로 canonical path 사용"
+  exit 1
+}
+
 cmd_hold_status() {
   if [ ! -f "$CHECKPOINT" ]; then
     echo '{"held":false}'
@@ -565,8 +685,10 @@ case "$CMD" in
   hold)           cmd_hold "$@" ;;
   resume-probe)   cmd_resume_probe ;;
   hold-status)    cmd_hold_status ;;
+  enqueue)        cmd_enqueue "$@" ;;
+  integrity)      cmd_integrity ;;
   *)
-    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status|hold|resume-probe|hold-status> [args]"
+    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status|hold|resume-probe|hold-status|enqueue|integrity> [args]"
     exit 1
     ;;
 esac