feat(ultraplan-local): add templates/ultrareview-template.md

plugins/ultraplan-local/templates/ultrareview-template.md

@@ -0,0 +1,138 @@
+---
+type: ultrareview
+review_version: "1.0"
+created: {YYYY-MM-DD}
+task: "{Task description from brief.md}"
+slug: {project-slug}
+project_dir: .claude/projects/{YYYY-MM-DD}-{slug}/
+brief_path: .claude/projects/{YYYY-MM-DD}-{slug}/brief.md
+scope_sha_start: {sha-from-progress.json/session_start_sha-OR-null-if-mtime-fallback}
+scope_sha_end: {sha-of-HEAD-at-review-time}
+reviewed_files_count: {N}
+findings:
+  - 0123456789abcdef0123456789abcdef01234567
+  - fedcba9876543210fedcba9876543210fedcba98
+---
+
+# Review: {Task description}
+
+## Executive Summary
+
+Two-to-four sentences: how was the brief honored, what is the verdict
+(BLOCK / WARN / ALLOW), and what is the most important finding the user
+should look at first.
+
+## Coverage
+
+| File | Treatment | Reason |
+|------|-----------|--------|
+| lib/foo.mjs | deep-review | matched deep-review pattern |
+| lib/bar.mjs | summary-only | low-risk, no test patterns matched |
+| dist/bundle.js | skip | matches generated-file pattern |
+| commands/baz.md `[uncommitted]` | deep-review | working-tree change since session_start_sha |
+
+> **`[uncommitted]` annotation** appears in the treatment column for files
+> in the working tree (uncommitted at review time). This is a brief-level
+> contract — see `brief.md` Assumptions section.
+
+## Findings (BLOCKER)
+
+### {finding-id-1-40-char-hex}
+
+- file: lib/foo.mjs
+- line: 42
+- rule_key: BROKEN_SUCCESS_CRITERION
+- brief_ref: SC3 — "review.md is parseable as input to /ultraplan-local"
+- title: Plan-validator rejects review.md when source_findings is flow-style
+- detail: The validator at lib/validators/plan-validator.mjs:N reads
+  `source_findings` via parseDocument(), which does not support flow-style
+  YAML arrays. The fixture review-run-A.md uses flow-style — Handover 6
+  is broken end-to-end.
+- recommended_action: Update template to use block-style YAML, regenerate
+  fixtures, add explicit test in tests/lib/source-findings.test.mjs.
+
+## Findings (MAJOR)
+
+### {finding-id-2-40-char-hex}
+
+- file: agents/code-correctness-reviewer.md
+- line: 34
+- rule_key: MISSING_BRIEF_REF
+- brief_ref: SC1 — "Every BLOCKER/MAJOR finding has rationale_anchor"
+- title: Agent prompt does not require brief_ref in output JSON
+- detail: The trailing JSON block in the agent prompt does not list
+  brief_ref as a required field. Findings emitted by this agent will fail
+  review-validator strict mode.
+- recommended_action: Add `brief_ref` to the required-fields list in the
+  prompt's JSON template.
+
+## Findings (MINOR)
+
+### {finding-id-3-40-char-hex}
+
+- file: lib/parsers/finding-id.mjs
+- line: 18
+- rule_key: MISSING_ERROR_HANDLING
+- brief_ref: NFR — "Token budget honesty"
+- title: TypeError thrown without surrounding context
+- detail: When called with bad input, throws bare TypeError. Caller has no
+  way to know which field was malformed — error message is informative but
+  the error itself has no `cause` chain.
+- recommended_action: Optional improvement: wrap error.cause with the
+  composite input that caused the throw.
+
+## Findings (SUGGESTION)
+
+### {finding-id-4-40-char-hex}
+
+- file: README.md
+- line: 24
+- rule_key: PLACEHOLDER_IN_CODE
+- brief_ref: Constraint — "Path-guard respect"
+- title: TODO comment about cookie path
+- detail: README mentions a TODO about cookie regeneration. Not a code
+  bug but worth noting for v1.1 cleanup.
+- recommended_action: Track in TODO.md if not already.
+
+## Remediation Summary
+
+- 1 BLOCKER → must address before next plan iteration
+- 1 MAJOR → should address before next plan iteration
+- 1 MINOR → nice-to-have for v1.1
+- 1 SUGGESTION → log and move on
+
+If running `/ultraplan-local --brief review.md`, the planner will consume
+the BLOCKER + MAJOR findings as plan goals (their `recommended_action`
+becomes the step intent). MINOR + SUGGESTION are skipped for v1.0
+plan-input.
+
+```json
+{
+  "verdict": "BLOCK",
+  "counts": { "BLOCKER": 1, "MAJOR": 1, "MINOR": 1, "SUGGESTION": 1 },
+  "findings": [
+    {
+      "id": "0123456789abcdef0123456789abcdef01234567",
+      "severity": "BLOCKER",
+      "rule_key": "BROKEN_SUCCESS_CRITERION",
+      "file": "lib/foo.mjs",
+      "line": 42,
+      "brief_ref": "SC3",
+      "title": "Plan-validator rejects review.md when source_findings is flow-style",
+      "detail": "The validator ...",
+      "recommended_action": "Update template to use block-style YAML ..."
+    },
+    {
+      "id": "fedcba9876543210fedcba9876543210fedcba98",
+      "severity": "MAJOR",
+      "rule_key": "MISSING_BRIEF_REF",
+      "file": "agents/code-correctness-reviewer.md",
+      "line": 34,
+      "brief_ref": "SC1",
+      "title": "Agent prompt does not require brief_ref in output JSON",
+      "detail": "The trailing JSON block ...",
+      "recommended_action": "Add brief_ref to the required-fields list ..."
+    }
+  ]
+}
+```