hatch3r 1.3.0 → 1.5.0

package/commands/board/pickup-delegation-multi.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-delegation-multi
 type: command
 description: Multi-issue sub-agent delegation protocols for board-pickup Steps 6b (epics) and 6c (batch). Covers level-by-level parallel execution, shared context, and quality pipelines.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Multi-Issue Delegation (Steps 6b, 6c)
 
@@ -80,6 +81,7 @@ For each dependency level, starting at Level 1:
    - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
    - Instruction to use GitHub MCP for issue reads, and follow the project's tooling hierarchy for external knowledge augmentation.
    - Explicit instruction: do NOT create branches, commits, or PRs.
+   - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
 
@@ -147,6 +149,7 @@ For each dependency level, starting at Level 1:
    - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
    - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
    - Explicit instruction: do NOT create branches, commits, or PRs.
+   - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
 
@@ -161,7 +164,11 @@ For each dependency level, starting at Level 1:
 After all implementer sub-agents complete across all levels:
 
 1. Run a combined quality check across all changes from all issues.
-2. Resolve any cross-issue file conflicts or integration issues.
+2. **File conflict resolution:** When parallel sub-agents modify the same file, apply this resolution protocol:
+   - **Disjoint regions:** Accept both changes (non-overlapping edits to different functions/sections).
+   - **Overlapping regions:** If changes touch the same lines or function, merge manually using the sub-agent that modified the larger scope as the base, then apply the smaller-scope change on top. Run tests after merge.
+   - **Semantic conflicts:** If two sub-agents make contradictory changes to the same interface, type, or contract, halt and surface both changes to the user with the conflict description. Do not auto-resolve semantic conflicts.
+   - **Prevention:** Step 3 (collision detection) should move file-overlapping issues to sequential dependency levels. Conflicts at this stage indicate a missed overlap in Step 3.4.
 3. Verify no regressions between parallel sub-agent outputs.
 
 ### 6c.5. Post-Implementation Quality Pipeline
@@ -176,6 +183,7 @@ After all implementations complete, run the two-stage quality pipeline across th
    - **Reference conventions** from Step 6c.2 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the reviewer reports 0 Critical + 0 Warning findings.
+   After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
 5. If still not clean after 3 iterations, **ASK** the user how to proceed.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**

package/commands/board/pickup-delegation.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-delegation
 type: command
 description: Single-issue sub-agent delegation protocol for board-pickup Step 6a. Covers research, implementation, and quality pipeline for standalone issues.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Single-Issue Delegation (Step 6a)
 
@@ -58,6 +59,7 @@ The implementer sub-agent prompt MUST include:
 - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
 - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
 - Explicit instruction: do NOT create branches, commits, or PRs.
+- Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 Await the implementer sub-agent. Collect its structured result (files changed, tests written, issues encountered).
 
@@ -73,6 +75,7 @@ After implementation completes, run the two-stage quality pipeline. Use the Task
    - **Reference conventions** from Step 6a.1 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the reviewer reports 0 Critical + 0 Warning findings.
+   After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
 5. If still not clean after 3 iterations, **ASK** the user how to proceed.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**
@@ -96,5 +99,6 @@ Each specialist sub-agent prompt MUST include:
 - All `scope: always` rule directives from `.agents/rules/` (subagents do not inherit rules automatically).
 - The diff or file changes to review.
 - The issue's acceptance criteria.
+- Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 Await all specialist sub-agents. Apply their feedback (fixes, additional tests, documentation updates) before proceeding to Step 7.

package/commands/board/pickup-github.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-github
 type: command
 description: GitHub-specific platform procedures for board-pickup. Covers gh CLI commands for issue listing, status updates, collision detection, PR creation, and label transitions.
 tags: [board, team, github]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — GitHub Platform Details
 
@@ -31,6 +32,10 @@ Platform-specific procedures for GitHub. Referenced from `hatch3r-board-pickup`.
 **Open PRs:**
 - `gh pr list -R {owner}/{repo} --state open` (fall back to `search_pull_requests` MCP).
 
+**Closed PRs for selected issue (abandoned work detection):**
+- `gh pr list -R {owner}/{repo} --state closed --search "closes #{N}"` — check if any recently closed (not merged) PRs reference this issue.
+- If found: Surface to the user: "Note: PR #{M} was closed without merge for issue #{N}. The previous work may be partially relevant. Options: (a) review the closed PR branch, (b) start fresh, (c) pick a different issue."
+
 ---
 
 ## Step 4: Update Issue Status — GitHub

