@leeovery/claude-technical-workflows 2.0.43 → 2.0.45

package/commands/link-dependencies.md

@@ -53,9 +53,9 @@ Compare the `format:` field across all discovered plans.
 ```
 Mixed output formats detected:
 
-- authentication: beads
-- billing-system: linear
-- notifications: beads
+- authentication: {format-a}
+- billing-system: {format-b}
+- notifications: {format-a}
 
 Cross-topic dependencies can only be wired within the same output format.
 Please consolidate your plans to use a single output format before linking dependencies.
@@ -78,15 +78,15 @@ For each plan, find the External Dependencies section:
 ```
 Dependency Summary
 
-Plan: authentication (format: beads)
+Plan: authentication (format: {format})
   - billing-system: Invoice generation (unresolved)
-  - user-management: User profiles → beads-7x2k (resolved)
+  - user-management: User profiles → {task-id} (resolved)
 
-Plan: billing-system (format: beads)
+Plan: billing-system (format: {format})
   - authentication: User context (unresolved)
   - ~~payment-gateway: Payment processing~~ → satisfied externally
 
-Plan: notifications (format: beads)
+Plan: notifications (format: {format})
   - authentication: User lookup (unresolved)
   - billing-system: Invoice events (unresolved)
 ```
@@ -133,11 +133,11 @@ Present a summary:
 Dependency Linking Complete
 
 RESOLVED (newly linked):
-  - authentication → billing-system: beads-b7c2.1.1 (Invoice generation)
-  - notifications → authentication: beads-a3f8.1.2 (Session management)
+  - authentication → billing-system: {task-id} (Invoice generation)
+  - notifications → authentication: {task-id} (Session management)
 
 ALREADY RESOLVED (no action needed):
-  - authentication → user-management: beads-9m3p
+  - authentication → user-management: {task-id}
 
 SATISFIED EXTERNALLY (no action needed):
   - billing-system → payment-gateway

package/commands/workflow/start-implementation.md

@@ -56,7 +56,7 @@ This outputs structured YAML. Parse it to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist
-- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists
+- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
 - `count` - total number of plans
 
 **From `environment` section:**
@@ -105,9 +105,9 @@ Present all discovered plans to help the user make an informed choice.
 ```
 Available Plans:
 
-  1. {topic-1} (in-progress) - format: local-markdown
-  2. {topic-2} (concluded) - format: local-markdown
-  3. {topic-3} (in-progress) - format: beads
+  1. {topic-1} (in-progress) - format: {format}
+  2. {topic-2} (concluded) - format: {format}
+  3. {topic-3} (in-progress) - format: {format}
 
 Which plan would you like to implement? (Enter a number or name)
 ```
@@ -259,6 +259,7 @@ Invoke the [technical-implementation](../../skills/technical-implementation/SKIL
 Implementation session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
+Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
 Scope: {all phases | Phase N | Task N.M | next-available}
 

package/commands/workflow/start-planning.md

@@ -64,7 +64,7 @@ This outputs structured YAML. Parse it to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist
-- `files` - each plan's name, format, and status
+- `files` - each plan's name, format, status, and plan_id (if present)
 
 **From `state` section:**
 - `scenario` - one of: `"no_specs"`, `"no_ready_specs"`, `"single_ready_spec"`, `"multiple_ready_specs"`
@@ -122,7 +122,7 @@ Cross-cutting specifications (reference context):
   - {rate-limiting} (concluded)
 
 Existing plans:
-  - {topic-3}.md (in-progress, local-markdown)
+  - {topic-3}.md (in-progress, {format})
 ```
 
 **Legend:**

package/commands/workflow/start-review.md

@@ -56,7 +56,7 @@ This outputs structured YAML. Parse it to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist
-- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists
+- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
 - `count` - total number of plans
 
 **From `state` section:**
@@ -154,6 +154,7 @@ Invoke the [technical-review](../../skills/technical-review/SKILL.md) skill for
 Review session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
+Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
 Scope: {all changes | specific paths | from git status}
 

package/commands/workflow/start-specification.md

@@ -388,8 +388,41 @@ Present the groupings with FULL status information.
 
 For each grouping, show:
 - The grouping name
