@rpamis/comet 0.2.7 → 0.2.9

package/README.md

@@ -8,9 +8,11 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rpamis/comet/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/rpamis/comet/ci.yml?branch=master&style=flat-square&label=CI" /></a>
+  <a href="https://deepwiki.com/rpamis/comet"><img alt="DeepWiki" src="https://img.shields.io/badge/DeepWiki-rpamis%2Fcomet-blue?style=flat-square" /></a>
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm weekly download count" src="https://img.shields.io/npm/dw/@rpamis/comet?style=flat-square&label=Downloads/wk" /></a>
   <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
 </p>
 
@@ -42,6 +44,28 @@ Superpowers generates Spec documents after brainstorming, but these documents ty
 
 The main entry `/comet` supports current Spec state detection, suitable for long tasks — after completing and closing CC midway, just `/comet continue` and Comet will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
 
+At the same time, Comet provides full Spec lifecycle management. During execution, it links OpenSpec change/spec artifacts with Superpowers design and planning documents, then automates handoff, state updates, validation, and archive sync so users do not have to repeatedly remind the Agent to keep documents synchronized and connected.
+
+## What You'll Learn
+
+Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec management capabilities, but prefer Superpowers' TDD-driven approach for coding.
+
+Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real practice. The Comet project can serve as a reference:
+
+- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature: Skill trigger prints on CC). Comet triggers many capabilities from OpenSpec and Superpowers. How is this Prompt written?
+
+- **How to make combined Skills flow automatically across phases** — Not relying on manual intervention. Comet's 5-phase flow can automatically trigger Skills for the core process except for necessary user choices, while the state machine also protects state transition reliability.
+
+- **How to turn the Spec lifecycle into a resumable workflow** — Comet links OpenSpec change/spec artifacts with Superpowers design and planning documents, then records phase, execution mode, verification results, and archive status in `.comet.yaml`, so the Agent can resume after interruption instead of rereading documents and guessing progress.
+
+- **How to turn document synchronization from "user reminders" into automation** — Comet puts handoff, state updates, validation, and archive sync into scripted flows, reducing repeated prompts like "remember to update the design doc", "remember to sync the spec", and "remember to archive the change".
+
+- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at phase exits. Scripts such as `comet-guard.sh`, `comet-yaml-validate.sh`, and `comet-state.sh` check tasks, state fields, verification evidence, and archive conditions before allowing the workflow to advance.
+
+- **How to distribute and install Skills across platforms** — Comet supports multiple AI coding platforms, project/global installation, Chinese/English Skill choices, and platform-specific directory differences such as Antigravity using different project-level and global paths. It can be a reference for CLI installers and Skill package structure.
+
+- **How to turn shell scripts into Agent workflow infrastructure** — Comet's scripts need to work across macOS, Linux, and Windows Git Bash while handling hashes, YAML fields, state machines, and archive flows. It shows how to move fragile workflow control out of scattered Prompt text and into testable, reusable tools.
+
 ## Install
 
 ```bash
@@ -63,7 +87,7 @@ comet init
 4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
 5. Install [Superpowers](https://github.com/obra/superpowers) skills
 6. Deploy Comet skills (in your chosen language) to selected platforms
-7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
+7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories for project-scope installs
 
 > [!TIP]
 > update version
@@ -81,40 +105,50 @@ comet init
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `comet init [path]` | Initialize Comet workflow |
-| `comet status [path]` | Show active changes, task progress, and next workflow command |
-| `comet doctor [path]` | Diagnose project/global Comet installation health |
-| `comet update [path]` | Update the npm package and installed Comet skills |
-| `comet --help` | Show help |
-| `comet --version` | Show version |
+<details>
+<summary><code>comet init [path]</code> — Initialize Comet workflow</summary>
 
-### init Options
+Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
 
 | Option | Description |
 |--------|-------------|
-| `--yes` | Non-interactive mode, auto-select detected platforms |
+| `--yes` | Non-interactive mode, auto-select detected platforms (or all if none detected) |
+| `--scope <scope>` | Install scope: `project` or `global` |
 | `--skip-existing` | Skip already installed components |
 | `--overwrite` | Overwrite already installed components |
 | `--json` | Output structured JSON |
 
 When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
 
-### status Options
+</details>
+
+<details>
+<summary><code>comet status [path]</code> — Show active changes and next workflow command</summary>
+
+Displays active changes, task progress, and the recommended next Comet workflow command.
 
 | Option | Description |
 |--------|-------------|
 | `--json` | Output active changes with `nextCommand` |
 
-### doctor Options
+</details>
+
+<details>
+<summary><code>comet doctor [path]</code> — Diagnose Comet installation health</summary>
+
+Checks project/global installation health, working directories, installed skills, scripts, and Comet state files.
 
 | Option | Description |
 |--------|-------------|
 | `--json` | Output structured diagnostic results |
 | `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
 
