docs: update specification — add agents plan errors command

Reviewed and APPROVED. Closes #2883.

docs/specification.md

@@ -344,6 +344,7 @@ The following standards are integrated into the architecture:
 <span style="color: cyan; font-weight: 600;">agents</span> plan artifacts <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> plan prompt <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> <span style="color: #66cc66;">&lt;GUIDANCE&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> plan rollback [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> <span style="color: #66cc66;">&lt;CHECKPOINT_ID&gt;</span>
+<span style="color: cyan; font-weight: 600;">agents</span> plan errors <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
 
 <span style="color: cyan; font-weight: 600;">agents</span> action create <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;">&lt;CFG_FILE&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> action list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;">&lt;NS&gt;</span>] [(<span style="color: magenta;"><span style="color: cyan;">--state</span>|<span style="color: yellow;">-s</span></span>) <span style="color: #66cc66;">&lt;STATE&gt;</span>] [<span style="color: #66cc66;">&lt;REGEX&gt;</span>]
@@ -15823,6 +15824,97 @@ List artifacts produced by a plan.
       - "4 artifacts listed"
     ```
 
+##### agents plan errors
+
+<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan errors <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span></code></pre></div>
+
+**Purpose**
+Show error decisions with recovery hints and retry history for a plan.
+
+**Arguments**
+
+- `<PLAN_ID>`: Plan ID (ULID).
+
+**Examples**
+
+=== "Rich"
+
+    <div class="highlight"><pre><code>
+    <span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan errors 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+
+    ╭─ Plan Errors ──────────────────────────────────────────────────────╮
+    │ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                  │
+    │ <span style="color: cyan; font-weight: 600;">Phase:</span> execute                                                    │
+    │ <span style="color: cyan; font-weight: 600;">State:</span> errored                                                    │
+    │ <span style="color: red; font-weight: 600;">Error:</span> Tool execution failed: write_file permission denied         │
+    │                                                                    │
+    │ <span style="color: cyan; font-weight: 600;">Error Category:</span> tool_execution                                    │
+    │ <span style="color: cyan; font-weight: 600;">Error Phase:</span> execute                                              │
+    │ <span style="color: cyan; font-weight: 600;">Retry Count:</span> 2/3                                                  │
+    │ <span style="color: cyan; font-weight: 600;">Retriable:</span> true                                                   │
+    │                                                                    │
+    │ <span style="color: cyan; font-weight: 600;">Recovery Suggestions:</span>                                             │
+    │   → Check sandbox permissions and retry execution                  │
+    │     <span style="opacity: 0.7;">$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J</span>              │
+    │   → Revert to Strategize phase to adjust the plan                  │
+    │     <span style="opacity: 0.7;">$ agents plan correct --mode revert -g "..." &lt;DECISION_ID&gt;</span>     │
+    ╰────────────────────────────────────────────────────────────────────╯
+
+    <span style="color: #66cc66; font-weight: 600;">✓ OK</span>
+    </code></pre></div>
+
+=== "Plain"
+
+    ```
+    $ agents plan errors 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+
+    Plan Errors
+      Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+      Phase: execute
+      State: errored
+      Error: Tool execution failed: write_file permission denied
+      Error Category: tool_execution
+      Error Phase: execute
+      Retry Count: 2/3
+      Retriable: true
+
+    Recovery Suggestions
+      → Check sandbox permissions and retry execution
+        $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+      → Revert to Strategize phase to adjust the plan
+        $ agents plan correct --mode revert -g "..." <DECISION_ID>
+
+    [OK]
+    ```
+
+=== "JSON"
+
+    ```json
+    {
+      "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
+      "phase": "execute",
+      "state": "errored",
+      "error_message": "Tool execution failed: write_file permission denied",
+      "error_category": "tool_execution",
+      "error_phase": "execute",
+      "retry_count": 2,
+      "max_retries": 3,
+      "is_retriable": true,
+      "recovery_hints": [
+        {
+          "action": "retry",
+          "message": "Check sandbox permissions and retry execution",
+          "cli_command": "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
+        },
+        {
+          "action": "revert",
+          "message": "Revert to Strategize phase to adjust the plan",
+          "cli_command": "agents plan correct --mode revert -g \"...\" <DECISION_ID>"
+        }
+      ]
+    }
+    ```
+
 ##### agents plan prompt
 
 <div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan prompt <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> <span style="color: #66cc66;">&lt;GUIDANCE&gt;</span></code></pre></div>