RavBogard/dan:unify

dan:unify

Close the execution loop for a completed plan. Reads task commits, deviations, and verification results to produce a SUMMARY.md file. Updates STATE.md and ROADMAP.md.

What It Does

1. Reads the target PLAN.md and its task commits
2. Gathers deviations, decisions, and issues from execution
3. Produces {phase}-{plan}-SUMMARY.md with:
   • Frontmatter (dependency graph, tech-stack, key-files, decisions, metrics)
   • Accomplishments, task commits, files created/modified
   • Deviations from plan, issues encountered
4. Updates STATE.md (advance plan counter, add decisions, record metrics)
5. Updates ROADMAP.md (plan progress row)

Execution Mode

Runs in-session (no agent spawning). Reads git log and plan files to produce summary.

CLI Tools

State and roadmap operations use the DAN CLI:

node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd $PROJECT_DIR state set "Plan" "3 of 4 in current phase"
node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd $PROJECT_DIR state get "Status"

<execution_flow>

<step name="identify_plan"> Determine which plan to unify (close the loop on).

1. If a plan path argument was provided by the user, use it directly:

   PLAN_FILE=$1   # e.g., ".planning/phases/02-core-loop/02-01-PLAN.md"
   

2. Otherwise, read STATE.md for current phase and plan position:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" state get "Phase"
   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" state get "Plan"
   

   Determine the phase directory and scan for unclosed plans.

