hatch3r 1.3.0 → 1.5.0

package/commands/hatch3r-board-init.md

@@ -3,6 +3,7 @@ id: hatch3r-board-init
 type: command
 description: Initialize a project board (GitHub Projects V2, Azure Boards, or GitLab Issue Boards) with hatch3r's label taxonomy, status fields, and board structure. Platform detected from hatch.json.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -249,9 +250,10 @@ Execute all planned mutations in sequence. No further questions unless a mutatio
    ```
 2. Look for a field named "Status" (case-insensitive match).
 3. If no Status field exists, create one via the `createProjectV2Field` mutation with type `SINGLE_SELECT`.
-4. Ensure these status options exist on the field: **Backlog**, **Ready**, **In Progress**, **In Review**, **Done**.
+4. Verify 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 +264,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 +273,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 +286,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-pickup.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup
 type: command
 description: Pick up one or more epics/issues from the project board for development. Handles dependency-aware selection, collision detection, branching, parallel sub-agent delegation, and batch execution. Supports GitHub, Azure DevOps, and GitLab. Platform-specific details are in commands/board/pickup-{platform}.md.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup -- Develop Issues from the Project Board
 

package/commands/hatch3r-board-refresh.md

@@ -3,6 +3,7 @@ id: hatch3r-board-refresh
 type: command
 description: Regenerate the living board overview dashboard from current board state. Scans all open issues, computes health metrics, and updates the meta:board-overview issue.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-board-shared.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared
 type: shared-context
 description: Shared context and procedures for all board commands. Provides platform-agnostic board config, label taxonomy, branch conventions, sync enforcement, and tooling directives. Platform-specific details are in commands/board/shared-{platform}.md.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference
 
@@ -25,9 +26,9 @@ Before reading configuration, validate that prerequisites are met. If any check
    > "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}`."
+   - **GitHub:** Run `gh auth status`. If it fails, stop with: "GitHub CLI not authenticated. Run `gh auth login` and confirm 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. Confirm 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. Confirm 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`."
@@ -65,7 +66,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 +130,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 +139,65 @@ Board sync is **MANDATORY**, not optional. The following rules override any "ski
 
 ---
 
