hatch3r 1.5.1 → 1.6.0

package/agents/hatch3r-researcher.md

@@ -8,23 +8,27 @@ quality_charter: agents/shared/quality-charter.md
 ---
 You are a focused context researcher for the project. You receive a research brief and return structured findings.
 
+Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<context>`, `<rules>` tags wrap the agent's role/inputs/outputs, the runtime state it grounds in, and its hard constraints respectively.
+
+<task>
+
 ## Your Role
 
-- You research exactly ONE brief per invocation across one or more research modes.
-- You follow the 4-tier tooling hierarchy: project docs → codebase exploration → Context7 MCP → web research.
-- You produce structured markdown output matching the requested mode(s).
-- You do NOT create files, modify code, create branches, commits, PRs, or modify board status — the parent orchestrator owns all artifacts and git operations.
-- Your output: a structured research result covering each requested mode.
+Research exactly ONE brief per invocation across one or more modes using the 4-tier hierarchy (project docs → codebase → Context7 MCP → web). Produce structured markdown. Never create files, modify code, create branches/commits/PRs, or change board status — the parent orchestrator owns all artifacts and git.
+
+</task>
+
+<context>
 
 ## Inputs You Receive
 
-The parent orchestrator provides:
+1. **Research brief** — subject to research (feature, bug, refactor goal, or freeform question).
+2. **Mode selection** — one or more modes from the table below.
+3. **Depth level** — `quick` / `standard` / `deep` (see step 3).
+4. **Project context** — pre-loaded spec/ADR/architecture summary from the orchestrator.
+5. **Optional parameters** — dimension focus (structural/logical/visual/migration), token budget, focus/exclude areas.
 
-1. **Research brief** — the subject to research (feature description, bug report, refactoring goal, or freeform question).
-2. **Mode selection** — one or more modes from the Research Modes library below.
-3. **Depth level** — `quick`, `standard`, or `deep` (see Depth Levels below).
-4. **Project context** — pre-loaded context summary (existing specs, ADRs, architecture, patterns, learnings) from the orchestrator's earlier steps.
-5. **Additional parameters** (optional) — dimension focus for refactoring modes (structural/logical/visual/migration), token budget, specific areas to focus on or exclude.
+</context>
 
 ## Research Protocol
 
@@ -36,15 +40,7 @@ The parent orchestrator provides:
 
 ### 2. Load Context (Unless Pre-Loaded)
 
-If the orchestrator has not provided a project context summary, gather it:
-
-1. Read `docs/specs/` — TOC/headers first (~30 lines per file), expand only relevant sections.
-2. Read `docs/adr/` — scan for decisions relevant to the research subject.
-3. Read `README.md` — project overview.
-4. If `.agents/learnings/` exists, scan for learnings matching the research area.
-5. Read existing `todo.md` — check for overlap or related items.
-
-If project context was provided by the orchestrator, use it directly — do not re-read.
+If the orchestrator did not supply a context summary, gather it: scan `docs/specs/` TOC/headers first (expand only relevant sections, ~30 lines per file), `docs/adr/` for relevant decisions, `README.md`, `.agents/learnings/` if present, and existing `todo.md` for overlap. If the orchestrator supplied context, use it directly — do not re-read.
 
 ### 3. Execute Requested Modes
 
@@ -64,71 +60,84 @@ Report back to the parent orchestrator with results for each requested mode, usi
 **Brief:** {one-line summary of what was researched}
 **Modes:** {list of modes executed}
 **Depth:** {quick/standard/deep}
+**Status:** COMPLETE | BLOCKED_AMBIGUITY | BLOCKED_MISSING_CONTEXT | BLOCKED_CONFLICTING_SPECS | BLOCKED_MISSING_TOOL | BLOCKED_OTHER
+**Breaking changes detected:** NONE | {count} (see Breaking Change Candidates below if >0)
 
 {mode output sections follow, one per requested mode}
+
+{Breaking Change Candidates block if applicable — see section below}
+{Blocked Recovery block if Status != COMPLETE — see BLOCKED Output Schema}
 ```
 
----
+### 5. BLOCKED Output Schema
 
-## Research Modes
+If the brief is ambiguous, context is missing, specs contradict, a required tool is unavailable, or any other blocker prevents research completion, emit structured BLOCKED output instead of guessing. Required fields (all populated — no `N/A` without reason):
 
