hatch3r 1.5.1 → 1.6.2

package/github-agents/hatch3r-docs-agent.md

@@ -3,6 +3,7 @@ name: hatch3r-docs-agent
 description: Technical writer who maintains specs, ADRs, and documentation
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 You are an expert technical writer for the project.

package/github-agents/hatch3r-lint-agent.md

@@ -3,6 +3,7 @@ name: hatch3r-lint-agent
 description: Code quality enforcer who fixes style, formatting, and type issues
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 You are a code quality engineer for the project.

package/github-agents/hatch3r-security-agent.md

@@ -3,6 +3,7 @@ name: hatch3r-security-agent
 description: Security analyst who audits code, rules, and data flows
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 You are an expert security analyst for the project.

package/github-agents/hatch3r-test-agent.md

@@ -3,6 +3,7 @@ name: hatch3r-test-agent
 description: QA engineer who writes and maintains tests
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 You are an expert QA engineer for the project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hatch3r",
-  "version": "1.5.1",
+  "version": "1.6.2",
   "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": {
@@ -20,6 +20,9 @@
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "inventory": "tsx scripts/inventory.ts",
+    "inventory:check-docs": "tsx scripts/inventory.ts --check-docs",
+    "validate:rule-parity": "tsx scripts/validate-rule-parity.ts",
     "lockfile:check": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https"
   },
   "keywords": [
@@ -78,14 +81,17 @@
     "commander": "^14.0.3",
     "inquirer": "^13.3.2",
     "ora": "^9.3.0",
+    "proper-lockfile": "^4.1.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "@types/proper-lockfile": "^4.1.4",
     "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.1.0",
     "lockfile-lint": "^5.0.0",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.57.2",
     "vitest": "^4.1.2"

package/rules/hatch3r-accessibility-standards.mdc

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

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

@@ -87,6 +87,7 @@ The TypeScript implementation of this schema with runtime validation is in `src/
 | 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. |

package/rules/hatch3r-agent-orchestration.md

@@ -30,8 +30,8 @@ Every task MUST follow this four-phase pipeline: **Phase 1 — Research** (`hatc
 | `hatch3r-implementer` | Single-task implementation | Always — one per task |
 | `hatch3r-reviewer` | Code review | Always — Phase 3 review loop |
 | `hatch3r-fixer` | Fix reviewer findings | Phase 3 — Critical/Warning findings |
-| `hatch3r-test-writer` | Tests | Always — Phase 4 (every code change) |
-| `hatch3r-security-auditor` | Security review | Always — Phase 4 (every code change) |
+| `hatch3r-test-writer` | Tests | Always — Phase 4 (every code change; skip per Phase Skip Criteria) |
+| `hatch3r-security-auditor` | Security review | Always — Phase 4 (every code change; skip per Phase Skip Criteria) |
 | `hatch3r-docs-writer` | Documentation | Phase 4 — evaluate when APIs/architecture/UX affected |
 | `hatch3r-lint-fixer` | Lint/type fixes | Conditional — lint errors present |
 | `hatch3r-a11y-auditor` | WCAG AA checks | Conditional — UI/accessibility changes |
@@ -117,7 +117,7 @@ For multi-sub-task implementations, the implementer performs a lightweight mini-
 
 Launch parallel subagents -- no artificial concurrency limit.
 
-- **Always:** `hatch3r-test-writer`, `hatch3r-security-auditor`
+- **Always** (except when Phase Skip Criteria applies — see below)**:** `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`
 
@@ -130,8 +130,8 @@ Launch parallel subagents -- no artificial concurrency limit.
 
 | Specialist | Mode | Trigger Conditions |
 |-----------|------|--------------------|
-| `hatch3r-test-writer` | Always | Any code change |
-| `hatch3r-security-auditor` | Always | Any code change |
+| `hatch3r-test-writer` | Always | Any code change; may skip per Phase Skip Criteria |
+| `hatch3r-security-auditor` | Always | Any code change; may skip per Phase Skip Criteria |
 | `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 |
@@ -196,6 +196,39 @@ 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.
 
+## Parallel Safety
+
+This section documents when spawning multiple sub-agents concurrently is safe and when it must remain sequential.
+
+### Design Rationale
+
+The pipeline's default is **linear per task** — Phase 1 → Phase 2 → Phase 3 → Phase 4, serially. `PipelineContext` captures a single logical handoff token that flows through sub-agents in sequence. LLM-driven orchestrators reason better with sequential, linearly-ordered context. Within Phase 4, parallel specialists are safe because they operate on read-only artifacts. Extending parallelism to Phases 1-3 requires explicit conditions.
+
+### Parallel-Safe Operations
+
+1. **Phase 4 Specialists** — test-writer, security-auditor, docs-writer, lint-fixer, etc. Read-only input from Phase 3 completion; independent outputs; no shared state mutation.
+2. **Intra-Phase-1 Researcher Modes** — multiple modes on the SAME task (symptom-trace + root-cause + codebase-impact) when the task is self-contained. Operate on read-only codebase; produce independent findings.
+3. **Per-Module Phase 2 Fan-Out (Disjoint `affectedFiles`)** — multi-module tasks with non-overlapping file sets; each implementer commits independently; merged post-Phase-2.
+4. **Tier 2/3 Elicitation Researchers** — parallel researchers on the same task to surface different perspectives; outputs tagged with confidence + perspective; orchestrator aggregates.
+
+### NOT Parallel-Safe
+
+1. **Cross-Phase Execution** — Phase 1 must complete before Phase 2 (Phase 2 depends on researchFindings). Phase 2 must complete before Phase 3 (review needs diff). Phase 3 must complete before Phase 4 (quality checks assume review-clean state).
+2. **Phase 3 Review Loop Iterations** — reviewer → fixer → re-reviewer must be serial.
+3. **Overlapping-File Implementers** — two Phase 2 implementers touching the same file must execute serially or use a merge-conflict detection gate.
+4. **Shared `PipelineContext` Field Writers** — if multiple agents mutate `state` / `featureFlags` / `metadata`, serialize them. Parallel agents must only READ context.
+5. **Phase 4 Validation Re-Review** — the confirmation pass after Phase 4 specialists must run serially; it checks fix-driven regressions.
+
+### Three Conditions to Parallelize
+
+ALL three must hold:
+
+1. **Read-only or disjoint writes** — agents read-only from context OR write to disjoint files/fields (no conflict zone).
+2. **Deterministic aggregation** — outputs merge without orchestrator intervention (tests: pass if all pass; findings: union).
+3. **Overhead < savings** — coordination cost (merge, conflict detection) is less than latency savings (max-of-agents vs sum-of-agents).
+
+**Default:** When in doubt, serialize. For typical hatch3r tasks (1–5 sub-tasks) the DAG-scheduling overhead often outweighs concurrency gain.
+
 ## 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:

package/rules/hatch3r-agent-orchestration.mdc

@@ -26,8 +26,8 @@ Every task MUST follow this four-phase pipeline: **Phase 1 — Research** (`hatc
 | `hatch3r-implementer` | Single-task implementation | Always — one per task |
 | `hatch3r-reviewer` | Code review | Always — Phase 3 review loop |
 | `hatch3r-fixer` | Fix reviewer findings | Phase 3 — Critical/Warning findings |
-| `hatch3r-test-writer` | Tests | Always — Phase 4 (every code change) |
-| `hatch3r-security-auditor` | Security review | Always — Phase 4 (every code change) |
+| `hatch3r-test-writer` | Tests | Always — Phase 4 (every code change; skip per Phase Skip Criteria) |
+| `hatch3r-security-auditor` | Security review | Always — Phase 4 (every code change; skip per Phase Skip Criteria) |
 | `hatch3r-docs-writer` | Documentation | Phase 4 — evaluate when APIs/architecture/UX affected |
 | `hatch3r-lint-fixer` | Lint/type fixes | Conditional — lint errors present |
 | `hatch3r-a11y-auditor` | WCAG AA checks | Conditional — UI/accessibility changes |
@@ -107,12 +107,13 @@ For multi-sub-task implementations, the implementer performs a lightweight mini-
 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. 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.
 
-- **Always:** `hatch3r-test-writer`, `hatch3r-security-auditor`
+- **Always** (except when Phase Skip Criteria applies — see below)**:** `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`
 
@@ -125,8 +126,8 @@ Launch parallel subagents -- no artificial concurrency limit.
 
 | Specialist | Mode | Trigger Conditions |
 |-----------|------|--------------------|
-| `hatch3r-test-writer` | Always | Any code change |
-| `hatch3r-security-auditor` | Always | Any code change |
+| `hatch3r-test-writer` | Always | Any code change; may skip per Phase Skip Criteria |
+| `hatch3r-security-auditor` | Always | Any code change; may skip per Phase Skip Criteria |
 | `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 |
@@ -191,6 +192,39 @@ 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.
 
+## Parallel Safety
+
+This section documents when spawning multiple sub-agents concurrently is safe and when it must remain sequential.
+
+### Design Rationale
+
+The pipeline's default is **linear per task** — Phase 1 → Phase 2 → Phase 3 → Phase 4, serially. `PipelineContext` captures a single logical handoff token that flows through sub-agents in sequence. LLM-driven orchestrators reason better with sequential, linearly-ordered context. Within Phase 4, parallel specialists are safe because they operate on read-only artifacts. Extending parallelism to Phases 1-3 requires explicit conditions.
+
+### Parallel-Safe Operations
+
+1. **Phase 4 Specialists** — test-writer, security-auditor, docs-writer, lint-fixer, etc. Read-only input from Phase 3 completion; independent outputs; no shared state mutation.
+2. **Intra-Phase-1 Researcher Modes** — multiple modes on the SAME task (symptom-trace + root-cause + codebase-impact) when the task is self-contained. Operate on read-only codebase; produce independent findings.
+3. **Per-Module Phase 2 Fan-Out (Disjoint `affectedFiles`)** — multi-module tasks with non-overlapping file sets; each implementer commits independently; merged post-Phase-2.
+4. **Tier 2/3 Elicitation Researchers** — parallel researchers on the same task to surface different perspectives; outputs tagged with confidence + perspective; orchestrator aggregates.
+
+### NOT Parallel-Safe
+
+1. **Cross-Phase Execution** — Phase 1 must complete before Phase 2 (Phase 2 depends on researchFindings). Phase 2 must complete before Phase 3 (review needs diff). Phase 3 must complete before Phase 4 (quality checks assume review-clean state).
+2. **Phase 3 Review Loop Iterations** — reviewer → fixer → re-reviewer must be serial.
+3. **Overlapping-File Implementers** — two Phase 2 implementers touching the same file must execute serially or use a merge-conflict detection gate.
+4. **Shared `PipelineContext` Field Writers** — if multiple agents mutate `state` / `featureFlags` / `metadata`, serialize them. Parallel agents must only READ context.
+5. **Phase 4 Validation Re-Review** — the confirmation pass after Phase 4 specialists must run serially; it checks fix-driven regressions.
+
+### Three Conditions to Parallelize
+
+ALL three must hold:
+
+1. **Read-only or disjoint writes** — agents read-only from context OR write to disjoint files/fields (no conflict zone).
+2. **Deterministic aggregation** — outputs merge without orchestrator intervention (tests: pass if all pass; findings: union).
+3. **Overhead < savings** — coordination cost (merge, conflict detection) is less than latency savings (max-of-agents vs sum-of-agents).
+
+**Default:** When in doubt, serialize. For typical hatch3r tasks (1–5 sub-tasks) the DAG-scheduling overhead often outweighs concurrency gain.
+
 ## 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:

package/rules/hatch3r-api-design.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-api-design
 type: rule
-description: API endpoint and contract design patterns for the project
+description: REST, GraphQL, and gRPC contract patterns covering versioning, auth, CORS, pagination, webhooks, rate limiting, and security headers
 scope: "**/api/**,**/routes/**,**/controllers/**,**/endpoints/**,**/*route*,**/*controller*,**/*endpoint*,**/*handler*,**/graphql/**,**/trpc/**"
 tags: [planning]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-api-design.mdc

@@ -1,6 +1,7 @@
 ---
-description: API endpoint and contract design patterns for the project
+description: REST, GraphQL, and gRPC contract patterns covering versioning, auth, CORS, pagination, webhooks, rate limiting, and security headers
 globs: ["**/api/**", "**/routes/**", "**/controllers/**", "**/endpoints/**", "**/*route*", "**/*controller*", "**/*endpoint*", "**/*handler*", "**/graphql/**", "**/trpc/**"]
+alwaysApply: false
 ---
 # API Design
 

package/rules/hatch3r-browser-verification.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-browser-verification
 type: rule
-description: Browser-based verification for UI and user-facing changes
+description: Playwright browser verification protocol for UI changes covering visual regression, screenshot capture, console checks, and accessibility spot-checks
 scope: conditional
 globs: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*.css,**/*.scss"
 tags: [review]

package/rules/hatch3r-browser-verification.mdc

@@ -1,5 +1,5 @@
 ---
-description: Browser-based verification for UI and user-facing changes
+description: Playwright browser verification protocol for UI changes covering visual regression, screenshot capture, console checks, and accessibility spot-checks
 globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/*.css", "**/*.scss"]
 alwaysApply: false
 ---
@@ -58,7 +58,7 @@ Commands in the "Does NOT Support" column are documentation-only, planning-only,
 
 ## Verification Protocol
 
-### 1. Ensure Dev Server is Running
+### 1. Confirm Dev Server is Running
 
 - Check if the project's dev server is already running (check terminal output or process list).
 - If not running, start it in the background using the project's dev command (e.g., `npm run dev`).
@@ -75,7 +75,7 @@ Commands in the "Does NOT Support" column are documentation-only, planning-only,
 
 ### 3. Capture Evidence
 
-- Take screenshots of the affected surfaces showing the change works correctly.
+- Take screenshots of the affected surfaces showing the change produces the expected visual and interactive result.
 - For before/after changes (visual refactors, bug fixes), capture both states when possible.
 - Note any browser console errors or warnings in the verification summary.
 - Include screenshots in the PR description or attach to the issue.

package/rules/hatch3r-ci-cd.mdc

@@ -1,6 +1,7 @@
 ---
 description: CI/CD pipeline standards covering stage gates, deployment strategies, and rollback procedures
 globs: ["**/.github/workflows/**", "**/Dockerfile*", "**/docker-compose*", "**/.gitlab-ci*", "**/Jenkinsfile", "**/azure-pipelines*", "**/.circleci/**", "**/deploy/**", "**/*pipeline*"]
+alwaysApply: false
 ---
 # CI/CD Standards
 

package/rules/hatch3r-code-standards.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-code-standards
 type: rule
-description: Code quality and file naming conventions for the project
+description: TypeScript typing discipline, naming, file size caps, Result types, barrel exports, import ordering, and monorepo boundary rules
 scope: always
 tags: [core, lang:typescript]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-code-standards.mdc

@@ -1,5 +1,5 @@
 ---
-description: Code quality and file naming conventions for the project
+description: TypeScript typing discipline, naming, file size caps, Result types, barrel exports, import ordering, and monorepo boundary rules
 alwaysApply: true
 ---
 # Code Standards
@@ -26,7 +26,7 @@ alwaysApply: true
 ### Discriminated Unions
 
 - Model domain variants with discriminated unions over polymorphic classes or `type` string checks. Every variant must share a common literal discriminant field (e.g., `kind`, `type`, `status`).
-- Use exhaustive `switch` with a `never` default case to ensure all variants are handled. The compiler will error when a new variant is added but not handled.
+- Use exhaustive `switch` with a `never` default case so the compiler errors when a new variant is added but not handled.
 
 ### Branded Types
 

package/rules/hatch3r-component-conventions.md

@@ -1,10 +1,10 @@
 ---
 id: hatch3r-component-conventions
 type: rule
-description: Rules for component development in web applications
+description: Component structure, styling tokens, loading/error/empty states, form validation timing, and accessible label patterns for Vue, React, and JSX
 scope: conditional
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
-tags: [implementation]
+globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx"
+tags: [implementation, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
 ---
 # Component Conventions

package/rules/hatch3r-component-conventions.mdc

@@ -1,5 +1,5 @@
 ---
-description: Rules for component development in web applications
+description: Component structure, styling tokens, loading/error/empty states, form validation timing, and accessible label patterns for Vue, React, and JSX
 globs: ["src/**/*.vue", "src/**/*.tsx", "src/**/*.jsx"]
 alwaysApply: false
 ---
@@ -75,7 +75,7 @@ alwaysApply: false
 - Group related fields with `<fieldset>` and `<legend>` (e.g., "Shipping Address", "Payment Details").
 - Use progressive disclosure for complex forms: show advanced options behind an expandable section or a follow-up step.
 - Autofocus the first input field on form mount.
-- Ensure tab order follows the visual layout order — never use positive `tabindex` values.
+- Verify tab order follows the visual layout order by tabbing through the form — never use positive `tabindex` values.
 
 ### Submit Behavior
 - Disable the submit button when the form has known validation errors (but keep it focusable for screen readers).

package/rules/hatch3r-data-classification.mdc

@@ -1,6 +1,7 @@
 ---
 description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
 globs: ["**/models/**", "**/schemas/**", "**/schema*", "**/database/**", "**/db/**", "**/*model*", "**/*entity*", "**/prisma/**", "**/drizzle/**", "**/*migration*"]
+alwaysApply: false
 ---
 # Data Classification Standards
 

package/rules/hatch3r-dependency-management.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-dependency-management
 type: rule
-description: Rules for managing project dependencies
+description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, and bundle-size impact gates for package manifests
 scope: "**/package.json,**/package-lock.json,**/yarn.lock,**/pnpm-lock.yaml,**/Cargo.toml,**/Cargo.lock,**/requirements*.txt,**/pyproject.toml,**/go.mod,**/go.sum,**/Gemfile*"
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-dependency-management.mdc

@@ -1,6 +1,7 @@
 ---
-description: Rules for managing project dependencies
+description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, and bundle-size impact gates for package manifests
 globs: ["**/package.json", "**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/Cargo.toml", "**/Cargo.lock", "**/requirements*.txt", "**/pyproject.toml", "**/go.mod", "**/go.sum", "**/Gemfile*"]
+alwaysApply: false
 ---
 # Dependency Management
 

package/rules/hatch3r-feature-flags.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-feature-flags
 type: rule
-description: Feature flag patterns and lifecycle for the project
+description: OpenFeature provider interface, percentage-based rollout, kill switches, stale-flag detection, audit logging, and evaluation context rules
 scope: conditional
 globs: "**/*feature-flag*,**/*featureFlag*,**/*feature_flag*,**/config/**"
 tags: [implementation]

package/rules/hatch3r-feature-flags.mdc

@@ -1,5 +1,5 @@
 ---
-description: Feature flag patterns and lifecycle for the project
+description: OpenFeature provider interface, percentage-based rollout, kill switches, stale-flag detection, audit logging, and evaluation context rules
 globs: ["**/*feature-flag*", "**/*featureFlag*", "**/*feature_flag*", "**/config/**"]
 alwaysApply: false
 ---

package/rules/hatch3r-git-conventions.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-git-conventions
 type: rule
-description: Git commit message and branching conventions
+description: Conventional Commits type list, subject line rules, breaking-change footer format, and branch naming template for type/short-description
 scope: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-git-conventions.mdc

@@ -1,6 +1,6 @@
 ---
-description: Git commit message and branching conventions
-globs: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
+description: Conventional Commits type list, subject line rules, breaking-change footer format, and branch naming template for type/short-description
+globs: ["**/.git/**", "**/.gitignore", "**/.gitattributes", "**/.gitmodules", "**/COMMIT_EDITMSG"]
 alwaysApply: false
 ---
 # Git Conventions

package/rules/hatch3r-i18n.md

@@ -3,8 +3,8 @@ id: hatch3r-i18n
 type: rule
 description: Internationalization, localization, and RTL support conventions for the project
 scope: conditional
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
-tags: [implementation]
+globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx,src/**/*.ts,**/locales/**,**/i18n/**,**/*i18n*,**/*locale*"
+tags: [implementation, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
 ---
 # Internationalization & RTL

package/rules/hatch3r-i18n.mdc

@@ -40,7 +40,7 @@ alwaysApply: false
 
 - Allow 30–40% text expansion for German/Finnish translations relative to English; test UI with pseudo-localization that pads strings.
 - Use `min-height` instead of fixed `height` on text containers to accommodate CJK line-height requirements (1.6–1.8 recommended).
-- Define font stacks per script family: Latin, CJK, Arabic, Devanagari — ensure each stack includes a web-safe fallback and `system-ui`.
+- Define font stacks per script family: Latin, CJK, Arabic, Devanagari — each stack must include a web-safe fallback and `system-ui`.
 - Truncate overflowing text with `text-overflow: ellipsis` plus `overflow: hidden` and `white-space: nowrap` only when semantically safe; provide title/tooltip with full text.
 - Avoid fixed-width containers for translatable text; prefer `min-width` / `max-width` with flex/grid layout.
 

package/rules/hatch3r-learning-consult.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-learning-consult
 type: rule
-description: Auto-consult project learnings before implementation
+description: Consult .agents/learnings/ for pitfalls, patterns, and past decisions before implementation with frontmatter-first scan and priority ordering
 scope: "**/.agents/learnings/**,**/learnings/**"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-learning-consult.mdc

@@ -1,6 +1,6 @@
 ---
-description: Auto-consult project learnings before implementation
-globs: "**/.agents/learnings/**,**/learnings/**"
+description: Consult .agents/learnings/ for pitfalls, patterns, and past decisions before implementation with frontmatter-first scan and priority ordering
+globs: ["**/.agents/learnings/**", "**/learnings/**"]
 alwaysApply: false
 ---
 # Learning Consultation

package/rules/hatch3r-migrations.mdc

@@ -1,6 +1,7 @@
 ---
 description: Database migration and schema change patterns for the project
 globs: ["**/migrations/**", "**/*migration*", "**/migrate/**", "**/seeds/**", "**/seeders/**", "**/prisma/migrations/**", "**/drizzle/**", "**/knex/**"]
+alwaysApply: false
 ---
 # Migrations
 

package/rules/hatch3r-observability-tracing-detail.mdc

@@ -34,6 +34,22 @@ Instrument the full lifecycle of an agent invocation with a dedicated span. This
 - **Required attributes:** `agent.id`, `agent.name`, `agent.parent_id`, `agent.task`, `agent.framework`
 - **Span events for state transitions:** `agent.planning`, `agent.tool_selection`, `agent.awaiting_human`, `agent.delegating`, `agent.completed`, `agent.error`
 
+```typescript
+const agentSpan = tracer.startSpan('agent.code_reviewer.invoke', {
+  attributes: {
+    'agent.id': invocationId,
+    'agent.name': 'code_reviewer',
+    'agent.parent_id': parentAgentId ?? '',
+    'agent.task': `review PR #${prNumber}`,
+    'agent.framework': 'custom',
+  },
+});
+agentSpan.addEvent('agent.planning');
+// ... agent reasoning and tool calls happen as child spans ...
+agentSpan.addEvent('agent.completed');
+agentSpan.end();
+```
+
 ## Tool Call Spans
 
 Every tool invocation by an agent creates a child span of the agent invocation span.
@@ -41,23 +57,100 @@ Every tool invocation by an agent creates a child span of the agent invocation s
 - **Span name pattern:** `tool.{tool_name}.execute`
 - **Required attributes:** `tool.name`, `tool.input_hash` (SHA-256), `tool.output_status`, `tool.duration_ms`, `tool.parameters_count`
 - Tool spans must be children of the invoking agent span. Set span status to `ERROR` when `tool.output_status` is `error` or `timeout`.
+- For tools performing I/O, create nested child spans using appropriate semantic conventions (`http.*`, `db.*`).
+
+```typescript
+const toolSpan = tracer.startSpan(
+  'tool.git_diff.execute',
+  { attributes: { 'tool.name': 'git_diff' } },
+  trace.setSpan(context.active(), agentSpan),
+);
+try {
+  const result = await tools.gitDiff(params);
+  toolSpan.setAttributes({
+    'tool.output_status': 'success',
+    'tool.duration_ms': performance.now() - startTime,
+    'tool.input_hash': hashInput(params),
+  });
+} catch (err) {
+  toolSpan.setAttributes({ 'tool.output_status': 'error' });
+  toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+  toolSpan.recordException(err);
+  throw err;
+} finally {
+  toolSpan.end();
+}
+```
 
 ## LLM Request/Response Tracing
 
 - **Span name pattern:** `gen_ai.{operation}` (e.g., `gen_ai.chat`, `gen_ai.completion`)
-- **Token tracking:** Capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. Aggregate in metrics.
+- **Token tracking:** Capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. Aggregate in metrics: Counter `gen_ai.tokens_total` with labels `{direction, model, agent_name}`, Histogram `gen_ai.request_duration_ms`.
 - **Model version tracking:** Record both `gen_ai.request.model` and `gen_ai.response.model` for drift detection.
-- **Retry spans:** Each retry attempt is a separate child span. Set `gen_ai.request.retries` on the final span.
-- Never log raw prompt content or full model responses as span attributes.
+- **Retry spans:** Each retry attempt is a separate child span. Set `gen_ai.request.retries` on the final span. Record `http.response.status_code` on failed spans (429 vs 500+).
+- Never log raw prompt content or full model responses as span attributes. Use token counts for cost tracking and correlated logs for prompt debugging in non-production environments.
+- Sample GenAI spans at 50-100% in production (higher than general spans) because each call is expensive and low volume.
 
 ## Tool Call Audit Trail
 
-Maintain a structured audit log for every tool invocation in agentic workflows. Key fields: `tool.name`, `tool.input_hash`, `tool.output_status`, `tool.duration_ms`, `agent.id`, `agent.name`, `correlation.id`, `timestamp`, `session.id`. Retain for 90 days minimum.
+Maintain a structured audit log for every tool invocation in agentic workflows, separate from tracing spans.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool.name` | string | Name of the tool invoked |
+| `tool.input_hash` | string | SHA-256 hash of tool input (never log raw input) |
+| `tool.output_status` | string | `success`, `error`, `timeout`, or `denied` |
+| `tool.duration_ms` | float | Execution time in milliseconds |
+| `agent.id` | string | ID of the invoking agent |
+| `agent.name` | string | Human-readable agent name |
+| `correlation.id` | string | Trace correlation ID |
+| `timestamp` | string | ISO 8601 timestamp |
+| `session.id` | string | Session identifier |
+
+- Log tool invocations at `info` level, failures at `error` level with `error.type` and `error.message`.
+- Aggregate tool call counts per agent per session for anomaly detection.
+- Retain audit logs for a minimum of 90 days.
 
 ## Correlation IDs for Agent Workflows
 
-- Use UUIDv4 with workflow-type prefix: `{workflow-type}-{uuid}`.
+- Use UUIDv4 with workflow-type prefix: `{workflow-type}-{uuid}` (e.g., `agent-run-550e8400-...`).
 - Generate at the workflow entry point. Propagate to all sub-agents and tool calls.
 - Every log entry, span, and metric must include `correlation.id`.
 - Cross-process: propagate via `X-Correlation-ID` header alongside W3C Trace Context.
-- Use OpenTelemetry `SpanLink` for cross-workflow references.
+- Use OpenTelemetry `SpanLink` for cross-workflow references (e.g., agent run triggered by CI event).
+
+```typescript
+import { randomUUID } from 'node:crypto';
+import { context, trace, SpanStatusCode } from '@opentelemetry/api';
+
+function generateCorrelationId(workflowType: string): string {
+  return `${workflowType}-${randomUUID()}`;
+}
+
+async function runAgentWorkflow(task: string): Promise<void> {
+  const correlationId = generateCorrelationId('agent-run');
+  const tracer = trace.getTracer('agent-orchestrator');
+  const rootSpan = tracer.startSpan('agent.orchestrator.invoke', {
+    attributes: {
+      'correlation.id': correlationId,
+      'agent.name': 'orchestrator',
+      'agent.task': task,
+    },
+  });
+  try {
+    await context.with(trace.setSpan(context.active(), rootSpan), async () => {
+      await delegateToSubAgent('code_reviewer', {
+        correlationId,
+        parentSpanId: rootSpan.spanContext().spanId,
+        task: 'review changes',
+      });
+    });
+  } catch (err) {
+    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: (err as Error).message });
+    rootSpan.recordException(err as Error);
+    throw err;
+  } finally {
+    rootSpan.end();
+  }
+}
+```