3. Find the most recent PLAN.md without a matching SUMMARY.md:

   PHASE_PATH="$PROJECT_DIR/.planning/phases/${PADDED_PHASE}-${PHASE_NAME}"
   for PLAN in $(ls "$PHASE_PATH"/*-PLAN.md 2>/dev/null); do
     PREFIX=$(basename "$PLAN" | sed 's/-PLAN.md//')
     SUMMARY="$PHASE_PATH/${PREFIX}-SUMMARY.md"
     [ ! -f "$SUMMARY" ] && PLAN_FILE="$PLAN" && break
   done
   

4. Parse the plan frontmatter and verify status:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" frontmatter parse "$PLAN_FILE"
   

   • If status is COMPLETED: proceed (summary is the missing piece)
   • If status is IN_PROGRESS: warn "Plan is still IN_PROGRESS. Producing summary anyway -- verify all tasks are done."
   • If status is DRAFT or APPROVED: error "Plan has not been executed yet. Run /dan:apply first."

5. If no unclosed plans found:

   All plans in phase ${PADDED_PHASE} have summaries. Nothing to unify.
   

</step> <step name="read_plan_and_commits"> Gather all execution evidence for the plan.

1. Read the PLAN.md file and extract:

   • Objective (from <objective> block)
   • Tasks (from <task> elements): name, type, files, done criteria
   • Success criteria (from <success_criteria> block)
   • Requirements covered (from frontmatter requirements)
   • Files modified (from frontmatter files_modified)

2. Read git log for commits matching this plan's identifier:

   git log --oneline --grep="(${PADDED_PHASE}-${PADDED_PLAN})" --all
   

   This captures all task commits (e.g., feat(02-01): ..., test(02-01): ...).

3. For each task in the plan, determine its status:

   • Completed: A commit exists with the task's description or file changes
   • Skipped: No matching commit and task was explicitly deferred
   • Modified: Commit exists but files or scope differ from plan

4. Check the current state of planned files:

   for FILE in ${FILES_MODIFIED}; do
     [ -f "$PROJECT_DIR/$FILE" ] && echo "EXISTS: $FILE" || echo "MISSING: $FILE"
   done
   

5. Count actual files created/modified from the git diff:

   git diff --name-only $(git log --oneline --grep="(${PADDED_PHASE}-${PADDED_PLAN})" --format="%H" | tail -1)^..$(git log --oneline --grep="(${PADDED_PHASE}-${PADDED_PLAN})" --format="%H" | head -1)
   

</step> <step name="gather_qualification_results"> Collect qualification and deviation data from the execution.

1. Check STATE.md decisions section for any qualification results:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" state get "Decisions"
   

   Look for entries mentioning this plan's identifier or PASS_WITH_CONCERNS.

2. Check for deviation patterns in commit messages:

   git log --oneline --grep="(${PADDED_PHASE}-${PADDED_PLAN})" --all | grep -iE "fix|deviat|missing|bug"
   

3. Collect any PASS_WITH_CONCERNS notes -- these become items in the "Deviations" or "Deferred" sections.

4. Note any auto-fixed bugs, added missing functionality, or blocking issues resolved during execution. These map to deviation rules:

   • Rule 1 (Bug fixes)
   • Rule 2 (Missing critical functionality)
   • Rule 3 (Blocking issues) </step>

<step name="produce_summary"> Create the SUMMARY.md file using the summary template structure.

1. Determine the summary file path:

   SUMMARY_FILE="$PHASE_PATH/${PADDED_PHASE}-${PADDED_PLAN}-SUMMARY.md"
   

2. Build the summary content following bin/templates/summary.md structure:

   Frontmatter:

   ---
   phase: {PADDED_PHASE}
   plan: {PADDED_PLAN}
   completed: {YYYY-MM-DD}
   ---
   

   Title: # Phase {PHASE} Plan {PLAN}: [Name] Summary

   One-liner: Substantive description of what was built (not "X implemented" but "JWT auth with refresh rotation using jose library").

   Sections:

   • Objective: Copied from the plan's <objective> block
   • What Was Built: List actual deliverables with file paths from git evidence
   • Plan vs Actual: Table comparing: | Aspect | Planned | Actual | |--------|---------|--------| | Tasks | {planned_count} | {actual_count} | | Files | {planned_files} | {actual_files} | | Duration | {estimated} | {actual_duration} |
   • Decisions Made: Any decisions logged during execution (from STATE.md or commit messages)
   • Deviations from Plan: Differences between planned and actual work. If none: "None - plan executed exactly as written."
   • Deferred Items: Anything planned but not completed. If none: "None."

3. Write the summary file: Use the Write tool to create $SUMMARY_FILE with the assembled content.

   </step>

<step name="update_state_and_roadmap"> Transition the plan to COMPLETED and update all tracking files.

1. Transition the plan status to COMPLETED:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" frontmatter set "$PLAN_FILE" status COMPLETED
   

   The lifecycle module validates the transition (IN_PROGRESS -> COMPLETED or COMPLETED -> COMPLETED is idempotent).

2. Update STATE.md -- advance the plan counter:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" state set "Plan" "${NEXT_PLAN_NUM} of ${TOTAL_PLANS} in current phase"
   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" state set "Last activity" "$(date +%Y-%m-%d) -- Completed plan ${PADDED_PHASE}-${PADDED_PLAN}"
   

3. Add any new decisions to STATE.md:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" state get "Decisions"
   

   Append new decisions from the execution if not already present.

4. Update ROADMAP.md -- mark the plan as complete: Find the plan's entry in ROADMAP.md and change [ ] to [x]:

   # Read ROADMAP.md, find the line for this plan, mark complete
   # Use Edit tool to change "- [ ] Plan XX-NN" to "- [x] Plan XX-NN"
   

5. Commit all changes:

   node "$HOME/.claude/dan/bin/dan-tools.cjs" --cwd "$PROJECT_DIR" commit "unify(${PADDED_PHASE}-${PADDED_PLAN}): close loop with summary" --files "$SUMMARY_FILE" "$PROJECT_DIR/.planning/STATE.md" "$PROJECT_DIR/.planning/ROADMAP.md" "$PLAN_FILE"
   

</step> <step name="offer_next"> Suggest the appropriate next action based on phase progress.

1. Check if more plans exist in the current phase:

   TOTAL_PLANS=$(ls "$PHASE_PATH"/*-PLAN.md 2>/dev/null | wc -l)
   COMPLETED_PLANS=$(ls "$PHASE_PATH"/*-SUMMARY.md 2>/dev/null | wc -l)
   

2. If uncompleted plans remain:

   Loop closed for plan ${PADDED_PHASE}-${PADDED_PLAN}.
   Next: Run `/dan:apply` on plan ${PADDED_PHASE}-${NEXT_PADDED_PLAN} to continue.
   

3. If all plans in the phase are complete:

   Phase ${PADDED_PHASE} complete -- all plans have summaries.
   Next: Run `/dan:verify` to validate phase deliverables, or `/dan:plan` for the next phase.
   

4. Always confirm closure:

   The loop is now closed for plan ${PADDED_PHASE}-${PADDED_PLAN}.
   

</step>

</execution_flow>