hatch3r 1.4.0 → 1.5.0

package/hooks/hatch3r-ci-failure.md

@@ -5,6 +5,7 @@ event: ci-failure
 agent: ci-watcher
 description: Diagnose CI pipeline failures
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Hook: ci-failure → ci-watcher
 

package/hooks/hatch3r-file-save.md

@@ -6,6 +6,7 @@ agent: context-rules
 description: Activate context-specific rules on file save
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Hook: file-save → context-rules
 

package/hooks/hatch3r-post-merge.md

@@ -5,6 +5,7 @@ event: post-merge
 agent: ci-watcher
 description: Check CI pipeline status after merge
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Hook: post-merge → ci-watcher
 

package/hooks/hatch3r-pre-commit.md

@@ -6,6 +6,7 @@ agent: lint-fixer
 description: Auto-fix lint and formatting issues before commit
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Hook: pre-commit → lint-fixer
 

package/hooks/hatch3r-pre-push.md

@@ -5,6 +5,7 @@ event: pre-push
 agent: security-auditor
 description: Scan for secrets and security issues before push
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Hook: pre-push → security-auditor
 

package/hooks/hatch3r-session-start.md

@@ -5,6 +5,7 @@ event: session-start
 agent: learnings-loader
 description: Load relevant learnings at session start
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Hook: session-start → learnings-loader
 

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "hatch3r",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Battle-tested agentic coding setup framework. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for every major AI coding tool.",
   "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/cli/index.js",
+      "types": "./dist/cli/index.d.ts"
+    }
+  },
   "bin": {
     "hatch3r": "./dist/cli/index.js"
   },
@@ -13,7 +19,8 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lockfile:check": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https"
   },
   "keywords": [
     "agents",
@@ -44,11 +51,15 @@
   "bugs": {
     "url": "https://github.com/hatch3r/hatch3r/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "engines": {
     "node": ">=22.0.0"
   },
   "files": [
-    "dist/",
+    "dist/cli/",
     "agents/",
     "checks/",
     "commands/",
@@ -73,12 +84,16 @@
     "@types/node": "^25.5.0",
     "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.1.0",
+    "lockfile-lint": "^5.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.7.0",
+    "typescript": "^6.0.2",
     "typescript-eslint": "^8.57.2",
     "vitest": "^4.1.2"
   },
   "overrides": {
     "flatted": "^3.4.2"
+  },
+  "comments": {
+    "overrides/flatted": "Pinned to >=3.4.2 to resolve security advisory in transitive eslint > flat-cache > flatted dependency"
   }
 }

package/rules/hatch3r-accessibility-standards.md

@@ -2,8 +2,9 @@
 id: hatch3r-accessibility-standards
 type: rule
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
-scope: always
+scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*a11y*,**/*accessibility*"
 tags: [a11y]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Accessibility Standards
 

package/rules/hatch3r-accessibility-standards.mdc

@@ -1,6 +1,6 @@
 ---
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
-alwaysApply: true
+globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/*a11y*", "**/*accessibility*"]
 ---
 # Accessibility Standards
 

package/rules/hatch3r-agent-orchestration-detail.md

@@ -3,7 +3,9 @@ id: hatch3r-agent-orchestration-detail
 type: rule
 description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
 scope: conditional
+globs: "**/.agents/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Agent Orchestration — Extended Reference
 
