feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

skills/implement-plan/claude-code/SKILL.md

@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
 ## Prerequisite Check (MANDATORY)
 
 Required:
+
 - Plan folder exists under `ai_plan/` at project root
 - `continuation-runbook.md` exists in plan folder
 - `milestone-plan.md` exists in plan folder
@@ -63,7 +64,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
 
 Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
 
-
 If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
 
 ```bash
@@ -101,6 +101,7 @@ Mark first story `in-dev` in `story-tracker.md`.
 #### Step 3: Implement Stories
 
 Execute each story in order. After completing each story:
+
 1. Mark `in-dev` -> `completed` in `story-tracker.md`
 2. Update counts
 3. Mark next story `in-dev`
@@ -135,6 +136,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
 ```
 
 Do NOT push. After committing:
+
 1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
 2. Mark milestone as `approved` in `story-tracker.md`.
 3. Move to next milestone.
@@ -150,6 +152,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
 ```
 
 Use `REVIEW_ID` for all milestone review temp file paths:
+
 - `/tmp/milestone-${REVIEW_ID}.md`
 - `/tmp/milestone-review-${REVIEW_ID}.md`
 - `/tmp/milestone-review-${REVIEW_ID}.json`
@@ -226,6 +229,7 @@ VERDICT: APPROVED
 ```
 
 Rules:
+
 - Order findings from `P0` to `P3`.
 - `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
 - Use `- None.` when a severity has no findings.
@@ -248,7 +252,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
 set -euo pipefail
 ```
 
-
 **If `REVIEWER_CLI` is `pi`:**
 
 Fresh call every round (Pi reviewer calls do not use session resume):
@@ -389,6 +392,7 @@ fi
 Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
 
 After the command completes:
+
 - If `REVIEWER_CLI=cursor`, extract the final review text:
 
 ```bash
@@ -414,14 +418,14 @@ Fallback is allowed only when the helper is missing or not executable.
    - `/tmp/milestone-review-${REVIEW_ID}.runner.out`
 3. Present review to the user:
 
-```
+```markdown
 ## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
 
 [Reviewer feedback]
 ```
 
-4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
-5. Check verdict:
+1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
+2. Check verdict:
    - **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
    - **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
    - **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
@@ -438,7 +442,7 @@ Fallback is allowed only when the helper is missing or not executable.
 
 Summarize revisions for the user:
 
-```
+```markdown
 ### Revisions (Round N)
 - [Change and reason, one bullet per issue addressed]
 ```
@@ -449,7 +453,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
 
 Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
 
-
 **If `REVIEWER_CLI` is `pi`:**
 
 Fresh call with prior-round context (Pi reviewer calls do not use session resume):
@@ -559,20 +562,20 @@ After all milestones are approved and committed:
 git merge implement/<plan-folder-name>
 ```
 
-4. Delete the worktree and its branch:
+1. Delete the worktree and its branch:
 
 ```bash
 git worktree remove <worktree-path>
 git branch -d implement/<plan-folder-name>
 ```
 
-5. Mark plan status as `completed` in `story-tracker.md`.
+1. Mark plan status as `completed` in `story-tracker.md`.
 
 ### Phase 7: Final Report
 
 Present summary:
 
-```
+```markdown
 ## Implementation Complete
 
 **Plan:** <plan-folder-name>
@@ -598,6 +601,7 @@ fi
 ```
 
 Rules:
+
 - Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
 - Notification failures are non-blocking, but they must be surfaced to the user.
 - Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
@@ -608,12 +612,14 @@ Rules:
 **ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
 
 Before starting any story:
+
 1. Open `story-tracker.md`
 2. Mark story `in-dev`
 3. Add notes if relevant
 4. Then begin implementation
 
 After completing any story:
+
 1. Mark story `completed`
 2. Review pending stories
 3. Update Last Updated and Stories Complete counts