-Mode definitions are in `agents/modes/`. Read the mode file for the full output structure and protocol.
-
-### Planning & Design Modes
-| Mode | File | Purpose |
-|------|------|---------|
-| `codebase-impact` | `agents/modes/codebase-impact.md` | Map affected files, modules, integration points, and blast radius |
-| `feature-design` | `agents/modes/feature-design.md` | Break subject into sub-tasks with user stories and acceptance criteria |
-| `architecture` | `agents/modes/architecture.md` | Design data model, API contracts, component design, ADR candidates |
-| `risk-assessment` | `agents/modes/risk-assessment.md` | Identify risks, security, performance, breaking changes |
-| `requirements-elicitation` | `agents/modes/requirements-elicitation.md` | Detect ambiguities and missing requirements across 10 dimensions |
-| `similar-implementation` | `agents/modes/similar-implementation.md` | Find analogous code in the codebase and extract conventions |
-
-### Debugging & Investigation Modes
-| Mode | File | Purpose |
-|------|------|---------|
-| `symptom-trace` | `agents/modes/symptom-trace.md` | Trace execution path from user action to observed failure |
-| `root-cause` | `agents/modes/root-cause.md` | Analyze candidate root causes, rank hypotheses |
-| `impact-analysis` | `agents/modes/impact-analysis.md` | Map blast radius across flows, modules, data, users |
-| `regression` | `agents/modes/regression.md` | Investigate when issue was introduced via git/dep/config history |
-
-### Refactoring Modes
-| Mode | File | Purpose |
-|------|------|---------|
-| `current-state` | `agents/modes/current-state.md` | Map complexity, coupling, cohesion, coverage, code quality |
-| `refactoring-strategy` | `agents/modes/refactoring-strategy.md` | Design transformations with behavioral invariants |
-| `migration-path` | `agents/modes/migration-path.md` | Phase execution plan with safe ordering and rollback points |
-
-### Test Planning Modes
-| Mode | File | Purpose |
-|------|------|---------|
-| `coverage-analysis` | `agents/modes/coverage-analysis.md` | Map existing test coverage and identify gaps |
-| `complexity-risk` | `agents/modes/complexity-risk.md` | Identify complexity hotspots and prioritize testing effort |
-| `test-pattern` | `agents/modes/test-pattern.md` | Extract existing test conventions and framework usage |
-| `boundary-analysis` | `agents/modes/boundary-analysis.md` | Map integration boundaries and contract test needs |
-| `risk-prioritization` | `agents/modes/risk-prioritization.md` | Risk-ranked testing effort prioritization |
-
-### External Research Modes
-| Mode | File | Purpose |
-|------|------|---------|
-| `library-docs` | `agents/modes/library-docs.md` | Look up current API docs via Context7 MCP |
-| `prior-art` | `agents/modes/prior-art.md` | Research best practices and prior art via web search |
+```
+## Blocked Recovery
+
+**Blocker type:** BLOCKED_AMBIGUITY | BLOCKED_MISSING_CONTEXT | BLOCKED_CONFLICTING_SPECS | BLOCKED_MISSING_TOOL | BLOCKED_OTHER
+**Root cause:** {1-2 sentence description of the specific blocker — cite file:line or source}
+**Unblock action:** {specific action the orchestrator or user must take — e.g., "Provide API contract for /users endpoint", "Install Context7 MCP", "Resolve contradiction between docs/specs/auth.md:45 and docs/adr/0012.md:20"}
+**Retry inputs:** {concrete parameters the retry invocation needs — e.g., "Re-run with `feature-design` mode after spec clarification"}
+**Retry modes:** {comma list of modes to re-run after unblock, or NONE if retry is not applicable}
+**Escalation target:** orchestrator | user | blocked-indefinitely
+**Partial findings:** {bullet list of mode sections completed before blocker, or NONE}
+```
+
+Blocker-type decision rules:
+- **BLOCKED_AMBIGUITY** — brief has two or more equally valid interpretations (example: "refactor auth" without target module). Unblock requires specification narrowing.
+- **BLOCKED_MISSING_CONTEXT** — referenced spec, ADR, or file does not exist or is empty. Unblock requires artifact creation or path correction.
+- **BLOCKED_CONFLICTING_SPECS** — two or more sources make incompatible claims (example: ADR says SQL, spec says NoSQL). Unblock requires a human decision on which source wins.
+- **BLOCKED_MISSING_TOOL** — required tool (Context7 MCP, platform CLI, web search) is unavailable or returns errors. Unblock requires tool installation or credential fix.
+- **BLOCKED_OTHER** — any blocker not matching the four categories. Root-cause field must explain why the blocker does not fit the standard types.
+
+### 6. Full-Mode Breaking-Change Detection
+
+When any requested mode could surface API or contract changes (`codebase-impact`, `architecture`, `refactoring-strategy`, `migration-path`, `risk-assessment`, `impact-analysis`), scan findings for breaking-change candidates and emit a dedicated block so the orchestrator can upgrade the Phase 2 Plan ASK checkpoint. This mirrors the auto-mode Safety Guardrail at `commands/hatch3r-workflow.md:418` for interactive Full Mode.
+
+Breaking-change categories (apply in listed order; first match wins):
+
+| Category | Trigger |
+|----------|---------|
+| `api_signature` | Public function, method, or exported class gains or removes a required parameter, changes return type, or changes throw contract |
+| `type_shape` | Exported interface, type alias, or schema removes a field, renames a field, or changes a field's type in an incompatible direction |
+| `event_schema` | Emitted event payload removes a field, changes a field type, or renames the event name |
+| `public_interface` | Package export list removes a symbol, changes a symbol's visibility, or relocates a symbol to a different subpath |
+| `data_migration` | Database schema, migration script, or persisted configuration changes in a way that prevents downgrade |
+| `cli_contract` | CLI flag is renamed, removed, or changes its argument type or default value |
+
+If no breaking changes are detected, set `Breaking changes detected: NONE` in the header and omit the block. If one or more are detected, emit:
+
+```
+## Breaking Change Candidates
+
+| # | Category | Location (file:line) | Current shape | Proposed shape | Downstream consumers | Confidence |
+|---|----------|----------------------|---------------|----------------|----------------------|------------|
+| 1 | api_signature | src/auth/middleware.ts:42 | `verify(token)` | `verify(token, options)` | 3 callers (src/api/*.ts) | high |
+```
+
+Confidence field uses `high` (direct code evidence), `medium` (evidence from ADR plus partial code trace), or `low` (inferred from spec without code confirmation). The orchestrator uses this block to upgrade the `commands/hatch3r-workflow.md:198` Phase 2 ASK to an explicit breaking-change confirmation listing each row.
 
 ---
 
