hatch3r 1.4.0 → 1.5.0

package/commands/hatch3r-board-fill.md

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

package/commands/hatch3r-board-groom.md

@@ -3,6 +3,7 @@ id: hatch3r-board-groom
 type: command
 description: Ongoing backlog refinement for existing board items. Re-prioritize, reclassify, re-scope, archive stale items, decompose oversized issues, merge duplicates, refresh dependencies, and remediate board health findings.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -142,12 +143,18 @@ Analyze the distribution of priority labels across the board:
 - Flag if all issues share the same priority (undifferentiated backlog).
 - Flag issues where priority does not align with risk (e.g., `priority:p3` + `risk:high`).
 
-#### 3f. Grouping Opportunities
+#### 3f. Grouping Opportunities & Standalone Audit
 
-Scan existing standalone issues for potential epic grouping:
+Scan existing standalone issues for epic grouping. Apply the **Epic Grouping Policy** from `hatch3r-board-shared`:
 
 - 2+ standalone issues sharing the same `area:*` labels.
 - 2+ standalone issues with semantically similar titles or overlapping scope.
+- 2+ standalone issues sharing the same `type:*` label (e.g., all `type:refactor` items).
+- 2+ standalone issues in the same broader domain (e.g., `area:api` + `area:middleware` = "backend").
+- **Single standalone issues** that could be absorbed into an existing epic (shared area, subsystem, or theme).
+- **Single standalone issues** that could become a themed 1-item epic (singleton promotion).
+
+Compute standalone ratio: `standalone_count / (epic_count + standalone_count)`. Flag if ratio exceeds 10%.
 
 #### 3g. Decomposition Candidates
 
@@ -198,6 +205,7 @@ Board Groom — Refinement Summary:
 
 Board Health:
   Total open issues: N (X epics, Y sub-issues, Z standalone)
+  Standalone ratio: Z/{X+Z} ({percentage}%) — target <=10%
   Missing metadata: M issues (details below)
   Stale issues: S issues
   Stale dependency refs: D issues
@@ -216,10 +224,10 @@ Grooming Opportunities:
   Dependency cleanup: K issues (stale refs, orphaned labels)
   Link fix candidates: L issues (advisory or comment-only links)
 
-Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | dep-refresh | health-fix | link-fix | all]
+Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | regroup | dep-refresh | health-fix | link-fix | all]
 ```
 
-**ASK:** "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / dep-refresh / health-fix / link-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
+**ASK:** "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / regroup / dep-refresh / health-fix / link-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
 
 ---
 
@@ -463,7 +471,61 @@ Link Fix Candidates:
 
 ---
 
-#### 4i. Health Fix (Board Health Remediation)
+#### 4i. Regroup Standalones
+
+Group standalone issues into existing or new epics. This action executes the grouping opportunities detected in Step 3f, following the **Epic Grouping Policy** from `hatch3r-board-shared`.
+
+1. Present regrouping proposals from Step 3f, organized by target epic:
+
+```
+Regroup Proposals:
+
+Absorb into existing epics:
+  #{N} "{title}" → Epic #{E} "{epic title}" (shared area:api)
+  #{M} "{title}" → Epic #{F} "{epic title}" (semantic overlap)
+
+Form new epics:
+  New epic: "Code Quality & Refactoring"
+    #{P} "{title}" (type:refactor)
+    #{Q} "{title}" (type:refactor)
+
+Singleton promotions:
+  #{R} "{title}" → New 1-item epic: "Performance Optimization" (no existing epic match, but themed for future absorption)
+
+Catch-all:
+  #{S} "{title}" → "General Improvements" epic (no thematic match)
+
+Standalone ratio: before={before}%, after={projected}% (target <=10%)
+```
+
+**ASK:** "Confirm regrouping proposals. For each: accept / reject / move to different epic. Items you reject will remain standalone. Confirm / adjust / skip."
+
+2. For confirmed regroupings:
+
+   **Absorb into existing epic:**
+   - Link the standalone as a sub-issue using the **Sub-Issue Linking Procedure** from `hatch3r-board-shared`.
+   - Update the epic body to include the new sub-issue in its checklist and `## Implementation Order`.
+
+   **Form new epic:**
+   - Create a new epic issue with Overview, Sub-issues checklist, and `## Implementation Order`.
+   - Link all grouped items as sub-issues using the Sub-Issue Linking Procedure.
+   - Apply labels: inherit the common labels from the grouped items, add `status:triage` (or `status:ready` if all sub-issues are ready).
+   - Sync the new epic to the board via the **Board Sync Procedure** from `hatch3r-board-shared`.
+
+   **Singleton promotion:**
+   - Create a new 1-item epic with the themed title.
+   - Link the standalone as its only sub-issue.
+   - The epic body notes: "This epic groups related work for {theme}. Future items in this area should be added as sub-issues."
+
+   **Catch-all:**
+   - If a "General Improvements" epic exists, absorb into it.
+   - If not, create one with all catch-all items as sub-issues.
+
+3. After execution, recalculate and report the standalone ratio.
+
+---
+
+#### 4j. Health Fix (Board Health Remediation)
 
 Fix structural gaps detected in Step 3b (missing metadata), board sync drift detected in Step 3k, and orphaned in-review issues detected in Step 3l.
 
@@ -608,12 +670,14 @@ Board Groom Complete:
     Archived (closed):  {count} issues
     Decomposed:         {count} issues → {count} new sub-issues
     Merged:             {count} duplicate pairs
+    Regrouped:          {count} standalones → {count} epics ({count} new epics created)
     Dependencies:       {count} refs cleaned, {count} new deps added, {count} epics reordered
     Health fixed:       {count} issues (missing metadata resolved)
     Readiness promoted: {count} issues (triage → ready)
 
   Board State:
     Total open:   {count} ({epics} epics, {sub} sub-issues, {standalone} standalone)
+    Standalone ratio: {percentage}% (target <=10%)
     Ready:        {count} ({available} available, {depWaiting} waiting on deps)
     In Progress:  {count}
     In Review:    {count}

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,7 +250,7 @@ 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.

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`."
@@ -138,6 +139,36 @@ 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`.

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

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`.

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
@@ -262,6 +263,7 @@ The reviewer prompt MUST include:
 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.