feat: add completion announcements, risk descriptions, iteration cap, and bolt terminology

- Add announcements field to intent.md frontmatter and Phase 5.9 prompt
  to configure changelog, release-notes, social-posts, blog-draft generation
- Generate announcement artifacts on intent completion (advance Step 5)
- Add risk section to unit template and unit decomposition checklist
- Add 50-iteration safety cap in advance Step 3 to prevent infinite loops
- Skip integrator for bolt change_strategy (in addition to single-unit)
- Add Bolt terminology mapping to ai-dlc-fundamentals skill

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

plugin/skills/advance/SKILL.md

@@ -112,9 +112,13 @@ READY_COUNT=$(echo "$DAG_SUMMARY" | han parse json readyCount -r)
 ```javascript
 if (dagSummary.allComplete) {
   // ALL UNITS COMPLETE - Check if integrator should run
-  // Skip integrator for single-unit intents (reviewer already validated it)
+  // Skip integrator for:
+  //   - Single-unit intents (reviewer already validated it)
+  //   - change_strategy "bolt" (single squashed branch, no multi-unit merge)
   const unitCount = dagSummary.totalCount;
-  if (unitCount > 1 && !state.integratorComplete) {
+  const changeStrategy = config.change_strategy || "unit";
+  const skipIntegrator = unitCount <= 1 || changeStrategy === "bolt";
+  if (!skipIntegrator && !state.integratorComplete) {
     // Spawn integrator on the intent branch
     // See Step 2e below
     return spawnIntegrator();
@@ -266,10 +270,28 @@ The re-queued units will be picked up on the next `/construct` cycle through the
 ### Step 3: Update State
 
 ```bash
