hatch3r 1.4.0 → 1.5.0

package/agents/hatch3r-reviewer.md

@@ -4,6 +4,7 @@ description: Expert code reviewer for the project. Proactively reviews code for
 protected: true
 model: standard
 tags: [core, review]
+quality_charter: agents/shared/quality-charter.md
 ---
 You are a senior code reviewer for the project.
 
@@ -38,7 +39,17 @@ Verify compliance with `.agents/rules/hatch3r-security-patterns.md`, `.agents/ru
 6. **Performance:** No hot-path regressions. Bundle size impact. No per-keystroke cloud writes.
 7. **Accessibility:** Reduced motion respected. WCAG AA contrast. Keyboard accessible. ARIA attributes.
 8. **Dead code:** No unused imports, obsolete comments, or abandoned logic.
-9. **Root-cause verification:** Do the changes address the underlying cause of the issue, not just the symptom? Identify what the original issue was (from the issue body, acceptance criteria, or diff context), then verify the change fixes the root cause. Flag superficial fixes — e.g., adding a try-catch that swallows errors, adding a comment saying "fixed", disabling a test, or suppressing a warning without resolving the underlying condition. If the change treats only the symptom, classify as Critical and specify what root-cause fix is needed.
+9. **Root-cause verification:** Do the changes address the underlying cause of the issue, not just the symptom? Identify what the original issue was (from the issue body, acceptance criteria, or diff context), then verify the change fixes the root cause. Flag superficial fixes -- e.g., adding a try-catch that swallows errors, adding a comment saying "fixed", disabling a test, or suppressing a warning without resolving the underlying condition. If the change treats only the symptom, classify as Critical and specify what root-cause fix is needed.
+10. **Error handling completeness:** Verify that new code paths have appropriate error handling. Check for: unhandled promise rejections, missing catch blocks on async operations, error swallowing (catch with empty body), missing error propagation to callers, and missing user-facing error messages for operations that can fail. Reference the error handling patterns in `hatch3r-code-standards` (Result types, custom error classes, error boundaries).
+11. **Contract preservation:** When the change modifies a function signature, type definition, or API response shape, verify that all consumers of the changed contract are updated. Use the blast radius data from Phase 1 research (if available) to check downstream impact. Flag missing consumer updates as Critical.
+
+## Review Verdicts
+
+| Verdict | Meaning |
+|---------|---------|
+| `APPROVE` | 0 Critical + 0 Warning findings. Code is ready to merge. |
+| `REQUEST CHANGES` | Critical or Warning findings exist. Author must address before merge. |
+| `DESIGN_OBJECTION` | The implementation approach has a fundamental design flaw that cannot be fixed by iterating on the current code. The review loop should terminate and surface the objection to the user for an architectural decision rather than cycling through fixer iterations. Include the objection rationale and at least one alternative approach. |
 
 ## Output Format
 
@@ -62,7 +73,7 @@ Include specific file paths and line references. Propose fixes where possible.
 Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
 **Context7 focus for this agent:**
-- Verify that reviewed code uses library APIs correctly (correct method signatures, proper error handling, non-deprecated usage)
+- Verify that reviewed code uses library APIs with valid method signatures, structured error handling, and non-deprecated usage
 
 **Web research focus for this agent:**
 - Known vulnerability patterns and security advisories when reviewing security-sensitive code (auth flows, cryptographic operations)
@@ -129,6 +140,17 @@ Example in a review finding:
 
 Apply this format whenever the review verdict is non-obvious, when downgrading or upgrading severity, or when recommending a specific fix over alternatives.
 
+## Review Loop Termination Conditions
+
+This agent participates in the Phase 3 review loop (see `hatch3r-agent-orchestration`). The loop terminates when any of these conditions is met:
+
+1. **Clean verdict** -- 0 Critical + 0 Warning findings. The loop exits successfully, followed by a confirmation pass for fix-driven regressions.
+2. **Design objection** -- Verdict is `DESIGN_OBJECTION`. The loop exits immediately without fixer iteration. The objection and alternative approaches are surfaced to the user for an architectural decision.
+3. **Max iterations reached** -- After 3 review-fix cycles (default, configurable up to 10), the loop exits with status UNRESOLVED. Remaining findings are surfaced to the user.
+4. **Manual termination** -- The orchestrator or user explicitly halts the loop.
+
+Accurate severity classification directly affects loop termination. Over-classifying findings as Critical or Warning when they should be Suggestions causes unnecessary fix-review iterations. Under-classifying causes real issues to slip through. Use structured reasoning (above) when severity is non-obvious.
+
 ## Boundaries
 
 - **Always:** Check privacy invariants, verify tests exist, review security implications, use the platform CLI for PR/issue reads

package/agents/hatch3r-security-auditor.md

@@ -4,6 +4,7 @@ description: Security analyst who audits database rules, cloud functions, event
 protected: true
 model: standard
 tags: [review, security]
+quality_charter: agents/shared/quality-charter.md
 ---
 You are an expert security analyst for the project.
 
@@ -56,6 +57,16 @@ Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hie
 - Latest CVEs, security advisories, OWASP Top 10, CWE references, and NIST guidelines for classifying findings
 - Known exploit techniques, attack patterns, and security hardening best practices for the application's technology stack
 
+## Confidence Expression
+
+Rate every security finding, vulnerability assessment, and fix suggestion as **high**, **medium**, or **low** confidence per the quality charter (`agents/shared/quality-charter.md`):
+
+- **High:** Verified against current code and security rules — you traced the auth flow, confirmed the vulnerability exists, and validated the exploit path.
+- **Medium:** Based on established security patterns and OWASP guidelines but not fully exploited or tested. Likely a real vulnerability but could be mitigated by other controls not visible in the audited scope.
+- **Low:** Best professional judgment based on code patterns — the threat model is unclear or the finding depends on runtime configuration. Recommend security team review before prioritizing.
+
+Include confidence in the output: each finding row and the overall **Status** should state their confidence level.
+
 ## Sub-Agent Delegation
 
 When auditing a large application with multiple modules:
@@ -99,6 +110,15 @@ When auditing a large application with multiple modules:
 - (deferred audits, areas needing deeper investigation)
 ```
 
