km-spec-driven-development 0.1.0

package/bin/km-spec

@@ -0,0 +1,995 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve symlinks to find the real script location (works on Linux and macOS)
+_SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$_SOURCE" ]]; do
+  _DIR="$(cd -P "$(dirname "$_SOURCE")" && pwd)"
+  _SOURCE="$(readlink "$_SOURCE")"
+  [[ "$_SOURCE" != /* ]] && _SOURCE="$_DIR/$_SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$_SOURCE")" && pwd)"
+TEMPLATES_DIR="${SCRIPT_DIR}/../templates"
+
+VERSION="0.1.0"
+
+# ─── Logo & Help ──────────────────────────────────────────────────────────────
+
+print_logo() {
+  cat <<'EOF'
+ _  __ __  __      ____
+| |/ /|  \/  |    / ___| _ __   ___  ___
+| ' / | |\/| |____\___ \| '_ \ / _ \/ __|
+| . \ | |  | |_____|__) | |_) |  __/ (__
+|_|\_\|_|  |_|    |____/| .__/ \___|\___|
+                         |_|
+
+KM Spec Driven Development
+Lightweight Spec Driven Development for AI-assisted projects
+EOF
+}
+
+print_help() {
+  print_logo
+  cat <<'EOF'
+
+Usage:
+  km-spec <command> [options]
+
+Commands:
+  init                         Initialize SDD structure
+  project                      Configure .specs/project/PROJECT.md
+  roadmap                      Configure .specs/project/ROADMAP.md
+  state                        Update .specs/project/STATE.md
+  stack                        Update Technical Context in CONVENTIONS.md
+  architecture                 Update Architecture in CONVENTIONS.md
+  structure                    Update Project Structure in CONVENTIONS.md
+  testing                      Update Testing in CONVENTIONS.md
+  integrations                 Update Integrations in CONVENTIONS.md
+  concerns                     Update Concerns in CONVENTIONS.md
+  feature <name>               Create a feature spec
+  quick <name>                 Create a quick task
+  status                       Show SDD status
+  doctor                       Validate SDD structure
+  help                         Show this help
+EOF
+}
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+slugify() {
+  local s
+  s="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
+  s="$(printf '%s' "$s" | sed \
+    -e 's/[áàãâä]/a/g' \
+    -e 's/[éèêë]/e/g'  \
+    -e 's/[íìîï]/i/g'  \
+    -e 's/[óòõôö]/o/g' \
+    -e 's/[úùûü]/u/g'  \
+    -e 's/[ç]/c/g'     \
+    -e 's/[ñ]/n/g')"
+  s="$(printf '%s' "$s" | sed 's/[^a-z0-9]/-/g; s/-\{2,\}/-/g; s/^-//; s/-$//')"
+  printf '%s' "$s"
+}
+
+require_templates() {
+  if [[ ! -d "$TEMPLATES_DIR" ]]; then
+    printf 'Error: templates directory not found at: %s\n' "$TEMPLATES_DIR" >&2
+    exit 1
+  fi
+}
+
+require_init() {
+  if [[ ! -d ".specs" ]]; then
+    printf 'Error: .specs/ not found in current directory.\nRun: km-spec init\n' >&2
+    exit 1
+  fi
+}
+
+ok()   { printf '  \033[32mOK   \033[0m %s\n' "$1"; }
+warn() { printf '  \033[33mWARN \033[0m %s\n' "$1"; }
+err()  { printf '  \033[31mERROR\033[0m %s\n' "$1"; }
+info() { printf '         %s\n' "$1"; }
+
+confirm() {
+  local reply
+  read -r -p "$1 [y/N] " reply || true
+  [[ "$reply" =~ ^[Yy]$ ]]
+}
+
+# update_section FILE HEADING NEW_CONTENT
+# Replaces the body of a ## section with NEW_CONTENT.
+# Appends the section if the heading is not found.
+# Preserves all other sections.
+update_section() {
+  local file="$1"
+  local heading="$2"
+  local content="$3"
+  local tmp_content tmp_result
+  tmp_content="$(mktemp)"
+  tmp_result="$(mktemp)"
+
+  printf '%s\n' "$content" > "$tmp_content"
+
+  awk -v heading="$heading" -v cf="$tmp_content" '
+    BEGIN {
+      in_section=0; inserted=0; n=0
+      while ((getline line < cf) > 0) lines[++n] = line
+      close(cf)
+    }
+    $0 == heading {
+      in_section=1; inserted=1
+      print $0
+      for (i=1; i<=n; i++) print lines[i]
+      next
+    }
+    in_section && /^## / { in_section=0 }
+    !in_section { print }
+    END {
+      if (!inserted) {
+        print ""
+        print heading
+        for (i=1; i<=n; i++) print lines[i]
+      }
+    }
+  ' "$file" > "$tmp_result"
+
+  cp "$tmp_result" "$file"
+  rm -f "$tmp_result" "$tmp_content"
+}
+
+# ─── cmd_help ─────────────────────────────────────────────────────────────────
+
+cmd_help() {
+  print_help
+}
+
+# ─── cmd_init ─────────────────────────────────────────────────────────────────
+
+cmd_init() {
+  require_templates
+
+  local force=false
+  [[ "${1:-}" == "--force" ]] && force=true
+
+  local created=0 skipped=0
+
+  local files=(
+    "AGENTS.md"
+    "SDD.md"
+    ".specs/project/PROJECT.md"
+    ".specs/project/ROADMAP.md"
+    ".specs/project/STATE.md"
+    ".specs/codebase/CONVENTIONS.md"
+    ".specs/features/.gitkeep"
+    ".specs/quick/.gitkeep"
+  )
+
+  printf '[KM Spec] Initializing SDD structure...\n\n'
+
+  for f in "${files[@]}"; do
+    local src="$TEMPLATES_DIR/$f"
+    local dst="./$f"
+    local dir
+    dir="$(dirname "$dst")"
+
+    if [[ ! -f "$src" ]]; then
+      warn "Template not found: $src"
+      continue
+    fi
+
+    mkdir -p "$dir"
+
+    if [[ -f "$dst" ]] && [[ "$force" != true ]]; then
+      printf '[KM Spec] Skipped: %s already exists\n' "$f"
+      skipped=$((skipped + 1))
+    else
+      cp "$src" "$dst"
+      printf '[KM Spec] Created: %s\n' "$f"
+      created=$((created + 1))
+    fi
+  done
+
+  printf '\n[KM Spec] Done. Created: %d  Skipped: %d\n' "$created" "$skipped"
+  printf '\nNext steps:\n'
+  printf '  km-spec project    — fill in project goals and constraints\n'
+  printf '  km-spec stack      — document the technical stack\n'
+}
+
+# ─── cmd_feature ──────────────────────────────────────────────────────────────
+
+cmd_feature() {
+  require_init
+
+  local name="${1:-}"
+  local force=false
+
+  if [[ -z "$name" ]]; then
+    printf 'Usage: km-spec feature "Feature Name"\n' >&2
+    exit 1
+  fi
+
+  shift || true
+  [[ "${1:-}" == "--force" ]] && force=true
+
+  local slug
+  slug="$(slugify "$name")"
+  local dir=".specs/features/$slug"
+
+  if [[ -d "$dir" ]] && [[ "$force" != true ]]; then
+    printf 'Feature already exists: %s\nUse --force to overwrite.\n' "$dir"
+    exit 1
+  fi
+
+  mkdir -p "$dir"
+
+  printf '\nCreating feature: %s\n\n' "$name"
+
+  local goal req1 req2 req3 ac1 ac2 ac3 oos
+  goal="" req1="" req2="" req3="" ac1="" ac2="" ac3="" oos=""
+  read -r -p "Feature goal: "              goal   || true
+  read -r -p "Requirement 1: "             req1   || true
+  read -r -p "Requirement 2: "             req2   || true
+  read -r -p "Requirement 3: "             req3   || true
+  read -r -p "Acceptance criterion 1: "    ac1    || true
+  read -r -p "Acceptance criterion 2: "    ac2    || true
+  read -r -p "Acceptance criterion 3: "    ac3    || true
+  read -r -p "Out of scope: "              oos    || true
+
+  cat > "$dir/spec.md" <<SPEC
+# Feature: $name
+
+## Goal
+
+$goal
+
+## Requirements
+
+- REQ-001: $req1
+- REQ-002: $req2
+- REQ-003: $req3
+
+## Acceptance Criteria
+
+- [ ] AC-001: $ac1
+- [ ] AC-002: $ac2
+- [ ] AC-003: $ac3
+
+## Out of Scope
+
+- $oos
+SPEC
+
+  cat > "$dir/tasks.md" <<TASKS
+# Tasks: $name
+
+## TASK-001 — Define implementation plan
+
+Status: TODO
+
+Related requirements:
+
+- REQ-001
+- REQ-002
+- REQ-003
+
+Objective:
+
+Create an implementation plan for this feature based on \`spec.md\`.
+
+Implementation steps:
+
+1. Read \`.specs/project/STATE.md\`.
+2. Read \`.specs/project/PROJECT.md\`.
+3. Read \`.specs/codebase/CONVENTIONS.md\`.
+4. Inspect the existing code before changing anything.
+5. Break the feature into atomic implementation tasks.
+
+Acceptance criteria:
+
+- [ ] Implementation tasks are clear and atomic.
+- [ ] Each task references related requirements.
+- [ ] Validation requirements are defined.
+
+Validation:
+
+- [ ] Build passes, if applicable.
+- [ ] Lint passes, if available.
+- [ ] Typecheck passes, if available.
+- [ ] Tests pass, if available.
+- [ ] Acceptance criteria verified.
+
+Notes:
+TASKS
+
+  cat > "$dir/validation.md" <<VALIDATION
+# Validation: $name
+
+## Validation Summary
+
+Status: Pending
+
+## Evidence
+
+| Gate | Result | Command / Notes |
+|------|--------|-----------------|
+| Build | Pending | |
+| Lint | Pending | |
+| Typecheck | Pending | |
+| Tests | Pending | |
+| Manual Review | Pending | |
+
+## Issues Found
+
+None.
+
+## Final Result
+
+Pending.
+VALIDATION
+
+  printf '\n'
+  printf '[KM Spec] Created: %s/spec.md\n' "$dir"
+  printf '[KM Spec] Created: %s/tasks.md\n' "$dir"
+  printf '[KM Spec] Created: %s/validation.md\n' "$dir"
+  printf '\nNext step: open %s/spec.md and review the spec.\n' "$dir"
+  printf 'Then ask your AI agent to implement TASK-001.\n'
+}
+
+# ─── cmd_quick ────────────────────────────────────────────────────────────────
+
+cmd_quick() {
+  require_init
+
+  local name="${1:-}"
+  local force=false
+
+  if [[ -z "$name" ]]; then
+    printf 'Usage: km-spec quick "Task Name"\n' >&2
+    exit 1
+  fi
+
+  shift || true
+  [[ "${1:-}" == "--force" ]] && force=true
+
+  local slug
+  slug="$(slugify "$name")"
+  local file=".specs/quick/${slug}.md"
+
+  if [[ -f "$file" ]] && [[ "$force" != true ]]; then
+    printf 'Quick task already exists: %s\nUse --force to overwrite.\n' "$file"
+    exit 1
+  fi
+
+  mkdir -p ".specs/quick"
+
+  printf '\nCreating quick task: %s\n\n' "$name"
+
+  local objective files_affected ac validation_steps
+  objective="" files_affected="" ac="" validation_steps=""
+  read -r -p "Objective: "              objective        || true
+  read -r -p "Likely affected files: "  files_affected   || true
+  read -r -p "Acceptance criteria: "    ac               || true
+  read -r -p "Validation steps: "       validation_steps || true
+
+  cat > "$file" <<QUICK
+# Quick Task: $name
+
+## Objective
+
+$objective
+
+## Scope
+
+Files likely affected:
+
+- $files_affected
+
+## Acceptance Criteria
+
+- [ ] $ac
+
+## Validation
+
+- [ ] Build passes, if applicable.
+- [ ] Lint passes, if available.
+- [ ] Typecheck passes, if available.
+- [ ] Tests pass, if available.
+- [ ] Manual check completed, if needed.
+
+Notes: $validation_steps
+
+## Summary
+
+[Describe what was changed after implementation.]
+QUICK
+
+  printf '\n[KM Spec] Created: %s\n' "$file"
+  printf '\nNext step: ask your AI agent to complete this task, then update the Summary section.\n'
+}
+
+# ─── cmd_project ──────────────────────────────────────────────────────────────
+
+cmd_project() {
+  require_init
+
+  local file=".specs/project/PROJECT.md"
+  mkdir -p ".specs/project"
+
+  if [[ -f "$file" ]] && [[ -s "$file" ]]; then
+    if ! confirm "PROJECT.md already exists. Overwrite?"; then
+      printf 'Aborted.\n'
+      exit 0
+    fi
+  fi
+
+  printf '\nConfiguring PROJECT.md\n\n'
+
+  local name desc problem users goals nonneg oos terms
+  name="" desc="" problem="" users="" goals="" nonneg="" oos="" terms=""
+  read -r -p "Project name: "                     name    || true
+  read -r -p "One-line description: "             desc    || true
+  read -r -p "Problem being solved: "             problem || true
+  read -r -p "Target users (comma-separated): "   users   || true
+  read -r -p "Main goals (comma-separated): "     goals   || true
+  read -r -p "Non-negotiables (comma-separated): " nonneg || true
+  read -r -p "Out of scope: "                     oos     || true
+  read -r -p "Key terms (term: definition): "     terms   || true
+
+  local users_md goals_md nonneg_md
+  users_md="$(printf '%s' "$users" | tr ',' '\n' | sed 's/^[[:space:]]*/- /')"
+  goals_md="$(printf '%s' "$goals" | tr ',' '\n' | sed 's/^[[:space:]]*/- /')"
+  nonneg_md="$(printf '%s' "$nonneg" | tr ',' '\n' | sed 's/^[[:space:]]*/- /')"
+
+  cat > "$file" <<PROJECT
+# Project
+
+## Name
+
+$name
+
+## One-Line Description
+
+$desc
+
+## Problem
+
+$problem
+
+## Target Users
+
+$users_md
+
+## Goals
+
+$goals_md
+
+## Non-Negotiables
+
+$nonneg_md
+
+## Out of Scope
+
+- $oos
+
+## Key Terms
+
+- $terms
+PROJECT
+
+  printf '\n[KM Spec] Updated: %s\n' "$file"
+  printf '\nNext step: km-spec stack\n'
+}
+
+# ─── cmd_roadmap ──────────────────────────────────────────────────────────────
+
+cmd_roadmap() {
+  require_init
+
+  local file=".specs/project/ROADMAP.md"
+  mkdir -p ".specs/project"
+
+  if [[ -f "$file" ]] && [[ -s "$file" ]]; then
+    if ! confirm "ROADMAP.md already exists. Overwrite?"; then
+      printf 'Aborted.\n'
+      exit 0
+    fi
+  fi
+
+  printf '\nConfiguring ROADMAP.md\n\n'
+
+  local phase ms_name ms_goal ms_status features backlog deferred
+  phase="" ms_name="" ms_goal="" ms_status="" features="" backlog="" deferred=""
+  read -r -p "Current phase (Discovery/Setup/MVP/Active Development/Stabilization/Maintenance): " phase    || true
+  read -r -p "Milestone name: "                     ms_name   || true
+  read -r -p "Milestone goal: "                     ms_goal   || true
+  read -r -p "Milestone status (Planned/In Progress/Done): " ms_status || true
+  read -r -p "Features in this milestone (comma-separated): " features || true
+  read -r -p "Backlog items (comma-separated): "    backlog   || true
+  read -r -p "Deferred items (comma-separated): "   deferred  || true
+
+  local features_md backlog_md deferred_md
+  features_md="$(printf '%s' "$features" | tr ',' '\n' | sed 's/^[[:space:]]*/- [ ] /')"
+  backlog_md="$(printf '%s' "$backlog"   | tr ',' '\n' | sed 's/^[[:space:]]*/- [ ] /')"
+  deferred_md="$(printf '%s' "$deferred" | tr ',' '\n' | sed 's/^[[:space:]]*/- [ ] /')"
+
+  cat > "$file" <<ROADMAP
+# Roadmap
+
+## Current Phase
+
+$phase
+
+## Milestones
+
+### Milestone 1 — $ms_name
+
+**Status:** $ms_status
+**Goal:** $ms_goal
+
+#### Features
+
+$features_md
+
+## Backlog
+
+$backlog_md
+
+## Deferred
+
+$deferred_md
+ROADMAP
+
+  printf '\n[KM Spec] Updated: %s\n' "$file"
+  printf '\nNext step: km-spec feature "Your first feature"\n'
+}
+
+# ─── cmd_state ────────────────────────────────────────────────────────────────
+
+cmd_state() {
+  require_init
+
+  local file=".specs/project/STATE.md"
+  if [[ ! -f "$file" ]]; then
+    printf 'Error: %s not found. Run: km-spec init\n' "$file" >&2
+    exit 1
+  fi
+
+  printf '\nUpdating STATE.md\n\n'
+
+  local focus last_task current_task next_steps decision blocker notes
+  focus="" last_task="" current_task="" next_steps="" decision="" blocker="" notes=""
+  read -r -p "Current focus: "                              focus       || true
+  read -r -p "Last completed task: "                        last_task   || true
+  read -r -p "Current task: "                               current_task || true
+  read -r -p "Suggested next steps (comma-separated): "     next_steps  || true
+  read -r -p "Decision to record (Enter to skip): "         decision    || true
+  read -r -p "Blocker to record (Enter to skip): "          blocker     || true
+  read -r -p "Notes for future agents: "                    notes       || true
+
+  local today
+  today="$(date '+%Y-%m-%d %H:%M')"
+
+  local next_md
+  next_md="$(printf '%s' "$next_steps" | tr ',' '\n' | awk 'NR>0{print NR". "$0}' | sed 's/^[0-9]*\.[[:space:]]*/& /')"
+
+  local decisions_text blockers_text
+  decisions_text="$([ -n "$decision" ] && printf '- %s' "$decision" || printf '- None.')"
+  blockers_text="$([ -n "$blocker" ] && printf '- %s' "$blocker" || printf '- None.')"
+
+  cat >> "$file" <<SESSION
+
+---
+
+## Session — $today
+
+**Current Focus:** $focus
+
+**Last Completed Task:** $last_task
+
+**Current Task:** $current_task
+
+**Suggested Next Steps:**
+
+$next_md
+
+**Decisions:**
+
+$decisions_text
+
+**Blockers:**
+
+$blockers_text
+
+**Notes:**
+
+$notes
+SESSION
+
+  printf '\n[KM Spec] Updated: %s\n' "$file"
+  printf '\n[KM Spec] Done.\n'
+}
+
+# ─── CONVENTIONS.md updaters ──────────────────────────────────────────────────
+
+conventions_file=".specs/codebase/CONVENTIONS.md"
+
+_require_conventions() {
+  require_init
+  if [[ ! -f "$conventions_file" ]]; then
+    printf 'Error: %s not found. Run: km-spec init\n' "$conventions_file" >&2
+    exit 1
+  fi
+}
+
+cmd_stack() {
+  _require_conventions
+  printf '\nUpdating Technical Context in CONVENTIONS.md\n\n'
+
+  local lang framework runtime pkgmgr database libs deploy cicd
+  lang="" framework="" runtime="" pkgmgr="" database="" libs="" deploy="" cicd=""
+  read -r -p "Language: "         lang      || true
+  read -r -p "Framework: "        framework || true
+  read -r -p "Runtime: "          runtime   || true
+  read -r -p "Package manager: "  pkgmgr    || true
+  read -r -p "Database: "         database  || true
+  read -r -p "Main libraries: "   libs      || true
+  read -r -p "Deployment: "       deploy    || true
+  read -r -p "CI/CD: "            cicd      || true
+
+  local content
+  content="
+- Language: $lang
+- Framework: $framework
+- Runtime: $runtime
+- Package manager: $pkgmgr
+- Database: $database
+- Main libraries: $libs
+- Deployment: $deploy
+- CI/CD: $cicd"
+
+  update_section "$conventions_file" "## 1. Technical Context" "$content"
+  printf '\n[KM Spec] Updated: %s\n' "$conventions_file"
+  printf '\nNext step: km-spec architecture\n'
+}
+
+cmd_architecture() {
+  _require_conventions
+  printf '\nUpdating Architecture in CONVENTIONS.md\n\n'
+
+  local modules dataflow patterns decisions
+  modules="" dataflow="" patterns="" decisions=""
+  read -r -p "Main modules: "                   modules   || true
+  read -r -p "Data flow: "                      dataflow  || true
+  read -r -p "Architectural patterns: "         patterns  || true
+  read -r -p "Important technical decisions: "  decisions || true
+
+  local content
+  content="
+- Main modules: $modules
+- Data flow: $dataflow
+- Architectural patterns: $patterns
+- Important decisions: $decisions"
+
+  update_section "$conventions_file" "## 2. Architecture" "$content"
+  printf '\n[KM Spec] Updated: %s\n' "$conventions_file"
+  printf '\nNext step: km-spec structure\n'
+}
+
+cmd_structure() {
+  _require_conventions
+  printf '\nUpdating Project Structure in CONVENTIONS.md\n\n'
+
+  local srcdir api_dir comp_dir svc_dir test_dir generated
+  srcdir="" api_dir="" comp_dir="" svc_dir="" test_dir="" generated=""
+  read -r -p "Main source directory: "       srcdir    || true
+  read -r -p "Where API files go: "          api_dir   || true
+  read -r -p "Where components go: "         comp_dir  || true
+  read -r -p "Where services go: "           svc_dir   || true
+  read -r -p "Where tests go: "              test_dir  || true
+  read -r -p "Generated files or folders: "  generated || true
+
+  local content
+  content="
+Main source directory: \`$srcdir\`
+
+File placement rules:
+
+- API files: $api_dir
+- Components: $comp_dir
+- Services: $svc_dir
+- Tests: $test_dir
+- Generated: $generated"
+
+  update_section "$conventions_file" "## 3. Project Structure" "$content"
+  printf '\n[KM Spec] Updated: %s\n' "$conventions_file"
+  printf '\nNext step: km-spec testing\n'
+}
+
+cmd_testing() {
+  _require_conventions
+  printf '\nUpdating Testing in CONVENTIONS.md\n\n'
+
+  local framework pattern unit_rules int_rules e2e_rules commands
+  framework="" pattern="" unit_rules="" int_rules="" e2e_rules="" commands=""
+  read -r -p "Test framework: "             framework  || true
+  read -r -p "Test file pattern: "          pattern    || true
+  read -r -p "Unit test rules: "            unit_rules || true
+  read -r -p "Integration test rules: "     int_rules  || true
+  read -r -p "E2E test rules: "             e2e_rules  || true
+  read -r -p "Commands to run tests: "      commands   || true
+
+  local content
+  content="
+- Test framework: $framework
+- Test file pattern: $pattern
+- Unit test rules: $unit_rules
+- Integration test rules: $int_rules
+- E2E test rules: $e2e_rules
+- Required commands: \`$commands\`
+
+Validation gates:
+
+- [ ] Build
+- [ ] Lint
+- [ ] Typecheck
+- [ ] Tests
+- [ ] Manual check when needed"
+
+  update_section "$conventions_file" "## 5. Testing" "$content"
+  printf '\n[KM Spec] Updated: %s\n' "$conventions_file"
+  printf '\nNext step: km-spec integrations\n'
+}
+
+cmd_integrations() {
+  _require_conventions
+  printf '\nUpdating Integrations in CONVENTIONS.md\n\n'
+
+  local svc_name purpose auth env_vars limits webhooks
+  svc_name="" purpose="" auth="" env_vars="" limits="" webhooks=""
+  read -r -p "Service name: "                          svc_name || true
+  read -r -p "Purpose: "                               purpose  || true
+  read -r -p "Authentication method: "                 auth     || true
+  read -r -p "Environment variables: "                 env_vars || true
+  read -r -p "Rate limits or risks: "                  limits   || true
+  read -r -p "Webhook details (Enter to skip): "       webhooks || true
+
+  local content
+  content="
+| Field | Value |
+|-------|-------|
+| Service | $svc_name |
+| Purpose | $purpose |
+| Auth | $auth |
+| Env vars | $env_vars |
+| Risks / limits | $limits |
+| Webhooks | ${webhooks:-None} |"
+
+  update_section "$conventions_file" "## 6. Integrations" "$content"
+  printf '\n[KM Spec] Updated: %s\n' "$conventions_file"
+  printf '\nNext step: km-spec concerns\n'
+}
+
+cmd_concerns() {
+  _require_conventions
+  printf '\nUpdating Concerns in CONVENTIONS.md\n\n'
+
+  local risks debt fragile low_cov deprecated
+  risks="" debt="" fragile="" low_cov="" deprecated=""
+  read -r -p "Known risks: "              risks      || true
+  read -r -p "Technical debt: "           debt       || true
+  read -r -p "Fragile areas: "            fragile    || true
+  read -r -p "Low test coverage areas: "  low_cov    || true
+  read -r -p "Deprecated patterns: "      deprecated || true
+
+  local content
+  content="
+- Known risks: $risks
+- Technical debt: $debt
+- Fragile areas: $fragile
+- Low test coverage areas: $low_cov
+- Deprecated patterns: $deprecated"
+
+  update_section "$conventions_file" "## 7. Concerns" "$content"
+  printf '\n[KM Spec] Updated: %s\n' "$conventions_file"
+  printf '\nRun km-spec status to review the full setup.\n'
+}
+
+# ─── cmd_status ───────────────────────────────────────────────────────────────
+
+cmd_status() {
+  printf 'KM Spec Status\n\n'
+
+  printf 'Base files:\n'
+  local base_files=("AGENTS.md" "SDD.md" ".specs/project/PROJECT.md"
+    ".specs/project/ROADMAP.md" ".specs/project/STATE.md"
+    ".specs/codebase/CONVENTIONS.md")
+
+  for f in "${base_files[@]}"; do
+    if [[ -f "$f" ]]; then
+      printf '  Found    %s\n' "$f"
+    else
+      printf '  Missing  %s\n' "$f"
+    fi
+  done
+
+  printf '\nFeatures:\n'
+  local feat_found=false
+  if [[ -d ".specs/features" ]]; then
+    for d in .specs/features/*/; do
+      [[ -d "$d" ]] || continue
+      printf '  %s\n' "$(basename "$d")"
+      feat_found=true
+    done
+  fi
+  [[ "$feat_found" == true ]] || printf '  (none)\n'
+
+  printf '\nQuick tasks:\n'
+  local quick_found=false
+  if [[ -d ".specs/quick" ]]; then
+    for f in .specs/quick/*.md; do
+      [[ -f "$f" ]] || continue
+      printf '  %s\n' "$(basename "$f" .md)"
+      quick_found=true
+    done
+  fi
+  [[ "$quick_found" == true ]] || printf '  (none)\n'
+
+  printf '\nCONVENTIONS.md sections:\n'
+  if [[ -f ".specs/codebase/CONVENTIONS.md" ]]; then
+    local sections=(
+      "## 1. Technical Context"
+      "## 2. Architecture"
+      "## 3. Project Structure"
+      "## 4. Coding Standards"
+      "## 5. Testing"
+      "## 6. Integrations"
+      "## 7. Concerns"
+      "## 8. AI Rules"
+      "## 9. Optional Expansion"
+    )
+    for s in "${sections[@]}"; do
+      if grep -qF "$s" ".specs/codebase/CONVENTIONS.md" 2>/dev/null; then
+        printf '  Found    %s\n' "$s"
+      else
+        printf '  Missing  %s\n' "$s"
+      fi
+    done
+  else
+    printf '  CONVENTIONS.md not found\n'
+  fi
+}
+
+# ─── cmd_doctor ───────────────────────────────────────────────────────────────
+
+cmd_doctor() {
+  printf 'KM Spec Doctor\n\n'
+
+  local errors=0 warnings=0
+
+  printf 'Required files:\n'
+  local required_files=("AGENTS.md" "SDD.md" ".specs/project/PROJECT.md"
+    ".specs/project/ROADMAP.md" ".specs/project/STATE.md"
+    ".specs/codebase/CONVENTIONS.md")
+  for f in "${required_files[@]}"; do
+    if [[ -f "$f" ]]; then ok "$f"
+    else err "$f — missing"; errors=$((errors + 1)); fi
+  done
+
+  printf '\nRequired directories:\n'
+  local required_dirs=(".specs/project" ".specs/codebase" ".specs/features" ".specs/quick")
+  for d in "${required_dirs[@]}"; do
+    if [[ -d "$d" ]]; then ok "$d"
+    else err "$d — missing"; errors=$((errors + 1)); fi
+  done
+
+  printf '\nForbidden standalone files (content must be inside CONVENTIONS.md):\n'
+  local forbidden=(".specs/codebase/STACK.md" ".specs/codebase/ARCHITECTURE.md"
+    ".specs/codebase/STRUCTURE.md" ".specs/codebase/TESTING.md"
+    ".specs/codebase/INTEGRATIONS.md" ".specs/codebase/CONCERNS.md")
+  for f in "${forbidden[@]}"; do
+    if [[ -f "$f" ]]; then
+      warn "$f — consolidate into CONVENTIONS.md"
+      warnings=$((warnings + 1))
+    else
+      ok "$(basename "$f") — not present (correct)"
+    fi
+  done
+
+  printf '\nCONVENTIONS.md sections:\n'
+  if [[ -f ".specs/codebase/CONVENTIONS.md" ]]; then
+    local sections=(
+      "## 1. Technical Context" "## 2. Architecture" "## 3. Project Structure"
+      "## 4. Coding Standards" "## 5. Testing" "## 6. Integrations"
+      "## 7. Concerns" "## 8. AI Rules"
+    )
+    for s in "${sections[@]}"; do
+      if grep -qF "$s" ".specs/codebase/CONVENTIONS.md" 2>/dev/null; then ok "$s"
+      else warn "$s — section missing"; warnings=$((warnings + 1)); fi
+    done
+  fi
+
+  printf '\nSTATE.md:\n'
+  if [[ -f ".specs/project/STATE.md" ]]; then
+    if [[ -s ".specs/project/STATE.md" ]]; then ok "STATE.md — not empty"
+    else warn "STATE.md — empty"; warnings=$((warnings + 1)); fi
+  fi
+
+  printf '\nAGENTS.md references:\n'
+  if [[ -f "AGENTS.md" ]]; then
+    local agents_ok=true
+    grep -q "STATE.md"       "AGENTS.md" 2>/dev/null || agents_ok=false
+    grep -q "PROJECT.md"     "AGENTS.md" 2>/dev/null || agents_ok=false
+    grep -q "CONVENTIONS.md" "AGENTS.md" 2>/dev/null || agents_ok=false
+    if [[ "$agents_ok" == true ]]; then
+      ok "AGENTS.md — references STATE.md, PROJECT.md, CONVENTIONS.md"
+    else
+      warn "AGENTS.md — missing one or more required file references"
+      warnings=$((warnings + 1))
+    fi
+  fi
+
+  printf '\nFeature integrity:\n'
+  local feat_checked=false
+  if [[ -d ".specs/features" ]]; then
+    for d in .specs/features/*/; do
+      [[ -d "$d" ]] || continue
+      feat_checked=true
+      local feat
+      feat="$(basename "$d")"
+      for req_file in spec.md tasks.md validation.md; do
+        if [[ -f "$d$req_file" ]]; then ok "$feat/$req_file"
+        else warn "$feat/$req_file — missing"; warnings=$((warnings + 1)); fi
+      done
+    done
+  fi
+  [[ "$feat_checked" == true ]] || info "No features found."
+
+  printf '\nQuick tasks:\n'
+  local quick_checked=false
+  if [[ -d ".specs/quick" ]]; then
+    for f in .specs/quick/*.md; do
+      [[ -f "$f" ]] || continue
+      quick_checked=true
+      ok "$(basename "$f")"
+    done
+  fi
+  [[ "$quick_checked" == true ]] || info "No quick tasks found."
+
+  printf '\nSummary:\n'
+  if [[ $errors -eq 0 ]] && [[ $warnings -eq 0 ]]; then
+    printf '  \033[32mAll checks passed.\033[0m\n'
+  else
+    [[ $errors -gt 0 ]]   && printf '  \033[31m%d error(s) found.\033[0m\n'   "$errors"
+    [[ $warnings -gt 0 ]] && printf '  \033[33m%d warning(s) found.\033[0m\n' "$warnings"
+  fi
+}
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+main() {
+  local cmd="${1:-help}"
+  shift || true
+
+  case "$cmd" in
+    init)          cmd_init "$@" ;;
+    feature)       cmd_feature "$@" ;;
+    quick)         cmd_quick "$@" ;;
+    project)       cmd_project "$@" ;;
+    roadmap)       cmd_roadmap "$@" ;;
+    state)         cmd_state "$@" ;;
+    stack)         cmd_stack "$@" ;;
+    architecture)  cmd_architecture "$@" ;;
+    structure)     cmd_structure "$@" ;;
+    testing)       cmd_testing "$@" ;;
+    integrations)  cmd_integrations "$@" ;;
+    concerns)      cmd_concerns "$@" ;;
+    status)        cmd_status "$@" ;;
+    doctor)        cmd_doctor "$@" ;;
+    help|--help|-h)          cmd_help ;;
+    version|--version|-v)    printf 'km-spec v%s\n' "$VERSION" ;;
+    *) printf 'Unknown command: %s\n\n' "$cmd" >&2; cmd_help; exit 1 ;;
+  esac
+}
+
+main "$@"