+# Increment iteration counter
+ITERATION=$(echo "$STATE" | han parse json iteration -r --default 1)
+ITERATION=$((ITERATION + 1))
+
+# Safety cap: prevent infinite loops
+MAX_ITERATIONS=50
+if [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
+  echo "## Safety Limit Reached"
+  echo ""
+  echo "Construction has reached ${MAX_ITERATIONS} iterations without completing."
+  echo "This likely indicates poorly specified criteria or a systematic issue."
+  echo ""
+  echo "**Action required:** Review the intent and unit specs, then run \`/construct\` to resume."
+  STATE=$(echo "$STATE" | han parse json --set "status=blocked" --set "iteration=$ITERATION")
+  han keep save iteration.json "$STATE"
+  exit 0
+fi
+
 # Update hat and signal SessionStart to increment iteration
 # Intent-level state saved to current branch (intent branch)
-# state.hat = nextHat, state.needsAdvance = true
-han keep save iteration.json '<updated JSON with hat and needsAdvance>'
+# state.hat = nextHat, state.iteration = ITERATION
+han keep save iteration.json '<updated JSON with hat and iteration>'
 ```
 
 ### Step 4: Confirm (Normal Advancement)
@@ -316,6 +338,32 @@ Intent branch ready: ai-dlc/{intent-slug}/main → ${DEFAULT_BRANCH}
 Create PR: gh pr create --base ${DEFAULT_BRANCH} --head ai-dlc/{intent-slug}/main
 ```
 
+### Completion Announcements
+
+If the intent has configured `announcements` in its frontmatter, generate each format:
+
+```bash
+ANNOUNCEMENTS=$(han parse yaml announcements < "$INTENT_DIR/intent.md" 2>/dev/null || echo "[]")
+```
+
+For each configured format, generate the announcement artifact in `.ai-dlc/{intent-slug}/`:
+
+| Format | File | Content |
+|--------|------|---------|
+| `changelog` | `CHANGELOG-entry.md` | Conventional changelog entry (Added/Changed/Fixed sections) |
+| `release-notes` | `release-notes.md` | User-facing feature summary in plain language |
+| `social-posts` | `social-posts.md` | Platform-optimized snippets (Twitter/LinkedIn ready) |
+| `blog-draft` | `blog-draft.md` | Long-form announcement with context, examples, and impact |
+
+Generate each from the intent's Problem/Solution, completed units, and success criteria. Commit the announcement artifacts:
+
+```bash
+git add .ai-dlc/${INTENT_SLUG}/
+git commit -m "announce: generate completion announcements for ${INTENT_SLUG}"
+```
+
+Skip this step if `announcements` is empty or `[]`.
+
 Then ask the user how to deliver using `AskUserQuestion`:
 
 ```json

plugin/skills/ai-dlc-fundamentals/SKILL.md

@@ -138,9 +138,11 @@ Each iteration:
 3. Makes progress (guided by criteria and backpressure)
 4. Saves state (for next iteration)
 
-## Hat-Based Workflows
+## Hat-Based Workflows (Bolts)
 
-Different phases of work require different mindsets. AI-DLC uses "hats" to formalize this:
+Different phases of work require different mindsets. AI-DLC uses "hats" to formalize this.
+
+**Terminology mapping:** In the AI-DLC paper, a **Bolt** is the smallest iteration cycle — one pass through the hat workflow for a unit. The plugin implements Bolts as hat sequences: each unit progresses through its workflow hats (e.g., planner → builder → reviewer), with reviewer rejection cycling back to the previous hat. One complete pass = one Bolt. Multiple rejections = multiple Bolts for that unit.
 
 ### Default Workflow
 
@@ -152,9 +154,9 @@ planner → builder → reviewer
 
 | Hat | Focus |
 |-----|-------|
-| Planner | Plan this iteration |
+| Planner | Plan this iteration (Bolt) |
 | Builder | Implement to spec |
-| Reviewer | Verify quality |
+| Reviewer | Verify quality — approve completes the Bolt, reject starts a new one |
 
 ### Hat Transitions
 

plugin/skills/construct/SKILL.md

@@ -554,9 +554,20 @@ INTEGRATOR_COMPLETE=$(echo "$STATE" | han parse json integratorComplete -r --def
 UNIT_COUNT=$(ls -1 "$INTENT_DIR"/unit-*.md 2>/dev/null | wc -l)
 ```
 
-Skip the integrator entirely if there is only one unit (the reviewer already validated it).
+Skip the integrator if:
+- Only one unit (the reviewer already validated it)
+- `change_strategy` is `bolt` (single squashed branch, no multi-unit merge)
 
-If `UNIT_COUNT > 1` and `integratorComplete` is not `true`:
+```bash
+source "${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+CONFIG=$(get_ai_dlc_config "$INTENT_DIR")
+CHANGE_STRATEGY=$(echo "$CONFIG" | jq -r '.change_strategy // "unit"')
+SKIP_INTEGRATOR=false
+[ "$UNIT_COUNT" -le 1 ] && SKIP_INTEGRATOR=true
+[ "$CHANGE_STRATEGY" = "bolt" ] && SKIP_INTEGRATOR=true
+```
+
+If `SKIP_INTEGRATOR` is false and `integratorComplete` is not `true`:
 
 1. Load integrator hat instructions:
 

plugin/skills/elaborate/SKILL.md

@@ -452,6 +452,7 @@ If yes, define each unit with **enough detail that a builder with zero prior con
 - **Technical specification**: Specific components, views, functions, or modules to create. If it's a UI, describe what the user sees and interacts with. If it's an API, describe the endpoints and their behavior. If it's a data layer, describe the transformations.
 - **Success criteria**: Specific, testable criteria that reference domain entities (not generic criteria like "displays data")
 - **Dependencies on other units**: What must be built first and why
+- **Risks**: What could go wrong? Security concerns, performance risks, integration fragility, data integrity issues. Each risk should note its impact and mitigation.
 - **What this unit is NOT**: Explicit boundaries to prevent scope creep. If another unit handles related concerns, say so.
 
 **Bad unit description** (too vague, builder will guess wrong):
@@ -620,6 +621,35 @@ Map user selections to config values:
 
 ---
 
+## Phase 5.9: Completion Announcements
+
+Ask the user if they want announcement artifacts generated when the intent completes.
+
+Use `AskUserQuestion`:
+```json
+{
+  "questions": [{
+    "question": "What announcement formats should be generated when this intent completes?",
+    "header": "Announcements",
+    "options": [
+      {"label": "None", "description": "No announcements — just deliver the code"},
+      {"label": "Changelog", "description": "Conventional changelog entry for developers"},
+      {"label": "Release notes", "description": "User-facing feature summary"},
+      {"label": "All formats", "description": "Changelog, release notes, social posts, and blog draft"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+Map selections to the `announcements` array in intent.md frontmatter:
+- "None" → `[]`
+- "Changelog" → `[changelog]`
+- "Release notes" → `[changelog, release-notes]`
+- "All formats" → `[changelog, release-notes, social-posts, blog-draft]`
+
+---
+
 ## Phase 6: Write AI-DLC Artifacts
 
 Create the intent branch and worktree, then write files in `.ai-dlc/{intent-slug}/`:
@@ -653,6 +683,7 @@ git:
   change_strategy: {unit|intent|trunk|bolt}
   auto_merge: {true|false}
   auto_squash: false
+announcements: []  # e.g., [changelog, release-notes, social-posts, blog-draft]
 created: {ISO date}
 status: active
 epic: ""  # Ticketing provider epic key (auto-populated if ticketing provider configured)
@@ -729,6 +760,9 @@ misinterpret what to build.}
 - [ ] {Criterion referencing specific domain entities, not generic}
 - [ ] {Another criterion}
 
+## Risks
+- **{Risk}**: {impact}. Mitigation: {how to address it}.
+
 ## Boundaries
 {What this unit does NOT handle. Reference which other units own related concerns.}