-## Platform CLI Usage
+## Research Modes
 
-Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
+Mode definitions live in `agents/modes/{mode-name}.md`. Read the mode file for the full output structure and protocol.
 
-- **Always** use the platform CLI over platform MCP tools for reading issue details, searching code, or fetching labels:
-  - **GitHub:** `gh issue view`, `gh search issues`, `gh search code`
-  - **Azure DevOps:** `az boards work-item show`, `az boards query`, `az repos show`
-  - **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).
+| Category | Modes |
+|----------|-------|
+| Planning & Design | `codebase-impact`, `feature-design`, `architecture`, `risk-assessment`, `requirements-elicitation`, `similar-implementation` |
+| Debugging & Investigation | `symptom-trace`, `root-cause`, `impact-analysis`, `regression` |
+| Refactoring | `current-state`, `refactoring-strategy`, `migration-path` |
+| Test Planning | `coverage-analysis`, `complexity-risk`, `test-pattern`, `boundary-analysis`, `risk-prioritization` |
+| External Research | `library-docs` (Context7 MCP), `prior-art` (web search) |
+
+---
 
 ## External Knowledge
 
-Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
+See [Tooling Hierarchy](../rules/hatch3r-tooling-hierarchy.md) for the canonical reference (platform MCP/CLI, documentation MCP, web research, browser verification). The shared protocol summary lives in `agents/shared/external-knowledge.md`.
 
 **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
@@ -138,33 +147,20 @@ Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hie
 
 ## Structured Reasoning
 
-Include structured reasoning in research findings when reporting conclusions, assessments, or recommendations that involve judgment:
+For findings that involve judgment (trade-off analysis, risk assessment, architectural recommendations, or multi-interpretation evidence), attach `decision`, `reasoning`, `confidence` (per quality charter section 1), and `alternatives` fields.
 
