agentic-devtools 0.2.60__tar.gz → 0.2.61__tar.gz

agentic_devtools-0.2.61/.github/agents/agdt.analyze-workflow.agent.md

@@ -0,0 +1,65 @@
+---
+description: "Analyze Workflow: Perform deep code analysis with multi-identity log scanning, external worktree context, and parameterized scoping via --issue-key or --pr-id"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+Expected input: a kebab-case workflow name, optionally followed by:
+
+- `--issue-key <KEY>` — Scope analysis to a specific issue's worktree state
+  (e.g. `--issue-key PROJECT-123`)
+- `--pr-id <N>` — Scope analysis to a specific PR's worktree state
+  (e.g. `--pr-id 42`)
+- `--static-only` — Disable external worktree log scanning
+
+`--issue-key` and `--pr-id` are mutually exclusive. When neither is provided,
+the analysis uses the current bootstrap worktree key.
+
+If no workflow name is provided, list available workflows and ask the user to
+choose.
+
+**Examples:**
+
+```text
+pull-request-review
+work-on-jira-issue --issue-key PROJECT-123
+pull-request-review --pr-id 42
+work-on-jira-issue --static-only
+```
+
+## Purpose
+
+Perform deep code analysis of any `agentic-devtools` workflow by following the
+structured 8-step methodology defined in the `workflow-analysis` SKILL.md. The
+agent reads the shared skill file, traces the workflow's full call graph, maps
+state lifecycle, identifies async boundaries, enumerates failure modes, and
+produces a structured JSON analysis file and a companion markdown report.
+
+Enhanced capabilities:
+
+- **Parameterized scoping** — use `--issue-key` or `--pr-id` to target a
+  specific worktree's state and logs instead of relying on the current bootstrap
+  context.
+- **Multi-identity log scanning** — scans all identity directories under
+  `.agdt/workflows/` for log evidence, attributing each entry with
+  `[identity: {name}]` for traceability.
+- **External worktree context** — collects read-only log evidence from external
+  git worktrees sharing the same `.agdt/` root (disable with `--static-only`).
+- **`external_context` output field** — structured external worktree evidence
+  in the JSON output schema (`null` when static-only or no external worktrees).
+
+## Instructions
+
+Follow the detailed instructions in the corresponding prompt file
+(`.github/prompts/agdt.analyze-workflow.prompt.md`).
+
+## Next Step
+
+Output files are ready for the **Create Issues from Analysis** agent
+(`agdt.create-issues-from-analysis`, tracked in #1132) to convert findings
+into actionable GitHub issues.

{agentic_devtools-0.2.60 → agentic_devtools-0.2.61}/.github/prompts/agdt.analyze-workflow.prompt.md

@@ -6,6 +6,98 @@ optimization opportunities by following a structured methodology.
 
 ---
 
+## Phase 0: Parameter Parsing & Context Resolution
+
+### 0.1 Parse Extended Arguments
+
+Extract from `$ARGUMENTS`:
+
+- `{workflow_name}` — required kebab-case workflow identifier (e.g.
+  `pull-request-review`, `work-on-jira-issue`)
+- `--issue-key {K}` — optional issue key for worktree scoping (e.g.
+  `--issue-key PROJECT-123`)
+- `--pr-id {N}` — optional PR ID for worktree scoping (e.g. `--pr-id 42`)
+- `--static-only` — optional flag to disable external worktree log scanning
+
+### 0.2 Mutual Exclusion Check
+
+If both `--issue-key` and `--pr-id` are present:
+
+> ERROR: --issue-key and --pr-id are mutually exclusive. Provide one or neither.
+
+Print the error and **stop**.
+
+### 0.3 Resolve Analysis Context
+
+Run the Python helper to resolve the analysis target. Use the variant that
+matches the parameters parsed in §0.1:
+
+**When `--issue-key` was provided:**
+
+```bash
+python -c "
+import sys
+from agentic_devtools.cli.analysis import resolve_analysis_context
+import json
+ctx = resolve_analysis_context(issue_key=sys.argv[1])
+print(json.dumps({'worktree_key': ctx.worktree_key, 'source': ctx.source, 'git_root': str(ctx.git_root), 'caller_state_dir': str(ctx.caller_state_dir)}))
+" "PROJECT-123"
+```
+
+**When `--pr-id` was provided:**
+
+```bash
+python -c "
+import sys
+from agentic_devtools.cli.analysis import resolve_analysis_context
+import json
+ctx = resolve_analysis_context(pr_id=sys.argv[1])
+print(json.dumps({'worktree_key': ctx.worktree_key, 'source': ctx.source, 'git_root': str(ctx.git_root), 'caller_state_dir': str(ctx.caller_state_dir)}))
+" "42"
+```
+
+**When neither was provided (bootstrap fallback):**
+
+```bash
+python -c "
+from agentic_devtools.cli.analysis import resolve_analysis_context
+import json
+ctx = resolve_analysis_context()
+print(json.dumps({'worktree_key': ctx.worktree_key, 'source': ctx.source, 'git_root': str(ctx.git_root), 'caller_state_dir': str(ctx.caller_state_dir)}))
+"
+```
+
+Replace `"PROJECT-123"` and `"42"` with the actual parameter values from §0.1.
+
+Store the resulting `worktree_key` and `git_root` for use in subsequent phases.
+
+### 0.4 Scan Identity Directories
+
+Run the Python helper to discover all identity directories and their logs:
+
+```bash
+python -c "
+import sys
+from pathlib import Path
+from agentic_devtools.cli.analysis import list_identity_directories, scan_identity_logs
+import json
+git_root = Path(sys.argv[1])
+worktree_key = sys.argv[2]
+workflow_name = sys.argv[3]
+identities = list_identity_directories(git_root)
+logs = scan_identity_logs(git_root, worktree_key, workflow_name)
+print(json.dumps({
+  'identities': [{'name': d.name, 'owner_email': d.owner_email} for d in identities],
+  'logs': [{'identity': l.identity, 'path': str(l.path), 'modified_time': l.modified_time} for l in logs]
+}))
+" "<git_root>" "<worktree_key>" "<workflow_name>"
+```
+
+If no identity directories are found, proceed with code-only analysis and note
+this in the findings.
+
+---
+
 ## Phase 1: Parse Input & Load Skill
 
 ### 1.1 Extract Workflow Name
@@ -155,12 +247,42 @@ resolution described later in this prompt (for example,
 `AGENTIC_DEVTOOLS_STATE_DIR` / `get_state_dir()` semantics) rather than
 assuming `.agdt/workflows/`, which is only the default location.
 
-Search for log files under the resolved `state_dir` that match the workflow
-name, including background-task log locations beneath that directory. Read any
-available logs to find actual error messages, timestamps, and state snapshots
-that confirm or refute the hypothesized failure modes from Step 5.
+**Multi-identity scanning:** If Phase 0 resolved identity directories and logs,
+use the `scan_identity_logs()` results from Phase 0.4 instead of searching a
+single directory. Each log excerpt should be attributed with the identity prefix
+using `format_evidence_prefix()`:
+
+```bash
+python -c "
+import sys
+from agentic_devtools.cli.analysis import format_evidence_prefix
+prefix = format_evidence_prefix(sys.argv[1])
+print(prefix)
+" "<identity_name>"
+```
+
+This produces `[identity: <identity_name>]` — prepend this to each log excerpt
+in the evidence field so the reader knows which agent produced the log.
+
+**External worktree context:** When `--static-only` was NOT set in Phase 0,
+also collect external worktree evidence:
+
+```bash
+python -c "
+import sys
+from agentic_devtools.cli.analysis import collect_external_context, build_external_context_field
+from pathlib import Path
+import json
+ctx = collect_external_context(Path(sys.argv[1]), sys.argv[2], static_only=False)
+result = build_external_context_field(ctx)
+print(json.dumps(result))
+" "<git_root>" "<worktree_key>"
+```
 
-If no log files exist, note in each finding's `evidence` field:
+Merge any external log evidence into the findings' `evidence` fields, attributed
+with both the identity prefix and the worktree path.
+
+If no log files exist (from any source), note in each finding's `evidence` field:
 
 > No log evidence available — this finding is based on code analysis only.
 
@@ -263,10 +385,19 @@ fields:
   "priority_order": [1],
   "cascade_graph": {
     "1": [2, 3]
-  }
+  },
+  "external_context": null
 }
 ```
 
+**`external_context` field rules:**
+
+- When `--static-only` was set or no external worktrees were found: set to `null`
+- When external worktree evidence was collected: populate with the dict returned
+  by `build_external_context_field()` (contains `worktrees_scanned`,
+  `log_evidence`, and `identities_scanned`)
+- The field must always be present in the output (set to `null`, never omitted)
+
 ### 3.3 Write Markdown Report
 
 Write `{workflow_name}-analysis.md` to the output directory using the markdown
@@ -312,6 +443,10 @@ Before finalizing, verify the output:
 5. Every key in `cascade_graph` matches a finding `id`, and every referenced
    downstream ID exists in `findings`.
 6. The `cascade_graph` is a DAG (no circular references).
+7. If `external_context` is present and not `null`, validate it contains
+   `worktrees_scanned`, `log_evidence`, and `identities_scanned` fields. If
+   `external_context` is `null`, that is valid (static-only or no external
+   worktrees).
 
 If any validation check fails, fix the output and re-write both files.
 
@@ -349,3 +484,8 @@ If any validation check fails, fix the output and re-write both files.
 | Output directory missing | Create it. |
 | Circular cascade detected | Break the weakest edge and note in executive summary. |
 | Zero findings | Write valid empty output files and report success. |
+| Both `--issue-key` and `--pr-id` provided | Print mutual exclusion error and **stop**. |
+| `--issue-key` or `--pr-id` value missing | Print usage error and **stop**. |
+| No identity directories found | Proceed with code-only evidence. Note in findings. |
+| External worktree inaccessible | Log warning, continue with available evidence. |
+| `--static-only` with external worktrees present | Respect flag — skip external scanning, set `external_context: null`. |

{agentic_devtools-0.2.60 → agentic_devtools-0.2.61}/.github/scripts/speckit-trigger/generate-spec-from-issue.sh

@@ -3,7 +3,8 @@
 # generate-spec-from-issue.sh - Generate a full speckit planning artifact suite
 #
 # Runs the complete speckit pipeline: specify → clarify → checklist → plan →
-# tasks → analyze.  Each phase invokes the Copilot SDK via copilot_generate.py.
+# tasks → analyze → markdownlint validation.  Each phase invokes the Copilot
+# SDK via copilot_generate.py.
 #
 # Usage: generate-spec-from-issue.sh
 #
@@ -24,6 +25,9 @@
 #                              (default: 32000).  If the spec content exceeds this
 #                              limit, deterministic reduction is applied before
 #                              calling the LLM.
+#   MARKDOWNLINT_MAX_ITERATIONS - Maximum number of markdownlint validation/
+#                                 remediation iterations (default: 5).  Phase 7
+#                                 retries up to this limit before failing.
 #
 # Outputs:
 #   GITHUB_OUTPUT: branch_name, spec_file, issue_number, spec_dir
@@ -41,6 +45,16 @@ ISSUE_BODY="${ISSUE_BODY:-}"
 ISSUE_URL="${ISSUE_URL:-}"
 COPILOT_MODEL="${COPILOT_MODEL:-claude-opus-4.6}"
 SPEC_BASE_PATH="${SPEC_BASE_PATH:-specs}"
+MARKDOWNLINT_MAX_ITERATIONS="${MARKDOWNLINT_MAX_ITERATIONS:-5}"
+# Validate as a positive base-10 integer; fall back to default on bad input
+# (e.g., non-numeric strings or octal-looking values like "08").
+if ! [[ "$MARKDOWNLINT_MAX_ITERATIONS" =~ ^[0-9]+$ ]] || (( 10#$MARKDOWNLINT_MAX_ITERATIONS <= 0 )); then
+    echo "Warning: MARKDOWNLINT_MAX_ITERATIONS='$MARKDOWNLINT_MAX_ITERATIONS' is not a valid positive integer. Using default (5)." >&2
+    MARKDOWNLINT_MAX_ITERATIONS=5
+fi
+# Maximum prompt size in characters for per-file LLM remediation (NFR-004).
+# Estimated token count = ceil(char_count / 4); 32000 chars ≈ 8000 tokens.
+MARKDOWNLINT_PROMPT_MAX_CHARS=32000
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
@@ -272,6 +286,288 @@ _strip_footer_from_text() {
     printf '%s' "$text" | sed -E ':a;N;$!ba;s/\n*\n---\n\*Generated by Copilot SDK \([^)]*\)\*[[:space:]]*$//'
 }
 
+# ========================== Markdownlint Validation ==========================
+
+# ---------------------------------------------------------------------------
+# check_npx_available
+#
+# Guards against missing npx.  Returns 0 if npx is available, 1 otherwise
+# with an actionable error message to stderr.
+# ---------------------------------------------------------------------------
+check_npx_available() {
+    if ! command -v npx &>/dev/null; then
+        echo "Error: npx is not available. Install Node.js/npm to enable markdownlint validation." >&2
+        return 1
+    fi
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# parse_markdownlint_output <raw_output>
+#
+# Parses markdownlint-cli2 stdout/stderr output into structured violation
+# records.  Each output line is in the format:
+#   filename:line:col rule/alias description
+# Prints one record per line as tab-separated: filename\tline\tcol\trule\tdescription
+# ---------------------------------------------------------------------------
+parse_markdownlint_output() {
+    local raw="$1"
+    if [[ -z "$raw" ]]; then
+        return 0
+    fi
+    # Match lines like: path/file.md:10:1 MD013/line-length Expected: ...
+    # or: path/file.md:10:1 error MD013/line-length Expected: ...
+    # or: path/file.md:10 MD013/line-length Expected: ...
+    # markdownlint-cli2 v0.22+ inserts "error"/"warning" between location and rule
+    echo "$raw" | while IFS= read -r line; do
+        # Skip empty lines and summary/metadata lines
+        [[ -z "$line" ]] && continue
+        [[ "$line" =~ ^markdownlint-cli2 ]] && continue
+        [[ "$line" =~ ^Finding: ]] && continue
+        [[ "$line" =~ ^Linting: ]] && continue
+        [[ "$line" =~ ^Summary: ]] && continue
+        # Pattern with col and optional severity: filename:line:col [error|warning] rule description
+        if [[ "$line" =~ ^(.+):([0-9]+):([0-9]+)[[:space:]]+(error|warning)[[:space:]]+([A-Z]+[0-9]+/[^[:space:]]+)[[:space:]]+(.+)$ ]]; then
+            printf '%s\t%s\t%s\t%s\t%s\n' "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}" "${BASH_REMATCH[5]}" "${BASH_REMATCH[6]}"
+        # Pattern with col, no severity: filename:line:col rule description
+        elif [[ "$line" =~ ^(.+):([0-9]+):([0-9]+)[[:space:]]+([A-Z]+[0-9]+/[^[:space:]]+)[[:space:]]+(.+)$ ]]; then
+            printf '%s\t%s\t%s\t%s\t%s\n' "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}" "${BASH_REMATCH[4]}" "${BASH_REMATCH[5]}"
+        # Pattern without col: filename:line rule description
+        elif [[ "$line" =~ ^(.+):([0-9]+)[[:space:]]+([A-Z]+[0-9]+/[^[:space:]]+)[[:space:]]+(.+)$ ]]; then
+            printf '%s\t%s\t%s\t%s\t%s\n' "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "0" "${BASH_REMATCH[3]}" "${BASH_REMATCH[4]}"
+        else
+            # Explicit no-op: prevents unmatched lines from leaving a non-zero
+            # exit status on the if-elif chain, which with set -euo pipefail
+            # would propagate through the pipeline and abort the caller.
+            :
+        fi
+    done
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# compute_violation_fingerprint <parsed_violations>
+#
+# Produces a deterministic fingerprint from parsed violations for stall
+# detection.  Uses filename, line, col, and rule (stable identity fields).
+# Prints an md5sum hash to stdout.
+# ---------------------------------------------------------------------------
+compute_violation_fingerprint() {
+    local violations="$1"
+    if [[ -z "$violations" ]]; then
+        echo "empty"
+        return 0
+    fi
+    # Extract stable fields (filename, line, col, rule), sort, and hash
+    echo "$violations" | awk -F'\t' '{print $1, $2, $3, $4}' | sort | md5sum | awk '{print $1}'
+}
+
+# ---------------------------------------------------------------------------
+# run_markdownlint_validation <spec_dir>
+#
+# Runs the markdownlint validation/remediation loop for markdown files in
+# the given spec directory.  Attempts auto-fix first, then LLM remediation
+# if violations remain.  Stops on clean result, stall detection, or max
+# iterations.
+#
+# Returns 0 on success (all files lint-clean), non-zero on failure.
+# ---------------------------------------------------------------------------
+run_markdownlint_validation() {
+    local spec_dir="$1"
+
+    # Guard: check npx availability (EC5)
+    if ! check_npx_available; then
+        return 1
+    fi
+
+    # Guard: check for markdown files (EC9 — empty spec directory)
+    # Use find instead of bash glob to reliably discover nested .md files
+    # without requiring shopt -s globstar (which is not enabled by default).
+    local md_files=()
+    while IFS= read -r -d '' f; do
+        md_files+=("$f")
+    done < <(find "$spec_dir" -name '*.md' -type f -print0)
+
+    if [[ ${#md_files[@]} -eq 0 ]]; then
+        echo "[Phase 7] No markdown files found in $spec_dir — skipping validation." >&2
+        return 0
+    fi
+
+    local max_iter="$MARKDOWNLINT_MAX_ITERATIONS"
+    local prev_fingerprint=""
+    local iteration=0
+    local total_iterations=0
+    local final_violation_count=0
+    local last_lint_exit=1
+    local stall_detected=false
+
+    echo "[Phase 7] Starting markdownlint validation (max $max_iter iterations, ${#md_files[@]} markdown files)" >&2
+
+    for (( iteration=1; iteration<=max_iter; iteration++ )); do
+        total_iterations=$iteration
+        echo "" >&2
+        echo "[Phase 7] Iteration $iteration/$max_iter" >&2
+
+        # Step 1: Auto-fix pass
+        echo "[Phase 7]   Running markdownlint-cli2 --fix..." >&2
+        npx markdownlint-cli2 --no-globs --fix "${md_files[@]}" 2>&1 || true
+
+        # Step 2: Check-only pass — capture output
+        local lint_output=""
+        local lint_exit=0
+        lint_output=$(npx markdownlint-cli2 --no-globs "${md_files[@]}" 2>&1) || lint_exit=$?
+        last_lint_exit=$lint_exit
+
+        if [[ $lint_exit -eq 0 ]]; then
+            echo "[Phase 7]   ✓ All files lint-clean after auto-fix." >&2
+            final_violation_count=0
+            break
+        fi
+
+        # Step 3: Parse remaining violations
+        local parsed=""
+        parsed=$(parse_markdownlint_output "$lint_output")
+
+        local violation_count=0
+        if [[ -n "$parsed" ]]; then
+            violation_count=$(printf '%s\n' "$parsed" | awk 'END{print NR}')
+        fi
+        final_violation_count=$violation_count
+
+        # Guard: lint failed but parser found no violations — treat as failure
+        # with diagnostics so unexpected output formats don't silently pass.
+        if [[ $violation_count -eq 0 ]]; then
+            echo "[Phase 7]   ⚠ markdownlint exited $lint_exit but no violations could be parsed." >&2
+            echo "[Phase 7]   Raw output:" >&2
+            echo "$lint_output" | head -20 >&2
+            break
+        fi
+
+        # Collect affected files
+        local affected_files=""
+        if [[ -n "$parsed" ]]; then
+            affected_files=$(echo "$parsed" | awk -F'\t' '{print $1}' | sort -u)
+        fi
+        local affected_count=0
+        if [[ -n "$affected_files" ]]; then
+            affected_count=$(printf '%s\n' "$affected_files" | awk 'END{print NR}')
+        fi
+
+        echo "[Phase 7]   $violation_count violation(s) remaining in $affected_count file(s)" >&2
+        if [[ -n "$affected_files" ]]; then
+            echo "$affected_files" | while IFS= read -r af; do
+                echo "[Phase 7]     - $af" >&2
+            done
+        fi
+
+        # Step 4: Stall detection
+        local current_fingerprint=""
+        current_fingerprint=$(compute_violation_fingerprint "$parsed")
+
+        if [[ "$current_fingerprint" == "$prev_fingerprint" ]]; then
+            echo "[Phase 7]   ⚠ Stall detected — violations unchanged from previous iteration." >&2
+            stall_detected=true
+            break
+        fi
+        prev_fingerprint="$current_fingerprint"
+
+        # Step 5-6: LLM remediation for each file with violations
+        echo "[Phase 7]   Running LLM remediation for $affected_count file(s)..." >&2
+
+        while IFS= read -r target_file; do
+            [[ -z "$target_file" ]] && continue
+
+            # Gather violations for this specific file
+            local file_violations=""
+            file_violations=$(echo "$parsed" | awk -F'\t' -v f="$target_file" '$1 == f {printf "Line %s: %s %s\n", $2, $4, $5}')
+
+            if [[ -z "$file_violations" ]]; then
+                continue
+            fi
+
+            # Read file content and strip footer
+            local file_content=""
+            file_content=$(cat "$target_file")
+            local stripped_content=""
+            stripped_content=$(strip_model_footer "$file_content")
+
+            # Build per-file LLM prompt (enforce <8K tokens ≈ 32000 chars)
+            local llm_prompt="You are a markdown lint fixer. Fix the following markdownlint violations in the markdown file below.
+
+## Violations to fix
+$file_violations
+
+## Rules
+- Output ONLY the corrected markdown content, nothing else
+- Do NOT add commentary, explanations, or code fences around the output
+- Do NOT change the meaning or structure of the content beyond what is needed to fix the violations
+- Preserve all headings, lists, tables, and code blocks
+- For MD041 (first-line-heading): ensure the file starts with a top-level heading (# Heading)
+- For MD013 (line-length): break long lines at natural points (after punctuation, between clauses) to stay under 200 characters
+- For MD040 (fenced-code-language): add an appropriate language identifier to fenced code blocks
+
+## File content to fix
+$stripped_content"
+
+            # Check prompt size (NFR-004: <8K tokens ≈ MARKDOWNLINT_PROMPT_MAX_CHARS chars)
+            local prompt_len=${#llm_prompt}
+            if [[ $prompt_len -gt $MARKDOWNLINT_PROMPT_MAX_CHARS ]]; then
+                echo "[Phase 7]     Warning: Prompt for $target_file exceeds $MARKDOWNLINT_PROMPT_MAX_CHARS chars ($prompt_len). Skipping LLM remediation for this file." >&2
+                continue
+            fi
+
+            # Call LLM
+            local corrected=""
+            if corrected=$(call_llm "$llm_prompt"); then
+                if [[ -n "$corrected" ]]; then
+                    printf '%s\n' "$corrected" > "$target_file"
+                    append_model_footer "$target_file"
+                    echo "[Phase 7]     ✓ LLM remediation applied to $(basename "$target_file")" >&2
+                else
+                    echo "[Phase 7]     Warning: LLM returned empty content for $(basename "$target_file"). Skipping." >&2
+                fi
+            else
+                echo "[Phase 7]     Warning: LLM call failed for $(basename "$target_file"). Continuing." >&2
+            fi
+        done <<< "$affected_files"
+    done
+
+    # Summary logging
+    echo "" >&2
+    echo "[Phase 7] === Validation Summary ===" >&2
+    echo "[Phase 7]   Iterations run: $total_iterations/$max_iter" >&2
+    echo "[Phase 7]   Final violations: $final_violation_count" >&2
+    echo "[Phase 7]   Last lint exit code: $last_lint_exit" >&2
+    if [[ "$stall_detected" == "true" ]]; then
+        echo "[Phase 7]   Stall detected: yes" >&2
+    fi
+
+    # Return status — gate on actual lint exit code, not just parsed count.
+    # This prevents silent success when lint fails but output can't be parsed.
+    if [[ $last_lint_exit -eq 0 && $final_violation_count -eq 0 ]]; then
+        echo "[Phase 7]   Result: ✓ SUCCESS — all files lint-clean" >&2
+        return 0
+    fi
+
+    # Check unparseable output before exhaustion: when lint fails but no
+    # violations were parsed, this is the most specific diagnosis regardless
+    # of whether we also hit the iteration limit.
+    if [[ $last_lint_exit -ne 0 && $final_violation_count -eq 0 ]]; then
+        echo "[Phase 7]   Result: ✗ FAILED — markdownlint exited $last_lint_exit but violations could not be parsed" >&2
+    elif [[ "$stall_detected" == "true" ]]; then
+        echo "[Phase 7]   Result: ✗ FAILED — stall detected with $final_violation_count remaining violation(s)" >&2
+    elif [[ $total_iterations -ge $max_iter && $final_violation_count -gt 0 ]]; then
+        echo "[Phase 7]   Result: ✗ FAILED — max iterations ($max_iter) exhausted with $final_violation_count remaining violation(s)" >&2
+    fi
+
+    # Print remaining violations for actionable output (capped at 50 lines to
+    # keep CI logs readable; full output is available via markdownlint re-run)
+    echo "[Phase 7]   Remaining violations:" >&2
+    npx markdownlint-cli2 --no-globs "${md_files[@]}" 2>&1 | head -50 >&2 || true
+
+    return 1
+}
+
 # ========================== Phase Functions ==================================
 
 # ---------------------------------------------------------------------------
@@ -777,7 +1073,7 @@ $tasks_content"
 # ========================== Orchestration ====================================
 
 echo ""
-echo "=== Phase 1/6: Specify ==="
+echo "=== Phase 1/7: Specify ==="
 SPEC_CONTENT=$(run_specify_phase) || { echo "Error: Specify phase failed after retries" >&2; exit 1; }
 if [[ -z "$SPEC_CONTENT" ]]; then
     echo "Error: Specify phase returned empty content" >&2
@@ -788,30 +1084,35 @@ append_model_footer "$SPEC_DIR/spec.md"
 echo "✓ Phase 1 complete: spec.md"
 
 echo ""
-echo "=== Phase 2/6: Clarify ==="
+echo "=== Phase 2/7: Clarify ==="
 run_clarify_phase || { echo "Error: Clarify phase failed after retries" >&2; exit 1; }
 echo "✓ Phase 2 complete: spec.md updated with clarifications"
 
 echo ""
-echo "=== Phase 3/6: Checklist ==="
+echo "=== Phase 3/7: Checklist ==="
 run_checklist_phase || { echo "Error: Checklist phase failed after retries" >&2; exit 1; }
 echo "✓ Phase 3 complete: checklists/requirements.md"
 
 echo ""
-echo "=== Phase 4/6: Plan ==="
+echo "=== Phase 4/7: Plan ==="
 COPILOT_TIMEOUT=900 run_plan_phase || { echo "Error: Plan phase failed after retries" >&2; exit 1; }
 echo "✓ Phase 4 complete: plan.md (+ optional artifacts)"
 
 echo ""
-echo "=== Phase 5/6: Tasks ==="
+echo "=== Phase 5/7: Tasks ==="
 COPILOT_TIMEOUT=900 run_tasks_phase || { echo "Error: Tasks phase failed after retries" >&2; exit 1; }
 echo "✓ Phase 5 complete: tasks.md"
 
 echo ""
-echo "=== Phase 6/6: Analyze ==="
+echo "=== Phase 6/7: Analyze ==="
 COPILOT_TIMEOUT=900 run_analyze_phase || { echo "Error: Analyze phase failed after retries" >&2; exit 1; }
 echo "✓ Phase 6 complete: analysis-report.md"
 
+echo ""
+echo "=== Phase 7/7: Markdownlint Validation ==="
+run_markdownlint_validation "$SPEC_DIR" || { echo "Error: Markdownlint validation failed — lint violations remain after remediation" >&2; exit 1; }
+echo "✓ Phase 7 complete: all markdown files lint-clean"
+
 # Output results (spec_dir as repo-relative path for portability)
 # Derive from SPEC_DIR by stripping REPO_ROOT prefix, so it stays correct
 # even if SPEC_BASE_PATH is set to an absolute-like path.