@rpamis/comet 0.3.6 → 0.3.8

package/assets/skills/comet/scripts/comet-archive.sh

@@ -6,6 +6,7 @@
 set -euo pipefail
 
 COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
+COMET_OPENSPEC="${COMET_OPENSPEC:-openspec}"
 
 red() { echo -e "\033[31m$1\033[0m" >&2; }
 green() { echo -e "\033[32m$1\033[0m" >&2; }
@@ -39,9 +40,9 @@ validate_change_name "$CHANGE"
 
 CHANGE_DIR="openspec/changes/$CHANGE"
 YAML="$CHANGE_DIR/.comet.yaml"
-SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 STATE_SH="$SCRIPT_DIR/comet-state.sh"
-TODAY=$(date +%Y-%m-%d)
+TODAY=$(date -u +%Y-%m-%d)
 ARCHIVE_NAME="${TODAY}-${CHANGE}"
 ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
 
@@ -158,45 +159,7 @@ fi
 
 step_ok "Archive target available"
 
-# --- Step 4: Sync delta specs → main specs ---
-
-sync_delta_specs() {
-  local delta_root="$CHANGE_DIR/specs"
-  if [ ! -d "$delta_root" ]; then
-    return 0
-  fi
-
-  for delta_spec_dir in "$delta_root"/*/; do
-    [ -d "$delta_spec_dir" ] || continue
-    local capability
-    capability=$(basename "$delta_spec_dir")
-    local delta_spec="$delta_spec_dir/spec.md"
-    local main_spec="openspec/specs/$capability/spec.md"
-
-    if [ ! -f "$delta_spec" ]; then
-      continue
-    fi
-
-    if [ "$DRY_RUN" -eq 1 ]; then
-      step_dry_run "Would sync: $capability → $main_spec"
-      continue
-    fi
-
-    if [ ! -f "$main_spec" ]; then
-      mkdir -p "openspec/specs/$capability"
-    elif ! cmp -s "$main_spec" "$delta_spec"; then
-      yellow "  [DIFF] Delta spec differs from main spec before sync: $capability"
-      diff -u "$main_spec" "$delta_spec" >&2 || true
-    fi
-    cp "$delta_spec" "$main_spec"
-
-    step_ok "Delta spec synced: $capability → openspec/specs/$capability/spec.md"
-  done
-}
-
-sync_delta_specs
-
-# --- Step 5: Annotate design doc frontmatter ---
+# --- Step 4: Prepare document frontmatter annotation ---
 
 annotate_frontmatter() {
   local file="$1"
@@ -214,6 +177,7 @@ annotate_frontmatter() {
   if head -1 "$file" | grep -q '^---'; then
     local tmp_file
     tmp_file=$(mktemp)
+    chmod 600 "$tmp_file"
     awk -v archive="$ARCHIVE_NAME" -v extra="$extra_fields" '
       /^archived-with:/ { next }
       NR==1 && /^---/ { print; next }
@@ -228,6 +192,7 @@ annotate_frontmatter() {
   else
     local tmp_file
     tmp_file=$(mktemp)
+    chmod 600 "$tmp_file"
     {
       echo "---"
       echo "archived-with: $ARCHIVE_NAME"
@@ -244,27 +209,78 @@ annotate_frontmatter() {
   step_ok "Annotated: $file"
 }
 
-if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
-  annotate_frontmatter "$DESIGN_DOC" "status: final"
-fi
+# --- Step 5: Run OpenSpec archive for delta merge and move ---
 
-# --- Step 6: Annotate plan frontmatter ---
+verify_main_specs_clean() {
+  if [ ! -d "openspec/specs" ]; then
+    return 0
+  fi
 
-if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
-  annotate_frontmatter "$PLAN_PATH" ""
-fi
+  local found=0
+  local matches
+  for spec_file in openspec/specs/*/spec.md; do
+    [ -f "$spec_file" ] || continue
+    matches=$(grep -nE '^## (ADDED|MODIFIED|REMOVED|RENAMED) Requirements$' "$spec_file" 2>/dev/null || true)
+    if [ -n "$matches" ]; then
+      red "FATAL: delta-only section heading leaked into main spec: $spec_file"
+      printf '%s\n' "$matches" >&2
+      found=1
+    fi
+  done
 
-# --- Step 7: Move change to archive ---
+  if [ "$found" -ne 0 ]; then
+    return 1
+  fi
+  return 0
+}
+
+resolve_archive_dir() {
+  if [ -d "$ARCHIVE_DIR" ]; then
+    return 0
+  fi
+  # Fallback: search for any directory matching *-$CHANGE in archive
+  local found
+  found=$(find "openspec/changes/archive" -maxdepth 1 -mindepth 1 -type d -name "*-$CHANGE" 2>/dev/null | head -1 || true)
+  if [ -n "$found" ]; then
+    ARCHIVE_DIR="$found"
+    ARCHIVE_NAME=$(basename "$found")
+    return 0
+  fi
+  return 1
+}
 
 if [ "$DRY_RUN" -eq 1 ]; then