+## Error Handling Security Audit
+
+In addition to the 8 security domains above, audit error handling for security implications:
+
+- **Information leakage in errors.** Verify that error responses do not include stack traces, internal file paths, database query fragments, or dependency version numbers. Reference `hatch3r-code-standards` error boundary patterns.
+- **Error-based authentication bypass.** Check that authentication/authorization failures return generic error messages. Distinct error messages for "user not found" vs. "wrong password" enable account enumeration.
+- **Fail-open conditions.** Verify that exception handlers in authorization paths default to deny (fail-closed). A catch block that returns `true` or allows access on error is a Critical finding.
+- **Rate limiting on error paths.** Verify that repeated failed authentication attempts, validation errors, and resource-not-found responses are rate-limited to prevent brute-force and enumeration attacks.
+
 ## Boundaries
 
 - **Always:** Test both allow and deny cases, verify invariants, check for secret leakage, validate input sanitization, use the platform CLI for issue/code reads

package/agents/hatch3r-test-writer.md

@@ -4,6 +4,7 @@ description: QA engineer who writes deterministic, isolated tests. Covers unit,
 model: standard
 protected: true
 tags: [core, review]
+quality_charter: agents/shared/quality-charter.md
 ---
 You are an expert QA engineer for the project.
 
@@ -62,6 +63,16 @@ Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hie
 - Testing best practices for specific scenarios (race conditions, WebSocket handlers, file uploads, streaming responses)
 - Security testing techniques (injection test patterns, auth bypass test cases) and known flaky test patterns
 
