hatch3r 1.3.0 → 1.4.0

package/commands/board/pickup-delegation.md

@@ -58,6 +58,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 +74,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 +98,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

@@ -31,6 +31,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

@@ -31,6 +31,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-post-impl.md

@@ -16,6 +16,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 +85,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:** Ensure 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

@@ -86,7 +86,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 +114,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-github.md

@@ -95,6 +95,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

@@ -83,6 +83,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 +105,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

@@ -153,7 +153,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 +175,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-board-groom.md

@@ -173,7 +173,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:
 
@@ -189,6 +205,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)
@@ -448,7 +465,7 @@ Link Fix Candidates:
 
 #### 4i. 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 +492,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

package/commands/hatch3r-board-init.md

@@ -252,6 +252,7 @@ Execute all planned mutations in sequence. No further questions unless a mutatio
 4. Ensure these status options exist on the field: **Backlog**, **Ready**, **In Progress**, **In Review**, **Done**.
    - For missing options, use the `updateProjectV2Field` mutation (or the appropriate mutation for adding options to a single-select field) to add them.
 5. Capture the field ID and each option's ID.
+6. **Verify built-in "Done on close" automation:** After board creation, check the Projects V2 built-in workflows. Navigate to Project settings > Workflows > "Item closed" and verify it is enabled with Status mapped to "Done". Also verify "Pull request merged" maps Status to "Done". These workflows are on by default for UI-created projects but may not be enabled for API-created projects. Without these workflows, the board status will remain "In Review" after PR merge until `board-groom` detects the drift.
 
 **If platform is `azure-devops`:**
 
@@ -262,6 +263,7 @@ Execute all planned mutations in sequence. No further questions unless a mutatio
 2. Map hatch3r statuses to Work Item States: **Backlog** → `New`, **Ready** → `Active`, **In Progress** → `Active`, **In Review** → `Resolved`, **Done** → `Closed`.
 3. If using a custom process, verify these states exist. Azure DevOps built-in processes (Agile, Scrum, CMMI) include these states by default.
 4. Store the state mapping in `board.statusOptions` for use by other board commands.
+5. **Note — Ready vs. In Progress:** Azure DevOps built-in processes map both "Ready" and "In Progress" to the `Active` state. The distinction is maintained via hatch3r tags on work items. For board-level visibility, consider configuring Azure Boards column splits: in the Board Settings, split the "Active" column into "Active - Ready" and "Active - In Progress" using tag-based rules. Projects with custom Azure DevOps process templates can alternatively add a "Ready" state to the work item type.
 
 **If platform is `gitlab`:**
 
@@ -270,8 +272,9 @@ Execute all planned mutations in sequence. No further questions unless a mutatio
    glab api projects/{project_id}/boards/{board_id}/lists --method POST --field label_id={label_id}
    ```
 2. Create scoped labels for each status first (see Step 2.3), then create board lists referencing those labels.
-3. Required board lists: **Backlog** (`status::triage`), **Ready** (`status::ready`), **In Progress** (`status::in-progress`), **In Review** (`status::in-review`).
+3. Required board lists: **Backlog** (`status::triage`), **Ready** (`status::ready`), **In Progress** (`status::in-progress`), **In Review** (`status::in-review`), **Done** (`status::done`).
 4. Store the board list IDs in `board.statusOptions`.
+5. **Note — Labels not auto-updated on close:** GitLab does not update labels when an issue is auto-closed via `Closes #N`. The `status::in-review` scoped label will remain on closed issues. This drift is detected and fixed by `board-groom` during the `health-fix` action. For automated cleanup, consider setting up a GitLab CI pipeline trigger on issue close events to apply `status::done`. Note: scoped labels require GitLab **Premium or Ultimate** tier.
 
 #### 2.3: Create Label Taxonomy
 
@@ -282,7 +285,7 @@ Execute all planned mutations in sequence. No further questions unless a mutatio
 |-----------|--------|
 | Type      | `type:bug`, `type:feature`, `type:refactor`, `type:qa`, `type:docs`, `type:infra` |
 | Executor  | `executor:agent`, `executor:human`, `executor:hybrid` |
-| Status    | `status:triage`, `status:ready`, `status:in-progress`, `status:in-review`, `status:blocked` |
+| Status    | `status:triage`, `status:ready`, `status:in-progress`, `status:in-review`, `status:done`, `status:blocked` |
 | Priority  | `priority:p0`, `priority:p1`, `priority:p2`, `priority:p3` |
 | Risk      | `risk:low`, `risk:med`, `risk:high` |
 | Meta      | `meta:board-overview`, `has-dependencies` |

