hatch3r 1.3.0 → 1.4.0

package/README.md

@@ -44,7 +44,7 @@ That's it. hatch3r detects your repo, asks about your project context (greenfiel
 | **Kiro** | `.kiro/steering/`, `.kiro/settings/mcp.json` |
 | **Goose** | `.goosehints` |
 | **Zed** | `.rules` |
-| **Amazon Q** | `.amazonq/rules/`, `.amazonq/settings.json` |
+| **Amazon Q** | `.amazonq/rules/`, `.amazonq/mcp.json` |
 
 Platform is auto-detected from your git remote during `hatch3r init`. All board commands, agents, rules, and skills adapt to your selected platform.
 
@@ -231,6 +231,7 @@ hatch3r is also available as a [Cursor plugin](https://cursor.com/marketplace).
 
 Full documentation is available at [docs.hatch3r.com](https://docs.hatch3r.com).
 
+- [Vision](governance/VISION.md) -- Framework north-star vision and principles
 - [MCP Setup](https://docs.hatch3r.com/docs/guides/mcp-setup) -- Connecting MCP servers and managing secrets
 - [Adapter Capability Matrix](https://docs.hatch3r.com/docs/reference/adapter-capability-matrix) -- Per-tool support and output paths
 - [Agent Teams](https://docs.hatch3r.com/docs/guides/agent-teams) -- Multi-agent team coordination and delegation patterns

package/agents/hatch3r-a11y-auditor.md

@@ -56,19 +56,15 @@ Follow the full accessibility standards defined in `.agents/rules/hatch3r-access
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- ARIA patterns and component accessibility APIs for the project's UI framework (React ARIA, Radix UI, Headless UI, Vuetify a11y props)
+- Accessibility testing library APIs (axe-core, jest-axe, Playwright accessibility snapshots) for audit automation
 
-- Use `resolve-library-id` then `query-docs` to look up correct ARIA patterns and component accessibility APIs for the project's UI framework (e.g., React ARIA, Radix UI, Headless UI, Vuetify a11y props).
-- Verify that components use the correct accessibility attributes by checking the framework's current documentation rather than relying on potentially outdated training data.
-- Look up accessibility testing library APIs (axe-core, jest-axe, Playwright accessibility snapshots) for audit automation.
-
-## Web Research Usage
-
-- Use web search for current WCAG success criteria interpretation and techniques when auditing specific patterns (e.g., combobox, carousel, data table, drag-and-drop).
-- Use web search for WAI-ARIA Authoring Practices and design pattern guidance for complex interactive components.
-- Use web search for screen reader compatibility notes across assistive technologies (NVDA, JAWS, VoiceOver) when findings involve cross-AT support.
+**Web research focus for this agent:**
+- Current WCAG success criteria interpretation, WAI-ARIA Authoring Practices, and design pattern guidance for complex interactive components
+- Screen reader compatibility notes across assistive technologies (NVDA, JAWS, VoiceOver)
 
 ## Sub-Agent Delegation
 

package/agents/hatch3r-architect.md

@@ -84,19 +84,15 @@ For decisions that warrant long-term documentation:
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- API surfaces for frameworks, ORMs, message brokers, and infrastructure libraries involved in architectural decisions
+- API contract assumptions (connection pooling, TTL semantics, acknowledgement modes) before recommending architecture
 
-- Use `resolve-library-id` then `query-docs` to look up current API surfaces for frameworks, ORMs, message brokers, and infrastructure libraries involved in architectural decisions.
-- Verify API contract assumptions (e.g., database driver connection pooling, cache client TTL semantics, queue library acknowledgement modes) before recommending architecture.
-- Prefer Context7 over guessing API capabilities or relying on potentially outdated training data when evaluating technology trade-offs.
-
-## Web Research Usage
-
-- Use web search for architecture pattern references, scalability case studies, and performance benchmarks when evaluating trade-offs between alternatives.
-- Use web search for current best practices and known pitfalls for specific technology choices (e.g., Redis vs Memcached for session storage, WebSocket vs SSE for real-time).
-- Use web search for cloud service limits, pricing models, and SLA guarantees when infrastructure decisions affect the architecture.
+**Web research focus for this agent:**
+- Architecture pattern references, scalability case studies, and performance benchmarks for trade-off evaluation
+- Cloud service limits, pricing models, and SLA guarantees when infrastructure decisions affect the architecture
 
 ## Output Format
 

package/agents/hatch3r-ci-watcher.md

@@ -61,18 +61,15 @@ Use the platform CLI to interact with CI runs (check `platform` in `.agents/hatc
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- CI action/task documentation when failures involve misconfigured actions or outdated action APIs
+- Testing framework and build tool docs to understand failure messages from tool configuration issues
 
-- Use `resolve-library-id` then `query-docs` to look up CI action/task documentation when failures involve misconfigured actions or outdated action APIs.
-- Look up testing framework and build tool docs via Context7 to understand failure messages originating from tool configuration issues (e.g., Vitest config options, TypeScript compiler flags, bundler settings).
-
-## Web Research Usage
-
-- Use web search for error messages that are unfamiliar or not found in local logs — CI-specific errors often have known solutions in issue trackers and forums.
-- Use web search for changelogs and breaking changes when a CI failure coincides with a dependency or action version update.
-- Use web search for known CI platform issues (e.g., GitHub Actions runner outages, Azure Pipelines agent pool problems) when failures appear infrastructure-related rather than code-related.
+**Web research focus for this agent:**
+- Unfamiliar CI-specific error messages, changelogs, and breaking changes coinciding with dependency or action version updates
+- Known CI platform issues (runner outages, agent pool problems) when failures appear infrastructure-related
 
 ## Output Format
 

package/agents/hatch3r-context-rules.md

@@ -37,15 +37,13 @@ Adapt to the project's actual directory structure and rule definitions.
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Framework convention accuracy when rules reference specific library patterns (React hook rules, Vue composition API patterns, Angular module conventions)
 
-- Use `resolve-library-id` then `query-docs` to verify framework convention accuracy when rules reference specific library patterns (e.g., React hook rules, Vue composition API patterns, Angular module conventions).
-
-## Web Research Usage
-
-- Use web search for current coding standard updates when rules reference evolving standards (e.g., updated ESLint recommended configs, new TypeScript strict mode behaviors).
+**Web research focus for this agent:**
+- Current coding standard updates when rules reference evolving standards (updated ESLint recommended configs, new TypeScript strict mode behaviors)
 
 ## Output Format
 

package/agents/hatch3r-dependency-auditor.md

@@ -82,21 +82,15 @@ When multiple vulnerabilities exist, prioritize by: exploitability in the projec
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Migration guides and breaking changes documentation for packages being upgraded (especially major version bumps)
+- Current API surface of packages before recommending upgrades; alternative package APIs when evaluating lighter replacements
 
-- Use `resolve-library-id` then `query-docs` to look up migration guides and breaking changes documentation for packages being upgraded (especially major version bumps).
-- Look up alternative package APIs via Context7 when evaluating lighter replacements for heavy dependencies.
-- Check current API surface of packages before recommending upgrades — verify that the project's usage patterns are still supported in the target version.
-- Prefer Context7 over guessing whether an API is deprecated or changed in a newer version.
-
-## Web Research Usage
-
-Use web research for: new CVE details (NVD, platform security advisories), package maintenance status, alternative package evaluation, current supply chain attack patterns. Security advisory sources by platform:
-- **GitHub:** GitHub Security Advisories, Dependabot alerts
-- **Azure DevOps:** Microsoft Defender for DevOps, WhiteSource/Mend
-- **GitLab:** GitLab Dependency Scanning, Advisory Database
+**Web research focus for this agent:**
+- New CVE details (NVD, platform security advisories), package maintenance status, alternative package evaluation
+- Current supply chain attack patterns and security advisory sources
 
 ## Output Format
 

package/agents/hatch3r-devops.md

@@ -74,21 +74,15 @@ Common infrastructure files:
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- IaC tool APIs (Terraform providers, Pulumi resources, CloudFormation resource types) for correct resource configuration
+- CI action/task APIs (GitHub Actions, Azure Pipelines tasks, GitLab CI components) and container tool docs (Docker, Kubernetes)
 
-- Use `resolve-library-id` then `query-docs` to look up IaC tool APIs (Terraform providers, Pulumi resources, CloudFormation resource types) for correct resource configuration.
-- Look up CI action/task APIs (GitHub Actions, Azure Pipelines tasks, GitLab CI components) via Context7 to use current input/output schemas.
-- Check container tool docs (Docker, Docker Compose, Kubernetes) for correct configuration syntax and available options.
-- Prefer Context7 over guessing IaC resource properties or CI action inputs — incorrect infrastructure config can cause outages.
-
-## Web Research Usage
-
-- Use web search for cloud service limits, quotas, pricing, and SLA guarantees when infrastructure decisions affect cost or availability.
-- Use web search for security hardening guides specific to the target cloud provider and deployment environment.
-- Use web search for known issues and migration guides when upgrading CI actions, IaC providers, or container base images.
-- Use web search for deployment strategy best practices and failure mode analysis for the project's hosting platform.
+**Web research focus for this agent:**
+- Cloud service limits, quotas, pricing, and SLA guarantees when infrastructure decisions affect cost or availability
+- Security hardening guides, deployment strategy best practices, and known issues when upgrading CI actions, IaC providers, or container base images
 
 ## Output Format
 

package/agents/hatch3r-docs-writer.md

@@ -37,19 +37,15 @@ You are an expert technical writer for the project.
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- API signatures, configuration options, and usage patterns when documenting library or framework integrations
+- Current library docs to ensure code examples in documentation use non-deprecated APIs
 
-- Use `resolve-library-id` then `query-docs` to verify API signatures, configuration options, and usage patterns when documenting library or framework integrations.
-- Prefer Context7 over training data when writing API reference docs — incorrect signatures in documentation are worse than no documentation.
-- Look up current library docs to ensure code examples in documentation use non-deprecated APIs.
-
-## Web Research Usage
-
-- Use web search for current industry documentation standards (e.g., Diátaxis framework, ADR conventions, API documentation best practices) when structuring new documentation.
-- Use web search for external standards or specifications referenced in project docs (e.g., OAuth 2.1, OpenAPI 3.x, WCAG criteria) to ensure accuracy.
-- Use web search for changelog and migration guide references when documenting version upgrades or breaking changes.
+**Web research focus for this agent:**
+- Current industry documentation standards (Diataxis framework, ADR conventions, API documentation best practices)
+- External standards or specifications referenced in project docs (OAuth 2.1, OpenAPI 3.x, WCAG criteria) for accuracy
 
 ## Output Format
 

package/agents/hatch3r-fixer.md

@@ -116,15 +116,9 @@ Use the project's configured platform CLI (check `platform` in `.agents/hatch.js
   - **GitLab:** `glab issue view`, `glab issue list --search`, `glab search`
 - **Fallback** to platform MCP only for operations not covered by the CLI (e.g., sub-issue management, project field mutations).
 
-## Context7 MCP Usage
+## External Knowledge
 
-- Use `resolve-library-id` then `query-docs` to look up current API patterns for frameworks and external dependencies.
-- Prefer Context7 over guessing API signatures or relying on potentially outdated training data.
-
-## Web Research Usage
-
-- Use web search for latest CVEs, security advisories, breaking changes, or novel error messages.
-- Use web search for current best practices when Context7 and local docs are insufficient.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
 ## Boundaries
 

package/agents/hatch3r-implementer.md

@@ -166,15 +166,9 @@ Use the project's configured platform CLI (check `platform` in `.agents/hatch.js
 
 MCP server env vars use `${env:VAR_NAME}` syntax in mcp.json. These are expanded at runtime by the tool adapter. When referencing environment variables in MCP configuration, use this syntax rather than shell-style `$VAR` or `%VAR%` notation. The adapter reads the variable from the host environment at server startup.
 
-## Context7 MCP Usage
+## External Knowledge
 
-- Use `resolve-library-id` then `query-docs` to look up current API patterns for frameworks and external dependencies.
-- Prefer Context7 over guessing API signatures or relying on potentially outdated training data.
-
-## Web Research Usage
-
-- Use web search for latest CVEs, security advisories, breaking changes, or novel error messages.
-- Use web search for current best practices when Context7 and local docs are insufficient.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
 ## Structured Reasoning
 

package/agents/hatch3r-learnings-loader.md

@@ -192,15 +192,13 @@ The learnings integrity mechanism uses SHA-256 hashing for tamper detection, not
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Verify that learnings referencing specific library patterns or APIs are still current; flag potentially outdated learnings where library APIs have changed
 
-- Use `resolve-library-id` then `query-docs` to verify that learnings referencing specific library patterns or APIs are still current — flag potentially outdated learnings where library APIs have changed.
-
-## Web Research Usage
-
-- Use web search to check whether learnings referencing external tools, services, or standards are still current (e.g., deprecated APIs, changed best practices, sunset services).
+**Web research focus for this agent:**
+- Check whether learnings referencing external tools, services, or standards are still current (deprecated APIs, changed best practices, sunset services)
 
 ## Output Format
 

package/agents/hatch3r-lint-fixer.md

@@ -26,17 +26,15 @@ Follow the naming, sizing, and type-safety conventions defined in `.agents/rules
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- ESLint rule documentation when a lint error's correct fix is unclear (e.g., `@typescript-eslint/no-floating-promises`, `react-hooks/exhaustive-deps`)
+- TypeScript compiler option docs when fixing strict mode violations (e.g., `strictNullChecks`, `noUncheckedIndexedAccess`)
 
-- Use `resolve-library-id` then `query-docs` to look up ESLint rule documentation when a lint error's correct fix is unclear (e.g., `@typescript-eslint/no-floating-promises`, `react-hooks/exhaustive-deps`).
-- Look up TypeScript compiler option docs via Context7 when fixing strict mode violations that require understanding compiler behavior (e.g., `strictNullChecks`, `noUncheckedIndexedAccess`).
-
-## Web Research Usage
-
-- Use web search for correct fix patterns when encountering unfamiliar or project-specific lint rules (custom ESLint plugins, framework-specific linter rules).
-- Use web search for type-safe alternatives when replacing deprecated API patterns flagged by linters.
+**Web research focus for this agent:**
+- Correct fix patterns for unfamiliar or project-specific lint rules (custom ESLint plugins, framework-specific linter rules)
+- Type-safe alternatives when replacing deprecated API patterns flagged by linters
 
 ## Output Format
 

package/agents/hatch3r-perf-profiler.md

@@ -47,19 +47,15 @@ Adapt to project-defined budgets. Common targets:
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Bundler optimization options (Vite, webpack, esbuild, Rollup) for tree-shaking, code splitting, and chunk configuration
+- Profiling tool APIs (Lighthouse CI, web-vitals, clinic.js, 0x) and framework-specific performance APIs (React Profiler, Vue DevTools, Angular CDK)
 
-- Use `resolve-library-id` then `query-docs` to look up bundler optimization options (Vite, webpack, esbuild, Rollup) for tree-shaking, code splitting, and chunk configuration.
-- Look up profiling tool APIs and configuration (Lighthouse CI, web-vitals, clinic.js, 0x) to verify correct measurement methodology.
-- Check framework-specific performance APIs (React Profiler, Vue DevTools performance tab, Angular CDK virtual scrolling) for optimization guidance.
-
-## Web Research Usage
-
-- Use web search for current Core Web Vitals thresholds and measurement methodology when auditing user-facing performance.
-- Use web search for optimization techniques specific to detected bottlenecks (e.g., image format benchmarks, font loading strategies, SSR vs SSG trade-offs).
-- Use web search for performance benchmarks and comparison data when recommending alternative libraries or approaches to replace heavy dependencies.
+**Web research focus for this agent:**
+- Current Core Web Vitals thresholds and measurement methodology for user-facing performance audits
+- Optimization techniques for detected bottlenecks and performance benchmarks when recommending alternative libraries
 
 ## Sub-Agent Delegation
 

package/agents/hatch3r-researcher.md

@@ -989,17 +989,15 @@ Use the project's configured platform CLI (check `platform` in `.agents/hatch.js
   - **GitLab:** `glab issue view`, `glab issue list --search`, `glab search`
 - **Fallback** to platform MCP only for operations not covered by the CLI (e.g., sub-issue management, project field mutations).
 
-## Context7 MCP Usage
+## External Knowledge
 
-- Use `resolve-library-id` then `query-docs` to look up current API patterns for frameworks and external dependencies.
-- Prefer Context7 over guessing API signatures or relying on potentially outdated training data.
-- The `library-docs` mode wraps this into a structured workflow, but any mode may use Context7 when external APIs are relevant.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Web Research Usage
+**Context7 focus for this agent:**
+- The `library-docs` mode wraps Context7 into a structured workflow, but any mode may use Context7 when external APIs are relevant
 
-- Use web search for latest CVEs, security advisories, breaking changes, or novel error messages.
-- Use web search for current best practices when Context7 and local docs are insufficient.
-- The `prior-art` mode wraps this into a structured workflow, but any mode may use web search when current information is needed.
+**Web research focus for this agent:**
+- The `prior-art` mode wraps web search into a structured workflow, but any mode may use web search when current information is needed
 
 ## Structured Reasoning
 

package/agents/hatch3r-reviewer.md

@@ -38,6 +38,7 @@ 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.
 
 ## Output Format
 
@@ -58,18 +59,14 @@ Include specific file paths and line references. Propose fixes where possible.
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Verify that reviewed code uses library APIs correctly (correct method signatures, proper error handling, non-deprecated usage)
 
-- Use `resolve-library-id` then `query-docs` to verify that reviewed code uses library APIs correctly (correct method signatures, proper error handling, non-deprecated usage).
-- When reviewing code that integrates with external libraries or frameworks, check Context7 for the current recommended patterns rather than relying on potentially outdated training data.
-
-## Web Research Usage
-
-- Use web search for known vulnerability patterns when reviewing security-sensitive code (auth flows, input handling, cryptographic operations).
-- Use web search for security advisories affecting dependencies used in the reviewed code.
-- Use web search for current best practices when the reviewed code uses patterns you are uncertain about (e.g., new framework features, evolving security standards).
+**Web research focus for this agent:**
+- Known vulnerability patterns and security advisories when reviewing security-sensitive code (auth flows, cryptographic operations)
+- Current best practices when reviewed code uses uncertain patterns (new framework features, evolving security standards)
 
 ## External Verification Signals
 

package/agents/hatch3r-security-auditor.md

@@ -46,20 +46,15 @@ Follow the security patterns defined in `.agents/rules/hatch3r-security-patterns
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Security library APIs (JWT verification, bcrypt, helmet, CSRF middleware, OAuth libraries) and correct auth/crypto usage
+- Framework-specific security middleware docs (Express helmet options, Next.js CSP config, Django security middleware)
 
-- Use `resolve-library-id` then `query-docs` to look up current API patterns for security libraries (JWT verification, bcrypt, helmet, CSRF middleware, OAuth libraries).
-- Verify correct usage of auth/crypto APIs in audited code — training data may reflect deprecated or insecure defaults.
-- Look up framework-specific security middleware docs (e.g., Express helmet options, Next.js CSP config, Django security middleware).
-
-## Web Research Usage
-
-- Use web search for latest CVEs and security advisories affecting dependencies found in the project (NVD, GitHub Security Advisories, platform-specific databases).
-- Use web search for current OWASP Top 10, CWE references, and NIST guidelines when classifying findings.
-- Use web search for known exploit techniques and attack patterns relevant to the application's technology stack.
-- Use web search for security hardening best practices when the codebase uses patterns not covered by local docs or Context7.
+**Web research focus for this agent:**
+- 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
 
 ## Sub-Agent Delegation
 

package/agents/hatch3r-test-writer.md

@@ -52,19 +52,15 @@ This interactive verification complements automated E2E test suites — use it t
 
 ## External Knowledge
 
-Follow the tooling hierarchy and platform CLI guidance defined in `agents/shared/external-knowledge.md`.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Testing framework APIs (Vitest, Jest, Playwright, Cypress, Testing Library), assertion libraries, and mocking utilities
+- Library-recommended testing patterns (React Testing Library queries, Playwright locators, Supertest assertion chains)
 
-- Use `resolve-library-id` then `query-docs` to look up current APIs for testing frameworks (Vitest, Jest, Playwright, Cypress, Testing Library) before writing tests.
-- Look up assertion library APIs, mocking utilities, and test runner configuration to use correct patterns rather than relying on potentially outdated training data.
-- When testing code that uses external libraries, query Context7 for the library's recommended testing patterns (e.g., React Testing Library queries, Playwright locators, Supertest assertion chains).
-
-## Web Research Usage
-
-- Use web search for testing best practices for specific scenarios (e.g., testing race conditions, WebSocket handlers, file uploads, streaming responses).
-- Use web search for known testing pitfalls and flaky test patterns in the project's testing framework.
-- Use web search for security testing techniques (e.g., injection test patterns, auth bypass test cases) when writing security-related tests.
+**Web research focus for this agent:**
+- 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
 
 ## Output Format
 

package/agents/shared/external-knowledge.md

@@ -9,3 +9,24 @@ Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). U
 - **GitHub:** `gh` CLI
 - **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
 - **GitLab:** `glab` CLI
+- **Fallback** to platform MCP only for operations not covered by the CLI (e.g., sub-issue management, project field mutations).
+
+## Context7 MCP Protocol
+
+Use `resolve-library-id` to find the library, then `query-docs` to retrieve current documentation. Apply this for any framework, library, or tool whose API surface may have changed since training data.
+
+- Prefer Context7 over guessing API signatures, configuration options, or behavioral details from potentially outdated training data.
+- Always verify: method names, parameter signatures, return types, and configuration keys before using them in code.
+- If Context7 returns no results, fall back to web research (below).
+
+## Web Research Protocol
+
+Use web search when Context7 does not cover the topic, or for information that changes frequently:
+
+- **Security:** Current CVE details (NVD), security advisories, supply chain attack patterns.
+- **Standards:** Current best practice guidance, specification updates, compliance requirements.
+- **Ecosystem:** Package maintenance status, alternative evaluations, community adoption signals.
+- **Platform-specific advisories** by platform:
+  - **GitHub:** GitHub Security Advisories, Dependabot alerts
+  - **Azure DevOps:** Microsoft Defender for DevOps, WhiteSource/Mend
+  - **GitLab:** GitLab Dependency Scanning, Advisory Database

package/agents/shared/quality-charter.md

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

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

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

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

@@ -80,6 +80,7 @@ For each dependency level, starting at Level 1:
    - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
    - Instruction to use GitHub MCP for issue reads, and follow the project's tooling hierarchy for external knowledge augmentation.
    - Explicit instruction: do NOT create branches, commits, or PRs.
+   - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
 
@@ -147,6 +148,7 @@ For each dependency level, starting at Level 1:
    - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
    - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
    - Explicit instruction: do NOT create branches, commits, or PRs.
+   - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
 
@@ -176,6 +178,7 @@ After all implementations complete, run the two-stage quality pipeline across th
    - **Reference conventions** from Step 6c.2 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the reviewer reports 0 Critical + 0 Warning findings.
+   After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
 5. If still not clean after 3 iterations, **ASK** the user how to proceed.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**