-### update Options
+</details>
+
+<details>
+<summary><code>comet update [path]</code> — Update Comet package and skills</summary>
+
+Updates the npm package and refreshes installed Comet skills in detected project/global targets.
 
 | Option | Description |
 |--------|-------------|
@@ -122,10 +156,20 @@ When multiple existing components are found on the same platform, interactive in
 | `--language <lang>` | Override detected skill language (`en`, `zh`) |
 | `--scope <scope>` | Update only `global` or `project` scope |
 
+</details>
+
+| Command | Description |
+|---------|-------------|
+| `comet --help` | Show help |
+| `comet --version` | Show version |
+
 ## Supported Platforms
 
 `comet init` supports 28 AI coding platforms:
 
+<details>
+<summary>View full platform list</summary>
+
 | Platform | Skills Dir | Platform | Skills Dir |
 |----------|-----------|----------|-----------|
 | Claude Code | `.claude/` | Cursor | `.cursor/` |
@@ -140,15 +184,20 @@ When multiple existing components are found on the same platform, interactive in
 | CoStrict | `.cospec/` | Crush | `.crush/` |
 | Factory Droid | `.factory/` | iFlow | `.iflow/` |
 | Pi | `.pi/` | Qoder | `.qoder/` |
-| Antigravity | `.agent/` | Bob Shell | `.bob/` |
+| Antigravity | `.agents/` | Bob Shell | `.bob/` |
 | ForgeCode | `.forge/` | Trae | `.trae/` |
 
+</details>
+
 ## Skills
 
 After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
 
 ### Comet Skills
 
+<details>
+<summary>View Comet skills</summary>
+
 | Skill | Description |
 |-------|-------------|
 | `/comet` | Main entry — auto-detects phase and dispatches to sub-commands |
@@ -160,15 +209,23 @@ After `comet init`, three groups of skills are installed to the selected platfor
 | `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
 | `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
 
+</details>
+
 ### Guard & Automation Scripts
 
+<details>
+<summary>View script list</summary>
+
 | Script | Purpose |
 |--------|---------|
 | `comet-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml` |
+| `comet-handoff.sh` | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
 | `comet-archive.sh` | One-command archive — validates state, syncs specs, moves to archive, updates status |
 | `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
 | `comet-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
 
+</details>
+
 ### OpenSpec Skills
 
 Spec lifecycle management: propose, explore, sync, verify, archive, and more.
@@ -219,37 +276,50 @@ Comet uses a decoupled state architecture with separate YAML files:
 | `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
 | `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
 
+All states and execution phases are updated via scripts, and each phase verifies that tasks are truly complete before advancing. Compared to storing complex state rules only in Skill text, this script-backed state machine gives Comet more reliable phase transitions, correct YAML, and easier breakpoint recovery; agents can read the current Spec situation through Comet's built-in commands.
+
+<details>
+<summary>View key .comet.yaml fields</summary>
+
 **Key Fields in `.comet.yaml`:**
 
 ```yaml
 workflow: full
 phase: build
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 build_mode: subagent-driven-development
 isolation: branch
-verify_mode: light
+verify_mode: null
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 verify_result: pending
-verification_report: docs/superpowers/reports/YYYY-MM-DD-change-verify.md
+verification_report: null
 branch_status: pending
 verified_at: null
 archived: false
+direct_override: false
+build_command: null
+verify_command: null
+handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
+handoff_hash: <sha256>
 ```
 
-In full workflow, `build_mode` and `isolation` may temporarily be `null` at init time, but they must be resolved before `build → verify`. `direct` is allowed by default only for hotfix/tweak; full workflow requires `direct_override: true`. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
+In full workflow, `build_mode`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
 