package/commands/board/pickup-gitlab.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-gitlab
 type: command
 description: GitLab-specific platform procedures for board-pickup. Covers glab CLI commands for issue listing, status updates, collision detection, MR creation, and label transitions.
 tags: [board, team, gitlab]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — GitLab Platform Details
 
@@ -31,6 +32,10 @@ Platform-specific procedures for GitLab. Referenced from `hatch3r-board-pickup`.
 **Open MRs:**
 - `glab mr list -R {namespace}/{project} --state opened`.
 
+**Closed MRs for selected issue (abandoned work detection):**
+- `glab mr list -R {namespace}/{project} --state closed` — check if any recently closed (not merged) MRs reference `Closes #{N}`.
+- If found: Surface to the user: "Note: MR !{M} was closed without merge for issue #{N}. The previous work may be partially relevant. Options: (a) review the closed MR branch, (b) start fresh, (c) pick a different issue."
+
 ---
 
 ## Step 4: Update Issue Status — GitLab

package/commands/board/pickup-modes.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-modes
 type: command
 description: Auto-advance mode, error handling, and guardrails for board-pickup. Covers --auto/--unattended operation, safety guardrails, and specification generation.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Modes, Guardrails, and Error Handling
 

package/commands/board/pickup-post-impl.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-post-impl
 type: command
 description: Post-implementation steps for board-pickup (Steps 7-10). Covers quality verification, commit/push, PR/MR creation, label transitions, board sync, dashboard refresh, reconciliation, and learnings capture.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Post-Implementation Steps (7-10)
 
@@ -16,6 +17,8 @@ Run the project's quality checks (linting, type checking, tests). Refer to the p
 
 Verify: all AC met, tests passing, no lint errors, dead code removed, project-specific invariants respected.
 
+Rate confidence in quality verification: high (all checks pass with comprehensive coverage), medium (checks pass but coverage gaps exist), low (checks pass minimally, recommend additional human review).
+
 ---
 
 ## Step 7a: Commit & Push
@@ -83,7 +86,12 @@ Follow the project's PR/MR creation skill or conventions:
 
 1. If all sub-issues addressed, confirm the PR body uses `Closes #<epic-number>` so the epic will auto-close on merge and transition to Done.
 2. Remind user `Closes #N` auto-closes on merge.
-3. If partial:
+3. **Post-merge board state advisory:** After merge, `Closes #N` will auto-close the issue, but label and board status updates to `status:done` / "Done" depend on platform automation:
+   - **GitHub:** Automatic IF the Projects V2 "Item closed" workflow is enabled (verify in Project > Workflows). Labels are NOT auto-updated — `status:in-review` remains on the closed issue.
+   - **Azure DevOps:** Verify the "Complete linked work items after merging" checkbox is checked during PR completion. State transitions to "Closed" only when this option is selected.
+   - **GitLab:** Labels are NOT updated on auto-close. `status::in-review` remains. Consider setting up a CI pipeline trigger on issue close events for automated cleanup.
+   - If automation is not configured, `board-groom` with the `health-fix` action will detect and fix the drift during the next grooming session.
+4. If partial:
 
 **ASK:** "PR created. N remaining sub-issues on epic #X. Continue with next sub-issue or stop?"
 