-  step_dry_run "Would move: $CHANGE_DIR → $ARCHIVE_DIR"
+  step_dry_run "Would run OpenSpec archive: $CHANGE"
 else
-  mkdir -p "openspec/changes/archive"
-  mv "$CHANGE_DIR" "$ARCHIVE_DIR"
-  step_ok "Moved to: $ARCHIVE_DIR"
+  if ! command -v "$COMET_OPENSPEC" >/dev/null 2>&1; then
+    red "FATAL: OpenSpec CLI not found: $COMET_OPENSPEC"
+    red "Install OpenSpec or set COMET_OPENSPEC to the openspec executable."
+    exit 1
+  fi
+
+  "$COMET_OPENSPEC" archive "$CHANGE" --yes >&2
+  if ! resolve_archive_dir; then
+    step_fail "OpenSpec archive output not found"
+    exit 1
+  else
+    step_ok "OpenSpec archive completed: $ARCHIVE_DIR"
+  fi
+
+  verify_main_specs_clean
+  step_ok "Main specs verified clean"
+fi
+
+# --- Step 6: Annotate design doc and plan frontmatter ---
+
+if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
+  annotate_frontmatter "$DESIGN_DOC" "status: final"
+fi
+
+if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
+  annotate_frontmatter "$PLAN_PATH" ""
 fi
 
-# --- Step 8: Mark archived via comet-state transition ---
+# --- Step 7: Mark archived via comet-state transition ---
 
 ARCHIVE_YAML="$ARCHIVE_DIR/.comet.yaml"
 
@@ -279,7 +295,7 @@ else
   fi
 fi
 
-# --- Step 9: Print summary ---
+# --- Step 8: Print summary ---
 
 echo "" >&2
 if [ "$DRY_RUN" -eq 1 ]; then

package/assets/skills/comet/scripts/comet-guard.sh

@@ -34,18 +34,26 @@ validate_change_name() {
   fi
 }
 