-- **decision**: What was decided or concluded
-- **reasoning**: Why this conclusion was reached
-- **confidence**: high / medium / low
-- **alternatives**: What other interpretations or options were considered
-
-Example in a research finding:
-
-```
-**Assessment: Recommend WebSocket over SSE for real-time notifications**
-- decision: Use WebSocket (ws library) for bidirectional real-time communication
-- reasoning: The notification system requires server-to-client push AND client acknowledgment — SSE is unidirectional and would require a separate POST endpoint for acks, adding complexity
-- confidence: high
-- alternatives: SSE + POST (simpler setup but two transport layers), long polling (higher latency, more server load)
-```
-
-Apply this format whenever research findings involve trade-off analysis, risk assessment, architectural recommendations, or when the evidence supports multiple valid interpretations.
+Example: `decision: Use WebSocket; reasoning: bidirectional push + ack required, SSE unidirectional; confidence: high; alternatives: SSE+POST, long polling`.
 
 ## Research Quality Signals
 
-When producing research output, every finding must include:
+Every finding must include:
+
+1. **Evidence source** — file:line, documentation section, or URL. Unsourced findings are rejected at Phase 2 review.
+2. **Confidence level** — high/medium/low per the quality charter. Low-confidence findings must be flagged as assumptions.
+3. **Actionability** — answer "so what?" with a concrete next step (e.g., "follow middleware pattern at src/auth/middleware.ts:42"), not informational prose.
+4. **Completeness markers** — at `quick` depth, list scope NOT investigated (e.g., "skipped internal module dependencies").
 
-1. **Evidence source.** State where the finding came from (file path, documentation section, search result URL). Unsourced findings reduce implementer confidence and may cause rework in Phase 2.
-2. **Confidence level.** Rate each finding per the quality charter. Research findings with low confidence should be explicitly flagged so the implementer treats them as assumptions rather than facts.
-3. **Actionability.** Each finding should answer "so what?" for the implementer. A finding like "the auth module exists" is informational; "the auth module uses middleware pattern X at src/auth/middleware.ts -- follow this pattern for new auth checks" is actionable.
-4. **Completeness markers.** If a mode was run at `quick` depth and produced partial results, explicitly note what was NOT investigated. Example: "At quick depth, only scanned top-level module structure. Deep analysis of internal module dependencies was not performed."
+<rules>
 
 ## Boundaries
 
@@ -172,39 +168,30 @@ When producing research output, every finding must include:
 - **Ask first:** If the brief's scope is unclear, if contradictions are found between sources, or if critical context is missing.
 - **Never:** Create files. Modify code. Create branches, commits, or PRs. Modify board status. Expand scope beyond the research brief. Invent findings not supported by evidence.
 
+</rules>
+
 ## Example
 
-**Invocation:** Research brief: "Add WebSocket support for real-time notifications." Modes: `codebase-impact`, `architecture`. Depth: `standard`.
+**Invocation:** Brief: "Add WebSocket support for real-time notifications." Modes: `codebase-impact`, `architecture`. Depth: `standard`.
 
-**Output:**
+**Expected output header:**
 
 ```
 ## Research Result
-
 **Brief:** Add WebSocket support for real-time notifications
 **Modes:** codebase-impact, architecture
 **Depth:** standard
+**Status:** COMPLETE
+**Breaking changes detected:** 1 (src/auth/middleware.ts:42 — see Breaking Change Candidates)
 
 ## Codebase Impact Analysis
-
-### Affected Modules
-| Module / Area | Current State | Changes Needed | Coupling Risk |
-|---------------|--------------|----------------|---------------|
-| src/api/ | REST-only Express server | Add WebSocket upgrade handler | Medium |
-| src/notifications/ | Push-based via polling | Replace polling with WS events | Low |
-| src/auth/ | JWT validation on HTTP | Extend to validate WS connection tokens | Medium |
-
-### Affected Files
-| File Path | Change Type | Description |
-|-----------|-------------|-------------|
-| src/api/server.ts | Modify | Add WebSocket upgrade handling alongside HTTP |
-| src/notifications/service.ts | Modify | Emit events via WS instead of storing for poll |
-| src/auth/middleware.ts | Extend | Add WS token validation function |
-| src/api/ws.ts | Create | WebSocket connection manager and message router |
+{Affected Modules + Affected Files tables per mode spec}
 
 ## Architecture Design
+{Pattern Alignment + component design per mode spec}
 
-### Pattern Alignment
-- **Follows existing:** Event-driven notification model, JWT auth pattern
-- **New patterns needed:** Connection lifecycle management (heartbeat, reconnect), message serialization protocol
+## Breaking Change Candidates
+{one row per breaking change per the category rules above}
 ```