@@ -20,6 +22,14 @@ PipelineContext {
   issueRef: string | null        // Issue number or null for plain chat
   deepContextTier: 1 | 2 | 3    // From hatch3r-deep-context scoring
 
+  // Detected project type for specialist selection (Finding #56)
+  projectType?: {
+    languages: string[]          // From repo analysis (e.g., "typescript", "python", "go")
+    frameworks: string[]         // Detected frameworks (e.g., "next", "express")
+    isMonorepo: boolean
+    packageManager: string       // "npm" | "yarn" | "pnpm" | "bun" | "unknown"
+  }
+
   // Phase 1 outputs (Research)
   researchFindings: {
     modes: string[]              // Researcher modes used
@@ -31,11 +41,14 @@ PipelineContext {
     resolvedRequirements: object | null  // From requirements-elicitation
   }
 
+  // Research gap flags from mid-implementation checkpoint (Finding #52)
+  researchGaps?: string[]        // Gaps identified during Phase 2
+
   // Phase 2 outputs (Implementation)
   implementationResult: {
     filesChanged: string[]
     testsWritten: string[]
-    status: "SUCCESS" | "PARTIAL" | "FAILED"
+    status: "SUCCESS" | "PARTIAL" | "FAILED" | "SKIPPED" | "TIMEOUT"
     reason: string | null
   }
 
@@ -65,6 +78,8 @@ PipelineContext {
 }
 ```
 
+The TypeScript implementation of this schema with runtime validation is in `src/pipeline/pipelineContext.ts`. Use `validatePhaseTransition()` to verify context completeness before advancing between phases.
+
 ## Resilience and Failure Handling
 
 ### Phase Failure Protocols
@@ -76,6 +91,7 @@ PipelineContext {
 | Phase 2 (Implementation) | Build/test failure | Attempt self-fix (max 2 iterations). Escalate to user if unresolved. |
 | Phase 2 (Implementation) | Scope creep detected | Halt. Surface deviation to user. Resume only with approval. |
 | Phase 3 (Review) | Max iterations (3) | Surface unresolved findings to user. Do not merge. |
+| Phase 3 (Review) | DESIGN_OBJECTION verdict | Terminate review loop immediately. Surface the objection and alternative approaches to the user for an architectural decision. Do not spawn fixer. |
 | Phase 3 (Review) | Fixer introduces regressions | Revert fixer changes. Surface original findings + regression to user. |
 | Phase 4 (Quality) | Specialist timeout | Log timeout. Continue with available results. Flag in output. |
 | Phase 4 (Quality) | Validation pass fails | Spawn fixer (max 2 attempts). Surface if unresolved. |
@@ -157,3 +173,35 @@ Auto-mode MUST halt and surface to user when:
 
 - **Token budget:** If cumulative subagent token usage exceeds 80% of estimated budget, surface to user before spawning additional agents.
 - **Time budget:** If pipeline duration exceeds 2x the estimated time (based on deep context tier), surface status and request continuation approval.
+
+## Adaptive Pipeline Behavior
+
+### Complexity-Driven Adaptation
+
+The pipeline should adapt its behavior based on observed task complexity, not just the initial tier assignment:
+
+| Signal During Execution | Adaptation |
+|------------------------|------------|
+| Phase 1 research finds >10 affected files (initial estimate was <5) | Upgrade tier to 3 if currently 2. Re-run `codebase-impact` at `deep` depth before Phase 2. |
+| Phase 2 implementer reports >3 research gaps | Pause Phase 2. Run targeted researcher with gap-specific modes before continuing. |
+| Phase 3 review loop reaches iteration 2 with increasing Critical count | Classify as complexity underestimate. Surface to user with recommendation to break the task into smaller sub-tasks. |
+| Phase 4 validation pass fails on first attempt | Check whether failure is in test-writer's new tests (expected -- fix test) or in pre-existing tests (regression -- fix implementation). Route to appropriate fixer. |
+
+### Post-Pipeline Learning
+
+After pipeline completion, the orchestrator should capture lessons for future runs:
+
+1. **Tier accuracy:** Was the initial tier correct? If the pipeline needed adaptation (above), log the mismatch for the learnings system.
+2. **Phase duration ratios:** Record time spent per phase. Anomalous ratios (e.g., Phase 3 taking 5x Phase 2) indicate systemic issues worth investigating.
+3. **Specialist value:** Record which Phase 4 specialists produced actionable findings vs. clean reports. Over time, this data informs smarter specialist dispatch.
+
+## Context Token Optimization
+
+When pipeline context exceeds 50% of the available context window, apply these compression strategies in order:
+
+1. **Summarize Phase 1 output.** Replace full research findings with a structured summary: affected files (list), blast radius (count + top 3), key conventions (bullet points). Keep raw data only for the fields the current phase needs.
+2. **Prune resolved findings.** After Phase 3 review loop, remove findings that were fixed and confirmed. Only carry forward unresolved findings.
+3. **Collapse specialist results.** In the final output, summarize specialist results as a single status table rather than including full specialist reports. Full reports are available on request.
+4. **Never truncate security findings.** Security auditor output is always included in full regardless of context pressure.
+
+These strategies preserve decision-critical information while reducing token overhead for long pipelines.

package/rules/hatch3r-agent-orchestration-detail.mdc

@@ -1,5 +1,6 @@
 ---
 description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
+globs: ["**/.agents/**", "**/pipeline/**", "**/*orchestrat*", "**/*agent*"]
 alwaysApply: false
 ---
 # Agent Orchestration — Extended Reference
@@ -17,6 +18,14 @@ PipelineContext {
   issueRef: string | null        // Issue number or null for plain chat
   deepContextTier: 1 | 2 | 3    // From hatch3r-deep-context scoring
 
+  // Detected project type for specialist selection (Finding #56)
+  projectType?: {
+    languages: string[]          // From repo analysis (e.g., "typescript", "python", "go")
+    frameworks: string[]         // Detected frameworks (e.g., "next", "express")
+    isMonorepo: boolean
+    packageManager: string       // "npm" | "yarn" | "pnpm" | "bun" | "unknown"
+  }
+
   // Phase 1 outputs (Research)
   researchFindings: {
     modes: string[]              // Researcher modes used
@@ -28,11 +37,14 @@ PipelineContext {
     resolvedRequirements: object | null  // From requirements-elicitation
   }
 
+  // Research gap flags from mid-implementation checkpoint (Finding #52)
+  researchGaps?: string[]        // Gaps identified during Phase 2
+
   // Phase 2 outputs (Implementation)
   implementationResult: {
     filesChanged: string[]
     testsWritten: string[]
-    status: "SUCCESS" | "PARTIAL" | "FAILED"
+    status: "SUCCESS" | "PARTIAL" | "FAILED" | "SKIPPED" | "TIMEOUT"
     reason: string | null
   }
 
@@ -62,6 +74,8 @@ PipelineContext {
 }
 ```
 
+The TypeScript implementation of this schema with runtime validation is in `src/pipeline/pipelineContext.ts`. Use `validatePhaseTransition()` to verify context completeness before advancing between phases.
+
 ## Resilience and Failure Handling
 
 ### Phase Failure Protocols
@@ -154,3 +168,35 @@ Auto-mode MUST halt and surface to user when:
 
 - **Token budget:** If cumulative subagent token usage exceeds 80% of estimated budget, surface to user before spawning additional agents.
 - **Time budget:** If pipeline duration exceeds 2x the estimated time (based on deep context tier), surface status and request continuation approval.
+
+## Adaptive Pipeline Behavior
+
+### Complexity-Driven Adaptation
+
+The pipeline should adapt its behavior based on observed task complexity, not just the initial tier assignment:
+
+| Signal During Execution | Adaptation |
+|------------------------|------------|
+| Phase 1 research finds >10 affected files (initial estimate was <5) | Upgrade tier to 3 if currently 2. Re-run `codebase-impact` at `deep` depth before Phase 2. |
+| Phase 2 implementer reports >3 research gaps | Pause Phase 2. Run targeted researcher with gap-specific modes before continuing. |
+| Phase 3 review loop reaches iteration 2 with increasing Critical count | Classify as complexity underestimate. Surface to user with recommendation to break the task into smaller sub-tasks. |
+| Phase 4 validation pass fails on first attempt | Check whether failure is in test-writer's new tests (expected -- fix test) or in pre-existing tests (regression -- fix implementation). Route to appropriate fixer. |
+
+### Post-Pipeline Learning
+
+After pipeline completion, the orchestrator should capture lessons for future runs:
+
+1. **Tier accuracy:** Was the initial tier correct? If the pipeline needed adaptation (above), log the mismatch for the learnings system.
+2. **Phase duration ratios:** Record time spent per phase. Anomalous ratios (e.g., Phase 3 taking 5x Phase 2) indicate systemic issues worth investigating.
+3. **Specialist value:** Record which Phase 4 specialists produced actionable findings vs. clean reports. Over time, this data informs smarter specialist dispatch.
+
+## Context Token Optimization
+
+When pipeline context exceeds 50% of the available context window, apply these compression strategies in order:
+
+1. **Summarize Phase 1 output.** Replace full research findings with a structured summary: affected files (list), blast radius (count + top 3), key conventions (bullet points). Keep raw data only for the fields the current phase needs.
+2. **Prune resolved findings.** After Phase 3 review loop, remove findings that were fixed and confirmed. Only carry forward unresolved findings.
+3. **Collapse specialist results.** In the final output, summarize specialist results as a single status table rather than including full specialist reports. Full reports are available on request.
+4. **Never truncate security findings.** Security auditor output is always included in full regardless of context pressure.
+
+These strategies preserve decision-critical information while reducing token overhead for long pipelines.

package/rules/hatch3r-agent-orchestration.md

@@ -4,6 +4,7 @@ type: rule
 description: Mandatory agent delegation, skill loading, and subagent usage directives for ALL tasks in ALL contexts
 scope: always
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Agent Orchestration
 
@@ -82,6 +83,21 @@ Spawn `hatch3r-implementer` via Task tool for ALL code changes. Never implement
 
 **Implementer prompt enrichment (Tier 2+):** Include `similar-implementation` findings as "Reference Conventions", resolved `requirements-elicitation` answers as "Resolved Requirements", and blast radius data (Tier 3 only).
 
+### Mid-Implementation Research Gap Checkpoint
+
+At the midpoint of Phase 2 (after initial files are modified but before completion), the implementer MUST evaluate whether research gaps exist. This prevents discovering missing context too late in the pipeline.
+
+**Checkpoint triggers:**
+1. Implementation requires modifying a file not listed in `researchFindings.affectedFiles`.
+2. An undocumented dependency or integration point is discovered.
+3. The implementer's confidence drops below "medium" for any sub-task.
+4. A test file expected from research does not exist or covers different behavior.
+
+**Actions when gaps are detected:**
+- Log the gap in `PipelineContext.researchGaps`.
+- If the gap is blocking (cannot proceed without the missing context): pause implementation, surface the gap to the orchestrator, and request a targeted re-run of `hatch3r-researcher` with the specific modes needed.
+- If the gap is non-blocking (can proceed with assumptions): document the assumption, continue implementation, and flag for reviewer attention in Phase 3.
+
 ### Per-Task Mini-Review
 
 For multi-sub-task implementations, the implementer performs a lightweight mini-review after each sub-task: verify correctness, check interface contracts, validate no regressions, gate progression. Mini-reviews are internal (no separate reviewer agent).
@@ -93,17 +109,47 @@ For multi-sub-task implementations, the implementer performs a lightweight mini-
 1. Spawn `hatch3r-reviewer` with diff and acceptance criteria. Reviewer includes blast radius summary.
 2. Critical/Warning findings: spawn `hatch3r-fixer` with full reviewer output.
 3. Re-review after fixes. Repeat until 0 Critical + 0 Warning, or max 3 iterations.
-4. **Confirmation pass** after clean review: lightweight re-review for fix-driven regressions and acceptance criteria completeness.
-5. Max iterations reached: surface to user for manual resolution.
+4. **Confirmation pass** after clean review: lightweight re-review for fix-driven regressions and acceptance criteria completeness. The confirmation pass checks only: (a) no new test failures compared to Phase 2 baseline, (b) no type errors introduced, (c) acceptance criteria from the issue are still met. It does not re-run the full review checklist.
+5. Max iterations reached: surface to user with a structured summary: iteration count, remaining Critical findings (with file:line), remaining Warning findings, and a recommendation (fix manually vs. accept risk). Never present raw reviewer output without summarization.
+6. **Review gate confidence signal:** When the review loop exits with a clean verdict, record the iteration count in `PipelineContext.reviewResult.iterations`. Clean-on-first-pass (iteration 1) signals higher confidence than clean-after-multiple-iterations (iteration 2-3). Phase 4 specialists and the orchestrator should factor this into their risk assessment.
 
 **Phase 4 — Final Quality** (after review loop is clean):
 
-Launch parallel subagents — no artificial concurrency limit.
+Launch parallel subagents -- no artificial concurrency limit.
 
 - **Always:** `hatch3r-test-writer`, `hatch3r-security-auditor`
 - **Evaluate:** `hatch3r-docs-writer` (when APIs/architecture/UX affected)
 - **Conditional:** `hatch3r-lint-fixer`, `hatch3r-a11y-auditor`, `hatch3r-perf-profiler`, `hatch3r-dependency-auditor`, `hatch3r-architect`, `hatch3r-devops`
 
+**Specialist Prompt Enrichment:** When spawning Phase 4 specialists, include:
+- The `filesChanged` list from Phase 2 so specialists focus on affected code.
+- The review verdict summary from Phase 3 so specialists do not re-flag already-reviewed issues.
+- The `researchFindings.blastRadius` so specialists can assess downstream impact of their changes.
+
+**Phase 4 Specialist Trigger Table:**
+
+| Specialist | Mode | Trigger Conditions |
+|-----------|------|--------------------|
+| `hatch3r-test-writer` | Always | Any code change |
+| `hatch3r-security-auditor` | Always | Any code change |
+| `hatch3r-docs-writer` | Evaluate | Public API, architecture, or UX changes |
+| `hatch3r-lint-fixer` | Conditional | Lint/type errors present |
+| `hatch3r-a11y-auditor` | Conditional | UI/accessibility changes |
+| `hatch3r-perf-profiler` | Conditional | Performance-sensitive changes |
+| `hatch3r-dependency-auditor` | Conditional | Dependency files modified (package.json, go.mod, Cargo.toml, requirements.txt, Gemfile, pom.xml, pubspec.yaml, mix.exs, composer.json, and their lockfiles) |
+| `hatch3r-architect` | Conditional | Architectural decisions, new modules/services |
+| `hatch3r-devops` | Conditional | CI/CD or infrastructure changes |
+
+**Project-Type-Aware Specialist Selection:**
+
+When `PipelineContext.projectType` is available (populated from repo analysis), use the detected languages and frameworks to enrich specialist prompts with language-specific hints. For example:
+- **TypeScript/JavaScript:** Include strict mode checks for lint-fixer, framework-specific test patterns for test-writer.
+- **Python:** Include ruff/mypy hints for lint-fixer, pytest patterns for test-writer, SSTI/SQLi checks for security-auditor.
+- **Go:** Include golangci-lint for lint-fixer, govulncheck for security-auditor, table-driven test patterns for test-writer.
+- **Rust:** Include clippy lints for lint-fixer, cargo-audit for security-auditor.
+
+See `src/pipeline/pipelineContext.ts` for the full `LANGUAGE_SPECIALIST_CONFIGS` mapping.
+
 ### Phase 4 Validation Pass
 
 After all Phase 4 specialists complete, run a validation pass to catch regressions:
@@ -112,6 +158,7 @@ After all Phase 4 specialists complete, run a validation pass to catch regressio
 2. No new failures: proceed to completion.
 3. New failures: identify causing specialist, spawn `hatch3r-fixer`, re-validate (max 2 iterations).
 4. Persistent regressions: surface to user. Do not silently accept.
+5. If any specialist produced code fixes (not just findings), spawn a lightweight `hatch3r-reviewer` re-review scoped to files modified by Phase 4 specialists. This prevents specialist fixes from bypassing the Phase 3 review gate. Max 1 re-review iteration; Critical findings trigger a single fixer pass.
 
 ### Specialist Success Criteria
 
@@ -149,6 +196,15 @@ Skill-referenced agent delegations are mandatory.
 3. Launch independent subagents in parallel — maximum parallelism.
 4. Await and review results. Surface BLOCKED or PARTIAL to user.
 
+## Cross-Phase Error Propagation
+
+When a phase produces a non-SUCCESS status, the orchestrator must propagate error context to downstream phases rather than silently dropping it:
+
+1. **Phase 1 PARTIAL** (incomplete research): Include the `researchGaps` list in the implementer prompt so the implementer knows which areas lack verified context. Set implementer confidence expectations accordingly.
+2. **Phase 2 PARTIAL** (incomplete implementation): Include the `reason` field and list of unimplemented acceptance criteria in the reviewer prompt. The reviewer must distinguish between "not done yet" and "done incorrectly."
+3. **Phase 3 UNRESOLVED** (review loop exhausted): Include the unresolved findings list in the Phase 4 specialist prompts. Specialists must not introduce changes that conflict with known unresolved issues.
+4. **Phase 4 specialist FAILED**: Include the failure reason when surfacing to the user. Never report "Phase 4 failed" without specifying which specialist failed and why.
+
 ## Correlation ID
 
 Generate a UUID v4 per top-level task before Phase 1. Include in every subagent prompt as `correlation_id`. All subagents include it in logs, outputs, and status reports. Epic sub-issues get individual IDs; batch tasks share one ID with a sub-task index.
@@ -175,11 +231,37 @@ All subagents MUST map findings to this scale.
 | **SKIPPED** | Intentionally not executed. |
 | **TIMEOUT** | Time budget exceeded; forward partial output. |
 
+## Phase Skip Criteria
+
+Consistent criteria for when each pipeline phase can be safely skipped. All commands that use the pipeline MUST reference these criteria — do not invent command-specific skip rules.
+
+| Phase | Can Skip When | Mandatory Minimum (even when skipped) |
+|-------|--------------|--------------------------------------|
+| **Phase 1 (Research)** | Trivial single-line edit (typo, comment, single-value config); Tier 1 single-file change with no cross-module impact; Research already cached in PipelineContext | Affected files identified (even via quick scan); existing tests noted |
+| **Phase 2 (Implement)** | Never — implementation is always required for code changes | All changes via hatch3r-implementer (never inline except trivial items in quick-change) |
+| **Phase 3 (Review)** | All items trivial (quick-change only); documentation-only change with no code | Quality checks (lint/typecheck/test) must pass; acceptance criteria verified |
+| **Phase 4 (Quality)** | Review loop unresolved AND user chose manual resolution; documentation-only; all trivial + quality checks pass (quick-change only) | test-writer + security-auditor always required for code changes; quality checks must pass |
+
+See `src/pipeline/pipelineContext.ts` for the programmatic `PHASE_SKIP_CRITERIA` constant.
+
+## Root-Cause Depth Requirements
+
+When a pipeline phase reports a failure or unexpected result, the orchestrator must perform root-cause classification before deciding the next action:
+
+| Symptom | Shallow Fix (avoid) | Root-Cause Fix (required) |
+|---------|---------------------|---------------------------|
+| Test failure after Phase 2 | Disable or skip the failing test | Identify why the implementation breaks the test -- fix the code or update the test with justification |
+| Lint errors after Phase 4 | Add `eslint-disable` comments | Fix the underlying code pattern that triggers the lint rule |
+| Type errors after fixer changes | Cast with `as any` | Trace the type mismatch to its source and fix the type definition or usage |
+| Review loop not converging | Surface to user after 3 iterations without analysis | Classify whether findings are oscillating (fixer A breaks what fixer B fixed) and surface the conflict pattern |
+
+The orchestrator must reject superficial fixes from any subagent. If a fixer's output contains suppression patterns (disable comments, `any` casts, test skips without linked issues), classify as PARTIAL and re-run with an adjusted prompt that requests a root-cause fix.
+
 ## Task Context Protocols
 
 **Single-task plain chat:** Classify task type, create synthetic issue context, run full pipeline. For issue references, fetch details via platform CLI.
 
-**Multi-task plain chat:** Parse into discrete tasks, classify each, build dependency graph, parallelize researchers and implementers per dependency level, run review loop after all implementations, then Phase 4 specialists.
+**Multi-task plain chat:** Parse into discrete tasks, classify each, build dependency graph, parallelize researchers and implementers per dependency level, run review loop after all implementations, then Phase 4 specialists. When parallel implementers modify the same file: accept disjoint region edits, merge overlapping regions using the larger-scope change as base, and halt on semantic conflicts (contradictory interface/contract changes) for user resolution.
 
 **Auto-mode guardrails:** In unattended execution, verify scope containment, no unapproved destructive operations, and output schema compliance after each phase. Halt on violation. See `hatch3r-agent-orchestration-detail` for full guardrail specifications.
 
@@ -201,6 +283,6 @@ All `scope: always` rules apply to every task including subagent work. Include r
 - `hatch3r-dependency-management` -- dependency-auditor
 
 **Tier 3 -- On-demand:**
-- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability`
+- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`, `hatch3r-observability-tracing-detail`
 
 For limited context windows, Tier 1 is mandatory. Tier 2/3 included selectively by agent role and task scope.

package/rules/hatch3r-agent-orchestration.mdc

@@ -79,6 +79,21 @@ Spawn `hatch3r-implementer` via Task tool for ALL code changes. Never implement
 
 **Implementer prompt enrichment (Tier 2+):** Include `similar-implementation` findings as "Reference Conventions", resolved `requirements-elicitation` answers as "Resolved Requirements", and blast radius data (Tier 3 only).
 
+### Mid-Implementation Research Gap Checkpoint
+
+At the midpoint of Phase 2 (after initial files are modified but before completion), the implementer MUST evaluate whether research gaps exist. This prevents discovering missing context too late in the pipeline.
+
+**Checkpoint triggers:**
+1. Implementation requires modifying a file not listed in `researchFindings.affectedFiles`.
+2. An undocumented dependency or integration point is discovered.
+3. The implementer's confidence drops below "medium" for any sub-task.
+4. A test file expected from research does not exist or covers different behavior.
+
+**Actions when gaps are detected:**
+- Log the gap in `PipelineContext.researchGaps`.
+- If the gap is blocking (cannot proceed without the missing context): pause implementation, surface the gap to the orchestrator, and request a targeted re-run of `hatch3r-researcher` with the specific modes needed.
+- If the gap is non-blocking (can proceed with assumptions): document the assumption, continue implementation, and flag for reviewer attention in Phase 3.
+
 ### Per-Task Mini-Review
 
 For multi-sub-task implementations, the implementer performs a lightweight mini-review after each sub-task: verify correctness, check interface contracts, validate no regressions, gate progression. Mini-reviews are internal (no separate reviewer agent).
@@ -90,17 +105,46 @@ For multi-sub-task implementations, the implementer performs a lightweight mini-
 1. Spawn `hatch3r-reviewer` with diff and acceptance criteria. Reviewer includes blast radius summary.
 2. Critical/Warning findings: spawn `hatch3r-fixer` with full reviewer output.
 3. Re-review after fixes. Repeat until 0 Critical + 0 Warning, or max 3 iterations.
-4. **Confirmation pass** after clean review: lightweight re-review for fix-driven regressions and acceptance criteria completeness.
-5. Max iterations reached: surface to user for manual resolution.
+4. **Confirmation pass** after clean review: lightweight re-review for fix-driven regressions and acceptance criteria completeness. The confirmation pass checks only: (a) no new test failures compared to Phase 2 baseline, (b) no type errors introduced, (c) acceptance criteria from the issue are still met. It does not re-run the full review checklist.
+5. Max iterations reached: surface to user with a structured summary: iteration count, remaining Critical findings (with file:line), remaining Warning findings, and a recommendation (fix manually vs. accept risk). Never present raw reviewer output without summarization.
 
 **Phase 4 — Final Quality** (after review loop is clean):
 
-Launch parallel subagents — no artificial concurrency limit.
+Launch parallel subagents -- no artificial concurrency limit.
 
 - **Always:** `hatch3r-test-writer`, `hatch3r-security-auditor`
 - **Evaluate:** `hatch3r-docs-writer` (when APIs/architecture/UX affected)
 - **Conditional:** `hatch3r-lint-fixer`, `hatch3r-a11y-auditor`, `hatch3r-perf-profiler`, `hatch3r-dependency-auditor`, `hatch3r-architect`, `hatch3r-devops`
 
+**Specialist Prompt Enrichment:** When spawning Phase 4 specialists, include:
+- The `filesChanged` list from Phase 2 so specialists focus on affected code.
+- The review verdict summary from Phase 3 so specialists do not re-flag already-reviewed issues.
+- The `researchFindings.blastRadius` so specialists can assess downstream impact of their changes.
+
+**Phase 4 Specialist Trigger Table:**
+
+| Specialist | Mode | Trigger Conditions |
+|-----------|------|--------------------|
+| `hatch3r-test-writer` | Always | Any code change |
+| `hatch3r-security-auditor` | Always | Any code change |
+| `hatch3r-docs-writer` | Evaluate | Public API, architecture, or UX changes |
+| `hatch3r-lint-fixer` | Conditional | Lint/type errors present |
+| `hatch3r-a11y-auditor` | Conditional | UI/accessibility changes |
+| `hatch3r-perf-profiler` | Conditional | Performance-sensitive changes |
+| `hatch3r-dependency-auditor` | Conditional | Dependency files modified (package.json, go.mod, Cargo.toml, requirements.txt, Gemfile, pom.xml, pubspec.yaml, mix.exs, composer.json, and their lockfiles) |
+| `hatch3r-architect` | Conditional | Architectural decisions, new modules/services |
+| `hatch3r-devops` | Conditional | CI/CD or infrastructure changes |
+
+**Project-Type-Aware Specialist Selection:**
+
+When `PipelineContext.projectType` is available (populated from repo analysis), use the detected languages and frameworks to enrich specialist prompts with language-specific hints. For example:
+- **TypeScript/JavaScript:** Include strict mode checks for lint-fixer, framework-specific test patterns for test-writer.
+- **Python:** Include ruff/mypy hints for lint-fixer, pytest patterns for test-writer, SSTI/SQLi checks for security-auditor.
+- **Go:** Include golangci-lint for lint-fixer, govulncheck for security-auditor, table-driven test patterns for test-writer.
+- **Rust:** Include clippy lints for lint-fixer, cargo-audit for security-auditor.
+
+See `src/pipeline/pipelineContext.ts` for the full `LANGUAGE_SPECIALIST_CONFIGS` mapping.
+
 ### Phase 4 Validation Pass
 
 After all Phase 4 specialists complete, run a validation pass to catch regressions:
@@ -109,6 +153,7 @@ After all Phase 4 specialists complete, run a validation pass to catch regressio
 2. No new failures: proceed to completion.
 3. New failures: identify causing specialist, spawn `hatch3r-fixer`, re-validate (max 2 iterations).
 4. Persistent regressions: surface to user. Do not silently accept.
+5. If any specialist produced code fixes (not just findings), spawn a lightweight `hatch3r-reviewer` re-review scoped to files modified by Phase 4 specialists. This prevents specialist fixes from bypassing the Phase 3 review gate. Max 1 re-review iteration; Critical findings trigger a single fixer pass.
 
 ### Specialist Success Criteria
 
@@ -146,6 +191,15 @@ Skill-referenced agent delegations are mandatory.
 3. Launch independent subagents in parallel — maximum parallelism.
 4. Await and review results. Surface BLOCKED or PARTIAL to user.
 
+## Cross-Phase Error Propagation
+
+When a phase produces a non-SUCCESS status, the orchestrator must propagate error context to downstream phases rather than silently dropping it:
+
+1. **Phase 1 PARTIAL** (incomplete research): Include the `researchGaps` list in the implementer prompt so the implementer knows which areas lack verified context. Set implementer confidence expectations accordingly.
+2. **Phase 2 PARTIAL** (incomplete implementation): Include the `reason` field and list of unimplemented acceptance criteria in the reviewer prompt. The reviewer must distinguish between "not done yet" and "done incorrectly."
+3. **Phase 3 UNRESOLVED** (review loop exhausted): Include the unresolved findings list in the Phase 4 specialist prompts. Specialists must not introduce changes that conflict with known unresolved issues.
+4. **Phase 4 specialist FAILED**: Include the failure reason when surfacing to the user. Never report "Phase 4 failed" without specifying which specialist failed and why.
+
 ## Correlation ID
 
 Generate a UUID v4 per top-level task before Phase 1. Include in every subagent prompt as `correlation_id`. All subagents include it in logs, outputs, and status reports. Epic sub-issues get individual IDs; batch tasks share one ID with a sub-task index.
@@ -172,11 +226,37 @@ All subagents MUST map findings to this scale.
 | **SKIPPED** | Intentionally not executed. |
 | **TIMEOUT** | Time budget exceeded; forward partial output. |
 
+## Phase Skip Criteria
+
+Consistent criteria for when each pipeline phase can be safely skipped. All commands that use the pipeline MUST reference these criteria — do not invent command-specific skip rules.
+
+| Phase | Can Skip When | Mandatory Minimum (even when skipped) |
+|-------|--------------|--------------------------------------|
+| **Phase 1 (Research)** | Trivial single-line edit (typo, comment, single-value config); Tier 1 single-file change with no cross-module impact; Research already cached in PipelineContext | Affected files identified (even via quick scan); existing tests noted |
+| **Phase 2 (Implement)** | Never — implementation is always required for code changes | All changes via hatch3r-implementer (never inline except trivial items in quick-change) |
+| **Phase 3 (Review)** | All items trivial (quick-change only); documentation-only change with no code | Quality checks (lint/typecheck/test) must pass; acceptance criteria verified |
+| **Phase 4 (Quality)** | Review loop unresolved AND user chose manual resolution; documentation-only; all trivial + quality checks pass (quick-change only) | test-writer + security-auditor always required for code changes; quality checks must pass |
+
+See `src/pipeline/pipelineContext.ts` for the programmatic `PHASE_SKIP_CRITERIA` constant.
+
+## Root-Cause Depth Requirements
+
+When a pipeline phase reports a failure or unexpected result, the orchestrator must perform root-cause classification before deciding the next action:
+
+| Symptom | Shallow Fix (avoid) | Root-Cause Fix (required) |
+|---------|---------------------|---------------------------|
+| Test failure after Phase 2 | Disable or skip the failing test | Identify why the implementation breaks the test -- fix the code or update the test with justification |
+| Lint errors after Phase 4 | Add `eslint-disable` comments | Fix the underlying code pattern that triggers the lint rule |
+| Type errors after fixer changes | Cast with `as any` | Trace the type mismatch to its source and fix the type definition or usage |
+| Review loop not converging | Surface to user after 3 iterations without analysis | Classify whether findings are oscillating (fixer A breaks what fixer B fixed) and surface the conflict pattern |
+
+The orchestrator must reject superficial fixes from any subagent. If a fixer's output contains suppression patterns (disable comments, `any` casts, test skips without linked issues), classify as PARTIAL and re-run with an adjusted prompt that requests a root-cause fix.
+
 ## Task Context Protocols
 
 **Single-task plain chat:** Classify task type, create synthetic issue context, run full pipeline. For issue references, fetch details via platform CLI.
 
-**Multi-task plain chat:** Parse into discrete tasks, classify each, build dependency graph, parallelize researchers and implementers per dependency level, run review loop after all implementations, then Phase 4 specialists.
+**Multi-task plain chat:** Parse into discrete tasks, classify each, build dependency graph, parallelize researchers and implementers per dependency level, run review loop after all implementations, then Phase 4 specialists. When parallel implementers modify the same file: accept disjoint region edits, merge overlapping regions using the larger-scope change as base, and halt on semantic conflicts (contradictory interface/contract changes) for user resolution.
 
 **Auto-mode guardrails:** In unattended execution, verify scope containment, no unapproved destructive operations, and output schema compliance after each phase. Halt on violation. See `hatch3r-agent-orchestration-detail` for full guardrail specifications.
 
@@ -198,6 +278,6 @@ All `scope: always` rules apply to every task including subagent work. Include r
 - `hatch3r-dependency-management` -- dependency-auditor
 
 **Tier 3 -- On-demand:**
-- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability`
+- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`, `hatch3r-observability-tracing-detail`
 
 For limited context windows, Tier 1 is mandatory. Tier 2/3 included selectively by agent role and task scope.

package/rules/hatch3r-api-design.md

@@ -2,8 +2,9 @@
 id: hatch3r-api-design
 type: rule
 description: API endpoint and contract design patterns for the project
-scope: always
+scope: "**/api/**,**/routes/**,**/controllers/**,**/endpoints/**,**/*route*,**/*controller*,**/*endpoint*,**/*handler*,**/graphql/**,**/trpc/**"
 tags: [planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 # API Design
 

package/rules/hatch3r-api-design.mdc

@@ -1,6 +1,6 @@
 ---
 description: API endpoint and contract design patterns for the project
-alwaysApply: true
+globs: ["**/api/**", "**/routes/**", "**/controllers/**", "**/endpoints/**", "**/*route*", "**/*controller*", "**/*endpoint*", "**/*handler*", "**/graphql/**", "**/trpc/**"]
 ---
 # API Design