-- Whether a specification already exists for this grouping
-- Each discussion in the grouping and whether it has an individual spec
+- Whether a specification already exists for this grouping (and its effective status)
+- Each discussion in the grouping and its incorporation status
+
+### Determining Discussion Status Within a Grouping
+
+For each grouping, first check if a grouped specification exists:
+1. Convert the grouping name to kebab-case (lowercase, spaces to hyphens)
+2. Check if `docs/workflow/specification/{kebab-name}.md` exists
+3. If it exists, get its `sources` array from the discovery output
+
+The sources array uses object format with explicit status tracking:
+```yaml
+sources:
+  - name: topic-a
+    status: incorporated
+  - name: topic-b
+    status: pending
+```
+
+**If a grouped spec exists for the grouping:**
+
+For each discussion in the grouping:
+1. Look up the discussion in the spec's `sources` array (by `name` field)
+2. If found → use the source's `status` field (`incorporated` or `pending`)
+3. If NOT found → status is `"pending"` (new source not yet added to spec)
+
+Calculate the **effective spec status**:
+- If ALL discussions in the grouping have `status: incorporated` → use the spec's actual status from file
+- If ANY discussion has `status: pending` OR is not in sources → effective status is `"needs update"`
+
+**If NO grouped spec exists:**
+
+For each discussion in the grouping:
+- If the discussion has an individual spec (`has_individual_spec: true`) → status is `"spec: {spec_status}"`
+- If the discussion has no spec → status is `"ready"`
 
 **Format:**
 
@@ -398,19 +431,20 @@ For each grouping, show:
 
 Recommended Groupings:
 
-### 1. {Grouping Name} {if spec exists: "(spec: {spec_status})"}
+### 1. {Grouping Name} (spec: {effective_status})
 | Discussion | Status |
 |------------|--------|
-| {topic-a} | discussion only |
-| {topic-b} | spec: {spec_status} |
-| {topic-c} | discussion only |
+| {topic-a} | incorporated |
+| {topic-b} | incorporated |
+| {topic-c} | pending |
 
 Coupling: {explanation}
 
 ### 2. {Another Grouping}
 | Discussion | Status |
 |------------|--------|
-| {topic-d} | discussion only |
+| {topic-d} | ready |
+| {topic-e} | spec: in-progress |
 
 Coupling: {explanation}
 
@@ -429,6 +463,13 @@ How would you like to proceed?
 (Enter 'refresh' to re-analyze)
 ```
 
+**Status Legend:**
+- `incorporated` - Discussion content has been woven into the grouped specification
+- `pending` - Discussion is part of the group but not yet incorporated into the spec
+- `ready` - Discussion has no spec yet (ready to be specified)
+- `spec: {status}` - Discussion has its own individual specification
+- `needs update` - Grouped spec exists but has pending sources to incorporate
+
 **STOP.** Wait for user to choose.
 
 → Based on choice, proceed to **Step 8**.
@@ -636,7 +677,9 @@ Proceed? (y/n)
 ```
 {Creating / Continuing} specification: {topic}
 
-Source: docs/workflow/discussion/{topic}.md
+Sources:
+- docs/workflow/discussion/{topic}.md
+
 Output: docs/workflow/specification/{topic}.md
 
 Proceed? (y/n)