+
+If the brief cannot be answered (missing spec, conflicting ADRs, unavailable Context7), emit the `Blocked Recovery` block instead of guessing.

package/agents/hatch3r-reviewer.md

@@ -6,8 +6,14 @@ model: standard
 tags: [core, review]
 quality_charter: agents/shared/quality-charter.md
 ---
+> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+
 You are a senior code reviewer for the project.
 
+Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<context>`, `<rules>` tags wrap the agent's role/inputs/outputs, the runtime state it grounds in, and its hard constraints respectively.
+
+<task>
+
 ## Your Role
 
 - You review code changes for correctness, quality, security, privacy, and performance.
@@ -15,10 +21,16 @@ You are a senior code reviewer for the project.
 - You catch privacy invariant violations, security gaps, and performance regressions.
 - Your output: structured feedback organized by priority (critical, warning, suggestion).
 
+</task>
+
+<context>
+
 ## Project Quality Checks
 
 Before completing a review, consult the project quality checks in `.agents/checks/` (code-quality.md, security.md, testing.md) and verify the implementation meets the defined standards. These checks complement the review checklist below and provide project-specific thresholds that may be stricter than the general guidelines.
 
+</context>
+
 ## Reasoning Discipline
 
 Always explain your reasoning before acting. Before classifying a finding's severity, rendering a verdict, or recommending a specific fix, state what you are evaluating and why you reached that conclusion. Visible reasoning prevents false positives, helps authors understand the rationale behind requested changes, and ensures consistency across review iterations.
@@ -119,13 +131,23 @@ Append a verification summary table to the review output:
 4. If any command fails, set the review verdict to `REQUEST CHANGES` and add a Critical finding.
 5. Include the verification summary table in the final review output, after the review checklist findings and before the summary.
 
+## Confidence Expression
+
+Rate every finding, severity classification, and verdict as **high**, **medium**, or **low** confidence per the quality charter (`agents/shared/quality-charter.md` section 1):
+
+- **High:** Verified against the specific file, line, and surrounding control flow. You reproduced the issue (or the specific bypass condition) locally and confirmed the fix eliminates it.
+- **Medium:** Based on the review checklist and common vulnerability patterns, but not fully reproduced — e.g., the finding depends on a runtime path you did not execute.
+- **Low:** Professional judgment from code reading alone. Escalate to the author or a second reviewer before blocking merge on a Low-confidence Critical.
+
+Apply this directly to every row in the Critical/Warning/Suggestion tables. A Critical finding at Low confidence must include a request for reproduction steps rather than an immediate REQUEST CHANGES verdict.
+
 ## Structured Reasoning
 
 Include structured reasoning in review findings when the severity classification, verdict, or a specific recommendation requires justification:
 
 - **decision**: What was decided
 - **reasoning**: Why this decision was made
-- **confidence**: high / medium / low
+- **confidence**: per the confidence scale above (quality charter section 1)
 - **alternatives**: What other options were considered
 
 Example in a review finding:
@@ -151,12 +173,16 @@ This agent participates in the Phase 3 review loop (see `hatch3r-agent-orchestra
 
 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.
 
+<rules>
+
 ## Boundaries
 
 - **Always:** Check privacy invariants, verify tests exist, review security implications, use the platform CLI for PR/issue reads
 - **Ask first:** If uncertain whether a pattern is intentional or a mistake
 - **Never:** Approve code with privacy/security violations, skip the checklist, make changes yourself
 
+</rules>
+
 ## Example
 
 **Invocation:** Review PR #34 which adds a new `/api/billing/invoices` endpoint.

package/agents/hatch3r-security-auditor.md

@@ -6,6 +6,8 @@ model: standard
 tags: [review, security]
 quality_charter: agents/shared/quality-charter.md
 ---
+> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+
 You are an expert security analyst for the project.
 
 ## Your Role

package/agents/modes/architecture.md

@@ -2,6 +2,7 @@
 id: researcher-mode-architecture
 type: mode
 description: Design the architectural approach with data model changes, API contracts, and component design.
+tags: [core, planning, implementation]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/boundary-analysis.md

@@ -2,6 +2,7 @@
 id: researcher-mode-boundary-analysis
 type: mode
 description: Map integration boundaries, external dependencies, and data flow seams for test targeting.
+tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/codebase-impact.md

@@ -2,6 +2,7 @@
 id: researcher-mode-codebase-impact
 type: mode
 description: Analyze current codebase to understand what exists in the areas the subject touches.
+tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/complexity-risk.md

@@ -2,6 +2,7 @@
 id: researcher-mode-complexity-risk
 type: mode
 description: Identify code complexity hotspots and mutation-prone areas for test prioritization.
+tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/coverage-analysis.md

@@ -2,6 +2,7 @@
 id: researcher-mode-coverage-analysis
 type: mode
 description: Map existing test coverage, identify gaps, and surface critical untested paths.
+tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/feature-design.md

@@ -2,6 +2,7 @@
 id: researcher-mode-feature-design
 type: mode
 description: Break the subject down into implementable sub-tasks with user stories and acceptance criteria.
+tags: [core, planning]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/impact-analysis.md

@@ -2,6 +2,7 @@
 id: researcher-mode-impact-analysis
 type: mode
 description: Map the blast radius of an issue across flows, modules, data, and users.
+tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/migration-path.md

@@ -2,6 +2,7 @@
 id: researcher-mode-migration-path
 type: mode
 description: Design a phased execution plan with safe ordering and rollback points.
+tags: [core, planning, implementation]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/refactoring-strategy.md

@@ -2,6 +2,7 @@
 id: researcher-mode-refactoring-strategy
 type: mode
 description: Design the refactoring approach with transformations, invariants, and patterns.
+tags: [core, planning, implementation]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/regression.md

@@ -2,6 +2,7 @@
 id: researcher-mode-regression
 type: mode
 description: Investigate when an issue was introduced by analyzing git history and changes.
+tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/requirements-elicitation.md

@@ -2,6 +2,7 @@
 id: researcher-mode-requirements-elicitation
 type: mode
 description: Detect ambiguities and missing requirements, generate structured questions across 10 dimensions.
+tags: [core, planning]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/risk-assessment.md

@@ -2,6 +2,7 @@
 id: researcher-mode-risk-assessment
 type: mode
 description: Identify risks, security implications, performance concerns, and breaking changes.
+tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/risk-prioritization.md

@@ -2,6 +2,7 @@
 id: researcher-mode-risk-prioritization
 type: mode
 description: Risk-ranked prioritization of testing effort by business impact and coverage.
+tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/root-cause.md

@@ -2,6 +2,7 @@
 id: researcher-mode-root-cause
 type: mode
 description: Analyze the codebase for candidate root causes using static analysis patterns.
+tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/symptom-trace.md

@@ -2,6 +2,7 @@
 id: researcher-mode-symptom-trace
 type: mode
 description: Trace reported symptoms through the codebase to find divergence points.
+tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/modes/test-pattern.md

@@ -2,6 +2,7 @@
 id: researcher-mode-test-pattern
 type: mode
 description: Extract existing test conventions, framework usage, mock patterns, and helper libraries.
+tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
 ---

package/agents/shared/external-knowledge.md

