km-spec-driven-development 0.1.0 → 0.2.0

package/bin/km-spec

@@ -11,7 +11,8 @@ done
 SCRIPT_DIR="$(cd -P "$(dirname "$_SOURCE")" && pwd)"
 TEMPLATES_DIR="${SCRIPT_DIR}/../templates"
 
-VERSION="0.1.0"
+VERSION="0.2.0"
+TEMPLATE_VERSION="1.0"
 
 # ─── Logo & Help ──────────────────────────────────────────────────────────────
 
@@ -31,7 +32,7 @@ EOF
 
 print_help() {
   print_logo
-  cat <<'EOF'
+  cat <<EOF
 
 Usage:
   km-spec <command> [options]
@@ -47,11 +48,36 @@ Commands:
   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
+  feature <name> [options]     Create a feature spec (non-interactive by default)
+  quick <name> [options]       Create a quick task (non-interactive by default)
   status                       Show SDD status
   doctor                       Validate SDD structure
   help                         Show this help
+  version                      Show version
+
+Feature options:
+  --description <text>         Confirmed overview text for the feature
+  --tier standard|complex      Planning depth (default: standard)
+  --interactive                Prompt for fields (legacy interview mode)
+  --force                      Overwrite files in the target feature directory
+
+Quick options:
+  --description <text>         Confirmed objective/description text
+  --interactive                Prompt for fields (legacy interview mode)
+  --force                      Overwrite files in the target quick-task directory
+
+Examples:
+  km-spec init
+  km-spec feature "User Authentication"
+  km-spec feature "User Authentication" --description "Login and session management"
+  km-spec feature "SSO Federation" --tier complex
+  km-spec feature "User Authentication" --interactive
+  km-spec quick "Fix login validation"
+  km-spec quick "Fix login validation" --description "Reject expired sessions"
+  km-spec doctor
+  km-spec status
+
+km-spec v${VERSION}
 EOF
 }
 