+## Confidence Expression
+
+Rate every recommendation, coverage assessment, and test design decision as **high**, **medium**, or **low** confidence per the quality charter (`agents/shared/quality-charter.md`):
+
+- **High:** Verified against current code — you read the source, traced the logic, and confirmed the test covers the actual 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 relying on this coverage assessment.
+
+Include confidence in the output: the **Status** line and any coverage gap assessments should state their confidence level. When proposing test strategies for complex or unfamiliar code, explicitly note lower confidence.
+
 ## Output Format
 
 ```
@@ -98,6 +109,19 @@ Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hie
 - (suggested refactors to improve testability, coverage gaps remaining)
 ```
 
+## Review Loop Awareness
+
+This agent runs in Phase 4, after the Phase 3 review loop has reached a clean verdict or terminated at max iterations. If the review loop exited with unresolved findings, the orchestrator may still invoke this agent for test coverage. Be aware that code may contain known issues flagged during review -- focus on writing tests for the implemented behavior, not on fixing code (that is the fixer agent's responsibility). If new test failures reveal issues not caught in review, report them in the Issues Encountered section.
+
+## Error Path Testing Requirements
+
+When writing tests for new or modified code, cover error paths proportionally to happy paths:
+
+- **Every function that can fail** (returns Result, throws, calls async operations) must have at least one test for the failure case.
+- **Error messages must be tested.** Verify that error messages contain actionable information (not just "something went wrong"). Test that error codes, status codes, and structured error fields are correct.
+- **Boundary conditions.** Test null/undefined inputs, empty collections, maximum-length inputs, and type boundary values (0, -1, MAX_SAFE_INTEGER) for functions that accept numeric or string parameters.
+- **Async error handling.** For async functions, test both rejected promises and thrown errors within async flows. Verify that errors propagate to callers with the expected error type and message.
+
 ## Boundaries
 
 - **Always:** Write tests to `tests/`, run tests before submitting, verify edge cases, check invariants from specs, use the platform CLI for issue reads

package/agents/modes/architecture.md

@@ -3,6 +3,7 @@ id: researcher-mode-architecture
 type: mode
 description: Design the architectural approach with data model changes, API contracts, and component design.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `architecture`
 

package/agents/modes/boundary-analysis.md

@@ -3,10 +3,11 @@ id: researcher-mode-boundary-analysis
 type: mode
 description: Map integration boundaries, external dependencies, and data flow seams for test targeting.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `boundary-analysis`
 
-Map integration boundaries, external dependencies, data flow boundaries, and event chains to identify where integration and contract tests are most needed. Used by `hatch3r-test-plan` to ensure test coverage at system seams.
+Map integration boundaries, external dependencies, data flow boundaries, and event chains to identify where integration and contract tests are most needed. Used by `hatch3r-test-plan` to target test coverage at system seams.
 
 **Output structure:**
 

package/agents/modes/codebase-impact.md

@@ -3,6 +3,7 @@ id: researcher-mode-codebase-impact
 type: mode
 description: Analyze current codebase to understand what exists in the areas the subject touches.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `codebase-impact`
 

package/agents/modes/complexity-risk.md

@@ -3,6 +3,7 @@ id: researcher-mode-complexity-risk
 type: mode
 description: Identify code complexity hotspots and mutation-prone areas for test prioritization.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `complexity-risk`
 

package/agents/modes/coverage-analysis.md

@@ -3,6 +3,7 @@ id: researcher-mode-coverage-analysis
 type: mode
 description: Map existing test coverage, identify gaps, and surface critical untested paths.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `coverage-analysis`
 

package/agents/modes/current-state.md

@@ -3,6 +3,7 @@ id: researcher-mode-current-state
 type: mode
 description: Map the current state of code being analyzed — complexity, coupling, cohesion, coverage.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `current-state`
 

package/agents/modes/feature-design.md

@@ -3,6 +3,7 @@ id: researcher-mode-feature-design
 type: mode
 description: Break the subject down into implementable sub-tasks with user stories and acceptance criteria.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `feature-design`
 

package/agents/modes/impact-analysis.md

@@ -3,6 +3,7 @@ id: researcher-mode-impact-analysis
 type: mode
 description: Map the blast radius of an issue across flows, modules, data, and users.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `impact-analysis`
 

package/agents/modes/library-docs.md

@@ -3,6 +3,7 @@ id: researcher-mode-library-docs
 type: mode
 description: Look up current API documentation for specific libraries via Context7 MCP.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `library-docs`
 
@@ -24,7 +25,7 @@ Look up current API documentation for specific libraries or frameworks using Con
 | {API} | {signature or usage pattern} | {relevant constraints, deprecations, or gotchas} |
 
 ### Key Patterns
-- {pattern}: {how to use it correctly}
+- {pattern}: {usage example with required parameters and expected output}
 
 ### Breaking Changes / Deprecations
 - {item}: {migration path}

package/agents/modes/migration-path.md

@@ -3,6 +3,7 @@ id: researcher-mode-migration-path
 type: mode
 description: Design a phased execution plan with safe ordering and rollback points.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `migration-path`
 

package/agents/modes/prior-art.md

@@ -3,6 +3,7 @@ id: researcher-mode-prior-art
 type: mode
 description: Research best practices, known issues, and ecosystem trends via web search.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `prior-art`
 

package/agents/modes/refactoring-strategy.md

@@ -3,6 +3,7 @@ id: researcher-mode-refactoring-strategy
 type: mode
 description: Design the refactoring approach with transformations, invariants, and patterns.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `refactoring-strategy`
 

package/agents/modes/regression.md

@@ -3,6 +3,7 @@ id: researcher-mode-regression
 type: mode
 description: Investigate when an issue was introduced by analyzing git history and changes.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `regression`
 

package/agents/modes/requirements-elicitation.md

@@ -3,6 +3,7 @@ id: researcher-mode-requirements-elicitation
 type: mode
 description: Detect ambiguities and missing requirements, generate structured questions across 10 dimensions.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `requirements-elicitation`
 

package/agents/modes/risk-assessment.md

@@ -3,6 +3,7 @@ id: researcher-mode-risk-assessment
 type: mode
 description: Identify risks, security implications, performance concerns, and breaking changes.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `risk-assessment`
 

package/agents/modes/risk-prioritization.md

@@ -3,6 +3,7 @@ id: researcher-mode-risk-prioritization
 type: mode
 description: Risk-ranked prioritization of testing effort by business impact and coverage.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `risk-prioritization`
 

package/agents/modes/root-cause.md

@@ -3,6 +3,7 @@ id: researcher-mode-root-cause
 type: mode
 description: Analyze the codebase for candidate root causes using static analysis patterns.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `root-cause`
 

package/agents/modes/similar-implementation.md

@@ -3,10 +3,11 @@ id: researcher-mode-similar-implementation
 type: mode
 description: Search the codebase for analogous features and extract implementation conventions.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `similar-implementation`
 
-Search the codebase for analogous features, components, or modules and extract their implementation conventions as a reference for the implementer. The goal is to ensure new code follows established patterns rather than inventing new approaches.
+Search the codebase for analogous features, components, or modules and extract their implementation conventions as a reference for the implementer. The goal is that new code follows established patterns rather than inventing new approaches.
 
 **Protocol:**
 

package/agents/modes/symptom-trace.md

@@ -3,6 +3,7 @@ id: researcher-mode-symptom-trace
 type: mode
 description: Trace reported symptoms through the codebase to find divergence points.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `symptom-trace`
 

package/agents/modes/test-pattern.md

@@ -3,10 +3,11 @@ id: researcher-mode-test-pattern
 type: mode
 description: Extract existing test conventions, framework usage, mock patterns, and helper libraries.
 parent: hatch3r-researcher
+quality_charter: agents/shared/quality-charter.md
 ---
 ### Mode: `test-pattern`
 
-Extract existing test conventions, framework usage, mock patterns, and helper libraries to ensure new tests follow established patterns. Used by `hatch3r-test-plan` to align the test strategy with the project's existing test infrastructure.
+Extract existing test conventions, framework usage, mock patterns, and helper libraries so new tests follow established patterns. Used by `hatch3r-test-plan` to align the test strategy with the project's existing test infrastructure.
 
 **Output structure:**
 

package/agents/shared/external-knowledge.md

@@ -30,3 +30,13 @@ Use web search when Context7 does not cover the topic, or for information that c
   - **GitHub:** GitHub Security Advisories, Dependabot alerts
   - **Azure DevOps:** Microsoft Defender for DevOps, WhiteSource/Mend
   - **GitLab:** GitLab Dependency Scanning, Advisory Database
+
+## When NOT to Use External Knowledge
+
+Skip external knowledge lookups when:
+
+- The answer is available in project documentation or codebase (tiers 1-2 of the hierarchy). Re-reading a local spec is faster and more accurate than a web search.
+- The question is about project-specific conventions (naming, file structure, state management). These are defined in local rules and learnings, not external sources.
+- The information is not time-sensitive and the agent's training data is sufficient (basic language features, well-established patterns like REST, SQL, HTTP status codes).
+
+Unnecessary external lookups waste tokens and introduce latency. Follow the hierarchy strictly: only escalate to the next tier when the current tier cannot answer the question.

package/agents/shared/quality-charter.md

@@ -76,3 +76,21 @@ Where possible, state acceptance criteria in measurable, verifiable terms:
 - **Not measurable:** "Make the app faster."
 
 When a recommendation cannot be quantified (e.g., "improve code readability"), provide a concrete before/after example instead.
+
+### 8. Escalate Ambiguity Early
+
+When encountering conflicting requirements, unclear acceptance criteria, or missing context:
+
+- **Stop and ask** rather than making assumptions that could cascade through later pipeline phases.
+- State what is ambiguous, what the possible interpretations are, and which interpretation you would choose if forced to proceed.
+- Log the ambiguity in the structured output (e.g., `researchGaps`, `Issues encountered`) so downstream agents inherit awareness.
+
+Ambiguity detected in Phase 1 costs minutes to resolve; ambiguity discovered in Phase 3 costs an entire review-fix cycle.
+
+### 9. Preserve Contracts
+
+When modifying code that is consumed by other modules, agents, or external systems:
+
+- Verify existing consumers before changing function signatures, type shapes, event schemas, or API responses.
+- If a contract change is necessary, document it explicitly in the structured output and flag for reviewer attention.
+- Prefer additive changes (new optional fields, overloaded signatures) over breaking changes.

package/checks/README.md

@@ -40,6 +40,7 @@ Agents (particularly `hatch3r-reviewer`) reference checks during code review:
 | `security` | Vulnerability patterns, input validation, secrets |
 | `testing` | Test coverage, test quality, regression tests |
 | `performance` | Bundle size, render performance, memory usage, network optimization, database queries |
+| `accessibility` | WCAG compliance, semantic HTML, keyboard navigation, screen reader support, inclusive design |
 
 ## Adding New Checks
 

package/checks/accessibility.md

@@ -0,0 +1,55 @@
+---
+id: accessibility
+type: check
+description: Accessibility review criteria covering WCAG compliance, semantic HTML, keyboard navigation, screen reader support, and inclusive design patterns
+---
+# Accessibility Check
+
+Review criteria for evaluating accessibility in pull requests.
+
+## Semantic HTML and ARIA
+
+- `[CRITICAL]` Interactive elements use native HTML controls (`<button>`, `<a>`, `<input>`, `<select>`) rather than styled `<div>` or `<span>` elements with click handlers.
+- `[CRITICAL]` Custom interactive components have appropriate ARIA roles, states, and properties (`role`, `aria-expanded`, `aria-selected`, `aria-disabled`, etc.).
+- `[CRITICAL]` Images have meaningful `alt` text, or `alt=""` and `aria-hidden="true"` if purely decorative.
+- `[CRITICAL]` Form inputs have associated `<label>` elements (via `for`/`id` or nesting). No input relies solely on placeholder text for identification.
+- `[RECOMMENDED]` Headings follow a logical hierarchy (`h1` > `h2` > `h3`) without skipping levels.
+- `[RECOMMENDED]` Landmark regions (`<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`) are used to structure the page.
+
+## Keyboard Navigation
+
+- `[CRITICAL]` All interactive elements are reachable and operable via keyboard (Tab, Shift+Tab, Enter, Space, Arrow keys as appropriate).
+- `[CRITICAL]` Focus is not trapped in a component unless it is a modal dialog with an explicit close mechanism.
+- `[CRITICAL]` Custom keyboard shortcuts do not conflict with screen reader or browser shortcuts.
+- `[RECOMMENDED]` Focus order follows the visual reading order (logical DOM order). No use of positive `tabindex` values.
+- `[RECOMMENDED]` Focus indicators are visible and meet contrast requirements. No `outline: none` without a custom visible focus style.
+
+## Visual Design and Color
+
+- `[CRITICAL]` Text meets WCAG 2.1 AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold).
+- `[CRITICAL]` Information is not conveyed by color alone. Status indicators, errors, and required fields use icons, text, or patterns in addition to color.
+- `[CRITICAL]` UI remains functional and readable at 200% browser zoom without horizontal scrolling or content clipping.
+- `[RECOMMENDED]` Touch targets are at least 44x44 CSS pixels for mobile interfaces.
+- `[RECOMMENDED]` Animations respect the `prefers-reduced-motion` media query — reduce or remove motion for users who have requested it.
+
+## Screen Reader Support
+
+- `[CRITICAL]` Dynamic content updates (toast notifications, live regions, inline validation) use `aria-live` regions (`polite` or `assertive`) to announce changes.
+- `[CRITICAL]` Modal dialogs trap focus, announce their title via `aria-labelledby`, and return focus to the trigger element on close.
+- `[CRITICAL]` Icon-only buttons and links have accessible names via `aria-label`, `aria-labelledby`, or visually hidden text.
+- `[RECOMMENDED]` Tables use `<th>` with `scope` attributes for column and row headers. Complex tables use `id`/`headers` associations.
+- `[RECOMMENDED]` Loading states are announced to screen readers, not just shown visually (e.g., `aria-busy="true"` on the updating region).
+
+## Content and Language
+
+- `[CRITICAL]` The page has a `lang` attribute on the `<html>` element matching the content language.
+- `[CRITICAL]` Error messages are descriptive, identify the field in error, and suggest how to fix the problem.
+- `[RECOMMENDED]` Link text is descriptive and makes sense out of context. Avoid generic "click here" or "read more" links.
+- `[RECOMMENDED]` Abbreviations and acronyms are expanded on first use or wrapped in `<abbr>` with a `title` attribute.
+
+## Media and Embedded Content
+
+- `[CRITICAL]` Video content has captions. Audio content has transcripts.
+- `[CRITICAL]` Auto-playing media can be paused or stopped by the user. No content flashes more than 3 times per second.
+- `[RECOMMENDED]` Audio descriptions are provided for video content where visual information is not conveyed through the audio track.
+- `[RECOMMENDED]` Embedded content (iframes, embeds) has a descriptive `title` attribute.

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

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-azure-devops
 type: command
 description: Azure DevOps-specific platform procedures for board-pickup. Covers az CLI commands for work item listing, status updates, collision detection, PR creation, and state transitions.
 tags: [board, team, azure-devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Azure DevOps Platform Details
 

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

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-delegation-multi
 type: command
 description: Multi-issue sub-agent delegation protocols for board-pickup Steps 6b (epics) and 6c (batch). Covers level-by-level parallel execution, shared context, and quality pipelines.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Multi-Issue Delegation (Steps 6b, 6c)
 
@@ -163,7 +164,11 @@ For each dependency level, starting at Level 1:
 After all implementer sub-agents complete across all levels:
 
 1. Run a combined quality check across all changes from all issues.
-2. Resolve any cross-issue file conflicts or integration issues.
+2. **File conflict resolution:** When parallel sub-agents modify the same file, apply this resolution protocol:
+   - **Disjoint regions:** Accept both changes (non-overlapping edits to different functions/sections).
+   - **Overlapping regions:** If changes touch the same lines or function, merge manually using the sub-agent that modified the larger scope as the base, then apply the smaller-scope change on top. Run tests after merge.
+   - **Semantic conflicts:** If two sub-agents make contradictory changes to the same interface, type, or contract, halt and surface both changes to the user with the conflict description. Do not auto-resolve semantic conflicts.
+   - **Prevention:** Step 3 (collision detection) should move file-overlapping issues to sequential dependency levels. Conflicts at this stage indicate a missed overlap in Step 3.4.
 3. Verify no regressions between parallel sub-agent outputs.
 
 ### 6c.5. Post-Implementation Quality Pipeline

package/commands/board/pickup-delegation.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-delegation
 type: command
 description: Single-issue sub-agent delegation protocol for board-pickup Step 6a. Covers research, implementation, and quality pipeline for standalone issues.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Single-Issue Delegation (Step 6a)
 

package/commands/board/pickup-github.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-github
 type: command
 description: GitHub-specific platform procedures for board-pickup. Covers gh CLI commands for issue listing, status updates, collision detection, PR creation, and label transitions.
 tags: [board, team, github]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — GitHub Platform Details
 

package/commands/board/pickup-gitlab.md

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-gitlab
 type: command
 description: GitLab-specific platform procedures for board-pickup. Covers glab CLI commands for issue listing, status updates, collision detection, MR creation, and label transitions.
 tags: [board, team, gitlab]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — GitLab Platform Details
 

package/commands/board/pickup-modes.md

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

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

@@ -3,6 +3,7 @@ id: hatch3r-board-pickup-post-impl
 type: command
 description: Post-implementation steps for board-pickup (Steps 7-10). Covers quality verification, commit/push, PR/MR creation, label transitions, board sync, dashboard refresh, reconciliation, and learnings capture.
 tags: [board, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Pickup — Post-Implementation Steps (7-10)
 
@@ -87,7 +88,7 @@ Follow the project's PR/MR creation skill or conventions:
 2. Remind user `Closes #N` auto-closes on merge.
 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.
+   - **Azure DevOps:** Verify the "Complete linked work items after merging" checkbox is checked during PR completion. State transitions to "Closed" only when this option is selected.
    - **GitLab:** Labels are NOT updated on auto-close. `status::in-review` remains. Consider setting up a CI pipeline trigger on issue close events for automated cleanup.
    - If automation is not configured, `board-groom` with the `health-fix` action will detect and fix the drift during the next grooming session.
 4. If partial:

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

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-azure-devops
 type: shared-context
 description: Azure DevOps-specific platform details for board shared context. Covers Work Items, Azure Boards, az CLI, and MCP tools.
 tags: [board, team, azure-devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference — Azure DevOps Platform Details
 

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

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

package/commands/board/shared-github.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-github
 type: shared-context
 description: GitHub-specific platform details for board shared context. Covers GitHub Issues, Projects V2, gh CLI, and MCP tools.
 tags: [board, team, github]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference — GitHub Platform Details
 

package/commands/board/shared-gitlab.md

@@ -3,6 +3,7 @@ id: hatch3r-board-shared-gitlab
 type: shared-context
 description: GitLab-specific platform details for board shared context. Covers GitLab Issues, Issue Boards, glab CLI, and label-based sync.
 tags: [board, team, gitlab]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Board Shared Reference — GitLab Platform Details
 

package/commands/hatch3r-agent-customize.md

@@ -3,6 +3,7 @@ id: hatch3r-agent-customize
 type: command
 description: Configure per-agent customization including model overrides, description changes, and project-specific markdown instructions
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-api-spec.md

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

package/commands/hatch3r-benchmark.md

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