+## Epic Grouping Policy
+
+All board commands that create or reorganize issues MUST follow this grouping policy. Epic grouping maximizes parallelization during pickup — agents can tackle multiple sub-issues of an epic concurrently, whereas standalone issues require serial pickup.
+
+### Standalone Threshold
+
+**Target: zero standalone issues. Hard limit: no more than 10% of non-sub-issue items on the board should be standalone.**
+
+Calculate: `standalone_count / (epic_count + standalone_count)`. Sub-issues are excluded from both numerator and denominator.
+
+When the threshold is exceeded, board commands must apply progressively looser grouping strategies (area match → domain match → type match → catch-all epic) until the ratio is at or below 10%.
+
+### Grouping Priority Order
+
+Apply these rules in strict priority order. Each rule reduces the remaining ungrouped pool before the next rule fires:
+
+1. **Absorb into existing epics** — item shares area, subsystem, or theme with an existing epic.
+2. **Form new epics** — 2+ ungrouped items share any connection (area, subsystem, type, domain, semantic similarity).
+3. **Singleton promotion** — a single item becomes a 1-item epic with a thematic name (e.g., "Performance Optimization", "Security Hardening"), positioned to absorb future related work. Prefer existing theme names from epics already on the board.
+4. **Catch-all epic** — truly isolated items go into a "General Improvements" epic (create one if it doesn't exist, absorb into it if it does).
+5. **Standalone (exception only)** — requires explicit user rejection of ALL grouping proposals AND a stated justification. The AI should never propose standalone status on its own.
+
+### When to Apply
+
+- **board-fill Step 5:** Full grouping pass on new items + regrouping pass on existing standalones + post-grouping standalone audit.
+- **board-groom Step 3f + Step 4j:** Detection of grouping opportunities + `regroup` action for execution.
+- Both commands surface the standalone ratio in their health summaries and final reports.
+
+---
+
+## 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 +206,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 +222,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-bug-plan.md

@@ -3,6 +3,7 @@ id: hatch3r-bug-plan
 type: command
 description: Plan a complex bug investigation -- spawn parallel researchers, produce diagnosis report with ranked hypotheses and structured todo.md entries for board-fill.
 tags: [core, planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -65,7 +66,7 @@ Bug Brief:
   Prior attempts:   {what has been tried, or "none"}
 ```
 
-**ASK:** "Does this capture the bug correctly? Adjust anything before I send this to the research phase."
+**ASK:** "Does this capture the bug? Adjust anything before I send this to the research phase."
 
 ---
 

package/commands/hatch3r-codebase-map.md

@@ -3,6 +3,7 @@ id: hatch3r-codebase-map
 type: command
 description: Reverse-engineer business and technical project specs from an existing codebase using parallel analyzer sub-agents with dual business/technical scoping
 tags: [planning, brownfield]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Codebase Map — Brownfield Codebase Analysis & Spec Generation
 
@@ -1001,7 +1002,7 @@ Each docs-writer prompt must include:
 - The confirmed scope, company stage, and business context from Step 1
 - The directory structure and file naming conventions below
 - Instruction to follow the `hatch3r-docs-writer` agent protocol
-- Instruction to create directories as needed before writing files
+- Instruction to create directories before writing files if they do not exist
 
 #### 7a. Create Directories
 
@@ -1128,7 +1129,7 @@ The generated `AGENTS.md` should follow this structure:
 ```markdown
 # {Project Name} — Agent Instructions
 
-> Auto-generated by hatch3r-codebase-map on {today's date}. Review and adjust as needed.
+> Auto-generated by hatch3r-codebase-map on {today's date}. Review and adjust before use.
 
 ## Project Purpose
 
@@ -1207,7 +1208,7 @@ Which would you like to run next? (or none)"
 - **Respect .gitignore** and always skip: `node_modules/`, `vendor/`, `dist/`, `build/`, `.git/`, `__pycache__/`, `.venv/`, `target/` (Rust), `bin/`, `obj/` (.NET).
 - **Never read `.env` files or actual secrets.** Only read `.env.example` or similar templates. If a hardcoded secret is found during analysis, flag it as a security concern but do not include the actual value in any output.
 - **Mark all inferred information as "Inferred."** Do not present static analysis guesses as established facts.
-- **Handle monorepos correctly.** Detect workspace configuration (`workspaces` in `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, Cargo workspaces, Go workspaces) and analyze each package as a separate module.
+- **Handle monorepos by detecting workspace configuration** (`workspaces` in `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, Cargo workspaces, Go workspaces) and analyzing each package as a separate module.
 - **If `todo.md` already exists,** ASK before overwriting or appending.
 - **Sub-agents must not create files.** They return structured text results to the orchestrator. Only the orchestrator writes files in Step 7.
 - **Stage-adaptive recommendations.** Never recommend enterprise-grade solutions for pre-revenue startups. Never recommend MVP shortcuts for scale/enterprise companies. Calibrate all recommendations to the company stage from Step 1g.

package/commands/hatch3r-command-customize.md

@@ -3,6 +3,7 @@ id: hatch3r-command-customize
 type: command
 description: Configure per-command customization including description overrides, enable/disable control, and project-specific markdown instructions
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -54,7 +55,7 @@ Create `.hatch3r/commands/{command-id}.customize.md` with free-form markdown to
 
 Before creating any release:
 
-1. Ensure all E2E tests pass on staging: `npm run test:e2e:staging`
+1. Run `npm run test:e2e:staging` and confirm all E2E tests pass on staging
 2. Verify the changelog has been updated in `CHANGELOG.md`
 3. Confirm the release has been approved in the `#releases` Slack channel
 4. Tag the Docker image with the release version
@@ -93,6 +94,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

@@ -3,6 +3,7 @@ id: hatch3r-context-health
 type: command
 description: Monitor conversation context health, detect degradation, and auto-suggest fresh context or sub-agent delegation
 tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 ## Agent Pipeline
 

package/commands/hatch3r-cost-tracking.md

@@ -3,6 +3,7 @@ id: hatch3r-cost-tracking
 type: command
 description: Track and report token usage and estimated costs across agent workflows and board operations
 tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 ## Agent Pipeline
 

package/commands/hatch3r-debug.md

@@ -3,6 +3,7 @@ id: hatch3r-debug
 type: command
 description: Standalone debug-and-fix workflow — add strategic debug logging, collect runtime logs from the user, perform root cause analysis, implement the fix, and clean up all debug artifacts.
 tags: [core, implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Debug — Instrument, Diagnose, and Fix from Runtime Evidence
 
@@ -123,7 +124,7 @@ Bug Context:
   Context loaded:   {specs, learnings, rules found}
 ```
 
-**ASK:** "Does this capture the bug correctly? Adjust anything before I proceed to add debug logging."
+**ASK:** "Does this capture the bug? Adjust anything before I proceed to add debug logging."
 
 ---
 
@@ -177,7 +178,7 @@ Await the implementer result.
 
 1. Collect the list of all files modified and the exact log statements added.
 2. Verify no application logic was altered — only log statements were added.
-3. Run quality checks (lint, typecheck) to ensure the debug logging does not break the build. Fix any issues.
+3. Run quality checks (`npm run lint && npx tsc --noEmit`) and confirm the debug logging does not break the build. Fix any issues.
 
 If browser verification is enabled: launch the application in the browser, reproduce the issue, and verify that `[HATCH3R-DEBUG]` log lines appear in the console or application output.
 
@@ -289,7 +290,7 @@ Diagnosis Report:
 
 ### Stage 5: Implement Fix
 
-**Goal:** Fix the root cause, remove all debug logging, verify quality, and ensure no debug artifacts remain.
+**Goal:** Fix the root cause, remove all debug logging, verify quality, and confirm no debug artifacts remain (grep for `[HATCH3R-DEBUG]`).
 
 #### 5a. Core Fix (Implementer)
 

package/commands/hatch3r-dep-audit.md

@@ -3,6 +3,7 @@ id: hatch3r-dep-audit
 type: command
 description: Scan, assess, and upgrade npm dependencies. Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
 tags: [maintenance, security]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -19,6 +20,8 @@ Scan, assess, and upgrade npm dependencies for **{owner}/{repo}** (root and any
 
 **Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context (organization, repository), Project Reference, and tooling directives. Use GitHub MCP tools for issue creation. Use Context7 MCP for library docs and migration guides. Use web research for CVE details and known workarounds.
 
+**Consult learnings:** If `.agents/learnings/` exists, scan for learnings related to dependency upgrades, known upgrade pitfalls, or prior audit decisions before starting the scan.
+
 ## Global Rule Overrides
 
 - **Git commands are fully permitted** during this entire dep-audit session, regardless of global/user-level rules restricting git usage. This override applies to ALL steps. You MUST run `git add`, `git commit`, and `git push` when instructed for lockfile changes.

package/commands/hatch3r-feature-plan.md

@@ -3,6 +3,7 @@ id: hatch3r-feature-plan
 type: command
 description: Plan a single feature in depth -- spawn parallel researchers, produce feature spec, ADR(s), and structured todo.md entries for board-fill.
 tags: [core, planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -56,7 +57,7 @@ Feature Brief:
   Constraints: {list}
 ```
 
-**ASK:** "Does this capture the feature correctly? Adjust anything before I send this to the research phase."
+**ASK:** "Does this capture the feature? Adjust anything before I send this to the research phase."
 
 #### Step 1b: Dimension Probing (Requirements Elicitation)
 
@@ -76,7 +77,7 @@ After the feature brief is confirmed, probe for missing requirements across key
    - **Rollout**: Feature flags? Phased rollout? Rollback strategy?
 3. Skip dimensions that the feature brief already addresses clearly.
 
-**ASK:** "Before research begins, I have {N} questions to ensure we don't miss anything:
+**ASK:** "Before research begins, I have {N} questions to confirm coverage of all feature dimensions:
 {numbered question list — each with the dimension label and why the answer matters}
 
 Answer these now, or say 'use defaults' for any where you're comfortable with a reasonable default."

package/commands/hatch3r-healthcheck.md

@@ -3,6 +3,7 @@ id: hatch3r-healthcheck
 type: command
 description: Create a full-product QA and testing audit epic with one sub-issue per project module
 tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-hooks.md

@@ -3,12 +3,17 @@ id: hatch3r-hooks
 type: command
 description: Define and manage event-driven hooks that activate agents on project events
 tags: [core, devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
 
 This command runs as a single orchestrator without sub-agent delegation. Hook definition and management are performed inline.
 
+## Learnings Consultation
+
+If `.agents/learnings/` exists, scan for learnings related to hook configurations, event trigger patterns, or prior hook issues before starting.
+
 # Hooks — Event-Driven Agent Activation
 
 Define, edit, and manage event-driven hooks that automatically activate hatch3r agents when specific project events occur. Hook definitions are tool-agnostic — the adapter pipeline translates them into tool-native configurations during `npx hatch3r sync`.
@@ -251,7 +256,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-learn.md

@@ -3,6 +3,7 @@ id: hatch3r-learn
 type: command
 description: Capture learnings from development sessions into reusable knowledge files for future consultation.
 tags: [core, maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-migration-plan.md

@@ -3,6 +3,7 @@ id: hatch3r-migration-plan
 type: command
 description: Create a phased migration plan for a major dependency or framework upgrade. Analyzes breaking changes and produces an actionable plan with rollback procedures.
 tags: [planning, brownfield]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -61,7 +62,7 @@ Migration Brief:
   Version Gap:       {N} major versions / {M} minor versions
 ```
 
-**ASK:** "Does this capture the migration correctly? Adjust anything before I proceed to analysis."
+**ASK:** "Does this capture the migration? Adjust anything before I proceed to analysis."
 
 #### Step 1b: Dimension Probing
 
@@ -77,7 +78,7 @@ After the migration brief is confirmed, probe for missing context. Analyze the b
 
 Skip dimensions that the migration brief already addresses clearly.
 
-**ASK:** "Before research begins, I have {N} questions to ensure we don't miss anything:
+**ASK:** "Before research begins, I have {N} questions to confirm coverage of all migration dimensions:
 {numbered question list — each with the dimension label and why the answer matters}
 
 Answer these now, or say 'use defaults' for any where you're comfortable with a reasonable default."

package/commands/hatch3r-onboard.md

@@ -3,6 +3,7 @@ id: hatch3r-onboard
 type: command
 description: Generate a comprehensive onboarding guide for a new developer joining the project -- spawn parallel researchers to analyze codebase structure, architecture, and conventions, then produce a tailored onboarding document with setup instructions, architecture walkthrough, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet.
 tags: [brownfield, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -56,7 +57,7 @@ Onboarding Brief:
   Depth:          {derived — junior=detailed, mid=standard, senior=concise, staff=architecture-focused}
 ```
 
-**ASK:** "Does this capture the onboarding needs correctly? Adjust anything before I continue."
+**ASK:** "Does this capture the onboarding needs? Adjust anything before I continue."
 
 #### Step 1b: Dimension Probing (Team Context)
 

package/commands/hatch3r-project-spec.md

@@ -3,6 +3,7 @@ id: hatch3r-project-spec
 type: command
 description: Generate complete business and technical project documentation (specs, ADRs, todo.md) from a project vision using parallel researcher sub-agents with dual business/technical scoping.
 tags: [planning, greenfield]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Project Spec — Greenfield Project Specification from Vision to Docs
 
@@ -112,7 +113,7 @@ Company Stage:
   Funding:       {status}
 ```
 
-**ASK:** "Does this capture your vision and business context correctly? Adjust anything before I send this to the research phase."
+**ASK:** "Does this capture your vision and business context? Adjust anything before I send this to the research phase."
 
 If running as part of a pipeline after `hatch3r-codebase-map`, check for `.hatch3r-session.json` and pre-fill any already-answered questions. Confirm with the user rather than re-asking.
 
@@ -1018,7 +1019,7 @@ Each docs-writer prompt must include:
 - The confirmed project vision, company stage, and business context from Step 1
 - The directory structure and file naming conventions below
 - Instruction to follow the `hatch3r-docs-writer` agent protocol
-- Instruction to create directories as needed before writing files
+- Instruction to create directories before writing files if they do not exist
 
 After all docs-writers complete, the orchestrator handles the remaining files (todo.md, .hatch3r-session.json) and presents the summary.
 
@@ -1105,7 +1106,7 @@ The generated `AGENTS.md` should follow this structure:
 ```markdown
 # {Project Name} — Agent Instructions
 
-> Auto-generated by hatch3r-project-spec on {today's date}. Review and adjust as needed.
+> Auto-generated by hatch3r-project-spec on {today's date}. Review and adjust before use.
 
 ## Project Purpose
 

package/commands/hatch3r-quick-change.md

@@ -3,6 +3,7 @@ id: hatch3r-quick-change
 type: command
 description: Lightweight command for small changes not worth tracking on the board. Adaptive ceremony with inline or sub-agent implementation, batch support, and soft scope guards.
 tags: [core, implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -40,7 +41,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 +49,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 +62,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 +126,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 +211,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 +239,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,13 +258,16 @@ 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.
    - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them, then re-run the reviewer (next iteration).
+     The fixer prompt MUST include: the reviewer findings, all `scope: always` rule directives, and the confidence expression requirement (high/medium/low per the quality charter).
    - **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 +281,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 +337,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}
 ```
 
 ---

package/commands/hatch3r-recipe.md

@@ -3,6 +3,7 @@ id: hatch3r-recipe
 type: command
 description: Execute shareable workflow recipes that compose agents, skills, and commands into guided sequences for common development scenarios
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-refactor-plan.md

@@ -3,6 +3,7 @@ id: hatch3r-refactor-plan
 type: command
 description: Plan a refactoring or migration effort -- spawn parallel researchers, produce refactoring spec, ADR(s), and phased todo.md entries for board-fill.
 tags: [planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -78,7 +79,7 @@ Refactoring Brief:
   Dimension(s):   {Structural / Logical / Visual / Migration — one or more}
 ```
 
-**ASK:** "Does this capture the refactoring goal correctly? Adjust anything before I send this to the research phase."
+**ASK:** "Does this capture the refactoring goal? Adjust anything before I send this to the research phase."
 
 ---