-All states and execution phases are updated via scripts, and **each phase verifies that tasks are truly completed before exiting — conditions are met before the phase exits and state is updated**. Compared to recording complex state management mechanisms in Skills, the script approach strongly guarantees the reliability of core state transitions, correctness of YAML files, and convenience of breakpoint recovery — Agents only need to use Comet's built-in commands to read state and know the current Spec's situation.
+</details>
 
 ### Reliability Features
 
 Comet ensures agent execution reliability through automated state transitions:
 
+<details>
+<summary>View reliability features</summary>
+
 1. **Entry Verification** — Each phase validates preconditions before execution
    - Checks file existence, state consistency, and phase transitions
    - Outputs `[HARD STOP]` with actionable suggestions if validation fails
 
 2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
-   - All phase transitions (design → build → verify → archive) use `guard --apply`
+   - All phase transitions (open → design/build → verify → archive) use `guard --apply`
    - No manual state editing required — eliminates write-verification errors
    - `comet-state.sh` is the agents' exclusive interface for state operations
    - Guard and archive scripts use `comet-state.sh` internally for state management
@@ -257,7 +327,7 @@ Comet ensures agent execution reliability through automated state transitions:
 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
    - Validates required and optional fields
    - Validates enum values, including `direct_override`
-   - Validates referenced file paths exist
+   - Validates `design_doc`, `plan`, and `handoff_context` paths exist, plus `handoff_hash` format
    - Detects unknown/typos fields
 
 4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
@@ -277,7 +347,7 @@ Comet ensures agent execution reliability through automated state transitions:
    - Moves change to archive directory and updates `archived: true`
    - Supports `--dry-run` for preview
 
-**Security**: Path traversal protection on all change name inputs
+</details>
 
 ## Project Structure
 
@@ -287,6 +357,7 @@ your-project/
 │   ├── comet/SKILL.md
 │   │   └── scripts/
 │   │       ├── comet-guard.sh       # Phase transition guard (--apply auto-updates state)
+│   │       ├── comet-handoff.sh     # Design handoff (OpenSpec → Superpowers context tracing)
 │   │       ├── comet-archive.sh     # One-command archive automation
 │   │       ├── comet-yaml-validate.sh # Schema validator
 │   │       └── comet-state.sh       # Unified state management (init/set/get/check/scale)
