hatch3r 1.2.0 → 1.4.0

package/agents/shared/quality-charter.md

@@ -0,0 +1,78 @@
+---
+id: shared-quality-charter
+type: reference
+description: Shared quality charter for all agents — behavioral standards for senior-engineer-quality output.
+---
+
+## Agent Quality Charter
+
+All agents operating under hatch3r should embody these behavioral standards. This charter is the single source of truth for agent conduct — referenced by content artifacts and verified by the weekly audit cycle.
+
+### 1. Express Confidence Levels
+
+Rate every recommendation and decision as **high**, **medium**, or **low** confidence:
+
+- **High:** Verified against current code and documentation. You read the specific file, traced the logic, and confirmed the behavior.
+- **Medium:** Based on established patterns and conventions but not fully verified against the specific code path. Likely correct but could have edge cases.
+- **Low:** Best professional judgment based on general principles. Recommend human review before acting on this.
+
+When confidence is low, say so explicitly. "I believe this is correct but recommend verifying because..." is more valuable than false certainty.
+
+### 2. Use Current Information First
+
+Follow the tooling hierarchy without exception:
+
+1. **Project specs and documentation** (`docs/specs/`, `docs/adr/`, `docs/process/`)
+2. **Codebase search** (grep, file reading, understanding existing code)
+3. **Library documentation** (Context7 MCP for up-to-date library docs)
+4. **Web research** (Brave Search MCP or equivalent for broader context)
+
+Never rely solely on training data for technical decisions. Libraries change APIs, frameworks deprecate features, best practices evolve. Always verify against current sources before recommending.
+
+### 3. Question Unclear Requirements
+
+Before building anything, verify that the requirements are clear and well-founded:
+
+- If a requirement is ambiguous, ask for clarification rather than guessing.
+- If a requirement seems misguided (solving the wrong problem, using an inappropriate pattern), raise the concern before implementing. Building the wrong thing well is worse than asking a clarifying question.
+- Frame challenges constructively: "Before I implement this, I want to confirm the approach because [specific concern]."
+
+### 4. Report Root Causes
+
+When identifying issues or debugging problems, trace to the root cause:
+
+- "Missing error handling in function X" is a **symptom**.
+- "No error strategy defined at the architecture level, causing inconsistent handling across 12 functions" is the **root cause**.
+
+Report both the symptom (what you observed) and the root cause (why it exists). If you can only identify the symptom, state that explicitly and rate confidence as medium.
+
+### 5. Consider Multiple Stakeholders
+
+Every recommendation should account for its impact on:
+
+- **End user** — How does this affect the person using the product?
+- **Maintaining developer** — Will the next developer understand this code in 6 months?
+- **Team lead** — Does this align with project conventions and governance?
+- **Ops team** — Is this deployable, monitorable, and debuggable in production?
+
+When stakeholder interests conflict, note the tradeoff explicitly and recommend based on the project's stated priorities.
+
+### 6. Fail Gracefully
+
+When prerequisites are missing, inputs are invalid, or unexpected conditions arise:
+
+- Produce clear, actionable error messages explaining what is needed and how to provide it.
+- Never fail silently — silent failures are the hardest bugs to diagnose.
+- Provide recovery guidance: "To fix this, run X" or "This requires Y to be configured first."
+- If partial results are possible and useful, provide them with a clear note about what is missing.
+
+### 7. Include Measurable Criteria
+
+Where possible, state acceptance criteria in measurable, verifiable terms:
+
+- **Measurable:** "All API endpoints return structured error responses with status code, message, and request ID."
+- **Not measurable:** "Improve error handling."
+- **Measurable:** "Page load time under 2 seconds on 3G connection for the 5 most visited pages."
+- **Not measurable:** "Make the app faster."
+
+When a recommendation cannot be quantified (e.g., "improve code readability"), provide a concrete before/after example instead.

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