-validate_change_name "$1"
-
-CHANGE="$1"
-PHASE="$2"
-APPLY=0
-SCRIPT_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
-if [[ "${3:-}" == "--apply" ]]; then
-  APPLY=1
-fi
-CHANGE_DIR="openspec/changes/$CHANGE"
-if [ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
-  CHANGE_DIR="openspec/changes/archive/$CHANGE"
+if [ "${COMET_GUARD_SOURCE_ONLY:-0}" = "1" ]; then
+  CHANGE="${CHANGE:-}"
+  PHASE="${PHASE:-}"
+  APPLY="${APPLY:-0}"
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+  CHANGE_DIR="${CHANGE_DIR:-}"
+else
+  validate_change_name "$1"
+
+  CHANGE="$1"
+  PHASE="$2"
+  APPLY=0
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+  if [[ "${3:-}" == "--apply" ]]; then
+    APPLY=1
+  fi
+  CHANGE_DIR="openspec/changes/$CHANGE"
+  if [ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
+    CHANGE_DIR="openspec/changes/archive/$CHANGE"
+  fi
 fi
 
 BLOCK=0
@@ -94,6 +102,27 @@ tasks_has_any() {
   [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
 }
 
+plan_tasks_all_done() {
+  local plan
+  plan=$(yaml_field_value "plan" 2>/dev/null || true)
+
+  if [ -z "$plan" ] || [ "$plan" = "null" ]; then
+    return 0
+  fi
+  if [ ! -f "$plan" ]; then
+    echo "plan file is missing at $plan" >&2
+    echo "Next: restore the Superpowers plan file or update .comet.yaml plan before leaving build." >&2
+    return 1
+  fi
+  if grep -q '^[[:space:]]*- \[ \]' "$plan"; then
+    echo "Unfinished Superpowers plan tasks:" >&2
+    grep -n '^[[:space:]]*- \[ \]' "$plan" >&2 || true
+    echo "Next: check off corresponding completed plan tasks, then commit the plan update." >&2
+    return 1
+  fi
+  return 0
+}
+
 yaml_field_value() {
   local field="$1"
   local yaml="$CHANGE_DIR/.comet.yaml"
@@ -182,6 +211,17 @@ is_windows_bash() {
 
 run_command_string() {
   local command="$1"
+  if [ -z "$command" ]; then
+    red "ERROR: build/verify command is empty" >&2
+    return 1
+  fi
+  # Basic command injection guard: reject dangerous shell metacharacters
+  # Quotes are allowed to support paths with spaces (e.g. Windows)
+  if [[ "$command" =~ [\;\|\&\$\`] ]]; then
+    red "ERROR: build/verify command contains shell metacharacters: $command" >&2
+    red "Allowed: alphanumeric, spaces, hyphens, underscores, dots, colons, forward slashes, quotes" >&2
+    return 1
+  fi
   echo "+ $command" >&2
   "$COMET_BASH" -lc "$command"
 }
@@ -219,12 +259,14 @@ handoff_source_files() {
 }
 
 compute_handoff_hash() {
-  handoff_source_files | while IFS= read -r file; do
+  local hash_input
+  hash_input=$(handoff_source_files | while IFS= read -r file; do
     if [ -f "$file" ]; then
       printf 'path:%s\n' "$file"
       printf 'sha256:%s\n' "$(hash_file "$file")"
     fi
-  done | hash_stream
+  done)
+  printf '%s' "$hash_input" | hash_stream
 }
 
 preflight() {
@@ -344,6 +386,47 @@ build_mode_allowed_for_workflow() {
   esac
 }
 
+subagent_dispatch_confirmed() {
+  local build_mode subagent_dispatch
+  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
+  subagent_dispatch=$(yaml_field_value "subagent_dispatch" 2>/dev/null || true)
+
+  if [ "$build_mode" != "subagent-driven-development" ]; then
+    return 0
+  fi
+
+  if [ "$subagent_dispatch" = "confirmed" ]; then
+    return 0
+  fi
+
+  echo "subagent_dispatch must be confirmed before using build_mode=subagent-driven-development" >&2
+  echo "Next: confirm the current platform has a real background subagent/Task/multi-agent dispatcher, then run:" >&2
+  echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE subagent_dispatch confirmed" >&2
+  echo "Or ask the user to switch to executing-plans and run:" >&2
+  echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE build_mode executing-plans" >&2
+  return 1
+}
+
+tdd_mode_selected() {
+  local workflow tdd_mode
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
+  tdd_mode=$(yaml_field_value "tdd_mode" 2>/dev/null || true)
+
+  case "$workflow" in
+    hotfix|tweak) return 0 ;;
+  esac
+
+  case "$tdd_mode" in
+    tdd|direct) return 0 ;;
+    *)
+      echo "tdd_mode must be tdd or direct for full workflow, got '${tdd_mode:-null}'" >&2
+      echo "Next: ask the user to choose TDD enforcement level, then run:" >&2
+      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE tdd_mode <tdd|direct>" >&2
+      return 1
+      ;;
+  esac
+}
+
 verify_result_is_pass() {
   local result
   result=$(yaml_field_value "verify_result" 2>/dev/null || true)
@@ -416,7 +499,7 @@ design_handoff_markdown_traceable() {
     echo "handoff markdown is missing Generated-by marker" >&2
     missing=1
   }
-  grep -Eq '^- Mode: (compact|full)$' "$markdown" || {
+  grep -Eq '^- Mode: (compact|full|beta)$' "$markdown" || {
     echo "handoff markdown is missing Mode marker" >&2
     missing=1
   }
@@ -435,6 +518,47 @@ design_handoff_markdown_traceable() {
   [ "$missing" -eq 0 ]
 }
 
+context_compression_mode() {
+  local mode
+  mode=$(yaml_field_value "context_compression" 2>/dev/null || true)
+  printf '%s\n' "${mode:-off}"
+}
+
+beta_spec_json_structurally_valid() {
+  local context missing=0
+  if [ "$(context_compression_mode)" != "beta" ]; then
+    return 0
+  fi
+
+  context=$(yaml_field_value "handoff_context" 2>/dev/null || true)
+  if [ -z "$context" ] || [ "$context" = "null" ]; then
+    echo "handoff_context is missing from .comet.yaml" >&2
+    return 1
+  fi
+  if [ ! -s "$context" ]; then
+    echo "spec-context.json is missing or empty: $context" >&2
+    return 1
+  fi
+
+  # Validate required JSON fields
+  grep -q '"change"' "$context" || { echo "spec-context.json missing 'change' field" >&2; return 1; }
+  grep -q '"phase"' "$context" || { echo "spec-context.json missing 'phase' field" >&2; return 1; }
+  grep -q '"mode": "beta"' "$context" || { echo "spec-context.json mode is not beta" >&2; return 1; }
+  grep -q '"files"' "$context" || { echo "spec-context.json missing 'files' field" >&2; return 1; }
+  grep -q '"context_hash"' "$context" || { echo "spec-context.json missing 'context_hash' field" >&2; return 1; }
+
+  # Verify all source files are referenced in the JSON
+  handoff_source_files | while IFS= read -r file; do
+    [ -f "$file" ] || continue
+    if ! grep -qF "$file" "$context"; then
+      echo "spec-context.json missing source file reference: $file" >&2
+      exit 2
+    fi
+  done || missing=1
+
+  [ "$missing" -eq 0 ]
+}
+
 design_doc_frontmatter_has() {
   local design_doc="$1"
   local field="$2"
@@ -494,32 +618,55 @@ guard_open() {
 guard_design() {
   echo "=== Guard: design → build ===" >&2
 
-  local design_doc
+  local design_doc workflow
   design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
 
   check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
   check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
   check "tasks.md exists" file_nonempty "$CHANGE_DIR/tasks.md"
   check "design handoff context exists" design_handoff_context_valid
   check "design handoff markdown is traceable" design_handoff_markdown_traceable
+  if [ "$(context_compression_mode)" = "beta" ]; then
+    check "beta spec-context.json is structurally valid" beta_spec_json_structurally_valid
+  fi
+
+  if [ "$workflow" = "full" ]; then
+    # Full workflow: design_doc is REQUIRED
+    check "design_doc is recorded for full workflow" design_doc_recorded
+  fi
 
   if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
     check "Design Doc ($design_doc) exists" file_nonempty "$design_doc"
     check "Design Doc frontmatter links current change" design_doc_links_current_change
     check "Design Doc declares technical design role" design_doc_declares_technical_role
     check "Design Doc declares OpenSpec as canonical spec" design_doc_declares_canonical_spec
-  else
-    warn "  [WARN] No design_doc recorded in .comet.yaml"
+  elif [ "$workflow" != "full" ]; then
+    warn "  [WARN] No design_doc recorded in .comet.yaml (optional for hotfix/tweak)"
   fi
 }
 
+design_doc_recorded() {
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
+    return 0
+  fi
+  echo "design_doc must point to an existing Superpowers Design Doc for full workflow before leaving design." >&2
+  echo "Next: create the Design Doc and run: \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE design_doc <path>" >&2
+  return 1
+}
+
 guard_build() {
   echo "=== Guard: build → verify ===" >&2
 
   check "isolation selected" isolation_selected
   check "build_mode selected" build_mode_selected
   check "build_mode allowed for workflow" build_mode_allowed_for_workflow
+  check "subagent dispatch confirmed" subagent_dispatch_confirmed
+  check "tdd_mode selected" tdd_mode_selected
   check "tasks.md all tasks checked" tasks_all_done
+  check "Superpowers plan all tasks checked" plan_tasks_all_done
   check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
   check "Build passes" build_passes
 }
@@ -538,6 +685,7 @@ guard_archive() {
 
   check "archived is true" archived_is_true
   check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
   check "tasks.md all tasks checked" tasks_all_done
 }
 
@@ -560,6 +708,14 @@ apply_state_update() {
 
 # --- Main ---
 
+if [ "${COMET_GUARD_SOURCE_ONLY:-0}" = "1" ]; then
+  return 0 2>/dev/null
+  # shellcheck disable=SC2317  # unreachable if sourced; fallback for direct execution
+  red "ERROR: COMET_GUARD_SOURCE_ONLY=1 is only for sourcing, not direct execution" >&2
+  # shellcheck disable=SC2317
+  exit 1
+fi
+
 case "$PHASE" in
   open)     preflight ; guard_open ;;
   design)   preflight ; guard_design ;;

package/assets/skills/comet/scripts/comet-handoff.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # Comet Handoff — creates machine-owned context packages between phases
 # Usage: comet-handoff.sh <change-name> design --write [--full]
+#        comet-handoff.sh <change-name> --hash-only
 
 set -euo pipefail
 
@@ -8,6 +9,7 @@ COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
 
 red() { echo -e "\033[31m$1\033[0m" >&2; }
 green() { echo -e "\033[32m$1\033[0m" >&2; }
+warn() { echo -e "\033[33m$1\033[0m" >&2; }
 
 validate_change_name() {
   local name="$1"
@@ -103,12 +105,14 @@ source_files() {
 }
 
 compute_context_hash() {
-  source_files | while IFS= read -r file; do
+  local hash_input
+  hash_input=$(source_files | while IFS= read -r file; do
     if [ -f "$file" ]; then
       printf 'path:%s\n' "$file"
       printf 'sha256:%s\n' "$(hash_file "$file")"
     fi
-  done | hash_stream
+  done)
+  printf '%s' "$hash_input" | hash_stream
 }
 
 json_escape() {
@@ -196,6 +200,86 @@ write_json_context() {
   } > "$output"
 }
 
+write_spec_projection_for_file() {
+  local file="$1"
+  echo "## $file"
+  echo ""
+  echo "- Source: $file"
+  echo "- Lines: 1-$(file_line_count "$file")"
+  echo "- SHA256: $(hash_file "$file")"
+  echo ""
+  echo '```md'
+  cat "$file"
+  echo '```'
+  echo ""
+}
+
+write_spec_markdown_context() {
+  local output="$1"
+  {
+    echo "# Comet Spec Context"
+    echo ""
+    echo "- Change: $CHANGE"
+    echo "- Phase: design"
+    echo "- Mode: beta"
+    echo "- Context hash: $CONTEXT_HASH"
+    echo ""
+    echo "Generated-by: comet-handoff.sh"
+    echo ""
+    echo "OpenSpec remains the canonical capability spec. This beta context pack verbatim-projects spec files and references supporting artifacts by hash, not an agent-authored summary."
+    echo ""
+    echo "## Source References"
+    echo ""
+    source_files | while IFS= read -r file; do
+      [ -f "$file" ] || continue
+      echo "- Source: $file"
+      echo "- SHA256: $(hash_file "$file")"
+    done
+    echo ""
+    echo "## Acceptance Projection"
+    echo ""
+    if [ -d "$CHANGE_DIR/specs" ]; then
+      find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort | while IFS= read -r file; do
+        write_spec_projection_for_file "$file"
+      done
+    else
+      echo "No delta spec files found."
+      echo ""
+    fi
+    echo "Full source files remain canonical. If a required heading or scenario is missing here, regenerate the handoff or read the source spec directly. Supporting files (proposal, design, tasks) are referenced by hash only."
+  } > "$output"
+}
+
+write_spec_json_context() {
+  local output="$1"
+  {
+    echo "{"
+    echo "  \"change\": \"$(json_escape "$CHANGE")\","
+    echo "  \"phase\": \"design\","
+    echo "  \"mode\": \"beta\","
+    echo "  \"canonical_spec\": \"openspec\","
+    echo "  \"generated_by\": \"comet-handoff.sh\","
+    echo "  \"context_hash\": \"$CONTEXT_HASH\","
+    echo "  \"files\": ["
+    local first_file=1
+    while IFS= read -r file; do
+      [ -f "$file" ] || continue
+      local role="supporting"
+      case "$file" in
+        */specs/*/spec.md) role="spec" ;;
+      esac
+      if [ "$first_file" -eq 0 ]; then
+        echo ","
+      fi
+      first_file=0
+      printf '    { "path": "%s", "sha256": "%s", "role": "%s" }' "$(json_escape "$file")" "$(hash_file "$file")" "$role"
+    done < <(source_files)
+    echo ""
+    echo "  ]"
+    echo "}"
+  } > "$output"
+}
+
 CHANGE="${1:-}"
 PHASE="${2:-}"
 MODE="${3:-}"
@@ -203,6 +287,25 @@ FULL_FLAG="${4:-}"
 
 validate_change_name "$CHANGE"
 
+# --hash-only: compute and output context hash without generating handoff files
+if [ "${PHASE:-}" = "--hash-only" ]; then
+  CHANGE_DIR="openspec/changes/$CHANGE"
+  if [ ! -d "$CHANGE_DIR" ]; then
+    red "ERROR: change directory not found: $CHANGE_DIR"
+    exit 1
+  fi
+  for required in proposal.md design.md tasks.md; do
+    if [ ! -s "$CHANGE_DIR/$required" ]; then
+      red "ERROR: required file missing or empty: $CHANGE_DIR/$required"
+      exit 1
+    fi
+  done
+  CONTEXT_HASH="$(compute_context_hash)"
+  printf '%s
+' "$CONTEXT_HASH"
+  exit 0
+fi
+
 if [ "$PHASE" != "design" ] || [ "$MODE" != "--write" ]; then
   red "Usage: comet-handoff.sh <change-name> design --write [--full]"
   exit 1
@@ -242,13 +345,37 @@ for required in proposal.md design.md tasks.md; do
 done
 
 HANDOFF_DIR="$CHANGE_DIR/.comet/handoff"
-CONTEXT_JSON="$HANDOFF_DIR/design-context.json"
-CONTEXT_MD="$HANDOFF_DIR/design-context.md"
+CONTEXT_COMPRESSION="$(yaml_field_value context_compression 2>/dev/null || true)"
+CONTEXT_COMPRESSION="${CONTEXT_COMPRESSION:-off}"
+case "$CONTEXT_COMPRESSION" in
+  off)
+    CONTEXT_JSON="$HANDOFF_DIR/design-context.json"
+    CONTEXT_MD="$HANDOFF_DIR/design-context.md"
+    ;;
+  beta)
+    if [ "$HANDOFF_MODE" = "full" ]; then
+      warn "[HANDOFF] --full is ignored in beta mode; spec files are projected verbatim"
+    fi
+    HANDOFF_MODE="beta"
+    CONTEXT_JSON="$HANDOFF_DIR/spec-context.json"
+    CONTEXT_MD="$HANDOFF_DIR/spec-context.md"
+    ;;
+  *)
+    red "ERROR: invalid context_compression: $CONTEXT_COMPRESSION"
+    red "Valid values: off, beta"
+    exit 1
+    ;;
+esac
 mkdir -p "$HANDOFF_DIR"
 
 CONTEXT_HASH="$(compute_context_hash)"
-write_markdown_context "$CONTEXT_MD"
-write_json_context "$CONTEXT_JSON"
+if [ "$CONTEXT_COMPRESSION" = "beta" ]; then
+  write_spec_markdown_context "$CONTEXT_MD"
+  write_spec_json_context "$CONTEXT_JSON"
+else
+  write_markdown_context "$CONTEXT_MD"
+  write_json_context "$CONTEXT_JSON"
+fi
 
 if [ -x "$STATE_SH" ] || [ -f "$STATE_SH" ]; then
   "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_context "$CONTEXT_JSON" >/dev/null