package/commands/board/shared-azure-devops.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-azure-devops
 type: shared-context
 description: Azure DevOps-specific platform details for board shared context. Covers Work Items, Azure Boards, az CLI, and MCP tools.
 tags: [board, team, azure-devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference — Azure DevOps Platform Details
 
@@ -86,7 +87,11 @@ Azure Boards syncs via Work Item State changes. There is no separate "add to boa
 | `status:in-progress` | `Active`        |
 | `status:in-review`   | `Resolved`      |
 | `status:blocked`     | `New`           |
-| (done)               | `Closed`        |
+| `status:done`        | `Closed`        |
+
+**Known limitation — Ready vs. In Progress granularity:** Both `status:ready` and `status:in-progress` map to the `Active` Work Item State because Azure DevOps built-in process templates (Agile, Scrum, CMMI) do not include a "Ready" state. The distinction is preserved in Work Item Tags (e.g., tag `status:ready` vs. `status:in-progress`), which hatch3r board commands always set alongside the State update. For projects that need board-level distinction:
+- **Custom process template:** Add a "Ready" state to the work item type in your Azure DevOps process template. Update the mapping above accordingly.
+- **Board column mapping:** Configure Azure Boards to use tag-based swim lanes or column splits to distinguish "Ready" from "In Progress" within the "Active" column.
 
 **Steps for each work item to sync:**
 
@@ -110,8 +115,14 @@ Azure Boards syncs via Work Item State changes. There is no separate "add to boa
    `az boards work-item relation add --id {child_id} --relation-type "System.LinkTypes.Hierarchy-Reverse" --target-id {parent_id}`.
    Record link status as `native`.
 
-2. **Fallback 1 — Comment trace:**
-   If relation add fails:
+2. **Fallback 1 — Advisory body-reference:**
+   If relation add fails, establish an advisory link via work item descriptions:
+   - Read the parent work item description. Append a sub-issue checklist entry: `- [ ] #{child} {title}` to the parent's description via `az boards work-item update --id {epic} --description "..."`.
+   - Read the child work item description. Prepend `> Parent: #{epic}` to the child's description via `az boards work-item update --id {child} --description "..."`.
+   - Record link status as `advisory`.
+
+3. **Fallback 2 — Comment trace:**
+   If both primary and Fallback 1 fail:
    `az boards work-item update --id {epic} --discussion "Sub-issue: #{child} — {title} (linking failed)"`.
    Record link status as `comment-only`.
 

package/commands/board/shared-board-overview.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-overview
 type: shared-context
 description: Board overview dashboard template, model pool, model selection heuristic, and lane computation algorithm. Referenced from hatch3r-board-shared.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Overview Reference
 

package/commands/board/shared-github.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-github
 type: shared-context
 description: GitHub-specific platform details for board shared context. Covers GitHub Issues, Projects V2, gh CLI, and MCP tools.
 tags: [board, team, github]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference — GitHub Platform Details
 
@@ -95,6 +96,7 @@ Read the mapping from `board.statusOptions` in `.agents/hatch.json`:
 | `status:ready`       | `board.statusOptions.ready`        |
 | `status:in-progress` | `board.statusOptions.inProgress`   |
 | `status:in-review`   | `board.statusOptions.inReview`     |
+| `status:done`        | `board.statusOptions.done`         |
 | `status:blocked`     | `board.statusOptions.backlog`      |
 
 **Steps for each issue to sync (gh CLI primary):**

package/commands/board/shared-gitlab.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-gitlab
 type: shared-context
 description: GitLab-specific platform details for board shared context. Covers GitLab Issues, Issue Boards, glab CLI, and label-based sync.
 tags: [board, team, gitlab]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference — GitLab Platform Details
 
@@ -83,6 +84,7 @@ GitLab board lists are label-based. Each status corresponds to a scoped label:
 | `status:ready`       | `status::ready`     |
 | `status:in-progress` | `status::in-progress` |
 | `status:in-review`   | `status::in-review` |
+| `status:done`        | `status::done`      |
 | `status:blocked`     | `status::blocked`   |
 
 **Steps for each issue to sync:**
@@ -104,8 +106,14 @@ GitLab board lists are label-based. Each status corresponds to a scoped label:
    `glab api projects/{project_id}/issues/{parent_iid}/links --method POST --field target_project_id={project_id} --field target_issue_iid={child_iid}`.
    Record link status as `native`.
 
-2. **Fallback 1 — Comment trace:**
-   If API linking fails:
+2. **Fallback 1 — Advisory body-reference:**
+   If API linking fails, establish an advisory link via issue descriptions:
+   - Read the parent epic body. Add a sub-issue checklist entry: `- [ ] #{child} {title}` to the epic's body via `glab issue update {epic} -R {namespace}/{project} --description "..."`.
+   - Read the child issue body. Prepend `> Parent: #{epic}` to the child's body via `glab issue update {child} -R {namespace}/{project} --description "..."`.
+   - Record link status as `advisory`.
+
+3. **Fallback 2 — Comment trace:**
+   If both primary and Fallback 1 fail:
    `glab issue note {epic} -R {namespace}/{project} --message "Sub-issue: #{child} — {title} (linking failed)"`.
    Record link status as `comment-only`.
 

package/commands/hatch3r-agent-customize.md

@@ -3,6 +3,7 @@ id: hatch3r-agent-customize
 type: command
 description: Configure per-agent customization including model overrides, description changes, and project-specific markdown instructions
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -153,7 +154,7 @@ Some agents have `protected: true` in their canonical frontmatter. This field ma
 
 ```yaml
 ---
-id: hatch3r-reviewer
+id: hatch3r-example-agent
 description: Expert code reviewer for the project...
 protected: true
 model: standard
@@ -175,6 +176,10 @@ The `protected` field is set in the canonical agent definition and cannot be ove
 - Invalid YAML produces warnings but does not prevent agent execution (graceful degradation)
 - Customization files should be committed to the repository
 
+## Unified Skill
+
+This command's workflow is handled by the `hatch3r-customize` skill with `type: agent`. The skill provides root-cause analysis, multi-stakeholder review, and quality gate steps that extend the workflow above. Invoke the skill directly or use this command for the agent-specific reference documentation (model resolution, protected agents, per-agent examples).
+
 ## Related
 
 - Skill customization: `hatch3r-skill-customize` command

package/commands/hatch3r-api-spec.md

@@ -3,6 +3,7 @@ id: hatch3r-api-spec
 type: command
 description: Generate or validate an OpenAPI specification from the codebase. Scans route definitions, extracts schemas, and produces a complete API spec.
 tags: [planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-benchmark.md

@@ -3,6 +3,7 @@ id: hatch3r-benchmark
 type: command
 description: Run and analyze performance benchmarks. Compare results against baselines, identify regressions, and produce performance reports.
 tags: [review, performance]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -60,7 +61,7 @@ Benchmark Brief:
   Metrics:      {time / memory / throughput / all}
 ```
 
-**ASK:** "Does this capture the benchmark plan correctly? Adjust anything before I begin discovery."
+**ASK:** "Does this capture the benchmark plan? Adjust anything before I begin discovery."
 
 ---
 
@@ -287,7 +288,7 @@ Files Created/Updated:
 
 **ASK:** "Results saved. Should these become the new baseline for future comparisons? (yes — overwrites previous baseline / no — keep existing baseline)"
 
-If yes, ensure `results.json` is structured as the canonical baseline for the next `previous-run` comparison.
+If yes, save `results.json` as the canonical baseline for the next `previous-run` comparison.
 
 ---
 
@@ -392,7 +393,7 @@ The benchmark report follows this structure:
 - **Always exclude the cold start run from statistics.** The first iteration warms caches and JIT — including it skews results.
 - **Never overwrite baseline without confirmation.** Step 10 explicitly asks before promoting results to baseline status.
 - **Preserve existing `.benchmarks/results.json` history.** Append new runs; do not truncate historical data without user approval.
-- **Do not benchmark in debug mode.** Ensure `NODE_ENV=production` and no debug flags are active unless explicitly requested.
+- **Do not benchmark in debug mode.** Verify `NODE_ENV=production` and no debug flags are active unless explicitly requested.
 - **Respect the project's tooling hierarchy** for knowledge augmentation: project docs first, then codebase exploration, then Context7 MCP, then web research.
 - **Report, don't interpret subjectively.** Present statistical facts. Flag regressions by threshold, not opinion. Let the user decide what matters.
 

package/commands/hatch3r-board-fill.md

@@ -3,6 +3,7 @@ id: hatch3r-board-fill
 type: command
 description: Create epics and issues/work items from todo.md, reorganize the board with dependency analysis, readiness assessment, and implementation ordering. Supports GitHub, Azure DevOps, and GitLab.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -99,6 +100,7 @@ Scan the entire board to build an inventory of all existing work. This scan feed
 ```
 Board Health:
   Total open issues: N (X epics, Y sub-issues, Z standalone)
+  Standalone ratio: Z/{X+Z} ({percentage}%) — target <=10%
   Missing dependency metadata: #N, #M ...
   Missing required labels: #N — no priority, no area ...
   Potential epic grouping candidates: #N + #M (shared theme) ...
@@ -304,18 +306,35 @@ Present a brief **Context Summary**: key constraints from documentation, current
 
 ### Step 5: Propose Grouping (Epics vs. Standalone)
 
-**Grouping philosophy:** Minimize standalone issues to near-zero. Group aggressively into epics. Standalone only if topically isolated from every other issue AND substantial enough to stand alone.
+**Grouping philosophy:** Target zero standalone issues. Every issue should belong to an epic. Standalone status is an exception that requires explicit justification, not a default. This maximizes parallelization during pickup — agents can tackle multiple sub-issues of an epic concurrently, whereas standalone issues require serial pickup. Follow the **Epic Grouping Policy** in `hatch3r-board-shared`.
+
+**Standalone threshold:** After grouping, no more than 10% of total non-sub-issue items on the board should be standalone (minimum 0, round down). If this threshold is exceeded, the post-grouping audit (Step 5d) forces additional grouping before proceeding.
 
 #### 5a. Group New Items
 
-1. **Absorb into existing epics first.**
-2. **Form new epics** from 2+ items sharing any connection (area, subsystem, category).
-3. **Adopt orphans** into broad thematic epics (e.g., "Security & Auth Hardening", "Infrastructure & Tooling").
-4. **Standalone only as last resort.**
+Apply these rules in strict order. Each rule reduces the remaining ungrouped pool before the next rule fires.
+
+1. **Absorb into existing epics first.** For each new item, check all existing epics on the board. If the item shares any `area:*` label, touches the same subsystem, or addresses the same feature domain as an existing epic, absorb it as a sub-issue of that epic. When multiple epics match, prefer the one with the strongest thematic overlap.
+
+2. **Form new epics from 2+ related items.** Group remaining ungrouped items that share any connection: same `area:*` label, same subsystem, same `type:*` category, related feature domain, or semantic similarity in title/description. Two items sharing any single connection is sufficient to form an epic. Name the epic after the shared theme.
+
+3. **Singleton promotion.** Any single remaining item that could plausibly belong to a broader theme (even a loose one like "Developer Experience", "Code Quality", "Performance", "Security Hardening", "Infrastructure & Tooling", "Documentation & Onboarding") becomes a 1-item epic with that theme as the epic title. The rationale: a themed epic can absorb future related work, whereas a standalone cannot. Prefer existing theme names from epics already on the board.
+
+4. **Catch-all epic.** If any items still remain after steps 1-3 (truly topically isolated from everything), group them into a single catch-all epic named "General Improvements" (or absorb into an existing "General Improvements" epic if one exists on the board). Do NOT leave them standalone.
+
+5. **Standalone as true last resort.** An item may remain standalone ONLY if the user explicitly rejects grouping for it during the ASK checkpoint AND provides a justification. The AI should never propose standalone status on its own — always propose a grouping first.
 
 #### 5b. Regroup Existing Standalone Issues
 
-Evaluate existing standalones for grouping into existing or new epics. Same aggressive philosophy.
+Scan ALL existing standalone issues on the board (from the Step 1.5 board scan). For each standalone:
+
+1. **Check against existing epics.** If the standalone shares an `area:*` label, subsystem, or semantic theme with any existing epic, propose absorbing it as a sub-issue.
+2. **Check against other standalones.** If 2+ existing standalones share a connection (area, subsystem, title similarity), propose forming a new epic from them.
+3. **Check against new epics.** If the standalone fits a new epic being formed in Step 5a, include it.
+4. **Singleton promotion.** Apply the same singleton promotion rule as 5a.3 — propose a thematic epic for isolated standalones.
+5. **Catch-all.** Remaining standalones go into the "General Improvements" epic per 5a.4.
+
+Present regrouping proposals clearly separated from new-item grouping, so the user can confirm or reject existing issue regrouping independently.
 
 #### 5c. Decomposition Check
 
@@ -328,9 +347,32 @@ After grouping, evaluate whether any individual item is too large to be a single
 
 For each item flagged for decomposition, propose specific sub-issues with one-line descriptions. Items already grouped into an epic become sub-issues of that epic; standalone items that decompose become a new epic with sub-issues.
 
-Present grouping proposals (from 5a + 5b) and decomposition proposals (from 5c) together.
+#### 5d. Post-Grouping Standalone Audit
+
+After Steps 5a-5c, perform a standalone audit before presenting proposals to the user.
+
+1. **Count remaining standalones.** Calculate the standalone ratio: `standalone_count / (epic_count + standalone_count)`. Sub-issues are excluded from this ratio.
+
+2. **Threshold check.** If the standalone ratio exceeds 10%, the audit fails:
+   - Re-examine each proposed standalone against ALL epics (existing and newly proposed) using progressively looser matching:
+     a. Same `area:*` label (exact match).
+     b. Same broader domain (e.g., `area:api` and `area:middleware` are both "backend").
+     c. Same `type:*` category (e.g., all `type:refactor` items form a "Code Quality" epic).
+     d. Catch-all "General Improvements" epic.
+   - Repeat until the ratio is at or below 10%, or every standalone has been re-examined and the AI has exhausted all grouping options.
+
+3. **Justify survivors.** For each item that remains standalone after the audit, include a one-line justification in the grouping proposal explaining why it could not be grouped (e.g., "Truly unique topic with no thematic overlap to any existing or proposed epic").
+
+4. **Surface the metric.** Include the standalone ratio in the grouping proposal output:
+   ```
+   Grouping Audit: {standalone_count}/{total} items standalone ({percentage}%)
+   Threshold: <=10% — {PASS/FAIL}
+   {if FAIL: "N standalones could not be grouped. Justifications below."}
+   ```
+
+Present grouping proposals (from 5a + 5b), decomposition proposals (from 5c), and audit results (from 5d) together.
 
-**ASK:** "Confirm grouping and decomposition, or: move items between groups / merge-split epics / convert epic↔standalone / reject decomposition / reject existing regrouping. Are there items here that still feel too large for a single issue?"
+**ASK:** "Confirm grouping, decomposition, and standalone audit results. Options: move items between groups / merge-split epics / convert epic<->standalone (requires justification) / reject decomposition / reject existing regrouping. Standalone ratio: {percentage}% ({PASS/FAIL}). Are there items here that still feel too large for a single issue?"
 
 ---
 
@@ -447,7 +489,7 @@ Acceptance criteria must be grounded in the user's stated requirements, not AI i
 3. **Codebase context (Step 4)** -- existing tests, interfaces, contracts, and architectural patterns that constrain the implementation inform technical criteria.
 4. **AI inference** -- only as a supplement for criteria the above sources don't cover. Flag AI-inferred criteria distinctly so the user can validate them.
 
-Each acceptance criterion must be **specific and testable**: an implementer reading it can determine pass/fail without ambiguity. Prefer "API returns 400 with validation error for missing required fields" over "API validates input properly."
+Each acceptance criterion must be **specific and testable**: an implementer reading it can determine pass/fail without ambiguity. Prefer "API returns 400 with validation error for missing required fields" over "API validates input."
 
 #### Scope Section
 
@@ -580,6 +622,7 @@ Existing Issues Updated:
 | Issue # | Title | Updates Applied |
 
 Board Summary: N created, M updated, X marked ready, Y still triage, Z parallel lanes
+Standalone ratio: {count}/{total} ({percentage}%) — target <=10%
 ```
 
 ---

package/commands/hatch3r-board-groom.md

@@ -3,6 +3,7 @@ id: hatch3r-board-groom
 type: command
 description: Ongoing backlog refinement for existing board items. Re-prioritize, reclassify, re-scope, archive stale items, decompose oversized issues, merge duplicates, refresh dependencies, and remediate board health findings.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -142,12 +143,18 @@ Analyze the distribution of priority labels across the board:
 - Flag if all issues share the same priority (undifferentiated backlog).
 - Flag issues where priority does not align with risk (e.g., `priority:p3` + `risk:high`).
 
-#### 3f. Grouping Opportunities
+#### 3f. Grouping Opportunities & Standalone Audit
 
-Scan existing standalone issues for potential epic grouping:
+Scan existing standalone issues for epic grouping. Apply the **Epic Grouping Policy** from `hatch3r-board-shared`:
 
 - 2+ standalone issues sharing the same `area:*` labels.
 - 2+ standalone issues with semantically similar titles or overlapping scope.
+- 2+ standalone issues sharing the same `type:*` label (e.g., all `type:refactor` items).
+- 2+ standalone issues in the same broader domain (e.g., `area:api` + `area:middleware` = "backend").
+- **Single standalone issues** that could be absorbed into an existing epic (shared area, subsystem, or theme).
+- **Single standalone issues** that could become a themed 1-item epic (singleton promotion).
+
+Compute standalone ratio: `standalone_count / (epic_count + standalone_count)`. Flag if ratio exceeds 10%.
 
 #### 3g. Decomposition Candidates
 
@@ -173,7 +180,23 @@ For each epic, compare the sub-issue references in the epic body (checklist item
 
 If `board.projectNumber` is configured, compare label-based status (`status:*` labels) against board column status via `gh project item-list {board.projectNumber} --owner {board.owner} --format json` (GitHub) or equivalent platform call. Flag issues where the label status and board column status diverge.
 
-#### 3l. Present Refinement Summary
+#### 3l. Orphaned In-Review Detection
+
+For each open issue with `status:in-review`:
+
+1. **GitHub:** Check if any open PR body references `Closes #N` for this issue: `gh pr list -R {owner}/{repo} --state open --json number,body` — parse for `Closes #{N}`.
+2. **Azure DevOps:** Check if any active PR is linked to this work item: `az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status active` — check work item relations.
+3. **GitLab:** Check if any open MR description references `Closes #N` for this issue: `glab mr list -R {namespace}/{project} --state opened` — parse descriptions for `Closes #{N}`.
+
+Also check for closed issues with `status:in-review` (or any non-`status:done` status label) — these are issues that were auto-closed on PR merge but whose labels and board status were not updated to "Done" (see Post-Merge Terminal State in `hatch3r-board-shared`).
+
+Flag two categories:
+- **Orphaned in-review (open):** Open issues with `status:in-review` but no associated open PR/MR — likely caused by PR closure without merge.
+- **Stale in-review (closed):** Closed issues still labeled `status:in-review` — should be `status:done` with board status "Done".
+
+---
+
+#### 3m. Present Refinement Summary
 
 Present findings grouped by category:
 
@@ -182,6 +205,7 @@ Board Groom — Refinement Summary:
 
 Board Health:
   Total open issues: N (X epics, Y sub-issues, Z standalone)
+  Standalone ratio: Z/{X+Z} ({percentage}%) — target <=10%
   Missing metadata: M issues (details below)
   Stale issues: S issues
   Stale dependency refs: D issues
@@ -189,6 +213,7 @@ Board Health:
   Epic ordering discrepancies: E epics
   Unlinked sub-issues: U issues (non-native links)
   Board sync drift: V issues (label/board status mismatch)
+  Orphaned in-review: O issues (open with no PR/MR), S issues (closed but not status:done)
 
 Grooming Opportunities:
   Re-prioritize candidates: R issues (priority/risk misalignment, priority inflation)
@@ -199,10 +224,10 @@ Grooming Opportunities:
   Dependency cleanup: K issues (stale refs, orphaned labels)
   Link fix candidates: L issues (advisory or comment-only links)
 
-Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | dep-refresh | health-fix | link-fix | all]
+Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | regroup | dep-refresh | health-fix | link-fix | all]
 ```
 
-**ASK:** "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / dep-refresh / health-fix / link-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
+**ASK:** "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / regroup / dep-refresh / health-fix / link-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
 
 ---
 
@@ -446,9 +471,63 @@ Link Fix Candidates:
 
 ---
 
-#### 4i. Health Fix (Board Health Remediation)
+#### 4i. Regroup Standalones
+
+Group standalone issues into existing or new epics. This action executes the grouping opportunities detected in Step 3f, following the **Epic Grouping Policy** from `hatch3r-board-shared`.
+
+1. Present regrouping proposals from Step 3f, organized by target epic:
+
+```
+Regroup Proposals:
+
+Absorb into existing epics:
+  #{N} "{title}" → Epic #{E} "{epic title}" (shared area:api)
+  #{M} "{title}" → Epic #{F} "{epic title}" (semantic overlap)
+
+Form new epics:
+  New epic: "Code Quality & Refactoring"
+    #{P} "{title}" (type:refactor)
+    #{Q} "{title}" (type:refactor)
+
+Singleton promotions:
+  #{R} "{title}" → New 1-item epic: "Performance Optimization" (no existing epic match, but themed for future absorption)
+
+Catch-all:
+  #{S} "{title}" → "General Improvements" epic (no thematic match)
+
+Standalone ratio: before={before}%, after={projected}% (target <=10%)
+```
+
+**ASK:** "Confirm regrouping proposals. For each: accept / reject / move to different epic. Items you reject will remain standalone. Confirm / adjust / skip."
+
+2. For confirmed regroupings:
+
+   **Absorb into existing epic:**
+   - Link the standalone as a sub-issue using the **Sub-Issue Linking Procedure** from `hatch3r-board-shared`.
+   - Update the epic body to include the new sub-issue in its checklist and `## Implementation Order`.
+
+   **Form new epic:**
+   - Create a new epic issue with Overview, Sub-issues checklist, and `## Implementation Order`.
+   - Link all grouped items as sub-issues using the Sub-Issue Linking Procedure.
+   - Apply labels: inherit the common labels from the grouped items, add `status:triage` (or `status:ready` if all sub-issues are ready).
+   - Sync the new epic to the board via the **Board Sync Procedure** from `hatch3r-board-shared`.
+
+   **Singleton promotion:**
+   - Create a new 1-item epic with the themed title.
+   - Link the standalone as its only sub-issue.
+   - The epic body notes: "This epic groups related work for {theme}. Future items in this area should be added as sub-issues."
+
+   **Catch-all:**
+   - If a "General Improvements" epic exists, absorb into it.
+   - If not, create one with all catch-all items as sub-issues.
+
+3. After execution, recalculate and report the standalone ratio.
+
+---
+
+#### 4j. Health Fix (Board Health Remediation)
 