@@ -97,45 +123,121 @@ confirm() {
   [[ "$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)"
+# Multi-line safe: use awk for placeholder replacement without eval.
+# render_template SRC DEST KEY=VALUE KEY=VALUE ...
+# Keys are placeholder names without braces (e.g. FEATURE_NAME).
+render_template() {
+  local src="$1"
+  local dest="$2"
+  shift 2
 
-  printf '%s\n' "$content" > "$tmp_content"
+  if [[ ! -f "$src" ]]; then
+    printf 'Error: template not found: %s\n' "$src" >&2
+    exit 1
+  fi
 
-  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]
+  local tmp
+  tmp="$(mktemp)"
+  cp "$src" "$tmp"
+
+  local pair key val
+  for pair in "$@"; do
+    key="${pair%%=*}"
+    val="${pair#*=}"
+    # Use awk with ENVIRON-style via -v and index replace for all occurrences.
+    # Pass value via file to preserve newlines safely.
+    local valfile
+    valfile="$(mktemp)"
+    printf '%s' "$val" > "$valfile"
+    local out
+    out="$(mktemp)"
+    awk -v key="{{${key}}}" -v vf="$valfile" '
+      BEGIN {
+        repl = ""
+        while ((getline line < vf) > 0) {
+          if (repl != "") repl = repl "\n"
+          repl = repl line
+        }
+        # trailing content without final newline still ok
+        close(vf)
       }
-    }
-  ' "$file" > "$tmp_result"
+      {
+        n = index($0, key)
+        if (n == 0) { print; next }
+        # replace all occurrences on the line
+        line = $0
+        out = ""
+        while ((n = index(line, key)) > 0) {
+          out = out substr(line, 1, n - 1) repl
+          line = substr(line, n + length(key))
+        }
+        print out line
+      }
+    ' "$tmp" > "$out"
+    mv "$out" "$tmp"
+    rm -f "$valfile"
+  done
 
-  cp "$tmp_result" "$file"
-  rm -f "$tmp_result" "$tmp_content"
+  mkdir -p "$(dirname "$dest")"
+  cp "$tmp" "$dest"
+  rm -f "$tmp"
+}
+
+next_feature_id() {
+  local n=0
+  local d
+  if [[ -d ".specs/features" ]]; then
+    for d in .specs/features/*/; do
+      [[ -d "$d" ]] || continue
+      n=$((n + 1))
+    done
+  fi
+  # When creating a new dir, this count includes existing only (new not yet created).
+  printf 'FEAT-%03d' $((n + 1))
+}
+
+complex_sections_text() {
+  cat <<'COMPLEX'
+## Component Boundaries
+
+| Boundary | Owns | Must not own | Confidence |
+|----------|------|--------------|------------|
+| [NEEDS CLARIFICATION] | | | [NEEDS CLARIFICATION] |
+
+## Data Model
+
+| Entity / table | Fields (summary) | Notes | Confidence |
+|----------------|------------------|-------|------------|
+| [NEEDS CLARIFICATION] | | | [NEEDS CLARIFICATION] |
+
+## API or Interface Contracts
+
+### Endpoint / interface: [NEEDS CLARIFICATION]
+
+- **Request:** [NEEDS CLARIFICATION]
+- **Response:** [NEEDS CLARIFICATION]
+- **Errors:** [NEEDS CLARIFICATION]
+
+## Security
+
+- [NEEDS CLARIFICATION]: Authn/authz, input validation, secrets, threat notes.
+
+## Performance
+
+- [NEEDS CLARIFICATION]: Latency, throughput, N+1, caching, limits.
+
+## Migration or Rollout
+
+- [NEEDS CLARIFICATION]: Schema migrations, feature flags, phased rollout.
+
+## Observability
+
+- [NEEDS CLARIFICATION]: Logs, metrics, traces, alerts.
+
+## Rollback Strategy
+
+- [NEEDS CLARIFICATION]: How to revert safely if the release fails.
+COMPLEX
 }
 
 # ─── cmd_help ─────────────────────────────────────────────────────────────────
@@ -156,6 +258,7 @@ cmd_init() {
 
   local files=(
     "AGENTS.md"
+    "HARNESS.md"
     "SDD.md"
     ".specs/project/PROJECT.md"
     ".specs/project/ROADMAP.md"
@@ -192,220 +295,398 @@ cmd_init() {
 
   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'
+  printf '  km-spec feature "Your Feature"   — scaffold a guided feature spec\n'
+  printf '  km-spec project                  — fill in project goals (optional interview)\n'
+  printf '  Read HARNESS.md and AGENTS.md before agent work\n'
 }
 
 # ─── cmd_feature ──────────────────────────────────────────────────────────────
 
 cmd_feature() {
   require_init
+  require_templates
 
   local name="${1:-}"
-  local force=false
-
-  if [[ -z "$name" ]]; then
-    printf 'Usage: km-spec feature "Feature Name"\n' >&2
+  if [[ -z "$name" || "$name" == --* ]]; then
+    printf 'Usage: km-spec feature "Feature Name" [--description TEXT] [--tier standard|complex] [--interactive] [--force]\n' >&2
     exit 1
   fi
-
   shift || true
-  [[ "${1:-}" == "--force" ]] && force=true
+
+  local force=false interactive=false description="" tier="standard"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=true; shift ;;
+      --interactive) interactive=true; shift ;;
+      --description)
+        if [[ -z "${2:-}" || "${2:-}" == --* ]]; then
+          printf 'Error: --description requires a value.\n' >&2
+          exit 1
+        fi
+        description="$2"
+        shift 2
+        ;;
+      --description=*)
+        description="${1#--description=}"
+        shift
+        ;;
+      --tier)
+        if [[ -z "${2:-}" || "${2:-}" == --* ]]; then
+          printf 'Error: --tier requires a value (standard|complex).\n' >&2
+          exit 1
+        fi
+        tier="$2"
+        shift 2
+        ;;
+      --tier=*)
+        tier="${1#--tier=}"
+        shift
+        ;;
+      *)
+        printf 'Error: unknown option for feature: %s\n' "$1" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  case "$tier" in
+    standard|complex) ;;
+    *)
+      printf 'Error: unknown tier "%s". Supported tiers: standard, complex.\n' "$tier" >&2
+      exit 1
+      ;;
+  esac
 
   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"
+  if [[ -z "$slug" ]]; then
+    printf 'Error: could not derive a safe slug from feature name.\n' >&2
     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.
+  local dir=".specs/features/$slug"
 
-Notes:
-TASKS
+  # Path safety: slug is already alnum+hyphen only
+  if [[ "$slug" == *"/"* || "$slug" == *".."* ]]; then
+    printf 'Error: invalid feature slug.\n' >&2
+    exit 1
+  fi
 
-  cat > "$dir/validation.md" <<VALIDATION
-# Validation: $name
+  if [[ -d "$dir" || -e "$dir" ]] && [[ "$force" != true ]]; then
+    printf 'Feature already exists: %s\nUse --force to overwrite generated files in this directory only.\n' "$dir" >&2
+    exit 1
+  fi
 
-## Validation Summary
+  if [[ "$force" == true ]] && [[ -d "$dir" ]]; then
+    printf '[KM Spec] --force: will replace generated files in %s:\n' "$dir"
+    printf '  - %s/spec.md\n' "$dir"
+    printf '  - %s/context.md\n' "$dir"
+    printf '  - %s/plan.md\n' "$dir"
+    printf '  - %s/tasks.md\n' "$dir"
+    printf '  - %s/validation.md\n' "$dir"
+  fi
 
-Status: Pending
+  mkdir -p "$dir"
 
-## Evidence
+  local feature_id created_date
+  created_date="$(date '+%Y-%m-%d')"
+  feature_id="$(next_feature_id)"
+  # If force-overwrite and existing FEAT id present, reuse it
+  if [[ -f "$dir/spec.md" ]]; then
+    local existing_id
+    existing_id="$(grep -E '\*\*Feature ID\*\*' "$dir/spec.md" 2>/dev/null | head -1 | sed -E 's/.*\|\s*(FEAT-[A-Za-z0-9-]+)\s*\|.*/\1/' || true)"
+    if [[ "$existing_id" == FEAT-* ]]; then
+      feature_id="$existing_id"
+    fi
+  fi
 
-| Gate | Result | Command / Notes |
-|------|--------|-----------------|
-| Build | Pending | |
-| Lint | Pending | |
-| Typecheck | Pending | |
-| Tests | Pending | |
-| Manual Review | Pending | |
+  local overview_block confirmed_block inferred_block
+  if [[ -n "$description" ]]; then
+    overview_block="[CONFIRMED]: ${description}"
+    confirmed_block="- [CONFIRMED]: Feature name is **${name}**.
+- [CONFIRMED]: Overview description provided at scaffold time (see Overview)."
+  else
+    overview_block="[NEEDS CLARIFICATION]: Write 1–3 sentences describing what this feature does and why it exists. Do not invent product claims."
+    confirmed_block="- [CONFIRMED]: Feature name is **${name}** (scaffold title only).
+- [NEEDS CLARIFICATION]: No overview description was provided at scaffold time."
+  fi
 
-## Issues Found
+  inferred_block="- None yet. Do **not** invent product requirements from the feature name.
+- Optional later: list non-binding ideas here only with explicit \`[INFERRED]\` labels, then promote with evidence."
+
+  # Interactive mode fills optional fields into overview/confirmed without inventing REQs
+  if [[ "$interactive" == true ]]; then
+    printf '\nInteractive feature setup: %s\n' "$name"
+    printf '(Leave blank to keep template placeholders. Requirements are never auto-invented.)\n\n'
+    local goal oos
+    goal="" oos=""
+    read -r -p "Feature goal / overview: " goal || true
+    read -r -p "Out of scope (optional): " oos || true
+    if [[ -n "$goal" ]]; then
+      overview_block="[CONFIRMED]: ${goal}"
+      confirmed_block="- [CONFIRMED]: Feature name is **${name}**.
+- [CONFIRMED]: Overview provided interactively (see Overview)."
+      description="$goal"
+    fi
+    if [[ -n "$oos" ]]; then
+      # Append note via environment for post-pass; store for sed after render
+      :
+    fi
+  fi
 
-None.
+  local complex_sections=""
+  if [[ "$tier" == "complex" ]]; then
+    complex_sections="$(complex_sections_text)"
+  else
+    complex_sections="<!-- Complex-tier sections omitted (tier=standard). Re-scaffold with --tier complex or add sections manually if complexity grows. -->"
+  fi
 
-## Final Result
+  local desc_context=""
+  if [[ -n "$description" ]]; then
+    desc_context="Scaffold description ([CONFIRMED] at creation): ${description}"
+  else
+    desc_context="[NEEDS CLARIFICATION]: No scaffold description provided."
+  fi
 
-Pending.
-VALIDATION
+  printf '\nCreating feature: %s (tier=%s)\n\n' "$name" "$tier"
+
+  local tdir="$TEMPLATES_DIR/features"
+  render_template "$tdir/spec.md" "$dir/spec.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=${feature_id}" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=${tier}" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}" \
+    "OVERVIEW_BLOCK=${overview_block}" \
+    "CONFIRMED_BLOCK=${confirmed_block}" \
+    "INFERRED_BLOCK=${inferred_block}"
+
+  render_template "$tdir/context.md" "$dir/context.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=${feature_id}" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=${tier}" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}" \
+    "DESCRIPTION_CONTEXT=${desc_context}"
+
+  render_template "$tdir/plan.md" "$dir/plan.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=${feature_id}" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=${tier}" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}" \
+    "COMPLEX_SECTIONS=${complex_sections}"
+
+  render_template "$tdir/tasks.md" "$dir/tasks.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=${feature_id}" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=${tier}" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}"
+
+  render_template "$tdir/validation.md" "$dir/validation.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=${feature_id}" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=${tier}" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}"
+
+  # Interactive optional out-of-scope injection
+  if [[ "$interactive" == true ]]; then
+    local oos_val="${oos:-}"
+    if [[ -n "${oos_val:-}" ]]; then
+      # Replace first NEEDS CLARIFICATION out-of-scope bullet with confirmed text
+      local tmp
+      tmp="$(mktemp)"
+      awk -v oos="$oos_val" '
+        BEGIN { done=0 }
+        !done && /\[NEEDS CLARIFICATION\]: List what this feature/ {
+          print "- [CONFIRMED]: " oos
+          done=1
+          next
+        }
+        { print }
+      ' "$dir/spec.md" > "$tmp"
+      mv "$tmp" "$dir/spec.md"
+    fi
+  fi
 
-  printf '\n'
   printf '[KM Spec] Created: %s/spec.md\n' "$dir"
+  printf '[KM Spec] Created: %s/context.md\n' "$dir"
+  printf '[KM Spec] Created: %s/plan.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'
+  printf '\nNext steps:\n'
+  printf '  1. Fill spec.md (requirements stay unresolved until confirmed).\n'
+  printf '  2. Ask your agent to follow AGENTS.md + HARNESS.md starting at TASK-001.\n'
 }
 
 # ─── cmd_quick ────────────────────────────────────────────────────────────────
 
 cmd_quick() {
   require_init
+  require_templates
 
   local name="${1:-}"
-  local force=false
-
-  if [[ -z "$name" ]]; then
-    printf 'Usage: km-spec quick "Task Name"\n' >&2
+  if [[ -z "$name" || "$name" == --* ]]; then
+    printf 'Usage: km-spec quick "Task Name" [--description TEXT] [--interactive] [--force]\n' >&2
     exit 1
   fi
-
   shift || true
-  [[ "${1:-}" == "--force" ]] && force=true
+
+  local force=false interactive=false description=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=true; shift ;;
+      --interactive) interactive=true; shift ;;
+      --description)
+        if [[ -z "${2:-}" || "${2:-}" == --* ]]; then
+          printf 'Error: --description requires a value.\n' >&2
+          exit 1
+        fi
+        description="$2"
+        shift 2
+        ;;
+      --description=*)
+        description="${1#--description=}"
+        shift
+        ;;
+      *)
+        printf 'Error: unknown option for quick: %s\n' "$1" >&2
+        exit 1
+        ;;
+    esac
+  done
 
   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"
+  if [[ -z "$slug" ]]; then
+    printf 'Error: could not derive a safe slug from task name.\n' >&2
+    exit 1
+  fi
+  if [[ "$slug" == *"/"* || "$slug" == *".."* ]]; then
+    printf 'Error: invalid quick-task slug.\n' >&2
     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:
+  local dir=".specs/quick/$slug"
+  local legacy_file=".specs/quick/${slug}.md"
 
-- $files_affected
+  if [[ -e "$dir" || -f "$legacy_file" ]] && [[ "$force" != true ]]; then
+    if [[ -f "$legacy_file" ]]; then
+      printf 'Quick task already exists (legacy file): %s\nUse --force to replace with directory layout (legacy file left in place unless removed manually).\n' "$legacy_file" >&2
+    else
+      printf 'Quick task already exists: %s\nUse --force to overwrite generated files in this directory only.\n' "$dir" >&2
+    fi
+    exit 1
+  fi
 
-## Acceptance Criteria
+  if [[ "$force" == true ]]; then
+    printf '[KM Spec] --force: will replace generated files in %s:\n' "$dir"
+    printf '  - %s/TASK.md\n' "$dir"
+    printf '  - %s/SUMMARY.md\n' "$dir"
+  fi
 
-- [ ] $ac
+  mkdir -p "$dir"
 
-## Validation
+  local created_date
+  created_date="$(date '+%Y-%m-%d')"
 
-- [ ] Build passes, if applicable.
-- [ ] Lint passes, if available.
-- [ ] Typecheck passes, if available.
-- [ ] Tests pass, if available.
-- [ ] Manual check completed, if needed.
+  local quick_objective quick_description
+  if [[ -n "$description" ]]; then
+    quick_objective="[CONFIRMED]: ${description}"
+    quick_description="[CONFIRMED]: ${description}"
+  else
+    quick_objective="[NEEDS CLARIFICATION]: State the objective in one sentence. Do not invent scope."
+    quick_description="[NEEDS CLARIFICATION]: Add brief context for the change. Inspect the repository before listing files."
+  fi
 
-Notes: $validation_steps
+  if [[ "$interactive" == true ]]; then
+    printf '\nInteractive quick task setup: %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
+    if [[ -n "$objective" ]]; then
+      quick_objective="[CONFIRMED]: ${objective}"
+      quick_description="[CONFIRMED]: ${objective}"
+    fi
+  fi
 
-## Summary
+  printf '\nCreating quick task: %s\n\n' "$name"
 
-[Describe what was changed after implementation.]
-QUICK
+  local tdir="$TEMPLATES_DIR/quick"
+  render_template "$tdir/TASK.md" "$dir/TASK.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=quick" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}" \
+    "QUICK_OBJECTIVE=${quick_objective}" \
+    "QUICK_DESCRIPTION=${quick_description}"
+
+  render_template "$tdir/SUMMARY.md" "$dir/SUMMARY.md" \
+    "FEATURE_NAME=${name}" \
+    "FEATURE_SLUG=${slug}" \
+    "FEATURE_ID=" \
+    "DESCRIPTION=${description}" \
+    "CREATED_DATE=${created_date}" \
+    "TIER=quick" \
+    "TEMPLATE_VERSION=${TEMPLATE_VERSION}"
+
+  # Interactive: inject optional fields into TASK.md if provided
+  if [[ "$interactive" == true ]]; then
+    if [[ -n "${files_affected:-}" ]]; then
+      local tmp
+      tmp="$(mktemp)"
+      awk -v f="$files_affected" '
+        /\[NEEDS CLARIFICATION\]: `path\/to\/file`/ && !done {
+          print "- [CONFIRMED]: " f
+          done=1
+          next
+        }
+        { print }
+      ' "$dir/TASK.md" > "$tmp"
+      mv "$tmp" "$dir/TASK.md"
+    fi
+    if [[ -n "${ac:-}" ]]; then
+      local tmp
+      tmp="$(mktemp)"
+      awk -v a="$ac" '
+        /\[NEEDS CLARIFICATION\]: Observable outcome/ && !done {
+          print "- [ ] [CONFIRMED]: " a
+          done=1
+          next
+        }
+        { print }
+      ' "$dir/TASK.md" > "$tmp"
+      mv "$tmp" "$dir/TASK.md"
+    fi
+    if [[ -n "${validation_steps:-}" ]]; then
+      printf '\n## Interactive validation notes\n\n%s\n' "$validation_steps" >> "$dir/TASK.md"
+    fi
+  fi
 
-  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'
+  printf '[KM Spec] Created: %s/TASK.md\n' "$dir"
+  printf '[KM Spec] Created: %s/SUMMARY.md\n' "$dir"
+  printf '\nNext step: ask your agent to complete TASK.md following AGENTS.md and HARNESS.md,\n'
+  printf 'then fill SUMMARY.md and update STATE.md.\n'
 }
 
 # ─── cmd_project ──────────────────────────────────────────────────────────────
@@ -478,7 +759,7 @@ $nonneg_md
 PROJECT
 
   printf '\n[KM Spec] Updated: %s\n' "$file"
-  printf '\nNext step: km-spec stack\n'
+  printf '\nNext step: km-spec feature "Your first feature"\n'
 }
 
 # ─── cmd_roadmap ──────────────────────────────────────────────────────────────
@@ -574,8 +855,17 @@ cmd_state() {
   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.')"
+  # Use printf -- so values starting with '-' are not treated as options
+  if [[ -n "$decision" ]]; then
+    decisions_text="$(printf -- '- %s' "$decision")"
+  else
+    decisions_text="- None."
+  fi
+  if [[ -n "$blocker" ]]; then
+    blockers_text="$(printf -- '- %s' "$blocker")"
+  else
+    blockers_text="- None."
+  fi
 
   cat >> "$file" <<SESSION
 
@@ -795,13 +1085,51 @@ cmd_concerns() {
   printf '\nRun km-spec status to review the full setup.\n'
 }
 
+# update_section FILE HEADING NEW_CONTENT
+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_status ───────────────────────────────────────────────────────────────
 
 cmd_status() {
   printf 'KM Spec Status\n\n'
 
   printf 'Base files:\n'
-  local base_files=("AGENTS.md" "SDD.md" ".specs/project/PROJECT.md"
+  local base_files=("AGENTS.md" "HARNESS.md" "SDD.md" ".specs/project/PROJECT.md"
     ".specs/project/ROADMAP.md" ".specs/project/STATE.md"
     ".specs/codebase/CONVENTIONS.md")
 
@@ -816,10 +1144,34 @@ cmd_status() {
   printf '\nFeatures:\n'
   local feat_found=false
   if [[ -d ".specs/features" ]]; then
+    local d
     for d in .specs/features/*/; do
       [[ -d "$d" ]] || continue
-      printf '  %s\n' "$(basename "$d")"
       feat_found=true
+      local feat layout tier
+      feat="$(basename "$d")"
+      layout="legacy"
+      if [[ -f "$d/spec.md" && -f "$d/context.md" && -f "$d/plan.md" && -f "$d/tasks.md" && -f "$d/validation.md" ]]; then
+        layout="standard"
+        if grep -qE '\|\s*\*\*Tier\*\*\s*\|\s*complex\s*\|' "$d/spec.md" 2>/dev/null \
+          || grep -qE '\*\*Tier\*\*.*complex' "$d/plan.md" 2>/dev/null \
+          || grep -q '## Component Boundaries' "$d/plan.md" 2>/dev/null; then
+          if grep -qiE 'Tier[[:space:]]*\|\s*complex|tier.*complex|\*\*Tier\*\*.*complex' "$d/spec.md" "$d/plan.md" 2>/dev/null; then
+            layout="complex"
+          fi
+        fi
+        # Prefer explicit tier field
+        if grep -qE '\| \*\*Tier\*\* \| complex \|' "$d/spec.md" 2>/dev/null; then
+          layout="complex"
+        elif grep -qE '\| \*\*Tier\*\* \| standard \|' "$d/spec.md" 2>/dev/null; then
+          layout="standard"
+        fi
+      elif [[ -f "$d/spec.md" && -f "$d/tasks.md" && -f "$d/validation.md" ]]; then
+        layout="legacy"
+      else
+        layout="incomplete"
+      fi
+      printf '  %s [%s]\n' "$feat" "$layout"
     done
   fi
   [[ "$feat_found" == true ]] || printf '  (none)\n'
@@ -827,10 +1179,16 @@ cmd_status() {
   printf '\nQuick tasks:\n'
   local quick_found=false
   if [[ -d ".specs/quick" ]]; then
+    local d f
+    for d in .specs/quick/*/; do
+      [[ -d "$d" ]] || continue
+      quick_found=true
+      printf '  %s/ [directory]\n' "$(basename "$d")"
+    done
     for f in .specs/quick/*.md; do
       [[ -f "$f" ]] || continue
-      printf '  %s\n' "$(basename "$f" .md)"
       quick_found=true
+      printf '  %s [legacy-file]\n' "$(basename "$f")"
     done
   fi
   [[ "$quick_found" == true ]] || printf '  (none)\n'
@@ -876,6 +1234,14 @@ cmd_doctor() {
     else err "$f — missing"; errors=$((errors + 1)); fi
   done
 
+  printf '\nRecommended files:\n'
+  if [[ -f "HARNESS.md" ]]; then
+    ok "HARNESS.md"
+  else
+    warn "HARNESS.md — missing (recommended for agent lifecycle; run km-spec init or copy from package templates)"
+    warnings=$((warnings + 1))
+  fi
+
   printf '\nRequired directories:\n'
   local required_dirs=(".specs/project" ".specs/codebase" ".specs/features" ".specs/quick")
   for d in "${required_dirs[@]}"; do
@@ -927,20 +1293,50 @@ cmd_doctor() {
       warn "AGENTS.md — missing one or more required file references"
       warnings=$((warnings + 1))
     fi
+    if ! grep -q "HARNESS.md" "AGENTS.md" 2>/dev/null; then
+      warn "AGENTS.md — does not reference HARNESS.md (recommended)"
+      warnings=$((warnings + 1))
+    fi
   fi
 
   printf '\nFeature integrity:\n'
   local feat_checked=false
   if [[ -d ".specs/features" ]]; then
+    local d
     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
+
+      # Core files: spec + tasks required; validation expected
+      for req_file in spec.md tasks.md; do
         if [[ -f "$d$req_file" ]]; then ok "$feat/$req_file"
-        else warn "$feat/$req_file — missing"; warnings=$((warnings + 1)); fi
+        else err "$feat/$req_file — missing"; errors=$((errors + 1)); fi
       done
+
+      if [[ -f "$d/validation.md" ]]; then ok "$feat/validation.md"
+      else warn "$feat/validation.md — missing"; warnings=$((warnings + 1)); fi
+
+      # New layout files: warn if missing (legacy compatible)
+      if [[ -f "$d/context.md" ]]; then ok "$feat/context.md"
+      else warn "$feat/context.md — missing (legacy layout; recommended for 0.2+)"; warnings=$((warnings + 1)); fi
+
+      if [[ -f "$d/plan.md" ]]; then ok "$feat/plan.md"
+      else warn "$feat/plan.md — missing (legacy layout; recommended for 0.2+; replaces design.md role)"; warnings=$((warnings + 1)); fi
+
+      # Lightweight content warnings
+      if [[ -f "$d/spec.md" ]]; then
+        if grep -qE '\{\{[A-Z0-9_]+\}\}' "$d/spec.md" 2>/dev/null; then
+          warn "$feat/spec.md — unresolved template placeholders {{…}}"
+          warnings=$((warnings + 1))
+        fi
+        # Empty requirement table rows that never left NEEDS CLARIFICATION only — informational
+        if ! grep -qE 'REQ-[0-9]+' "$d/spec.md" 2>/dev/null; then
+          warn "$feat/spec.md — no REQ-XXX identifiers found"
+          warnings=$((warnings + 1))
+        fi
+      fi
     done
   fi
   [[ "$feat_checked" == true ]] || info "No features found."
@@ -948,10 +1344,22 @@ cmd_doctor() {
   printf '\nQuick tasks:\n'
   local quick_checked=false
   if [[ -d ".specs/quick" ]]; then
+    local d f
+    for d in .specs/quick/*/; do
+      [[ -d "$d" ]] || continue
+      quick_checked=true
+      local q
+      q="$(basename "$d")"
+      if [[ -f "$d/TASK.md" ]]; then ok "quick/$q/TASK.md"
+      else warn "quick/$q/TASK.md — missing"; warnings=$((warnings + 1)); fi
+      if [[ -f "$d/SUMMARY.md" ]]; then ok "quick/$q/SUMMARY.md"
+      else warn "quick/$q/SUMMARY.md — missing"; warnings=$((warnings + 1)); fi
+    done
     for f in .specs/quick/*.md; do
       [[ -f "$f" ]] || continue
       quick_checked=true
-      ok "$(basename "$f")"
+      warn "$(basename "$f") — legacy single-file quick task (prefer quick/<slug>/TASK.md + SUMMARY.md)"
+      warnings=$((warnings + 1))
     done
   fi
   [[ "$quick_checked" == true ]] || info "No quick tasks found."
@@ -963,6 +1371,9 @@ cmd_doctor() {
     [[ $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
+
+  # Exit non-zero only on errors (warnings are informational)
+  [[ $errors -eq 0 ]]
 }
 
 # ─── Main ─────────────────────────────────────────────────────────────────────