Skill Todo

       in_active=$(jq -r --arg n "$project_num" \
         '.active_projects[] | select(.project_number == ($n | tonumber)) | .project_number' \
         specs/state.json 2>/dev/null)

       in_archive=$(jq -r --arg n "$project_num" \
         '.completed_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/archive/state.json 2>/dev/null)

       if [ -z "$in_active" ] && [ -z "$in_archive" ]; then
         orphaned_in_specs+=("$dir")
       fi
     done
     ```

  2. Scan specs/archive/ for orphaned directories:
     ```bash
     for dir in specs/archive/OC_[0-9]*_*/ specs/archive/[0-9]*_*/; do
       [ -d "$dir" ] || continue
       basename_dir=$(basename "$dir")
       project_num=$(echo "$basename_dir" | sed 's/^OC_//' | cut -d_ -f1)

       in_archive=$(jq -r --arg n "$project_num" \
         '.completed_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/archive/state.json 2>/dev/null)

       if [ -z "$in_archive" ]; then
         orphaned_in_archive+=("$dir")
       fi
     done
     ```

  3. Scan TODO.md for completed/abandoned tasks not tracked in state.json or archive:
     - Parse task headers (`### {N}.` or `### OC_{N}.`) and status lines (`[COMPLETED]`/`[ABANDONED]`)
     - Cross-reference each against active_projects and archive completed_projects
     - Collect as `todo_md_orphans[]` if: status is completed/abandoned, not in either state file, and has a directory in specs/
</process>

       in_active=$(jq -r --arg n "$project_num" \
         '.active_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/state.json 2>/dev/null)
       
       in_archive=$(jq -r --arg n "$project_num" \
         '.completed_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/archive/state.json 2>/dev/null)
       
       if [ -z "$in_active" ] && [ -n "$in_archive" ]; then
         misplaced_in_specs+=("$dir")
       fi
     done
     ```
</process>

     ## Phase 1: Current Priorities (High Priority)

     - [ ] (No items yet -- add roadmap items here)

     ## Success Metrics

     - (Define success metrics here)
     ```
  1. Read specs/ROADMAP.md
  2. For each completed task, extract:
     - completion_summary from completion_data
     - roadmap_items if present
     - Task N references from summaries
  3. Match against ROADMAP.md items
  4. Track roadmap_matches array with confidence levels
</process>

  2. Deduplicate against existing memory-index.json:
     - Read `.memory/memory-index.json` (if missing or empty, skip dedup -- all candidates are CREATE)
     - For each candidate, compute keyword overlap against every index entry:
       ```
       overlap = |candidate.suggested_keywords INTERSECT entry.keywords| / |candidate.suggested_keywords|
       ```
     - Classify dedup action:
       - overlap > 90%: mark `dedup_action = "NOOP"` (exclude from prompt)
       - overlap > 60%: mark `dedup_action = "UPDATE"` (present with warning label)
       - overlap <= 60%: mark `dedup_action = "CREATE"` (standard new memory)
     - If ALL candidates are NOOP after dedup, set `harvest_candidates = []` and skip to Stage 8

  3. Apply three-tier classification:
     - **Tier 1** (pre-selected): category in [PATTERN, CONFIG] AND confidence >= 0.8
     - **Tier 2** (shown, not pre-selected): category in [WORKFLOW, TECHNIQUE] AND confidence >= 0.5
     - **Tier 3** (hidden by default): category == INSIGHT OR confidence < 0.5
     - Assign `tier` (1, 2, or 3) to each non-NOOP candidate

  4. Store the classified candidate list as `harvest_candidates`:
     Each entry contains: `task_number`, `content`, `category`, `source_artifact`, `confidence`, `suggested_keywords`, `tier`, `dedup_action`
</process>

  2. Update specs/state.json:
     - Remove from active_projects array

  3. Update specs/TODO.md:
     - Remove archived entries (both regular and TODO.md orphans)
     - Pattern to match task entry start:
       ```lua
       -- Match both "### OC_N. " and "### N. " formats
       local task_start_pattern = "###%s+(OC_)?(%d+)%.%s+"
       ```
     - For each task to remove:
       a. Find entry start (header line)
       b. Find entry end (next task header or end of Active Tasks section)
       c. Extract complete entry including all lines
       d. Validate entry matches expected format before removal
     - Use Edit tool to remove validated entries:
       ```lua
       -- Remove the matched section
       edit_file("specs/TODO.md", old_entry_content, "")
       ```
     - Note: next_project_number should NOT be decremented when removing orphans
       (numbering continues from highest used number)

  4. Move project directories to specs/archive/

  5. Remove archived task from Recommended Order section (non-blocking):
     ```bash
     # Remove archived task from Recommended Order section (non-blocking)
     if source "$PROJECT_ROOT/.claude/scripts/update-recommended-order.sh" 2>/dev/null; then
         remove_from_recommended_order "$project_number" || echo "Note: Failed to update Recommended Order"
     fi
     ```

  6. Track orphaned directories (if approved)

  7. Move misplaced directories (if approved)

  8. Archive TODO.md orphans:
     For each selected orphan in `selected_todo_orphans`:
     a. Build archive entry from TODO.md data:
        ```json
        {
          "project_number": orphan.project_number,
          "project_name": orphan.project_name,
          "status": orphan.status,  // "completed" or "abandoned"
          "created_at": "TODO.md_orphan",  // Marker indicating source
          "archived_at": "YYYY-MM-DDTHH:MM:SSZ"
        }
        ```
     b. Add entry to specs/archive/state.json completed_projects array
     c. Move directory from specs/ to specs/archive/:
        ```bash
        source_dir="specs/OC_${orphan.project_number}_${orphan.project_name}/"
        if [ ! -d "$source_dir" ]; then
          source_dir="specs/${orphan.project_number}_${orphan.project_name}/"
        fi
        target_dir="specs/archive/$(basename "$source_dir")"
        mv "$source_dir" "$target_dir"
        ```
     d. Track orphan archival for CHANGE_LOG.md
     e. If no directory found, log warning:
        ```
        Warning: TODO.md orphan {N} has no directory in specs/
        Archive entry created but no files moved
        ```

  9. **Vault Threshold Check (MANDATORY)**

     **CRITICAL: ALWAYS EXECUTE - DO NOT SKIP**

     This sub-step MUST be executed unconditionally after archiving tasks.
     The bash block below produces output for BOTH vault-needed and vault-not-needed cases.

     Execute vault threshold detection:
     ```bash
     # UNCONDITIONAL VAULT CHECK - produces output in all cases
     PROJECT_ROOT="${PROJECT_ROOT:-.}"
     STATE_FILE="${PROJECT_ROOT}/specs/state.json"
     VAULT_THRESHOLD=1000

     next_num=$(jq -r '.next_project_number // 0' "$STATE_FILE")

     if [[ "$next_num" -gt "$VAULT_THRESHOLD" ]]; then
         echo ""
         echo "=============================================="
         echo "  VAULT THRESHOLD EXCEEDED"
         echo "=============================================="
         echo "  next_project_number: $next_num"
         echo "  threshold: $VAULT_THRESHOLD"
         echo "  status: VAULT OPERATION REQUIRED"
         echo "=============================================="
         echo ""
         vault_needed=true
     else
         echo ""
         echo "Vault check: next_project_number=$next_num (threshold: $VAULT_THRESHOLD) - OK"
         echo ""
         vault_needed=false
     fi
     ```

     **Decision Logic**:
     - If `vault_needed=true`: Proceed to sub-step 9.1 (VaultConfirmation)
     - If `vault_needed=false`: Skip sub-steps 9.1-9.4, continue to Stage 11 (UpdateRoadmap)

  9.1. **VaultConfirmation** (if vault_needed=true)

     Identify tasks requiring renumbering:
     ```bash
     # Find active tasks with project_number > 1000
     tasks_to_renumber=$(jq -r '
       .active_projects[] |
       select(.project_number > 1000) |
       {
         old_number: .project_number,
         new_number: (.project_number - 1000),
         project_name: .project_name,
         status: .status
       }
     ' specs/state.json)

     # Count tasks to renumber
     renumber_count=$(echo "$tasks_to_renumber" | jq -s 'length')

     # Build mapping array: [{old: 1001, new: 1}, {old: 1003, new: 3}, ...]
     renumber_mappings=$(jq -n --argjson tasks "$tasks_to_renumber" '
       [$tasks[] | {old: .old_number, new: .new_number, name: .project_name}]
     ')
     ```

     Build preview of renumbering:
     ```bash
     # Format preview of task renumbering
     renumber_preview=""
     for mapping in $(echo "$renumber_mappings" | jq -c '.[]'); do
       old=$(echo "$mapping" | jq -r '.old')
       new=$(echo "$mapping" | jq -r '.new')
       name=$(echo "$mapping" | jq -r '.name')
       renumber_preview="${renumber_preview}\n  - Task ${old} (${name}) -> Task ${new}"
     done
     ```

     Present AskUserQuestion for vault confirmation:
     ```json
     {
       "question": "Task numbering has exceeded 1000. Initiate vault archival?",
       "header": "Vault Operation",
       "description": "Current next_project_number: {next_num}\nActive tasks to renumber: {renumber_count}\n\nRenumbering preview:{renumber_preview}\n\nThis will:\n1. Move specs/archive/ to specs/vault/{NN-vault}/\n2. Renumber tasks > 1000 by subtracting 1000\n3. Reset next_project_number",
       "multiSelect": false,
       "options": [
         {"label": "Yes, proceed with vault operation", "value": "proceed"},
         {"label": "No, skip vault this time", "value": "skip"}
       ]
     }
     ```

     Handle user response:
     ```bash
     if [ "$user_response" = "proceed" ]; then
       vault_approved=true
       # Continue to sub-step 9.2
     else
       vault_approved=false
       # Skip to Stage 11 (UpdateRoadmap)
     fi
     ```

  9.2. **CreateVault** (if vault_approved=true)

     Calculate vault number:
     ```bash
     # Get current vault_count (or 0 if not set)
     vault_count=$(jq -r '.vault_count // 0' specs/state.json)
     new_vault_num=$((vault_count + 1))
     vault_dir_name=$(printf "%02d-vault" "$new_vault_num")
     vault_path="specs/vault/${vault_dir_name}"
     ```

     Create vault directory structure:
     ```bash
     mkdir -p "$vault_path"
     ```

     Move archive contents to vault:
     ```bash
     # Move archive directory to vault
     if [ -d "specs/archive" ]; then
       mv "specs/archive" "${vault_path}/archive"
     fi
     ```

     Move archive state.json to vault root:
     ```bash
     # Archive state.json becomes vault state.json
     if [ -f "${vault_path}/archive/state.json" ]; then
       mv "${vault_path}/archive/state.json" "${vault_path}/state.json"
     fi
     ```

     Create vault meta.json:
     ```bash
     # Calculate metadata
     current_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
     archived_count=$(jq -r '.completed_projects | length' "${vault_path}/state.json" 2>/dev/null || echo "0")
     task_range="1-$((next_num - renumber_count - 1))"

     # Create meta.json
     jq -n \
       --arg vault_num "$new_vault_num" \
       --arg created_at "$current_timestamp" \
       --arg task_range "$task_range" \
       --argjson archived_count "$archived_count" \
       --argjson final_task_num "$next_num" \
       '{
         vault_number: ($vault_num | tonumber),
         created_at: $created_at,
         task_range: $task_range,
         archived_count: $archived_count,
         final_task_number: $final_task_num,
         description: "Vault containing archived tasks from task numbering cycle"
       }' > "${vault_path}/meta.json"
     ```

     Reinitialize empty specs/archive/ with fresh state.json:
     ```bash
     mkdir -p "specs/archive"

     # Create fresh archive state.json
     jq -n '{
       "_comment": "Archive state for completed and abandoned tasks",
       "completed_projects": [],
       "archived_at": "'"$current_timestamp"'"
     }' > "specs/archive/state.json"
     ```

  9.3. **RenumberTasks** (if vault_approved=true)

     For each task in renumber_mappings, update state.json:
     ```bash
     # Update each task's project_number and artifact paths
     for mapping in $(echo "$renumber_mappings" | jq -c '.[]'); do
       old_num=$(echo "$mapping" | jq -r '.old')
       new_num=$(echo "$mapping" | jq -r '.new')
       task_name=$(echo "$mapping" | jq -r '.name')

       # Update project_number
       # Update artifact paths (4-digit dir -> 3-digit dir)
       old_padded=$(printf "%04d" "$old_num")
       new_padded=$(printf "%03d" "$new_num")

       # Use jq to update the task entry
       jq --argjson old "$old_num" \
          --argjson new "$new_num" \
          --arg old_pad "$old_padded" \
          --arg new_pad "$new_padded" '
         .active_projects |= map(
           if .project_number == $old then
             .project_number = $new |
             .artifacts |= (if . then map(
               .path |= gsub("specs/\($old_pad)_"; "specs/\($new_pad)_") |
               .path |= gsub("specs/\($old)_"; "specs/\($new_pad)_")
             ) else . end)
           else . end
         )
       ' specs/state.json > specs/state.json.tmp
       mv specs/state.json.tmp specs/state.json
     done
     ```

     Update dependencies arrays (task numbers > 1000):
     ```bash
     # Build mapping for all renumbered tasks
     jq --argjson mappings "$renumber_mappings" '
       # Create lookup from mappings
       ($mappings | map({(.old | tostring): .new}) | add) as $lookup |
       .active_projects |= map(
         .dependencies |= (if . then map(
           . as $dep |
           if $lookup[$dep | tostring] then
             $lookup[$dep | tostring]
           else $dep end
         ) else . end)
       )
     ' specs/state.json > specs/state.json.tmp
     mv specs/state.json.tmp specs/state.json
     ```

     Rename task directories:
     ```bash
     for mapping in $(echo "$renumber_mappings" | jq -c '.[]'); do
       old_num=$(echo "$mapping" | jq -r '.old')
       new_num=$(echo "$mapping" | jq -r '.new')
       task_name=$(echo "$mapping" | jq -r '.name')

       old_padded=$(printf "%04d" "$old_num")
       new_padded=$(printf "%03d" "$new_num")

       # Find source directory (could be 3-digit or 4-digit padded)
       source_dir=""
       if [ -d "specs/${old_padded}_${task_name}" ]; then
         source_dir="specs/${old_padded}_${task_name}"
       elif [ -d "specs/${old_num}_${task_name}" ]; then
         source_dir="specs/${old_num}_${task_name}"
       fi

       # Rename to 3-digit padded format
       if [ -n "$source_dir" ]; then
         target_dir="specs/${new_padded}_${task_name}"
         mv "$source_dir" "$target_dir"
       fi
     done
     ```

     Update TODO.md entries:
     ```bash
     for mapping in $(echo "$renumber_mappings" | jq -c '.[]'); do
       old_num=$(echo "$mapping" | jq -r '.old')
       new_num=$(echo "$mapping" | jq -r '.new')

       old_padded=$(printf "%04d" "$old_num")
       new_padded=$(printf "%03d" "$new_num")

       # Update task headers: ### 1001. Title -> ### 1. Title
       sed -i "s/^### ${old_num}\./### ${new_num}./" specs/TODO.md

       # Update artifact links with directory references
       sed -i "s|${old_padded}_|${new_padded}_|g" specs/TODO.md
       sed -i "s|${old_num}_|${new_padded}_|g" specs/TODO.md

       # Update dependency references
       sed -i "s|Task #${old_num}|Task #${new_num}|g" specs/TODO.md
     done
     ```

  9.4. **ResetState** (if vault_approved=true)

     Calculate new next_project_number:
     ```bash
     # Find maximum project_number in active_projects after renumbering
     max_active=$(jq -r '[.active_projects[].project_number] | max // 0' specs/state.json)
     new_next_num=$((max_active + 1))
     ```

     Update state.json with new next_project_number:
     ```bash
     jq --argjson new_next "$new_next_num" \
        '.next_project_number = $new_next' specs/state.json > specs/state.json.tmp
     mv specs/state.json.tmp specs/state.json
     ```

     Increment vault_count:
     ```bash
     jq '.vault_count = (.vault_count // 0) + 1' specs/state.json > specs/state.json.tmp
     mv specs/state.json.tmp specs/state.json
     ```

     Add entry to vault_history:
     ```bash
     current_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
     archived_count=$(jq -r '.completed_projects | length' "${vault_path}/state.json" 2>/dev/null || echo "0")
     task_range="1-$((next_num - renumber_count - 1))"

     jq --arg vault_dir "$vault_path/" \
        --argjson vault_num "$new_vault_num" \
        --arg created "$current_timestamp" \
        --arg range "$task_range" \
        --argjson archived "$archived_count" \
        --argjson final "$next_num" '
       .vault_history = (.vault_history // []) + [{
         vault_number: $vault_num,
         vault_dir: $vault_dir,
         created_at: $created,
         task_range: $range,
         archived_count: $archived,
         final_task_number: $final
       }]
     ' specs/state.json > specs/state.json.tmp
     mv specs/state.json.tmp specs/state.json
     ```

     Add vault transition comment to TODO.md:
     ```bash
     current_date=$(date +"%Y-%m-%d")
     transition_comment="<!-- Vault transition: ${current_date} - Tasks 1-$((next_num - renumber_count - 1)) archived to ${vault_path}/ -->"

     # Insert after frontmatter or at top of file
     if grep -q "^---$" specs/TODO.md; then
       # Has frontmatter, insert after closing ---
       sed -i "/^---$/,/^---$/{/^---$/{n;a\\

${transition_comment} }}" specs/TODO.md else # No frontmatter, insert at top sed -i "1i${transition_comment}" specs/TODO.md fi ```

     After sub-step 9.4 completes, continue to Stage 11 (UpdateRoadmap).

  <!-- CHECKPOINT: Stage 10 complete when vault_check output is present AND
       (vault_needed=false OR vault operations 9.1-9.4 completed) -->
</process>
<checkpoint>vault_check_complete output present; if vault_needed, sub-steps 9.1-9.4 executed</checkpoint>

  For each candidate in `approved_memories`:

  1. **Generate slug**:
     - Derive from candidate category + content first few words (lowercase, hyphens, no special chars)
     - Example: `pattern-jq-safe-not-operator`, `config-lean4-lake-env`
     - Collision check: if `MEM-{slug}.md` exists in `.memory/10-Memories/`, append numeric suffix (`-2`, `-3`, ...)

  2. **Create memory file** at `.memory/10-Memories/MEM-{slug}.md`:
     - Use template from `.memory/30-Templates/memory-template.md`
     - Field mapping from candidate:
       - `{{title}}` -> descriptive title derived from content (first ~60 chars, cleaned)
       - `{{date}}` -> current date (YYYY-MM-DD)
       - `{{tags}}` -> `[{category}]` (e.g., `[PATTERN]`)
       - `{{topic}}` -> derived from category (lowercase, e.g., "pattern", "configuration")
       - `{{source}}` -> `"Task {N}: {source_artifact}"`
       - `{{last_updated}}` -> current date (YYYY-MM-DD)
       - `retrieval_count` -> `0`
       - `last_retrieved` -> `null`
       - `keywords` -> candidate's `suggested_keywords` array
       - `summary` -> first 60 characters of `content`
       - `token_count` -> `word_count(content) * 1.3` (rounded to integer)
       - `{{content}}` -> candidate's `content` field

  3. After ALL memory files are created, **batch-regenerate indexes**:
     - `.memory/memory-index.json`: Rebuild from filesystem scan of `.memory/10-Memories/MEM-*.md`
       - Parse frontmatter of each file to populate entries array
       - Update `entry_count`, `total_tokens`, `generated_at`
     - `.memory/20-Indices/index.md`: Rebuild table of contents from all memory files
     - `.memory/10-Memories/README.md`: Update memory listing

  Note: `memory_candidates` field is implicitly cleaned when the task entry is removed from
  active_projects and moved to archive during Stage 10.
</process>

  **Suggested Next Steps**:

  After displaying the archival summary, append a numbered "Suggested Next Steps" list.
  The list always includes at least one item (the archive review suggestion).
  Distill suggestions are conditionally added based on `memory_health` from state.json.

  1. Read `memory_health` from specs/state.json with fallback:
     ```bash
     memory_health=$(jq -r '.memory_health // {}' specs/state.json)
     total_memories=$(echo "$memory_health" | jq -r '.total_memories // 0')
     never_retrieved=$(echo "$memory_health" | jq -r '.never_retrieved // 0')
     health_score=$(echo "$memory_health" | jq -r '.health_score // 100')
     last_distilled=$(echo "$memory_health" | jq -r '.last_distilled // null')
     ```
     If `memory_health` is absent or empty (`{}`), suppress all /distill suggestions
     (only show the archive review suggestion).

  2. Always include as the first suggestion:
     `1. Review the archive at specs/archive/ to verify task directories moved correctly`

  3. Suppress ALL /distill suggestions when `total_memories < 5`:
     - Do not mention /distill at all in this case

  4. When `total_memories >= 5`, evaluate these conditions (in order):

     a. Suggest `/distill --report` when `total_memories >= 10`:
        `N. Run /distill --report to review memory vault health ({total_memories} memories, {health_score}/100 health)`

     b. Suggest `/distill` (full interactive) when ANY of these conditions are true:
        - `total_memories >= 30`
        - `never_retrieved / total_memories > 0.5` AND `total_memories >= 5`
        - `last_distilled` is null or stale (older than 30 days) AND `total_memories >= 10`

        Format: `N. Run /distill to maintain memory vault ({total_memories} memories, {health_score}/100 health)`

     Note: If condition (b) is met, it replaces condition (a) -- do not show both
     /distill --report and /distill suggestions. Show the stronger suggestion only.

  5. Format as a clean numbered list:
     ```
     Suggested next steps:
     1. Review the archive at specs/archive/ to verify task directories moved correctly
     2. Run /distill to maintain memory vault (42 memories, 72/100 health)
     ```
</process>

<validation>Validate state updates, CHANGE_LOG.md entries, and memory creation.</validation>

<return_format>Brief text summary with archival counts and operation results.</return_format>

Error Handling

See rules/error-handling.md for general patterns. Skill-specific: jq failures skip affected operation; git failures are non-blocking; user cancel or AskUserQuestion failure defaults to skip.

Example Usage

/todo              # Archive with full workflow
/todo --dry-run    # Preview what would be archived