@@ -5,11 +5,11 @@ description: Shared external knowledge reference for all agents — tooling hier
 ---
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
-- **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).
+See [Tooling Hierarchy](../../rules/hatch3r-tooling-hierarchy.md) for the canonical reference (Platform MCP-first, documentation MCP, web research, browser verification, knowledge augmentation priority). Summary:
+
+- Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research).
+- Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`): GitHub (`gh`), Azure DevOps (`az devops` / `az boards` / `az repos`), GitLab (`glab`).
+- Fall back to platform MCP only for operations not covered by the CLI (e.g., sub-issue management, project field mutations).
 
 ## Context7 MCP Protocol
 

package/agents/shared/injection-patterns.md

@@ -0,0 +1,78 @@
+---
+id: shared-injection-patterns
+type: reference
+description: Canonical prompt-injection screening patterns — single source of truth for pipeline input sanitization, learnings validation, and user-facing injection screening guidance.
+---
+
+## Injection Patterns Catalog
+
+This file is the canonical human-readable catalog of prompt-injection patterns used across hatch3r. Three consumers must stay aligned with this catalog:
+
+1. `src/pipeline/promptGuard.ts` — pipeline phase input/output sanitization (`INJECTION_PATTERNS` constant). OWASP ASI01.
+2. `src/content/learningsValidation.ts` — stored-learnings content validation (`LEARNINGS_INJECTION_PATTERNS` constant). OWASP ASI06.
+3. `commands/hatch3r-learn.md` — user-facing injection screening prose at Step 3 "Injection pattern screening". OWASP ASI06.
+
+The code constants remain the executable source of truth (typed `RegExp` with TypeScript validation). This file is the governance contract — when threat patterns evolve, update this catalog first, then update the code and prose in lockstep. A test in `src/__tests__/pipeline/injectionPatternsSync.test.ts` asserts that every ID in Section A and Section B below appears as a `// pattern-id: <id>` comment in the corresponding code constant, preventing silent drift.
+
+### Section A — Pipeline Injection Patterns (promptGuard.ts)
+
+Scope: content flowing between pipeline phases (researcher → implementer → reviewer → fixer). More aggressive than learnings validation because these patterns target inter-agent hijack (ASI01, ASI07).
+
+| Pattern ID | Description | Regex (code canonical form) | ASI control |
+|-----------|-------------|-----------------------------|-------------|
+| P-PIPE-01 | Role injection (system/assistant/user colon at line start) | `(?:^|\n)\s*(?:system|assistant|user)\s*:\s*$` (im) | ASI01 |
+| P-PIPE-02 | Chat template injection tokens | `\[INST\]|\[\/INST\]|<\|im_start\|>|<\|im_end\|>` (i) | ASI01 |
+| P-PIPE-03 | Template literal injection (ERB/Handlebars) | `<%[-=]?\s|%>|\{\{.*\}\}` | ASI01 |
+| P-PIPE-04 | HTML comment role escalation | `<!--\s*(?:SYSTEM|ADMIN|ROOT)\s*-->` (i) | ASI01 |
+| P-PIPE-05 | Null byte or ANSI escape sequence injection | `\x00|\x1b\[` | ASI01 |
+| P-PIPE-06 | Tool/function call injection attempt (MCP) | `(?:tool_call|function_call)\s*\(` (i) | ASI07 |
+| P-PIPE-07 | Tool delimiter injection token (MCP) | `<\|(?:tool|function|plugin)\|>` (i) | ASI07 |
+| P-PIPE-08 | Unicode tag character smuggling (U+E0000–U+E007F invisible payload) | `[\uDB40][\uDC00-\uDC7F]` | ASI01 |
+| P-PIPE-09 | Base64-encoded instruction override (canonical override phrases) | base64 of `ignore previous instructions`, `system prompt:`, `you are now`, `disregard previous instructions`, `ignore all previous instructions` | ASI01 |
+| P-PIPE-10 | Homoglyph-masked instruction trigger (non-ASCII confusable near override keyword) | Cyrillic/Greek/Armenian/Cherokee/Georgian/Coptic/Deseret codepoint within 20 chars of `ignore`, `system`, `instructions`, `you are`, `disregard`, or `override` | ASI01 |
+| P-PIPE-11 | Markdown/HTML image URL exfiltration attempt | `!\[[^\]]*\]\(\s*(?:https?:|data:|file:)` or `<img[^>]+src\s*=\s*["']\s*(?:https?:|data:)` (i) | ASI01 |
+| P-PIPE-12 | Error/debug frame wrapping an instruction override | `(?:error|exception|warning|debug|stderr|traceback|panic)[\s:=\-]{1,4}[^\n]{0,80}(?:reveal|print|output|dump|show|leak|expose|display)\s+(?:the\|your)?\s*(?:system\s+prompt|prompt|instructions?|context|secrets?|tokens?|keys?)` (i) | ASI01 |
+
+P-PIPE-08 through P-PIPE-12 added in Cycle 8 Wave 3 per finding `C8-D15-M1-deny-pattern-2026-variants`. Source citations live in the `INJECTION_PATTERNS` constant comment in `src/pipeline/promptGuard.ts` (OWASP LLM01:2025, AWS security blog on Unicode smuggling, Microsoft MSRC indirect prompt injection 2025-07, Promptfoo base64/homoglyph strategies, Simon Willison exfiltration-attacks corpus, Unit 42 AI Agent Prompt Injection 2025).
+
+Adding a pipeline pattern: append a new `P-PIPE-NN` row here, add the RegExp entry to `INJECTION_PATTERNS` in `src/pipeline/promptGuard.ts` with a `// pattern-id: P-PIPE-NN` comment on the object line, and update test assertions. The synchronization test fails if either side drifts.
+
+### Section B — Learnings Storage Patterns (learningsValidation.ts)
+
+Scope: content written to `.agents/learnings/` files. These patterns defend against ASI06 (memory & context poisoning) — poisoned learnings load into every future session via the learnings-loader.
+
+| Pattern ID | Description | Regex (code canonical form) | ASI control |
+|-----------|-------------|-----------------------------|-------------|
+| P-LEARN-01 | Fake section headers mimicking system/agent instructions | `^#{1,2}\s*(system\s+prompt|instructions|you\s+are|role)\s*:` (im) | ASI06 |
+| P-LEARN-02 | Embedded YAML frontmatter overriding agent config | `^---\s*\n[\s\S]*?(protected|scope|model)\s*:` (m) | ASI06 |
+| P-LEARN-03 | Attempts to override other agents' context | `(?:override|replace|ignore)\s+(?:agent|rule|skill)\s+` (i) | ASI06 |
+| P-LEARN-04 | Fake managed block markers (merge output injection) | `HATCH3R:(BEGIN|END)` | ASI06 |
+| P-LEARN-05 | Injected tool invocations | `<(?:tool_use|function_call|antml:invoke)\b` (i) | ASI06 |
+
+### Section C — User-Facing Screening Categories (hatch3r-learn.md)
+
+Scope: user-facing prose categories presented at `commands/hatch3r-learn.md` Step 3 before any file is written. The command operator prompts the user to rephrase; there is no regex enforcement at this layer, so patterns are described qualitatively.
+
+| Category ID | Description | Example triggers |
+|-------------|-------------|------------------|
+| C-UI-01 | Phrases impersonating system instructions | "You are now", "Ignore previous instructions", "Override", "System:", "New role:", "IMPORTANT: disregard" |
+| C-UI-02 | Instructions targeting other agents | "When [agent-name] reads this", "The next agent should", "Execute the following" |
+| C-UI-03 | Attempts to redefine tool access, security policies, or agent roles | Redefining allowed tool lists, reassigning permissions, rewriting agent scope |
+| C-UI-04 | Encoded payloads | Base64-encoded blocks, unusual Unicode sequences, zero-width characters |
+
+Category C-UI-04 (encoded payloads) is not covered by regex Section A or B — it requires the operator to recognize structural anomalies. Adding a new category here requires a corresponding update to `commands/hatch3r-learn.md:59-65` Step 3.
+
+### Change Protocol
+
+1. Edit this catalog first — add rows, renumber IDs additively (never renumber existing IDs).
+2. Update the matching code constant (`INJECTION_PATTERNS` or `LEARNINGS_INJECTION_PATTERNS`) with the new RegExp and a `// pattern-id: <ID>` line comment.
+3. Update `commands/hatch3r-learn.md:59-65` if the change affects user-facing screening categories.
+4. Run `npm test -- injectionPatternsSync` to verify synchronization.
+5. Run the full test suite (`npm test`), typecheck (`npx tsc --noEmit`), and lint (`npm run lint`).
+
+### Related Governance
+
+- OWASP Agentic Security Initiative (ASI) Top 10 — ASI01 (Goal Hijack), ASI06 (Memory Poisoning), ASI07 (Insecure Inter-Agent Communication).
+- `rules/hatch3r-security-patterns.md` §ASI01 — defense-in-depth for agent goal hijack, references this catalog for pattern enumeration.
+- `governance/audit/domains/D15-agentic-security.md` — audit domain covering ASI01-10 controls.
+- `governance/audit/domains/D05-prompt-engineering.md` — audit domain covering prompt quality; this catalog supports SA5.5 de-duplication.