package/commands/hatch3r-board-shared.md

@@ -65,7 +65,7 @@ All board commands read project-specific configuration from `.agents/hatch.json`
     "labels": {
       "types": ["type:bug", "type:feature", "type:refactor", "type:qa", "type:docs", "type:infra"],
       "executors": ["executor:agent", "executor:human", "executor:hybrid"],
-      "statuses": ["status:triage", "status:ready", "status:in-progress", "status:in-review", "status:blocked"],
+      "statuses": ["status:triage", "status:ready", "status:in-progress", "status:in-review", "status:done", "status:blocked"],
       "meta": ["meta:board-overview"]
     },
     "branchConvention": "{type}/{short-description}",
@@ -129,7 +129,7 @@ Cache link status per child (`native` / `advisory` / `comment-only`) in the run
 Board sync is **MANDATORY**, not optional. The following rules override any "skip if null" or "skip silently" language elsewhere when the board is configured (GitHub: `board.projectNumber` set; Azure DevOps: project configured; GitLab: board configured).
 
 1. **Every issue/work item created or updated by a board command MUST be synced to the board — no exceptions.** This includes newly created issues, status changes, label updates, and any mutation that affects board state. Skipping sync for any item is a violation of this policy.
-2. **Status MUST be updated after every status-changing operation.** The four canonical statuses — Ready, In Progress, In Review, Done — must be reflected on the board immediately after the corresponding label change. Do not batch status updates to "later" or defer them. See the platform sub-files for platform-specific status update commands.
+2. **Status MUST be updated after every status-changing operation.** The five canonical statuses — Ready, In Progress, In Review, Done, Blocked — must be reflected on the board immediately after the corresponding label change. Do not batch status updates to "later" or defer them. See the platform sub-files for platform-specific status update commands.
 3. **All available board fields (priority, sprint, area, iteration) MUST be populated when the data is available.** Never leave a board field empty if the information exists in the issue's labels, body, or metadata.
 4. **Board overview dashboard MUST be regenerated after any batch of issue operations.** This is in addition to the per-run regeneration rule — if a board command performs multiple batches of mutations, the dashboard must reflect the final state.
 5. **Fallback: never silently skip sync.** See platform sub-files for escalation paths. Silent skipping is prohibited.
@@ -138,6 +138,35 @@ Board sync is **MANDATORY**, not optional. The following rules override any "ski
 
 ---
 
+## Post-Merge Terminal State
+
+When a PR/MR merges and `Closes #N` auto-closes the referenced issues, the board item lifecycle must reach its terminal state. The `status:in-review` label should be replaced with `status:done`, and the board status should be set to "Done" using `board.statusOptions.done`.
+
+**Platform-specific behavior and recommendations:**
+
+- **GitHub:** The built-in Projects V2 "Item closed" workflow sets the Status field to "Done" when an issue is closed. This workflow is enabled by default for projects created via the GitHub UI, but projects created via API (as `board-init` does) may not have it enabled. **Verify** the workflow is active: Project settings > Workflows > "Item closed" > confirm Status maps to "Done". If disabled, enable it. Without this workflow, the board status will remain "In Review" until `board-groom` detects and fixes the drift. GitHub does NOT auto-update labels on close — the `status:in-review` label remains on the closed issue.
+- **Azure DevOps:** Work item auto-transition to "Closed" requires the **"Complete linked work items after merging"** checkbox during PR completion. This is opt-in per PR (not automatic by default). ADO also supports `Fixes #N` / `Resolves #N` syntax in PR descriptions for state transitions. **Recommend** checking this option consistently, or configuring it as the user's default.
+- **GitLab:** Labels are NOT updated on auto-close. The `status::in-review` scoped label remains on the closed issue. GitLab does not have a built-in "set label on close" automation. The `status::done` label must be applied manually, via a CI pipeline trigger on issue close events, or will be caught and fixed during `board-groom` drift remediation. Note: scoped labels (`status::done`) require GitLab **Premium or Ultimate** tier.
+
+Board commands that detect closed issues with `status:in-review` (or any non-`status:done` status label) should treat this as drift and remediate per the platform-specific sync procedure.
+
+---
+
+## PR Closed Without Merge
+
+When a PR/MR is closed without merging, the referenced issues remain open with `status:in-review`. This is drift that must be resolved:
+
+1. **Expected behavior:** Issues should revert to:
+   - `status:in-progress` — if the developer intends to continue work on a different branch or rework the changes.
+   - `status:ready` — if the work is abandoned and the issue should return to the backlog for future pickup.
+2. **Board sync:** The board status should be updated to match the new label ("In Progress" or "Ready").
+3. **Detection:** `board-groom` Step 3l detects orphaned `status:in-review` issues (those with no open PR/MR referencing them). The user decides the target state during grooming.
+4. **Collision detection:** During `board-pickup` Step 3, if collision detection finds a closed-without-merge PR for the selected issue, surface this context to the user so they can decide whether to reuse the branch, start fresh, or pick a different issue.
+
+This situation is NOT automatically remediated because the correct target state depends on developer intent. Board commands surface it as a diagnostic for user decision.
+
+---
+
 ## End-of-Run Reconciliation Procedure
 
 Every mutating board command (`board-fill`, `board-groom`, `board-pickup`) runs this procedure as its final step before the summary output. It catches silent failures and drift accumulated during the run.