-Fix structural gaps detected in Step 3b (missing metadata).
+Fix structural gaps detected in Step 3b (missing metadata), board sync drift detected in Step 3k, and orphaned in-review issues detected in Step 3l.
 
 1. For each issue with missing required labels, infer the missing labels from issue content using the same classification tables as `board-fill` Step 3:
    - Missing `type:*` → infer from title/body keywords.
@@ -475,6 +554,42 @@ Health Fix — Missing Metadata:
    - **Azure DevOps:** `az boards work-item update --id N --fields "System.Tags=..."`.
    - **GitLab:** `glab issue update N --label "..."`.
 
+4. **Board sync drift remediation:** For each issue flagged in Step 3k where label status and board column status diverge:
+
+   - **Labels are source of truth.** Update the board to match the label.
+   - Use the platform-specific Board Sync Procedure to set the board status to the value corresponding to the issue's current status label.
+   - **Special case — closed issue with `status:in-review`:** If the issue is closed (state = closed) but the label is `status:in-review` and the board shows "In Review":
+     1. Replace `status:in-review` with `status:done` on the issue.
+     2. Sync board status to "Done" using `board.statusOptions.done`.
+   - Present drift fixes in the batch:
+
+```
+Board Sync Drift Remediation:
+
+| # | Title | Label Status | Board Status | Action |
+|---|-------|-------------|--------------|--------|
+| #N | {title} | status:ready | In Progress | Sync board -> Ready |
+| #M | {title} | status:in-review (closed) | In Review | Label -> status:done, board -> Done |
+```
+
+No separate ASK — drift fixes are presented alongside the metadata fixes in the same Health Fix confirmation prompt.
+
+5. **Orphaned in-review remediation:** For each issue flagged in Step 3l:
+
+   a. **Closed issue with `status:in-review`** (stale in-review): Suggest replacing `status:in-review` with `status:done` and syncing board to "Done". This is the post-merge terminal state that was not reached (see Post-Merge Terminal State in `hatch3r-board-shared`).
+   b. **Open issue with `status:in-review` but no open PR/MR** (orphaned in-review): Present the issue with context (last PR if any, time since last update). Suggest `status:ready` (if work appears abandoned) or `status:in-progress` (if rework is likely).
+
+```
+Orphaned In-Review Remediation:
+
+| # | Title | State | Last PR | Suggested Status | Reason |
+|---|-------|-------|---------|------------------|--------|
+| #N | {title} | closed | PR #M (merged) | status:done | Closed issue still labeled in-review |
+| #K | {title} | open | PR #J (closed, not merged) | status:ready | PR closed 14 days ago, no replacement |
+```
+
+**ASK:** "Confirm or adjust status changes for in-review issues. Enter per-issue decisions (e.g., '#N -> done, #K -> in-progress'), or 'confirm all' / 'skip'."
+
 ---
 
 ### Step 5: Readiness Re-evaluation
@@ -555,12 +670,14 @@ Board Groom Complete:
     Archived (closed):  {count} issues
     Decomposed:         {count} issues → {count} new sub-issues
     Merged:             {count} duplicate pairs
+    Regrouped:          {count} standalones → {count} epics ({count} new epics created)
     Dependencies:       {count} refs cleaned, {count} new deps added, {count} epics reordered
     Health fixed:       {count} issues (missing metadata resolved)
     Readiness promoted: {count} issues (triage → ready)
 
   Board State:
     Total open:   {count} ({epics} epics, {sub} sub-issues, {standalone} standalone)
+    Standalone ratio: {percentage}% (target <=10%)
     Ready:        {count} ({available} available, {depWaiting} waiting on deps)
     In Progress:  {count}
     In Review:    {count}