@exaudeus/workrail 3.12.0 → 3.14.0

package/workflows/mr-review-workflow.json

@@ -1,277 +0,0 @@
-{
-  "id": "mr-review-workflow",
-  "name": "Adaptive MR Review Workflow",
-  "version": "0.2.0",
-  "description": "An adaptive workflow to guide an AI agent in performing a comprehensive code review. It adjusts its rigor based on MR complexity and includes checkpoints for architectural and self-critique to provide deep, actionable feedback.",
-  "preconditions": [
-    "User has the full code diff accessible (e.g., as text in a file).",
-    "User has the MR title, purpose, and any relevant ticket numbers.",
-    "The agent has access to file-reading tools."
-  ],
-  "clarificationPrompts": [
-    "Provide the associated ticket ID(s)/link(s) and paste full text if possible.",
-    "Provide links (or attach) any dev plan, design/architecture doc, or BRD relevant to this MR.",
-    "Provide the code diff (paste content or give a file path)."
-  ],
-  "metaGuidance": [
-    "The ultimate goal is to assist, not replace, a human reviewer. The human owns the final merge decision.",
-    "All feedback should be constructive and actionable. Explain the 'why' behind suggestions.",
-    "The goal is continuous improvement, not perfection. Approve changes that are 'better' to maintain velocity.",
-    "Foster a blameless culture of collective ownership. The code is a shared asset.",
-    "Use prefixes like 'Nit:' for non-blocking, minor suggestions to keep focus on important issues.",
-    "Embrace small, single-purpose pull requests for faster, more thorough reviews.",
-    "When citing issues, always try to provide specific file paths and line numbers from the diff.",
-    "Maintain the persona of a helpful, collaborative senior engineer.",
-    "If at any point you determine that a crucial piece of information is missing, you must pause and ask the user to provide it.",
-    "Auto-advance: after completing each step, immediately get the next step; only pause for explicit requireConfirmation or missing critical inputs.",
-    "FunctionReferences are mandatory. When a step lists functionReferences, execute each in the listed order before producing chat output.",
-    "FunctionReferences are conceptual (not MCP tools). ‘Execute’ means: read the function’s definition and perform those actions using your available tools; do not look for tools with the same names.",
-    "Use each function's definition as the authoritative checklist for how to perform the step and what to produce (doc updates, context vars).",
-    "Document I/O: create/update the file at reviewDocPath using file-writing tools. If the agent cannot write files, output the exact doc content with the intended path so the user can save it.",
-    "If a function requires inputs that are missing, state exactly what is missing and pause. Otherwise, do not ask for confirmation.",
-    "If prompt text and a function definition conflict, prefer the function definition for the how, and the step prompt for the what.",
-    "Phase 1a is user-driven: request ticket/dev/design/BRD; wait for user reply; do not search or analyze code in this step.",
-    "Do not self-confirm. Only proceed after explicit user confirmation or 'skip'; then set contextGatheringComplete=true or skipContextGathering=true.",
-    "discoverModulePatterns(): Compute moduleRoot; scan only moduleRoot to build patternCatalog.",
-    "discoverModulePatterns() details: moduleRoot = nearest common ancestor, clamped to package/src; catalog = naming, DI, errors, logging, tests, layout.",
-    "consolidatePatternFindings(): Compare changes to patternCatalog (scoped to moduleRoot).",
-    "consolidatePatternFindings() details: produce patternFindings + grouped patternAppendix; set patternAppendixReady=true.",
-    "initReviewDoc(): Create live Markdown at project root; set reviewDocPath.",
-    "initReviewDoc() details: filename '<YYYY-MM-DD>--<ticket-or-branch>--mr-review.md'; insert section markers; if no file I/O, output full doc and path.",
-    "upsertSection(): Upsert under a known section marker; never duplicate sections; keep formatting concise.",
-    "appendChangedFileRow(): Append/update Changed Files table row: File | +/- | Summary | Risk.",
-    "appendFinding(): Append finding under severity (Critical/Major/Minor) with path:line, 1–2-line rationale, optional tiny diff.",
-    "appendPatternResult(): Append Pattern Adherence row (Check | Result | Note); add brief per-file deviations.",
-    "appendMRComment(): Append copy-ready MR comment: file:line, short title, rationale, optional tiny diff.",
-    "logRevision(): Append timestamped message to the Revision Log describing the update.",
-    "discoverHygieneSignals(): Scan moduleRoot changed files + neighbors for hygiene issues.",
-    "discoverHygieneSignals() details: focused/disabled/skipped tests; no‑assert tests; commented‑out code; stale/misleading comments; TODO/FIXME/HACK/BUG w/o tickets; pattern inconsistencies; debug prints; unused code.",
-    "consolidateHygieneFindings(): Cap total ≤10 and ≤3 per category; dedupe; group by file.",
-    "consolidateHygieneFindings() details: elevate Major only for clearly risky cases; produce category counts and capped items.",
-    "appendHygieneFinding(): Append hygiene bullet grouped by file: 'path:line — short note (≤2 lines)'.",
-    "appendHygieneFinding() details: if duplicated in Nits, reference '(linked in Nits)'.",
-    "finalizeReviewDocument(): Branch on complexity for different finalization logic.",
-    "finalizeReviewDocument() Trivial: brief approve summary; ≤2 hygiene; quick nits; set status=Final; log.",
-    "finalizeReviewDocument() Non‑trivial: exec summary (3 positives, 3 risks, recommendation); dedupe/sort findings; ensure sections + curated comments; set status=Final; log."
-  ],
-  "steps": [
-    {
-      "id": "phase-0-triage",
-      "title": "Phase 0: Triage & Review Focus",
-      "prompt": "To begin the Merge Request review, please provide the full context below and classify the MR's complexity. This will tailor the depth of the review.\n\n**1. MR Context:**\n* **MR Title/Purpose:** [User provides the title and a brief description of its purpose.]\n* **Related Ticket(s):** [User provides ticket numbers or links.]\n* **Key Requirements/Acceptance Criteria:** [User lists key requirements from the ticket(s).]\n\n**2. Code Diff:**\n[User pastes the full `git diff` output or provides a path to a file containing the diff.]\n\n**3. Complexity Classification & Focus:**\n* **Classification:** Please choose one: **[Trivial]**, **[Standard]**, or **[High-Risk]**.\n* **PR Size:** Is this a small, focused change (<400 lines)? If not, does it have a single, clear purpose?\n* **Areas of Focus (Optional):** Are there specific areas you want me to pay close attention to? (e.g., 'performance implications', 'API design', 'data integrity').",
-      "agentRole": "You are a code review coordinator and triage specialist with expertise in assessing merge request complexity and risk. Your role is to efficiently classify reviews and establish appropriate focus areas to ensure the right level of scrutiny for each change.",
-      "guidance": [
-        "**[Trivial]:** For minor fixes (typos, docs). This will run a condensed, single-phase review.",
-        "**[Standard]:** For typical features or bug fixes. This uses the full, multi-phase review process.",
-        "**[High-Risk]:** For major architectural changes or features touching sensitive code. This follows the full process with maximum diligence."
-      ],
-      "functionReferences": ["initReviewDoc()", "logRevision()"],
-      "requireConfirmation": true
-    },
-    {
-      "id": "phase-1-context",
-      "title": "Phase 1: Contextual Understanding & Confirmation",
-      "prompt": "My goal is to ensure I fully understand the MR before the deep analysis. Based on the context you provided, I will perform the following tasks:\n\n1.  **Summarize Goal:** Briefly summarize what I understand to be the primary goal and scope of this MR.\n2.  **File Overview:** List all changed files (added, modified, deleted) and provide a one-sentence summary of the changes for each.\n3.  **Initial Questions:** Formulate any immediate questions I have about the MR's purpose or requirements.\n4.  **Confirmation Gate:** Does my summary accurately reflect the MR's goal? Please confirm before I proceed.\n\nI will also update the live review document with the Changed Files table and the Context summary.",
-      "agentRole": "You are a thorough code review analyst specializing in requirement comprehension and change impact assessment. Your strength is quickly understanding the intent and scope of code changes while identifying potential gaps in understanding early in the review process.",
-      "guidance": [
-        "This is a critical sanity check. If the agent's summary is incorrect, correct it now to prevent a flawed review. This step is skipped for 'Trivial' reviews.",
-        "Doc writes: update only 'Context Summary' and 'Changed Files' sections; do not add 'Questions' or extra headings.",
-        "Ask any clarifying questions in chat only; do not write them into the doc.",
-        "Do not create placeholders for issues (Critical/Major/Minor) in this step."
-      ],
-      "runCondition": { "var": "complexity", "not_equals": "Trivial" },
-      "requireConfirmation": true,
-      "functionReferences": ["upsertSection()", "appendChangedFileRow()", "logRevision()"]
-    },
-    
-    {
-      "id": "phase-1a-llm-context-gathering",
-      "title": "Phase 1a: Comprehensive Context Gathering",
-      "prompt": "To perform a thorough review, I need you to provide source documents. In this step I will not search or analyze code—I'm waiting for your inputs. Please provide:\n\n1. **Ticket(s):** Link(s) and, if possible, paste the full text (requirements, acceptance criteria).\n2. **Dev/Design Docs:** Dev plan; design/architecture docs; any BRD/ADR/decision records relevant to this MR.\n3. **Technical Context:** If this change relies on other parts of the codebase, paste relevant code snippets or file contents; include coding standards or module conventions if available.\n\nI will synthesize this information once received.\n\n**Confirmation & Gating:**\n- After you confirm that I have the right context (or explicitly instruct me to skip), I will set `contextGatheringComplete = true` or `skipContextGathering = true` accordingly.\n- I will not proceed to deeper analysis until one of these is set.",
-      "agentRole": "You are a context-aware analyst ensuring you have all necessary information before starting a deep review.",
-      "guidance": [
-        "User-driven step: ask for ticket, dev plan, design/architecture docs, BRD/ADR, and any coding standards.",
-        "Do not search or analyze code in this step; wait for user inputs.",
-        "Only after explicit confirmation or 'skip' set contextGatheringComplete=true or skipContextGathering=true."
-      ],
-      "runCondition": { "var": "complexity", "not_equals": "Trivial" },
-      "requireConfirmation": true
-    },
-    {
-      "id": "phase-1b-familiarization",
-      "title": "Phase 1b: Neighborhood, Call Graph, and Contracts Familiarization",
-      "prompt": "Build a lightweight understanding of surrounding code to increase review accuracy.\n\nTasks:\n1) Neighborhood Map: For each changed file, list immediate neighbors in moduleRoot (imports/exports/same-folder), co-located tests, and closest entry points (routes/endpoints/commands). Cap neighbors per file.\n2) Bounded Call Graph: For changed functions/classes, gather callers and callees up to 2 hops within moduleRoot; cap nodes/edges; prioritize edges touching changed code.\n3) Contracts & Invariants: List public symbols, API endpoints, DB/tables/messages touched nearby. Capture any stated invariants or assumptions from comments.\n\nDoc-first: Upsert sections 'Neighborhood Map', 'Bounded Call Graph', and 'Contracts & Invariants' with concise tables/bullets. Include only the highest-signal items (apply caps).",
-      "agentRole": "You are a codebase navigator building context around the change to improve downstream analysis.",
-      "guidance": [
-        "Initialize majorIssuesFound = false.",
-        "Scope strictly to moduleRoot and changed files plus immediate neighbors.",
-        "Cap per-file neighbors and graph size to avoid noise; prefer edges directly related to the diff.",
-        "Write full details to the live doc; in chat, keep output minimal.",
-        "Small Multiples: for each changed symbol, render mini path lines (≤6 nodes) for top 1–2 inbound and 1–2 outbound paths; width ≤100; highlight changed as [*name*]; tag HOT where applicable.",
-        "Path Lists with Aliasing: collapse repeated subpaths using deterministic aliases (A1, A2, ...); reuse aliases across paths; append an 'Alias Legend' listing alias → full subpath.",
-        "Ordering: HOT-first, then shortest path, then alphabetical; depth ≤2; dedupe identical paths.",
-        "Caps: ≤5 anchors; ≤8 total paths; ≤12 nodes across all small multiples; if exceeded, render 'Adjacency Summary' with per-edge counts instead.",
-        "Flow Anchors: map entrypoints to changed symbols; table 'Anchor | Type | Target Symbol | Notes'; cap ≤5 anchors.",
-        "Hot-Path ranking: score edges (diff touch, anchor, ticket keyword, test ref); tag HOT if score ≥ threshold; prefer HOT paths in ASCII output.",
-        "Legend in doc: [*name*]=changed; HOT=high-impact; 'A -> B'=calls; 'Route -> Handler'; 'Job -> Worker'.",
-        "If caps exceeded, write 'Adjacency Summary': 'Node | In | Out | Notes' (top-K by degree/frequency) and add 1–2 uncertainty questions."
-      ],
-      "runCondition": { "and": [ { "var": "complexity", "not_equals": "Trivial" }, { "or": [ { "var": "contextGatheringComplete", "equals": true }, { "var": "skipContextGathering", "equals": true } ] } ] },
-      "functionReferences": ["upsertSection()", "logRevision()"],
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-2-depth-analysis-loop",
-      "type": "loop",
-      "title": "Phase 2: Progressive Depth Analysis",
-      "runCondition": { "and": [ { "var": "complexity", "not_equals": "Trivial" }, { "or": [ { "var": "contextGatheringComplete", "equals": true }, { "var": "skipContextGathering", "equals": true } ] } ] },
-      "loop": {
-        "type": "for",
-        "count": 4,
-        "maxIterations": 4,
-        "iterationVar": "analysisDepth"
-      },
-      "body": [
-        {
-          "id": "discover-module-patterns",
-          "title": "Discover Module Patterns (Depth 1)",
-          "prompt": "Compute `moduleRoot` as the nearest common ancestor of changed files, clamped to the package or `src/` subtree. Scan only within `moduleRoot` to gather exemplars (naming, DI, error handling, logging, test style, file layout). Exclude changed files from discovery so they cannot define patterns. Only elevate a rule to a 'pattern' when observed ≥2 times across distinct files; record singletons as 'candidate conventions'. Produce `patternCatalog` (validated patterns) and `patternExamples` (1–3 exemplars per pattern) in context. Do not block or require confirmation.",
-          "agentRole": "You are a codebase pattern scout building a concise pattern catalog for the current module.",
-          "guidance": [
-            "Scope strictly to `moduleRoot` discovered from changed files.",
-            "Exclude changed files from discovery; use them only later for comparison.",
-            "Require ≥2 occurrences across distinct files to qualify as a pattern; otherwise mark as 'candidate convention'.",
-            "Capture 1–3 exemplars per validated pattern with file:line for the doc.",
-            "Cap exemplars (e.g., 3–5 per concern) for speed."
-          ],
-          "runCondition": { "var": "analysisDepth", "equals": 1 },
-          "functionReferences": ["discoverModulePatterns()"],
-          "requireConfirmation": false
-        },
-        {
-          "id": "perform-analysis-pass",
-          "title": "Analysis Pass {{analysisDepth}} of 4",
-          "prompt": "Act as a Senior Staff Engineer. Your task is to review the code based on the checklist for the current analysis depth. Think step-by-step.\n\n**Current Depth: {{analysisDepth}}**\n\n**Checklist:**\n* **Depth 1 (Basic Scan):** Check for style guide violations, simple bugs (e.g., typos, unused variables), and common security vulnerabilities (OWASP Top 10).\n* **Depth 2 (Standard Review):** Check for logical errors, edge cases, adherence to SOLID principles, and maintainability issues.\n* **Depth 3 (Deep Architectural Review):** Check for alignment with system architecture, long-term impact, performance bottlenecks, and dependency risks.\n\n**Instructions:**\n1.  **Summarize Focus:** State which depth level you are on and what you will focus on.\n2.  **Analyze:** Perform the review based on the checklist for depth {{analysisDepth}}.\n3.  **List Findings:** Document your findings, categorizing them as 'Critical', 'Major', or 'Minor'.\n4.  **Set Flag:** If you find any 'Critical' or 'Major' issues, set the context variable `majorIssuesFound = true`.",
-          "agentRole": "You are a Senior Staff Engineer performing a structured, multi-pass code review with increasing levels of scrutiny.",
-          "guidance": [
-            "At each depth, focus only on the items in that checklist.",
-            "Use Chain-of-Thought reasoning to explain your findings (keep chat concise; write full details to the doc).",
-            "Retrieval bias: Prefer reading files/functions from 'Neighborhood Map' and HOT paths before broader scans.",
-            "Depth 2: Prefer Flow Anchors and HOT paths; walk 2–3 inbound/outbound traces; verify control/data flow vs invariants; record surprises.",
-            "Depth 3: On HOT paths, check module boundaries, DI patterns, performance, and consumer contracts; note potential breakages.",
-            "Propose tiny diffs (non-blocking) for the top 1–2 Major findings: fenced unified diff with file paths; ≤8 changed lines total and ≤2 hunks per patch; add one-line rationale; scope narrow; skip if ambiguous and state why.",
-            "For each proposed patch, add a matching ready-to-copy MR comment (file:line + rationale).",
-            "Append patches to the 'Proposed Patches' section; append MR comments and log the revision.",
-            "Caps per pass: ≤2 patches; ≤3 MR comments; ≤1200 chars of total patch text.",
-            "Self-critique: list 1–2 least-confident areas and what would increase confidence under 'Confidence & Follow-ups'."
-          ],
-          "runCondition": { "or": [ { "var": "analysisDepth", "equals": 1 }, { "var": "analysisDepth", "equals": 2 }, { "var": "analysisDepth", "equals": 3 } ] },
-          "functionReferences": ["upsertSection()", "appendFinding()", "appendMRComment()", "logRevision()"],
-          "requireConfirmation": false
-        },
-        {
-          "id": "perform-nit-hunt",
-          "title": "Nit Hunt (Depth 4)",
-          "prompt": "Perform a focused nit hunt in `moduleRoot` on changed files and immediate neighbors. Be picky but objective. Provide concise, actionable nits with one-line rationale and suggested fix.",
-          "agentRole": "You are a meticulous reviewer surfacing small, high-signal improvements.",
-          "guidance": [
-            "Targets: naming clarity; small readability/style inconsistencies; redundant comments; commented/dead code; import/order polish; safe micro-perf; test naming/structure.",
-            "Quotas: if majorIssuesFound==true aim 5–8 (cap 12); else aim 8–12 (cap 15); ≤3 per category; 1–2 lines each; dedupe; group by file; prefix 'Nit:'.",
-            "MUST add ready-to-copy MR comments for the top 3 nits (file:line, short title, 1–2 line rationale, optional tiny diff); log the revision.",
-            "Append Nit grouped by file: 'path:line — nit text'."
-          ],
-          "runCondition": { "var": "analysisDepth", "equals": 4 },
-          "functionReferences": ["appendMRComment()", "upsertSection()", "logRevision()"],
-          "requireConfirmation": false
-        }
-      ]
-    },
-    {
-      "id": "consolidate-patterns",
-      "title": "Consolidate Pattern Findings",
-      "prompt": "Using `moduleRoot` and `patternCatalog`, compare the MR changes to validated patterns (patterns observed ≥2 times across distinct files). Do not use changed code to define patterns. Summarize adherence and deviations, and generate a grouped `patternAppendix` (by directory/file). If no patterns meet the threshold, state this and list 'candidate conventions' separately as informative only. Set `patternAppendixReady = true`.",
-      "agentRole": "You are a senior engineer consolidating pattern adherence findings for clear reporting.",
-      "guidance": [
-        "Restrict to the module of the MR (`moduleRoot`).",
-        "Avoid re-scanning if `patternCatalog` already exists; reuse it.",
-        "Do not treat changed code as patterns; match only against validated patterns from `patternCatalog` (≥2 distinct occurrences).",
-        "Produce 'Patterns' and 'Pattern Deviations' sections: adherence table with confidence + counts; deviation ledger with file:line, rationale, and suggested alignment.",
-        "Include per-pattern occurrence counts in the module (excluding changed files)."
-      ],
-      "runCondition": { "var": "complexity", "not_equals": "Trivial" },
-      "functionReferences": ["consolidatePatternFindings()", "appendPatternResult()", "upsertSection()", "logRevision()"],
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-3-impact-analysis",
-      "title": "Phase 3: Testing, Documentation & Impact Analysis",
-      "prompt": "My goal is to assess the secondary impacts of this change.\n\n1.  **Testing:** Based on the code changes, what tests would be expected (unit, integration, etc.)? Are new tests included? Are existing tests updated? Are there obvious gaps in test coverage for the new logic?\n2.  **Documentation:** Is new or complex logic adequately commented? Could any external documentation (e.g., READMEs) be affected by this change?\n3.  **Breaking Changes:** Are there any changes that could break backward compatibility for APIs or other parts of the codebase?\n\nDoc-first subsections to add/update:\n- Impacted User Flows: table 'Flow/Anchor | Type | Path/ID | Handler Chain (short) | Impact | Risk(L/M/H)'.\n- Affected Consumers: table 'Consumer | Type | Breakage Risk | Migration Note'.\n- Test Gaps & Proposals: table 'Scope | Target | Purpose | Sketch'.",
-      "agentRole": "You are a software quality engineer specializing in testing strategy and impact analysis. Your expertise includes identifying testing gaps, documentation requirements, and potential breaking changes that could affect system stability or user experience.",
-      "guidance": [
-        "Assessing test coverage is critical. A lack of tests for new logic is often a 'Major' or 'Critical' concern.",
-        "Derive Impacted User Flows from Flow Anchors and HOT paths (depth ≤2); cap ≤5 flows; prefer acceptance-criteria keywords.",
-        "List Affected Consumers (importers/API clients/message consumers); cap ≤8; rank by usage frequency and proximity to changed code.",
-        "Test skeletons: for top-risk flows/consumers, add concise code fences (project test style if clear) with a suggested file path comment at top; ≤25 lines per sketch; ≤6 total sketches (≤2 per top risk).",
-        "For data/schema/API changes, add at least one Contract test proposal; total test proposals cap ≤10.",
-        "Add 2 ready-to-copy MR comments for the highest-risk gaps; log the revision."
-      ],
-      "runCondition": { "and": [ { "var": "complexity", "not_equals": "Trivial" }, { "or": [ { "var": "contextGatheringComplete", "equals": true }, { "var": "skipContextGathering", "equals": true } ] } ] },
-      "functionReferences": ["upsertSection()", "appendMRComment()", "logRevision()"],
-      "requireConfirmation": false
-    },
-    {
-      "id": "hygiene-and-inconsistencies",
-      "title": "Hygiene & Inconsistencies Sweep",
-      "prompt": "Perform a platform-agnostic hygiene sweep scoped to the current module and changed files. Surface concise, actionable findings across categories:\n\n- Tests: disabled/skipped/focused tests; tests with no assertions; mismatched or overly generic names\n- Comments: commented-out code blocks; stale/misleading comments; suppression directives without justification\n- TODO/FIXME/HACK/BUG: missing ticket/reference or clearly stale; high density in an area\n- Inconsistencies: naming/DI/logging/error handling divergences from local patterns; ad-hoc debug prints; obvious unused identifiers/unreachable code\n\nConstraints:\n- Total ≤10 items; ≤3 per category; dedupe similar items; group by file; keep each note ≤2 lines\n- Elevate to Major only when clearly risky (e.g., focused tests, tests with no assertions)\n\nWrite results to the live doc under 'Hygiene & Inconsistencies' with category counts and bullets grouped by file. For the top 2–3 actionable items, add Ready-to-Copy MR comments. Log the revision.",
-      "agentRole": "You are a pragmatic reviewer catching small but valuable quality issues without adding noise.",
-      "guidance": [
-        "Scope strictly to moduleRoot and changed files plus immediate neighbors.",
-        "Write full details to the live doc; in chat, report counts and the doc path."
-      ],
-      "runCondition": { "var": "complexity", "not_equals": "Trivial" },
-      "functionReferences": ["discoverHygieneSignals()", "consolidateHygieneFindings()", "appendHygieneFinding()", "appendMRComment()", "upsertSection()", "logRevision()"],
-      "requireConfirmation": false
-    },
-    {
-      "id": "prepare-nit-appendix",
-      "title": "Prepare Nit Appendix",
-      "prompt": "Consolidate all non-blocking 'Nit:' items found so far into a clean appendix.\n\nTasks:\n1. Aggregate `nitFindings` by file.\n2. Format each entry as: `filePath:line - short description` with one-line context if helpful.\n3. Produce markdown in `nitAppendix`.\n4. Set `nitAppendixReady = true` and `nitsCount` accordingly.",
-      "agentRole": "You are a meticulous note-taker consolidating non-blocking suggestions for clarity and follow-through.",
-      "guidance": [
-        "This step is non-blocking and purely for documentation quality.",
-        "Deterministic ordering: sort by file path ASC → line ASC → category ASC; group by file.",
-        "Categories: Naming; Readability; Style; Comments; Imports/Order; Tests (naming/structure); Minor Perf.",
-        "Row format: 'path:line — Nit: short text (≤2 lines); suggested fix: <one-liner> [category]'; optional tiny diff snippet ≤6 lines only if helpful.",
-        "Dedupe: identical path:line + similar text → keep one; if overlap with Hygiene/Patterns, keep in the most specific section and cross-reference in the other.",
-        "Caps: ≤15 total; ≤3 per category; if exceeded, append a single 'More items omitted due to caps.' line.",
-        "Cross-link any existing MR comments to their nit rows (e.g., 'MR: MR-##').",
-        "If fewer than 3 Nit MR comments exist overall, create minimal ready-to-copy MR comments for the highest-signal remaining nits to reach 3 (file:line, short title, 1–2 line rationale, optional tiny diff).",
-        "Recap (output.notesMarkdown): Summarize what you reviewed, key findings (counts by severity), decisions made, and the doc path. Be specific about what you found."
-      ],
-      "runCondition": { "and": [ { "var": "complexity", "not_equals": "Trivial" }, { "or": [ { "var": "contextGatheringComplete", "equals": true }, { "var": "skipContextGathering", "equals": true } ] } ] },
-      "functionReferences": ["appendMRComment()", "upsertSection()", "logRevision()"],
-      "requireConfirmation": false
-    },
-    {
-      "id": "finalize-review-document",
-      "title": "Finalize Review Document",
-      "prompt": "Finalize the live review document (no new analysis).\n\nBranching:\n- If `complexity == 'Trivial'`:\n  1) Upsert a brief Executive Summary (1–2 lines) with 'Recommendation: Approve'.\n  2) Perform light hygiene (≤2 items) on changed files; write concise bullets under 'Hygiene & Inconsistencies'.\n  3) Quick Nit sweep; write bullets under 'Nit Appendix'.\n  4) Update Header: set status=Final; include final counts.\n  5) Append 'Finalized trivial review' to the Revision Log.\n\n- Otherwise (non-trivial):\n  1) Upsert Executive Summary (3 positives, 3 risks, final recommendation).\n  2) Dedupe and sort Findings (Severity → File → Line).\n  3) Ensure sections exist: Patterns, Pattern Deviations, Tests & Docs, Ideas & Alternatives, Nits, MR Comments.\n  4) Ensure every Critical/Major finding has a curated MR comment; add minimal ones if missing.\n  5) Update Header: set status=Final; include final counts and decision.\n  6) Append 'Finalized document' to the Revision Log.\n\nRecap (output.notesMarkdown): Summarize what you finalized — decision, key finding counts by severity, and the doc path. For non-trivial reviews, include top risks and the recommendation rationale.",
-      "agentRole": "You are a facilitator ensuring the final document is complete, accurate, and consumable.",
-      "guidance": [
-        "Write full details to the live doc. Recap (output.notesMarkdown): Summarize what you finalized, key findings, recommendation, and the doc path.",
-        "Ensure sections exist: 'Executive Summary', 'Decision Criteria', 'Risk Heatmap', 'Proposed Patches', 'Test Gaps & Proposals', 'Confidence & Follow-ups'; create missing sections with stable anchors.",
-        "Executive Summary template: 3 positives (≤120 chars each); 3 risks (≤120 chars each); decision & rationale (≤2 lines); add links to Patterns, Deviations, Tests, Hygiene; total ≤12 lines.",
-        "Decision Criteria checklist: Scope fit; Tests adequate; Pattern adherence; Performance risk; Backwards compatibility; Security basics. Render as 'Criteria: [✓/✗] label — 1 phrase note' in fixed order.",
-        "Risk Heatmap table: rows 'Risk | Area | Likelihood(L/M/H) | Impact(L/M/H) | Mitigation(≤1 line)'; sort by Impact desc then Likelihood desc; cap ≤6 rows; add 'omitted due to caps' line if needed.",
-        "Dedupe patches and MR comments; ensure every Critical/Major has either a patch or a copy-ready MR comment.",
-        "If any Critical/Major lacks an MR comment, generate a minimal ready-to-copy comment (file:line, short title, 1–2 line rationale, optional tiny diff snippet).",
-        "Ensure at least 3 Nit MR comments exist overall; if fewer, create minimal Nit MR comments for the top remaining nits to reach 3.",
-        "Group MR comments by file and dedupe similar entries; add a 'Missing Comments Summary' note if any comments were auto-added.",
-        "Cross-link each MR comment to its related Proposed Patch when applicable ('See Proposed Patch: <title>').",
-        "Keep all caps deterministic; if any list exceeds its cap, add a single trailing 'More items omitted due to caps.' line."
-      ],
-      "functionReferences": ["finalizeReviewDocument()", "upsertSection()", "discoverHygieneSignals()", "consolidateHygieneFindings()", "appendHygieneFinding()", "logRevision()"],
-      "requireConfirmation": false
-    }
-  ]
-}