@@ -308,51 +379,15 @@ your-project/
     └── plans/                   # Implementation plans
 ```
 
-## What You'll Learn
-
-Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec management capabilities, but prefer Superpowers' TDD-driven approach for coding.
-
-Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real practice. The Comet project can serve as a reference:
-
-- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature: Skill trigger prints on CC). Comet will trigger many capabilities from OpenSpec and Superpowers — how is this Prompt written?
-
-- **How to make combined Skills multi-phase auto-flow** — Not relying on manual intervention. Comet's 5-phase flow automatically triggers Skills for core processes except necessary user selections, while the **state machine mechanism** also ensures state transition reliability.
-
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, PR process, and guidance for adding platforms or skills.
 
-```bash
-# Clone
-git clone https://github.com/rpamis/comet
-cd comet
-
-# Install dependencies
-pnpm install
-
-# Dev mode (watch)
-pnpm dev
-
-# Build
-pnpm build
-
-# Test (unit + coverage)
-pnpm test
-pnpm test:coverage
-pnpm test:shell         # bats shell tests
-
-# Lint & format
-pnpm lint
-pnpm format
-```
-
 See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 
-## Security
+## Roadmap
 
-- Pre-publish scan for API keys, secrets, tokens, and private keys
-- `.npmignore` prevents source code and config files from entering the npm package
-- `.gitignore` covers secrets, credentials, IDE configs, and more
+Track our development progress and upcoming features on the [Comet Roadmap](https://github.com/orgs/rpamis/projects/1).
 
 ## License
 

package/assets/manifest.json

@@ -4,6 +4,7 @@
     "comet/SKILL.md",
     "comet/scripts/comet-guard.sh",
     "comet/scripts/comet-state.sh",
+    "comet/scripts/comet-handoff.sh",
     "comet/scripts/comet-archive.sh",
     "comet/scripts/comet-yaml-validate.sh",
     "comet-open/SKILL.md",

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

@@ -73,11 +73,49 @@ yaml_field() {
     bash "$STATE_SH" get "$CHANGE" "$field" 2>/dev/null
   else
     if [ -f "$YAML" ]; then
-      grep "^${field}:" "$YAML" | sed "s/^${field}: *//" | tr -d '"' | tr -d "'"
+      local value
+      value=$(grep "^${field}:" "$YAML" 2>/dev/null | sed "s/^${field}: *//" || true)
+      value=$(strip_inline_comment "$value")
+      strip_wrapping_quotes "$value"
     fi
   fi
 }
 
+strip_inline_comment() {
+  local value="$1"
+  printf '%s\n' "$value" | awk -v squote="'" '
+    {
+      out = ""
+      quote = ""
+      for (i = 1; i <= length($0); i++) {
+        c = substr($0, i, 1)
+        if (quote == "") {
+          if (c == "\"" || c == squote) {
+            quote = c
+          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
+            sub(/[[:space:]]+$/, "", out)
+            print out
+            next
+          }
+        } else if (c == quote) {
+          quote = ""
+        }
+        out = out c
+      }
+      print out
+    }
+  '
+}
+
+strip_wrapping_quotes() {
+  local value="$1"
+  case "$value" in
+    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
+    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
+    *) printf '%s\n' "$value" ;;
+  esac
+}
+
 if [ ! -f "$YAML" ]; then
   red "FATAL: .comet.yaml not found in $CHANGE_DIR/"
   exit 1

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

@@ -98,10 +98,37 @@ yaml_field_value() {
   if [ -f "$yaml" ]; then
     local value
     value=$(grep "^${field}:" "$yaml" 2>/dev/null | sed "s/^${field}: *//" || true)
+    value=$(strip_inline_comment "$value")
     strip_wrapping_quotes "$value"
   fi
 }
 
+strip_inline_comment() {
+  local value="$1"
+  printf '%s\n' "$value" | awk -v squote="'" '
+    {
+      out = ""
+      quote = ""
+      for (i = 1; i <= length($0); i++) {
+        c = substr($0, i, 1)
+        if (quote == "") {
+          if (c == "\"" || c == squote) {
+            quote = c
+          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
+            sub(/[[:space:]]+$/, "", out)
+            print out
+            next
+          }
+        } else if (c == quote) {
+          quote = ""
+        }
+        out = out c
+      }
+      print out
+    }
+  '
+}
+
 strip_wrapping_quotes() {
   local value="$1"
   case "$value" in
@@ -130,6 +157,7 @@ project_config_value() {
   for config in ".comet.yaml" "comet.yaml" ".comet.yml" "comet.yml"; do
     if [ -f "$config" ]; then
       value=$(grep "^${field}:" "$config" 2>/dev/null | sed "s/^${field}: *//" || true)
+      value=$(strip_inline_comment "$value")
       value=$(strip_wrapping_quotes "$value")
       if [ -n "$value" ] && [ "$value" != "null" ]; then
         echo "$value"
@@ -156,6 +184,47 @@ run_command_string() {
   bash -lc "$command"
 }
 
+hash_stream() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 | awk '{print $1}'
+  else
+    echo "sha256sum or shasum is required" >&2
+    return 1
+  fi
+}
+
+hash_file() {
+  local file="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file" | awk '{print $1}'
+  else
+    echo "sha256sum or shasum is required" >&2
+    return 1
+  fi
+}
+
+handoff_source_files() {
+  printf '%s\n' "$CHANGE_DIR/proposal.md"
+  printf '%s\n' "$CHANGE_DIR/design.md"
+  printf '%s\n' "$CHANGE_DIR/tasks.md"
+  if [ -d "$CHANGE_DIR/specs" ]; then
+    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
+  fi
+}
+
+compute_handoff_hash() {
+  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
+}
+
 preflight() {
 
   if [ ! -d "$CHANGE_DIR" ]; then
@@ -291,6 +360,118 @@ branch_status_handled() {
   [ "$status" = "handled" ]
 }
 
+design_handoff_context_valid() {
+  local context recorded_hash actual_hash markdown
+  context=$(yaml_field_value "handoff_context" 2>/dev/null || true)
+  recorded_hash=$(yaml_field_value "handoff_hash" 2>/dev/null || true)
+
+  if [ -z "$context" ] || [ "$context" = "null" ]; then
+    echo "handoff_context is missing from .comet.yaml" >&2
+    echo "Next: run bash \"\$COMET_HANDOFF\" $CHANGE design --write before invoking Superpowers." >&2
+    return 1
+  fi
+  if [ ! -s "$context" ]; then
+    echo "handoff_context does not point to a non-empty file: $context" >&2
+    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
+    return 1
+  fi
+  if [[ ! "$recorded_hash" =~ ^[a-f0-9]{64}$ ]]; then
+    echo "handoff_hash is missing or invalid: ${recorded_hash:-null}" >&2
+    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
+    return 1
+  fi
+
+  actual_hash=$(compute_handoff_hash)
+  if [ "$actual_hash" != "$recorded_hash" ]; then
+    echo "OpenSpec artifacts changed after handoff was generated." >&2
+    echo "Expected handoff_hash: $recorded_hash" >&2
+    echo "Actual handoff_hash:   $actual_hash" >&2
+    echo "Next: rerun comet-handoff.sh so Superpowers receives the current OpenSpec context." >&2
+    return 1
+  fi
+
+  markdown="${context%.json}.md"
+  if [ ! -s "$markdown" ]; then
+    echo "design handoff markdown is missing or empty: $markdown" >&2
+    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
+    return 1
+  fi
+}
+
+design_handoff_markdown_traceable() {
+  local context markdown missing=0
+  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
+  markdown="${context%.json}.md"
+  if [ ! -s "$markdown" ]; then
+    echo "design handoff markdown is missing or empty: $markdown" >&2
+    return 1
+  fi
+  grep -q '^Generated-by: comet-handoff\.sh$' "$markdown" || {
+    echo "handoff markdown is missing Generated-by marker" >&2
+    missing=1
+  }
+  grep -Eq '^- Mode: (compact|full)$' "$markdown" || {
+    echo "handoff markdown is missing Mode marker" >&2
+    missing=1
+  }
+  handoff_source_files | while IFS= read -r file; do
+    [ -f "$file" ] || continue
+    if ! grep -q "^- Source: $file$" "$markdown"; then
+      echo "handoff markdown is missing source reference: $file" >&2
+      exit 2
+    fi
+    if ! grep -q "^- SHA256: $(hash_file "$file")$" "$markdown"; then
+      echo "handoff markdown is missing current sha256 for: $file" >&2
+      exit 2
+    fi
+  done || missing=1
+
+  [ "$missing" -eq 0 ]
+}
+
+design_doc_frontmatter_has() {
+  local design_doc="$1"
+  local field="$2"
+  local expected="$3"
+  awk '
+    {
+      line = $0
+      sub(/^\357\273\277/, "", line)
+    }
+    !in_fm && line == "---" { in_fm = 1; next }
+    in_fm && line == "---" { exit }
+    in_fm { print line }
+  ' "$design_doc" | grep -Eq "^${field}: ['\"]?${expected}['\"]?[[:space:]]*$"
+}
+
+design_doc_links_current_change() {
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  if [ -z "$design_doc" ] || [ "$design_doc" = "null" ] || [ ! -s "$design_doc" ]; then
+    echo "design_doc must point to an existing Superpowers Design Doc before leaving design." >&2
+    return 1
+  fi
+  design_doc_frontmatter_has "$design_doc" "comet_change" "$CHANGE"
+}
+
+design_doc_declares_technical_role() {
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ] &&
+    design_doc_frontmatter_has "$design_doc" "role" "technical-design"
+}
+
+design_doc_declares_canonical_spec() {
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ] &&
+    design_doc_frontmatter_has "$design_doc" "canonical_spec" "openspec"
+}
+
 archived_is_true() {
   local val
   val=$(yaml_field_value "archived" 2>/dev/null || true)
@@ -315,10 +496,16 @@ guard_design() {
   design_doc=$(yaml_field_value "design_doc" 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 [ -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"
   fi
@@ -395,7 +582,7 @@ else
     apply_state_update "$PHASE"
     case "$PHASE" in
       open)
-        new_phase=$(grep "^phase:" "$CHANGE_DIR/.comet.yaml" | sed 's/^phase: *//' | tr -d '"' | tr -d "'")
+        new_phase=$(yaml_field_value "phase")
         green "  [APPLY] .comet.yaml updated: phase=$new_phase"
         ;;
       design) green "  [APPLY] .comet.yaml updated: phase=build" ;;