@@ -146,6 +175,11 @@ Every mutating board command (`board-fill`, `board-groom`, `board-pickup`) runs
 2. **Sub-issue link verification:** Review `link_results` in the run cache. For links recorded as `advisory`, retry the platform-specific primary link method once to upgrade to `native`. Report all non-native links (`advisory` / `comment-only`) in the reconciliation output.
 3. **Label consistency:** Verify all created/updated issues have required labels (`type:*`, `priority:*`, `executor:*`) and correct `has-dependencies` state per rule 7 of Board Sync Enforcement. Fix any gaps.
 4. **PR linkage:** For issues transitioned to `status:in-progress` or `status:in-review`, verify any associated open PR body contains `Closes #N` for the addressed issues. Auto-fix if missing by updating the PR body.
+5. **Orphaned in-review detection:** For all cached issues with `status:in-review` (not just those transitioned during this run), verify an open PR/MR exists that references `Closes #N`:
+   - **GitHub:** `gh pr list -R {owner}/{repo} --state open --json number,body` — parse for `Closes #{N}`.
+   - **Azure DevOps:** `az repos pr list --status active` — check work item links.
+   - **GitLab:** `glab mr list -R {namespace}/{project} --state opened` — parse descriptions for `Closes #{N}`.
+   Flag orphaned in-review issues (those with no associated open PR/MR) in the reconciliation report. This catches issues that drifted to `status:in-review` in previous runs but lost their PR (closed without merge, PR deleted, etc.). Also flag closed issues still labeled `status:in-review` that should be `status:done`.
 
 ### Reconciliation Report
 
@@ -157,6 +191,7 @@ Reconciliation:
   Sub-issue links: {N} native, {M} advisory, {K} comment-only
   Label gaps:   {N} fixed, {M} remaining (list)
   PR linkage:   {N} verified, {M} missing `Closes` (list)
+  Orphaned in-review: {N} open issues with no PR/MR, {M} closed issues not status:done (list)
   Errors:       {list or "None"}
 ```
 

package/commands/hatch3r-command-customize.md

@@ -93,6 +93,10 @@ enabled: false
 - Invalid YAML produces warnings but does not prevent command 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: command`. The skill provides root-cause analysis, multi-stakeholder review, and quality gate steps that extend the workflow above.
+
 ## Related
 
 - Agent customization: `hatch3r-agent-customize` command

package/commands/hatch3r-hooks.md

@@ -251,7 +251,7 @@ Add `priority` and `timeout` to hook frontmatter:
 
 ```markdown
 ---
-id: pre-commit-lint-fixer
+id: my-pre-commit-lint-fixer
 type: hook
 event: pre-commit
 agent: lint-fixer

package/commands/hatch3r-quick-change.md

@@ -40,7 +40,7 @@ This command intentionally skips:
 - GitHub issues and PRs
 - Researcher sub-agent
 - Full review pipeline (security-auditor, test-writer, docs-writer)
-- Learnings capture
+- Learnings capture (consultation of existing learnings retained — see Step 2c)
 
 It retains:
 - Quality checks (lint, typecheck, test) -- always mandatory
@@ -48,6 +48,7 @@ It retains:
 - Light code review (reviewer for nontrivial items only)
 - `scope: always` rules from `.agents/rules/`
 - Soft scope guards to prevent misuse
+- Lightweight learnings consultation (file-path scan, 150-token budget)
 
 ---
 
@@ -60,7 +61,7 @@ It retains:
 1. **No shared context loading.** Do NOT read `hatch3r-board-shared`. Do NOT fetch GitHub issues or PRs.
 2. **Minimal researcher usage.** No researcher for Tier 1 items. For Tier 2 items that proceed through quick-change, only `similar-implementation` at `quick` depth. Tier 3 items must be routed to `hatch3r-workflow`.
 3. **Targeted file reads only.** Read only files directly relevant to the described change(s).
-4. **No learnings capture.** Quick changes are too small to produce meaningful learnings.
+4. **No learnings capture.** Quick changes are too small to produce meaningful learnings. Existing learnings are consulted via a lightweight file-path scan (Step 2c) with a 150-token budget — no new learnings are written.
 5. **Minimal rule loading.** Load `scope: always` rules only when spawning sub-agents in Steps 4b or 6.
 
 ---
@@ -124,6 +125,26 @@ Quick Change Scope:
   Estimated scope: {N} files, ~{N} lines
 ```
 