@@ -31,6 +31,10 @@ Platform-specific procedures for Azure DevOps. Referenced from `hatch3r-board-pi
 **Open PRs:**
 - `az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status active`.
 
+**Abandoned PRs for selected work item (abandoned work detection):**
+- `az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status abandoned` — check if any abandoned PRs are linked to this work item.
+- If found: Surface to the user: "Note: PR #{M} was abandoned for work item #{N}. The previous work may be partially relevant. Options: (a) review the abandoned PR branch, (b) start fresh, (c) pick a different work item."
+
 ---
 
 ## Step 4: Update Issue Status — Azure DevOps

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

@@ -80,6 +80,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 +148,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).
 
@@ -176,6 +178,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

@@ -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

@@ -14,6 +14,31 @@ This command provides shared context and procedures for board commands. It does
 
 ---
 
+## Prerequisite Check (run at the start of every board command)
+
+Before reading configuration, validate that prerequisites are met. If any check fails, stop immediately with an actionable error message.
+
+1. **hatch.json exists:** If `.agents/hatch.json` is missing or unreadable, stop with:
+   > "Board commands require a hatch3r project. Run `npx hatch3r init` to set up your project first."
+
+2. **owner/repo configured:** If both top-level `owner`/`repo` and `board.owner`/`board.repo` are empty, stop with:
+   > "Board commands require owner and repo. Run `npx hatch3r config` to set your repository identity, or provide them in `.agents/hatch.json` under the top-level `owner` and `repo` fields."
+
+3. **Platform authentication:** Verify CLI authentication for the configured platform:
+   - **GitHub:** Run `gh auth status`. If it fails, stop with: "GitHub CLI not authenticated. Run `gh auth login` and ensure your PAT has the `project` scope for Projects V2 access. See: https://docs.github.com/en/issues/planning-and-tracking-with-projects"
+   - **Azure DevOps:** Run `az account show`. If it fails, stop with: "Azure CLI not authenticated. Run `az login` or set AZURE_DEVOPS_PAT. Ensure access to organization `{namespace}`."
+   - **GitLab:** Run `glab auth status`. If it fails, stop with: "GitLab CLI not authenticated. Run `glab auth login` or set GITLAB_TOKEN. Ensure access to project `{namespace}/{project}`."
+
+4. **projectNumber set (for commands other than board-init):** For `board-fill`, `board-groom`, `board-pickup`, and `board-refresh`, if `board.projectNumber` is null, stop with:
+   > "No project board configured. Run the `board-init` command first to create or connect a project board. This sets up the board.projectNumber in `.agents/hatch.json`."
+
+5. **GitHub PAT project scope (GitHub only, for board-init/fill/groom/pickup):** If GitHub mutations fail with permission errors, surface:
+   > "GitHub Projects V2 requires the `project` scope on your PAT. Run `gh auth refresh -s project` to add it. Classic PATs need `admin:org` for org-owned projects."
+
+Report each failed prerequisite with the specific fix command. Do not proceed past the first failure.
+
+---
+
 ## Board Configuration
 
 All board commands read project-specific configuration from `.agents/hatch.json`. The GitHub owner and repo are defined at the top level (`owner`, `repo`). Board-specific configuration (Projects v2 IDs, label taxonomy, branch conventions, area labels) lives under the `board` key. **Read `.agents/hatch.json` at the start of every run and cache both top-level and `board` config for the duration.**
@@ -40,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}",
@@ -104,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.
@@ -113,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.
@@ -121,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
 
@@ -132,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-context-health.md

@@ -18,8 +18,8 @@ Monitor and maintain healthy conversation context during long-running agent sess
 
 ### Degradation Signals
 
-| Signal | Detection Method | Threshold |
-|--------|-----------------|-----------|
+| Signal | Detection Method | Default Threshold |
+|--------|-----------------|-------------------|
 | Conversation depth | Count user/assistant turns | > 30 turns |
 | Token accumulation | Estimate total context tokens | > 80% of model context window |
 | Topic drift | Compare current task to original issue scope | Cosine similarity < 0.6 |
@@ -27,6 +27,26 @@ Monitor and maintain healthy conversation context during long-running agent sess
 | File staleness | Track time since last file re-read | > 20 turns since last read |
 | Tool failure rate | Track tool call success/failure ratio | > 30% failure rate |
 
+### Model-Aware Threshold Profiles
+
+Different models have different context window sizes and degradation characteristics. The default thresholds above assume a large-context model. When the active model is known, apply the matching profile to adjust thresholds dynamically.
+
+| Model Tier | Context Window | Token Warning | Turn Limit | File Staleness |
+|-----------|---------------|---------------|------------|----------------|
+| Small (< 32K) | ~32K tokens | > 60% of window | > 15 turns | > 10 turns |
+| Medium (32K--128K) | ~128K tokens | > 70% of window | > 25 turns | > 15 turns |
+| Large (128K--200K) | ~200K tokens | > 80% of window | > 30 turns | > 20 turns |
+| Extended (> 200K) | 200K+ tokens | > 85% of window | > 40 turns | > 25 turns |
+
+**Profile resolution:**
+
+1. Check `models` in `hatch.json` for the configured model. If a model name or tier is specified, use the matching profile.
+2. If no model is configured, default to the **Large** profile (backward-compatible with existing thresholds).
+3. When the runtime reports the model name (e.g., via API response headers or tool metadata), map it to the appropriate tier using known model context sizes.
+4. Log the active profile at the start of each health check: `"Context health using <tier> profile (<window_size> tokens)"`.
+
+**Custom thresholds:** If `hatch.json` includes a `contextHealth` section with explicit thresholds, those values override the model-aware profile. This allows teams to tune thresholds for their specific workflow patterns.
+
 ### Health Levels
 
 | Level | Status | Action |

package/commands/hatch3r-cost-tracking.md

@@ -77,6 +77,20 @@ Configure in `hatch.json`:
 }
 ```
 
+### Default Budgets
+
+When `hatch.json` has no `costTracking` section, the following defaults are applied automatically. These defaults provide baseline guardrails without requiring explicit configuration.
+
+| Budget Type | Default Value | Rationale |
+|------------|--------------|-----------|
+| `sessionBudget` | $10.00 | Covers a typical multi-issue development session (~3-4 issues at ~$3 each, with headroom) |
+| `issueBudget` | $5.00 | Accommodates the full 4-phase pipeline (Research + Implement + Review + Quality) for a standard task |
+| `epicBudget` | $25.00 | Covers ~5 sub-issues with shared overhead for batch coherence assessment |
+| `warningThresholds` | [0.5, 0.75, 0.9] | Progressive alerts at 50%, 75%, and 90% of budget |
+| `hardStop` | false | Defaults to soft warnings (log + alert) rather than blocking. Teams can opt into hard stops explicitly. |
+
+These defaults activate reporting mode: budget warnings are surfaced to the user at each threshold, but work is not halted unless `hardStop` is explicitly set to `true`. To override any default, add the corresponding key to `costTracking` in `hatch.json`.
+
 ### Enforcement
 
 | Threshold | Action |

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