@@ -680,7 +723,9 @@ Invoke the [technical-specification](../../skills/technical-specification/SKILL.
 ```
 Specification session for: {topic}
 
-Source: docs/workflow/discussion/{topic}.md
+Sources:
+- docs/workflow/discussion/{topic}.md
+
 Output: docs/workflow/specification/{topic}.md
 
 Additional context: {summary of user's answers from Step 10}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.43",
+  "version": "2.0.45",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/scripts/discovery-for-implementation-and-review.sh

@@ -55,9 +55,10 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         date=$(extract_field "$file" "date")
         date=${date:-"unknown"}
         format=$(extract_field "$file" "format")
-        format=${format:-"local-markdown"}
+        format=${format:-"MISSING"}
         specification=$(extract_field "$file" "specification")
         specification=${specification:-"${name}.md"}
+        plan_id=$(extract_field "$file" "plan_id")
 
         # Check if linked specification exists
         spec_exists="false"
@@ -73,6 +74,9 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         echo "      format: \"$format\""
         echo "      specification: \"$specification\""
         echo "      specification_exists: $spec_exists"
+        if [ -n "$plan_id" ]; then
+            echo "      plan_id: \"$plan_id\""
+        fi
 
         plan_count=$((plan_count + 1))
     done

package/scripts/discovery-for-planning.sh

@@ -136,13 +136,17 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
 
         name=$(basename "$file" .md)
         format=$(extract_field "$file" "format")
-        format=${format:-"local-markdown"}
+        format=${format:-"MISSING"}
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
+        plan_id=$(extract_field "$file" "plan_id")
 
         echo "    - name: \"$name\""
         echo "      format: \"$format\""
         echo "      status: \"$status\""
+        if [ -n "$plan_id" ]; then
+            echo "      plan_id: \"$plan_id\""
+        fi
     done
 else
     echo "  exists: false"

package/scripts/discovery-for-specification.sh

@@ -35,9 +35,8 @@ extract_array_field() {
     local file="$1"
     local field="$2"
     local result
-    # Look for field followed by array items (- item), excluding --- delimiters
-    result=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | \
-        grep -v "^---$" | \
+    # Look for field followed by array items (- item), within frontmatter only
+    result=$(awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null | \
         sed -n "/^${field}:/,/^[a-z_]*:/p" | \
         grep "^[[:space:]]*-" | \
         sed 's/^[[:space:]]*-[[:space:]]*//' | \
@@ -46,6 +45,62 @@ extract_array_field() {
     echo "$result"
 }
 
+# Helper: Extract sources with status from object format
+# Outputs YAML-formatted source entries with name and status
+# Usage: extract_sources_with_status <file>
+#
+# Note: This only handles the object format. Legacy simple array format
+# is converted by migration 004 before discovery runs.
+extract_sources_with_status() {
+    local file="$1"
+    local in_sources=false
+    local current_name=""
+    local current_status=""
+
+    # Read frontmatter and parse sources block
+    while IFS= read -r line; do
+        # Detect start of sources block
+        if [[ "$line" =~ ^sources: ]]; then
+            in_sources=true
+            continue
+        fi
+
+        # Detect end of sources block (next top-level field)
+        if $in_sources && [[ "$line" =~ ^[a-z_]+: ]] && [[ ! "$line" =~ ^[[:space:]] ]]; then
+            # Output last source if pending
+            if [ -n "$current_name" ]; then
+                echo "      - name: \"$current_name\""
+                echo "        status: \"${current_status:-incorporated}\""
+            fi
+            break
+        fi
+
+        if $in_sources; then
+            # Object format: "  - name: value"
+            if [[ "$line" =~ ^[[:space:]]*-[[:space:]]*name:[[:space:]]*(.+)$ ]]; then
+                # Output previous source if exists
+                if [ -n "$current_name" ]; then
+                    echo "      - name: \"$current_name\""
+                    echo "        status: \"${current_status:-incorporated}\""
+                fi
+                current_name="${BASH_REMATCH[1]}"
+                current_name=$(echo "$current_name" | sed 's/^"//' | sed 's/"$//' | xargs)
+                current_status=""
+            # Status line: "    status: value"
+            elif [[ "$line" =~ ^[[:space:]]*status:[[:space:]]*(.+)$ ]]; then
+                current_status="${BASH_REMATCH[1]}"
+                current_status=$(echo "$current_status" | sed 's/^"//' | sed 's/"$//' | xargs)
+            fi
+        fi
+    done < <(awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null)
+
+    # Output last source if pending (end of frontmatter)
+    if [ -n "$current_name" ]; then
+        echo "      - name: \"$current_name\""
+        echo "        status: \"${current_status:-incorporated}\""
+    fi
+}
+
 # Start YAML output
 echo "# Specification Command State Discovery"
 echo "# Generated: $(date -Iseconds)"
@@ -101,7 +156,6 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         status=${status:-"active"}
 
         superseded_by=$(extract_field "$file" "superseded_by")
-        sources=$(extract_array_field "$file" "sources")
 
         echo "  - name: \"$name\""
         echo "    status: \"$status\""
@@ -110,11 +164,11 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
             echo "    superseded_by: \"$superseded_by\""
         fi
 
-        if [ -n "$sources" ]; then
+        # Extract sources with status (handles both old and new format)
+        sources_output=$(extract_sources_with_status "$file")
+        if [ -n "$sources_output" ]; then
             echo "    sources:"
-            for src in $sources; do
-                echo "      - \"$src\""
-            done
+            echo "$sources_output"
         fi
     done
 else

package/scripts/migrate.sh

@@ -116,8 +116,10 @@ for script in "${MIGRATION_SCRIPTS[@]}"; do
     MIGRATIONS_RUN=$((MIGRATIONS_RUN + 1))
 done
 
-# Only output if files were actually updated
+# Report results
 if [ "$FILES_UPDATED" -gt 0 ]; then
     echo ""
     echo "$FILES_UPDATED file(s) migrated. Review with \`git diff\`, then proceed."
+else
+    echo "[SKIP] No changes needed"
 fi

package/scripts/migrations/002-specification-frontmatter.sh

@@ -17,6 +17,9 @@
 #   status: in-progress | concluded
 #   type: feature | cross-cutting | (empty if unknown)
 #   date: YYYY-MM-DD
+#   sources:              # Optional - only if Sources field exists
+#     - discussion-one
+#     - discussion-two
 #   ---
 #
 #   # Specification: {Topic}
@@ -128,17 +131,51 @@ for file in "$SPEC_DIR"/*.md; do
         date_value=$(date +%Y-%m-%d)
     fi
 
+    # Extract sources from **Sources**: source1, source2, ... (comma-separated list of discussion names)
+    # These link the specification back to the discussions that informed it
+    sources_raw=$(grep -m1 '^\*\*Sources\*\*:' "$file" 2>/dev/null | \
+        sed 's/^\*\*Sources\*\*:[[:space:]]*//' | \
+        xargs || echo "")
+
+    # Convert comma-separated list to array
+    sources_array=()
+    if [ -n "$sources_raw" ]; then
+        IFS=',' read -ra sources_parts <<< "$sources_raw"
+        for src in "${sources_parts[@]}"; do
+            # Trim whitespace
+            src=$(echo "$src" | xargs)
+            if [ -n "$src" ]; then
+                sources_array+=("$src")
+            fi
+        done
+    fi
+
     #
     # Build new file content
     #
 
-    # Create frontmatter
-    frontmatter="---
+    # Create frontmatter (conditionally include sources if present)
+    if [ ${#sources_array[@]} -gt 0 ]; then
+        sources_yaml=""
+        for src in "${sources_array[@]}"; do
+            sources_yaml="${sources_yaml}
+  - $src"
+        done
+        frontmatter="---
 topic: $topic_kebab
 status: $status_new
 type: $type_new
 date: $date_value
+sources:$sources_yaml
 ---"
+    else
+        frontmatter="---
+topic: $topic_kebab
+status: $status_new
+type: $type_new
+date: $date_value
+---"
+    fi
 
     # Extract H1 heading (preserve original)
     h1_heading=$(grep -m1 "^# " "$file")

package/scripts/migrations/003-planning-frontmatter.sh

@@ -6,7 +6,7 @@
 #
 # Legacy format (partial frontmatter + inline metadata):
 #   ---
-#   format: local-markdown
+#   format: {format}
 #   ---
 #
 #   # Implementation Plan: {Feature/Project Name}
@@ -20,8 +20,9 @@
 #   topic: {topic-name}
 #   status: in-progress | concluded
 #   date: YYYY-MM-DD
-#   format: local-markdown
+#   format: {format}         # Required - no default, MISSING if not present
 #   specification: {topic}.md
+#   plan_id: {id}            # Optional - migrated from 'epic' or 'project' fields
 #   ---
 #
 #   # Implementation Plan: {Feature/Project Name}
@@ -83,9 +84,18 @@ for file in "$PLAN_DIR"/*.md; do
     topic_kebab=$(basename "$file" .md)
 
     # Extract format from existing frontmatter (if present)
-    format_value=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | grep "^format:" | sed 's/^format:[[:space:]]*//' | xargs || echo "")
+    # Use awk to extract only the first frontmatter block (between first pair of --- delimiters)
+    # This avoids matching --- horizontal rules in body content
+    format_value=$(awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null | grep "^format:" | sed 's/^format:[[:space:]]*//' | xargs || echo "")
     if [ -z "$format_value" ]; then
-        format_value="local-markdown"  # Default format
+        format_value="MISSING"  # No default - missing format is an error
+    fi
+
+    # Extract plan_id from existing frontmatter - could be 'epic' (beads) or 'project' (linear/backlog)
+    # These are migrated to a unified 'plan_id' field
+    plan_id_value=$(awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null | grep "^epic:" | sed 's/^epic:[[:space:]]*//' | xargs || echo "")
+    if [ -z "$plan_id_value" ]; then
+        plan_id_value=$(awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null | grep "^project:" | sed 's/^project:[[:space:]]*//' | xargs || echo "")
     fi
 
     # Extract status from **Status**: Value
@@ -107,8 +117,8 @@ for file in "$PLAN_DIR"/*.md; do
             ;;
     esac
 
-    # Extract date from **Date**: YYYY-MM-DD
-    date_value=$(grep -m1 '^\*\*Date\*\*:' "$file" 2>/dev/null | \
+    # Extract date from **Date**: YYYY-MM-DD or **Created**: YYYY-MM-DD
+    date_value=$(grep -m1 '^\*\*Date\*\*:\|^\*\*Created\*\*:' "$file" 2>/dev/null | \
         grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' || echo "")
 
     # Use today's date if none found
@@ -134,14 +144,25 @@ for file in "$PLAN_DIR"/*.md; do
     # Build new file content
     #
 
-    # Create frontmatter
-    frontmatter="---
+    # Create frontmatter (conditionally include plan_id if present)
+    if [ -n "$plan_id_value" ]; then
+        frontmatter="---
+topic: $topic_kebab
+status: $status_new
+date: $date_value
+format: $format_value
+specification: $spec_value
+plan_id: $plan_id_value
+---"
+    else
+        frontmatter="---
 topic: $topic_kebab
 status: $status_new
 date: $date_value
 format: $format_value
 specification: $spec_value
 ---"
+    fi
 
     # Extract H1 heading (preserve original)
     h1_heading=$(grep -m1 "^# " "$file")

package/scripts/migrations/004-sources-object-format.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+#
+# 004-sources-object-format.sh
+#
+# Migrates specification sources from simple array format to object format
+# with status tracking. Also ensures all specs have a sources field.
+#
+# Previous format (from 002-specification-frontmatter.sh):
+#   sources:
+#     - topic-a
+#     - topic-b
+#
+# New format:
+#   sources:
+#     - name: topic-a
+#       status: incorporated
+#     - name: topic-b
+#       status: incorporated
+#
+# Status values:
+#   - pending: Source selected but content not yet extracted
+#   - incorporated: Source content has been fully woven into the specification
+#
+# For existing sources, we assume "incorporated" since they were part of
+# the specification when it was created/worked on.
+#
+# For specs WITHOUT a sources field:
+#   - If a matching discussion exists (same filename), add it as incorporated
+#   - If no matching discussion, add empty sources: [] and report for user review
+#
+# This script is sourced by migrate.sh and has access to:
+#   - is_migrated "filepath" "migration_id"
+#   - record_migration "filepath" "migration_id"
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="004"
+SPEC_DIR="docs/workflow/specification"
+DISCUSSION_DIR="docs/workflow/discussion"
+
+# Skip if no specification directory
+if [ ! -d "$SPEC_DIR" ]; then
+    return 0
+fi
+
+# Helper: Extract ONLY the frontmatter content (between first pair of --- delimiters)
+# Documents may contain --- elsewhere (horizontal rules), so sed range matching
+# can return content beyond frontmatter. Use awk for precise first-block extraction.
+extract_frontmatter() {
+    local file="$1"
+    awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null
+}
+
+# Helper: Check if sources are already in object format
+# Returns 0 if already migrated (has "name:" entries), 1 if not
+sources_already_object_format() {
+    local file="$1"
+    # Look for "- name:" pattern within the sources block (frontmatter only)
+    # This indicates the new object format
+    # Using subshell with || false to ensure proper exit code without pipefail issues
+    ( extract_frontmatter "$file" | \
+        sed -n '/^sources:/,/^[a-z_]*:/p' | \
+        grep -q "^[[:space:]]*-[[:space:]]*name:" 2>/dev/null ) || return 1
+    return 0
+}
+
+# Helper: Extract sources array items (simple string format)
+# Returns space-separated list of source names
+extract_simple_sources() {
+    local file="$1"
+    # Extract sources from frontmatter only, then find the sources block
+    extract_frontmatter "$file" | \
+        sed -n '/^sources:/,/^[a-z_]*:/p' | \
+        grep -v "^sources:" | \
+        grep -v "^[a-z_]*:" | \
+        { grep "^[[:space:]]*-[[:space:]]" || true; } | \
+        { grep -v "name:" || true; } | \
+        sed 's/^[[:space:]]*-[[:space:]]*//' | \
+        sed 's/^"//' | \
+        sed 's/"$//' | \
+        tr '\n' ' ' | \
+        sed 's/[[:space:]]*$//' || true
+}
+
+# Process each specification file
+for file in "$SPEC_DIR"/*.md; do
+    [ -f "$file" ] || continue
+
+    # Check if already migrated via tracking
+    if is_migrated "$file" "$MIGRATION_ID"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if file has YAML frontmatter
+    if ! head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if file has sources field at all
+    has_sources_field=false
+    if grep -q "^sources:" "$file" 2>/dev/null; then
+        has_sources_field=true
+    fi
+
+    # If sources field exists, check if already in object format
+    if $has_sources_field && sources_already_object_format "$file"; then
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    #
+    # Build new sources block in object format
+    #
+    new_sources_block="sources:"
+    sources_added=false
+
+    if $has_sources_field; then
+        # Extract existing sources from simple array format
+        sources=$(extract_simple_sources "$file")
+
+        for src in $sources; do
+            # Clean the source name (trim whitespace, sed avoids xargs quote issues)
+            src=$(echo "$src" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            if [ -n "$src" ]; then
+                new_sources_block="${new_sources_block}
+  - name: $src
+    status: incorporated"
+                sources_added=true
+            fi
+        done
+    else
+        # No sources field - check for matching discussion by filename
+        spec_name=$(basename "$file" .md)
+        discussion_file="$DISCUSSION_DIR/${spec_name}.md"
+
+        if [ -f "$discussion_file" ]; then
+            # Matching discussion found - add it as incorporated
+            new_sources_block="${new_sources_block}
+  - name: $spec_name
+    status: incorporated"
+            sources_added=true
+        fi
+    fi
+
+    # If no sources were added, use empty array format
+    if ! $sources_added; then
+        new_sources_block="sources: []"
+        # Echo info for Claude to prompt user about unmatched specs
+        spec_name=$(basename "$file" .md)
+        echo "MIGRATION_INFO: Specification '$spec_name' has no matching discussion. Sources field set to empty - please review and add sources manually."
+    fi
+
+    #
+    # Update sources block in file
+    #
+
+    # Extract frontmatter (only the first block between --- delimiters)
+    frontmatter=$(extract_frontmatter "$file")
+
+    if $has_sources_field; then
+        # Remove old sources block from frontmatter
+        # First, remove lines from "sources:" until the next top-level field or end of frontmatter
+        new_frontmatter=$(echo "$frontmatter" | awk '
+/^sources:/ { skip=1; next }
+/^[a-z_]+:/ && skip { skip=0 }
+skip == 0 { print }
+')
+    else
+        # No existing sources field - use frontmatter as-is
+        new_frontmatter="$frontmatter"
+    fi
+
+    # Add new sources block at the end
+    new_frontmatter="${new_frontmatter}
+${new_sources_block}"
+
+    # Extract content after frontmatter (everything after the second ---)
+    # Uses awk to skip only the first two --- delimiters, preserving any --- in body content
+    content=$(awk '/^---$/ && c<2 {c++; next} c>=2 {print}' "$file")
+
+    # Write new file
+    {
+        echo "---"
+        echo "$new_frontmatter"
+        echo "---"
+        echo "$content"
+    } > "$file"
+
+    record_migration "$file" "$MIGRATION_ID"
+
+    # Report appropriate message based on what was done
+    if $has_sources_field; then
+        report_update "$file" "converted sources to object format"
+    elif $sources_added; then
+        report_update "$file" "added sources field with matching discussion"
+    else
+        report_update "$file" "added empty sources field (no matching discussion found)"
+    fi
+done

package/skills/technical-planning/references/output-backlog-md.md

@@ -53,7 +53,7 @@ The plan file in `docs/workflow/planning/{topic}.md` serves as the reference poi
 ```markdown
 ---
 format: backlog-md
-project: {TOPIC_NAME}
+plan_id: {TOPIC_NAME}
 ---
 
 # Plan Reference: {Topic Name}

package/skills/technical-planning/references/output-beads.md

@@ -240,7 +240,7 @@ Create `docs/workflow/planning/{topic}.md`:
 ```markdown
 ---
 format: beads
-epic: bd-{EPIC_ID}
+plan_id: bd-{EPIC_ID}
 ---
 
 # Plan Reference: {Topic Name}
@@ -304,7 +304,7 @@ The `format: beads` frontmatter tells implementation to use beads CLI:
 ```yaml
 ---
 format: beads
-epic: bd-a3f8
+plan_id: bd-a3f8
 ---
 ```
 
@@ -327,7 +327,7 @@ In the task body:
 
 ### Reading Plans
 
-1. Extract `epic` ID from frontmatter
+1. Extract `plan_id` (beads epic ID) from frontmatter
 2. Check `.beads/config.yaml` for `no-db` setting
 3. Run `bd ready` to get unblocked tasks
 4. View task details with `bd show bd-{id}`

package/skills/technical-planning/references/output-linear.md

@@ -148,7 +148,7 @@ Create `docs/workflow/planning/{topic}.md`:
 ```markdown
 ---
 format: linear
-project: {PROJECT_NAME}
+plan_id: {PROJECT_NAME}
 project_id: {ID from MCP response}
 team: {TEAM_NAME}
 ---
@@ -207,7 +207,7 @@ The frontmatter contains all information needed to query Linear:
 ```yaml
 ---
 format: linear
-project: USER-AUTH-FEATURE
+plan_id: USER-AUTH-FEATURE
 project_id: abc123-def456
 team: Engineering
 ---
@@ -257,7 +257,7 @@ Linear:
 
 ### Reading Plans
 
-1. Extract `project_id` from frontmatter
+1. Extract `plan_id` (Linear project name) from frontmatter
 2. Query Linear MCP for project issues
 3. Filter issues by phase label (e.g., `phase-1`, `phase-2`)
 4. Process in phase order

package/skills/technical-specification/references/specification-guide.md

@@ -148,6 +148,11 @@ topic: {topic-name}
 status: in-progress
 type: feature
 date: YYYY-MM-DD  # Use today's actual date
+sources:
+  - name: discussion-one
+    status: incorporated
+  - name: discussion-two
+    status: pending
 ---
 
 # Specification: [Topic Name]
@@ -169,6 +174,45 @@ date: YYYY-MM-DD  # Use today's actual date
 - **status**: `in-progress` (building) or `concluded` (complete)
 - **type**: `feature` (something to build) or `cross-cutting` (patterns/policies)
 - **date**: Last updated date
+- **sources**: Array of source discussions with incorporation status (see below)
+
+### Sources and Incorporation Status
+
+**All specifications must track their sources**, even when built from a single discussion. This enables proper tracking when additional discussions are later added to the same grouping.
+
+When a specification is built from discussion(s), track each source with its incorporation status:
+
+```yaml
+sources:
+  - name: auth-flow
+    status: incorporated
+  - name: api-design
+    status: pending
+```
+
+**Status values:**
+- `pending` - Source has been selected for this specification but content extraction is not complete
+- `incorporated` - Source content has been fully extracted and woven into the specification
+
+**When to update source status:**
+
+1. **When creating the specification**: All sources start as `pending`
+2. **After completing exhaustive extraction from a source**: Mark that source as `incorporated`
+3. **When adding a new source to an existing spec**: Add it with `status: pending`
+
+**How to determine if a source is incorporated:**
+
+A source is `incorporated` when you have:
+- Performed exhaustive extraction (reviewed ALL content in the source for relevant material)
+- Presented and logged all relevant content from that source
+- No more content from that source needs to be extracted
+
+**Important**: The specification's overall `status: concluded` should only be set when:
+- All sources are marked as `incorporated`
+- Both review phases are complete
+- User has signed off
+
+If a new source is added to a concluded specification (via grouping analysis), the specification effectively needs updating - even if the file still says `status: concluded`, the presence of `pending` sources indicates work remains.
 
 ## Specification Types