+#### 2c. Lightweight Learnings Scan (Optional)
+
+If `.agents/learnings/` exists:
+
+1. Collect the file paths from the affected areas identified in Step 1.
+2. Scan learning file frontmatter for `area` or `tags` that match the affected file paths or directories.
+3. If matches found (max 3 learnings, highest confidence first), surface them as a brief heads-up:
+
+   ```
+   Heads up — relevant learnings:
+     - [{category}] {one-line learning summary} (from: {learning filename})
+     - ...
+   ```
+
+4. If no matches found: continue silently. Do not mention learnings.
+
+**Token budget:** Max 150 tokens for this entire step. Read frontmatter only — do not read learning bodies unless the frontmatter matches. Limit to 3 surfaced learnings. If more than 3 match, show the 3 with highest confidence.
+
+If `.agents/learnings/` does not exist, skip this step silently.
+
 **ASK:** "Proceed with these changes? (yes / adjust)"
 
 ---
@@ -189,6 +210,7 @@ The implementer prompt MUST include:
 - Explicit instruction: do NOT create branches, commits, or PRs.
 - **Reference conventions** from `similar-implementation` output (if step 2 ran) — triggers the implementer's Convention Lock step.
 - If no researcher ran: explicit instruction that no researcher context is available; work from the change description and codebase alone.
+- 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.
 
 If multiple nontrivial items affect **independent areas** (no shared files), spawn one implementer per area and run them in parallel.
 
@@ -216,7 +238,7 @@ Run the project's quality gates. Refer to `package.json` scripts, `README.md`, o
 
 Max 2 retry loops on quality check failures. After 2 retries:
 
-**ASK:** "Quality checks still failing after 2 fix attempts: {specific failures}. Options: (a) I'll fix manually, commit what we have, (b) keep trying, (c) abort changes."
+**ASK:** "Quality checks still failing after 2 fix attempts: {specific failures}. Fix confidence: {high/medium/low — based on whether root cause is identified}. Options: (a) I'll fix manually, commit what we have, (b) keep trying, (c) abort changes."
 
 ---
 
@@ -235,6 +257,7 @@ The reviewer prompt MUST include:
 - Focus areas: **correctness and code quality only**. Skip security deep-dive, performance profiling, and documentation review.
 - All `scope: always` rule directives from `.agents/rules/`.
 - Iteration number and previous findings (if not the first iteration).
+- 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.
 
 2. Process reviewer output:
    - If **0 Critical and 0 Warning** findings: review loop is clean. Proceed to Step 6b.
@@ -242,6 +265,7 @@ The reviewer prompt MUST include:
    - **Suggestions**: skip. The point of quick-change is speed.
 
 3. If 3 iterations complete and findings remain, **ASK** the user whether to proceed or fix manually.
+   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.
 
 4. After any fixes, re-run quality checks (Step 5a) to verify nothing broke.
 
@@ -255,6 +279,7 @@ After the review loop is clean, spawn both agents in parallel via the Task tool:
 Both prompts MUST include:
 - The diff of all changes made.
 - All `scope: always` rule directives from `.agents/rules/`.
+- 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.
 
 Apply any resulting changes (new tests, security fixes). Re-run quality checks (Step 5a) if changes were made.
 
@@ -310,6 +335,7 @@ Quick Change Complete:
   Quality: lint {pass/fail}, types {pass/fail}, tests {pass/fail}
   Review: {skipped / N findings applied}
   Git: {committed on {branch} / committed and pushed / skipped}
+  Confidence: {high/medium/low — overall assessment of change correctness}
 ```
 
 ---