hatch3r 1.7.5 → 1.9.0

package/{agents → dist/content/agents}/hatch3r-reviewer.md

@@ -4,7 +4,7 @@ type: agent
 description: Expert code reviewer for the project. Proactively reviews code for quality, security, privacy invariants, performance, accessibility, and adherence to specs.
 protected: true
 model: standard
-tags: [core, review]
+tags: [review, floor:protocol]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 efficiency_tier: standard
@@ -36,7 +36,7 @@ Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<con
 
 ## 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.
+Before completing a review, consult the project quality checks in `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>
 
@@ -50,7 +50,7 @@ Before reviewing, scan `docs/specs/` (if present) for specifications relevant to
 
 ## Review Checklist
 
-Verify compliance with `.agents/rules/hatch3r-security-patterns.md`, `.agents/rules/hatch3r-code-standards.md`, and `.agents/rules/hatch3r-testing.md` across all review items:
+Verify compliance with `rules/hatch3r-security-patterns.md`, `rules/hatch3r-code-standards.md`, and `rules/hatch3r-testing.md` across all review items:
 
 1. **Correctness:** Does the code do what the issue/spec requires?
 2. **Privacy invariants:** No sensitive content in events/cloud data. Metadata allowlisted. Redaction defaults. Sensitive collections deny-all client access.
@@ -79,7 +79,7 @@ Verify compliance with `.agents/rules/hatch3r-security-patterns.md`, `.agents/ru
     - **SLO + burn-rate alert:** user-facing route has an SLO file and a multi-window multi-burn-rate alert (2%/5%/10%); raw threshold alerts on a critical route flagged as Warning.
     - **Error tracker wired:** unhandled errors reach Sentry-class tooling with `release` tag, source maps, and PII scrubber. Releases without the release tag are Critical.
 
-    Cross-reference: `skills/hatch3r-observability-verify` and `rules/hatch3r-observability.md`. Findings reuse the severity vocabulary above.
+    Cross-reference: `skills/hatch3r-observability-verify` and `rules/hatch3r-observability-metrics.md`. Findings reuse the severity vocabulary above.
 
 14. **migration.review:** Evaluate schema and event-schema changes for safe deploy semantics:
     - **Expand-contract pattern:** the diff stages expand, migrate, contract across separate deploys; a single-deploy destructive change is Critical.
@@ -260,6 +260,8 @@ 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.
 
+After the loop exits clean, Phase 4 specialists run bounded by `max_phase4_parallel` (default `3`, env-overridable via `HATCH3R_MAX_PHASE4_PARALLEL`). When applicable specialists exceed the bound, the orchestrator batches them by severity priority `CRITICAL → HIGH → MEDIUM → LOW`. Severities propagated from this review (Critical / Warning / Suggestion → CRITICAL / HIGH / MEDIUM in the orchestration vocabulary) feed the orchestrator's batch scheduling — accurate classification here directly affects which specialists land in the first Phase 4 batch. See `rules/hatch3r-agent-orchestration.md` Phase 4 — Final Quality for batching semantics.
+
 <rules>
 
 ## Boundaries

package/{agents → dist/content/agents}/hatch3r-security-auditor.md

@@ -4,7 +4,7 @@ type: agent
 description: Security analyst who audits database rules, cloud functions, event metadata, and data flows. Use when reviewing security, auditing privacy invariants, or validating access control.
 protected: true
 model: standard
-tags: [review, security]
+tags: [review, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 efficiency_tier: standard
@@ -28,7 +28,7 @@ Before any action, scan the brief for unresolved questions in scope, acceptance
 
 ## Critical Invariants to Enforce
 
-Follow the security patterns defined in `.agents/rules/hatch3r-security-patterns.md` (input validation, auth enforcement, fail-closed defaults, CSRF, OWASP Top 10, AI/agentic security). In addition, enforce these project-specific invariants:
+Follow the security patterns defined in `rules/hatch3r-security-patterns.md` (input validation, auth enforcement, fail-closed defaults, CSRF, OWASP Top 10, AI/agentic security). In addition, enforce these project-specific invariants:
 
 - **Data pipeline:** No sensitive content anywhere in the data pipeline
 - **Metadata:** Event metadata validated against allowlist (client AND server)

package/{agents → dist/content/agents}/hatch3r-test-writer.md

@@ -4,7 +4,7 @@ type: agent
 description: QA engineer who writes deterministic, isolated tests. Covers unit, integration, E2E, security rules, and contract tests.
 model: standard
 protected: true
-tags: [core, review]
+tags: [review, floor:protocol]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 efficiency_tier: standard
@@ -37,7 +37,7 @@ Before any action, scan the brief for unresolved questions in scope, acceptance
 
 ## Test Standards
 
-Follow the full testing standards defined in `.agents/rules/hatch3r-testing.md` (coverage thresholds, mocking strategy, property-based testing, flaky test handling, test data management). Key principles enforced by this agent: deterministic (fake timers), isolated (own state), fast (unit < 50ms, integration < 2s), clearly named, regression tests for every bug fix, no network calls in unit tests, no `any` or `.skip` without a linked issue.
+Follow the full testing standards defined in `rules/hatch3r-testing.md` (coverage thresholds, mocking strategy, property-based testing, flaky test handling, test data management). Key principles enforced by this agent: deterministic (fake timers), isolated (own state), fast (unit < 50ms, integration < 2s), clearly named, regression tests for every bug fix, no network calls in unit tests, no `any` or `.skip` without a linked issue.
 
 ## Commands
 

package/{agents → dist/content/agents}/shared/external-knowledge.md

@@ -10,7 +10,7 @@ cache_friendly: true
 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`).
+- Use the project's configured platform CLI (check `platform` in `.hatch3r/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 → dist/content/agents}/shared/injection-patterns.md

@@ -41,7 +41,7 @@ Adding a pipeline pattern: append a new `P-PIPE-NN` row here, add the RegExp ent
 
 ### 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.
+Scope: content written to `.hatch3r/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 |
 |-----------|-------------|-----------------------------|-------------|

package/{agents → dist/content/agents}/shared/quality-charter.md

@@ -6,6 +6,8 @@ efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 ---
 
+> Last updated: 2026-05-26
+
 ## Agent Quality Charter
 
 All agents operating under hatch3r should embody these behavioral standards. This charter is the single source of truth for agent conduct — referenced by content artifacts and verified by the weekly audit cycle.
@@ -60,6 +62,8 @@ Every recommendation should account for its impact on:
 
 When stakeholder interests conflict, note the tradeoff explicitly and recommend based on the project's stated priorities.
 
+Apply the subset of stakeholders relevant to the project's declared maturity tier (solo / team / scaleup / enterprise per `hatch3r config maturity`). **Solo:** end user + maintaining developer (you). **Team:** + team lead. **Scaleup:** + ops team. **Enterprise:** + compliance + security review. When the tier is unknown, default to solo and ask via `agents/shared/user-question-protocol.md`.
+
 ### 6. Fail Gracefully
 
 When prerequisites are missing, inputs are invalid, or unexpected conditions arise:
@@ -98,7 +102,11 @@ When modifying code that is consumed by other modules, agents, or external syste
 - If a contract change is necessary, document it explicitly in the structured output and flag for reviewer attention.
 - Prefer additive changes (new optional fields, overloaded signatures) over breaking changes.
 
-### 10. Standardized Iteration Summary
+### 10. Consult Prior Learnings
+
+Before answering project-specific questions about prior work, decisions, or resolved issues, read `.hatch3r/learnings/INDEX.md` (when present) and any topic-applies index entries matched against the current task. Cite the consulted entry IDs in the structured output. Implementer + Reviewer + Researcher agents are bound; other roles consult when context applies.
+
+### 11. Standardized Iteration Summary
 
 Every user-facing iteration ends with the canonical Iteration Summary block defined in `rules/hatch3r-iteration-summary.md`.
 
@@ -106,6 +114,26 @@ Required fields: Status (closed enum: SUCCESS | PARTIAL | FAILED | BLOCKED), Out
 
 Never substitute a prose paragraph for the block. Never silently skip Not Done — if scope was fully completed, write `None — full scope completed`. Never inflate confidence — if you did not verify, say medium and name the unknown.
 
+### 12. Anti-Duplication Procedure
+
+Before writing implementation code: run a codebase pattern search (grep for similar function names, similar type shapes, similar comment headers); report findings in the structured output. After writing: run a duplication scan (jscpd or equivalent) against the affected directories; flag any block matching ≥30 lines or ≥80% similarity with existing code. Refactor or justify before merge; silent duplication is a P4 violation.
+
+### 13. Adversarial Thinking
+
+For any non-trivial design choice, hold an internal adversarial review: what is the strongest case AGAINST this approach? What edge case breaks it? What stakeholder loses under this choice? Surface the counter-argument in the structured output alongside the chosen approach.
+
+### 14. Severity Discipline
+
+When classifying issues (bugs, code smells, design concerns), apply the severity taxonomy from `governance/AUDIT.md` §Severity Taxonomy (Critical / High / Medium / Low / Info). Calibrate against blast radius + reversibility + user impact. Critical reserved for production-blocking; Low/Info for cosmetic-only.
+
+### 15. Currency Verification
+
+Every external claim (library version, API behavior, platform feature) is verified against current official documentation (≤180 days). When sources conflict, prefer the publication with the most recent access date. CLI tools (`gh`, `curl`, `jq`) preferred over training-data recall.
+
+### 16. Senior-Engineer Outside-In Posture
+
+Approach every task from the perspective of a senior engineer with an outside-in user-facing perspective: the user judges by user-visible quality (UI/UX, performance, error recovery), not internal cleverness. Solve for user-visible quality first; refactor for maintainability second. When trade-offs surface between internal elegance and user-facing correctness, choose user-facing correctness.
+
 ### UI/UX quality (for agent-produced output in end-user projects)
 
 When an agent produces UI for an end-user project, the charter binds it to these criteria. Each is measurable; each is a regression if missed.
@@ -123,8 +151,8 @@ Cross-reference: this section is audited under D10 SA10.9 (`governance/audit/dom
 
 When an agent produces a service that handles a request, the charter binds it to these criteria. Each is measurable.
 
-- **OpenTelemetry spans on request path:** every inbound request and every outbound call (DB, HTTP, queue, RPC) emits an OTel span with `trace_id` and `span_id` propagated end-to-end; instrumented-route ratio = 100% (no silent paths). Reference `rules/hatch3r-observability.md`.
-- **Structured logs with trace correlation:** every log line is JSON, carries `trace_id`, includes service name + version + environment, and uses log levels mapped to severity. Stack traces emitted on `error`. Reference `rules/hatch3r-observability.md`.
+- **OpenTelemetry spans on request path:** every inbound request and every outbound call (DB, HTTP, queue, RPC) emits an OTel span with `trace_id` and `span_id` propagated end-to-end; instrumented-route ratio = 100% (no silent paths). Reference `rules/hatch3r-observability-tracing.md` and `rules/hatch3r-observability-logging.md`.
+- **Structured logs with trace correlation:** every log line is JSON, carries `trace_id`, includes service name + version + environment, and uses log levels mapped to severity. Stack traces emitted on `error`. Reference `rules/hatch3r-observability-tracing.md` and `rules/hatch3r-observability-logging.md`.
 - **RED + USE metrics on user-facing services:** Rate, Errors, Duration per route plus Utilization, Saturation, Errors per resource. Histograms over averages on latency.
 - **SLO with multi-window multi-burn-rate alerts:** every user-facing service declares an availability + latency SLO; alerts use the 2%/5%/10% multi-window multi-burn-rate pattern (Google SRE workbook), not raw threshold alerts.
 - **Error tracker with PII scrubbing:** Sentry-class tooling with source-map upload, release tag, environment tag, and an allowlist scrubber for known PII fields before egress.

package/{agents → dist/content/agents}/shared/user-content-templates.md

@@ -12,7 +12,7 @@ Canonical reference for the body and frontmatter shapes `hatch3r-creator` produc
 
 ### 1. Agent Skeleton
 
-**Path:** `.agents/user/agents/<NAME>.md`. **Required:** `id`, `description`, `model`, `tags`. **Optional:** `protected` (always `false` for user agents), `quality_charter` (auto-injected), `adapters` (restricts adapter propagation when present).
+**Path:** `.hatch3r/overrides/agents/<NAME>.md`. **Required:** `id`, `description`, `model`, `tags`. **Optional:** `protected` (always `false` for user agents), `quality_charter` (auto-injected), `adapters` (restricts adapter propagation when present).
 
 ```yaml
 ---
@@ -55,11 +55,36 @@ Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<con
 - **Always:** <ALWAYS-1>
 - **Never:** <NEVER-1>
 </rules>
+
+## Confidence Expression
+Per `agents/shared/quality-charter.md` §1 and `governance/audit/templates/rigor-contract.md`, rate every recommendation and decision as **high**, **medium**, or **low** confidence and name the basis (direct measurement, sampled observation, inference from analogue).
+
+- **High:** Verified against the specific code/document path read this turn (<FILE-OR-FIXTURE-VERIFIED>).
+- **Medium:** Pattern-based on convention or analogue (<NAMED-PATTERN-OR-ANALOGUE>); not fully traced.
+- **Low:** Best professional judgment without verification (<UNKNOWN-OR-MISSING-INPUT>); recommend human review before acting.
+
+Emit confidence in the structured result block above. Dropping the field is a charter violation.
+
+## Failure Modes
+| Failure | Status | Recovery |
+|---|---|---|
+| <KNOWN-FAILURE-1> | BLOCKED | <RECOVERY-1> |
+| <KNOWN-FAILURE-2> | PARTIAL | <RECOVERY-2> |
+| Ambiguous input that maps to ≥2 reasonable interpretations | BLOCKED | Apply `agents/shared/user-question-protocol.md` before any write. |
+| Required input missing | BLOCKED | Surface a single multiple-choice question naming the missing field and a safe default. |
+| Underlying tool error (filesystem, network, sub-agent timeout) | BLOCKED | Surface the error verbatim; do not silent-retry. |
+
+## Quality Charter
+This agent inherits `agents/shared/quality-charter.md` via the frontmatter `quality_charter:` field. The charter binds: §1 confidence levels, §4 root-cause reporting, §6 fail-gracefully, §7 measurable criteria, §8 escalate-ambiguity-early, §10 standardized iteration summary. List below any agent-specific section overrides — if none, write `None — full charter applies`:
+
+- <CHARTER-OVERRIDE-OR-NONE>
 ```
 
+The three sections above (Confidence Expression, Failure Modes, Quality Charter) are required on every user-authored agent. `hatch3r-creator` injects placeholders during composition and reports `gentleWarnings` when any section is missing or left unsubstituted at save time.
+
 ### 2. Skill Skeleton
 
-**Path:** `.agents/user/skills/<NAME>/SKILL.md` inside a new directory created via `mkdir -p`. The layout matches the canonical pattern at `skills/hatch3r-<name>/SKILL.md`. **Required:** `id`, `description`, `tags`. **Optional:** `quality_charter` (auto-injected).
+**Path:** `.hatch3r/overrides/skills/<NAME>/SKILL.md` inside a new directory created via `mkdir -p`. The layout matches the canonical pattern at `skills/hatch3r-<name>/SKILL.md`. **Required:** `id`, `description`, `tags`. **Optional:** `quality_charter` (auto-injected).
 
 ```yaml
 ---
@@ -100,7 +125,7 @@ Recommended step count: 3-7. Skills with more than 7 steps trigger a gentle warn
 
 ### 3. Rule Skeleton
 
-**Path:** `.agents/user/rules/<NAME>.md` plus the auto-generated companion `.agents/user/rules/<NAME>.mdc`. The `.md` is canonical; `.mdc` is generated by `saveUserContent` using the `.md → .mdc` scope transform from `rules/hatch3r-content-authoring.md`. **Required:** `id`, `type`, `description`, `scope`, `tags`. **Required when scope=conditional:** `globs`. **Optional:** `precedence` (default `normal`), `quality_charter` (auto-injected).
+**Path:** `.hatch3r/overrides/rules/<NAME>.md` plus the auto-generated companion `.hatch3r/overrides/rules/<NAME>.mdc`. The `.md` is canonical; `.mdc` is generated by `saveUserContent` using the `.md → .mdc` scope transform from `rules/hatch3r-content-authoring.md`. **Required:** `id`, `type`, `description`, `scope`, `tags`. **Required when scope=conditional:** `globs`. **Optional:** `precedence` (default `normal`), `quality_charter` (auto-injected).
 
 Three scope shapes (pick one):
 
@@ -143,10 +168,10 @@ The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a s
 
 ### 4. Command Skeleton
 
-**Path:** `.agents/user/commands/<NAME>.md`. **Required:** `id`, `type`, `description`, `orchestrator`, `tags`. **Required when orchestrator=true:** `agentPipeline` (non-empty array). **Optional:** `quality_charter` (auto-injected). Two variants follow; pick by the `orchestrator` value.
+**Path:** `.hatch3r/overrides/commands/<NAME>.md`. **Required:** `id`, `type`, `description`, `orchestrator`, `tags`. **Required when orchestrator=true:** `agentPipeline` (non-empty array). **Optional:** `quality_charter` (auto-injected). Two variants follow; pick by the `orchestrator` value.
 
 ```yaml
-# 4a. Inline command — orchestrator: false. Modeled after commands/hatch3r-recipe.md.
+# 4a. Inline command — orchestrator: false. Modeled after commands/hatch3r-debug.md.
 ---
 id: <NAME>
 type: command
@@ -158,7 +183,7 @@ quality_charter: agents/shared/quality-charter.md
 ```
 
 ```yaml
-# 4b. Orchestrator command — orchestrator: true. Modeled after commands/hatch3r-board-init.md.
+# 4b. Orchestrator command — orchestrator: true. Modeled after commands/hatch3r-board-fill.md.
 ---
 id: <NAME>
 type: command
@@ -190,9 +215,12 @@ This command runs as a single orchestrator without sub-agent delegation.
 - <GUARDRAIL-1>
 ```
 
-Body skeleton — 4b orchestrator (Phase 1 collect, Phase 2 delegate, Phase 3 housekeeping):
+Body skeleton — 4b orchestrator (Step 0 detect ambiguity, Phase 1 collect, Phase 2 delegate, Phase 3 housekeeping):
 
 ```markdown
+## §0 Detect Ambiguity (P8 B1)
+Before any action, scan the user's request for unresolved questions in scope, target artifact, irreversibility, or constraint conflicts (multiple matching files, missing acceptance criteria, ambiguous "small" boundary, conflicting requirements). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. ASK rules in Phase 1 remain in force for residual ambiguity discovered mid-workflow.
+
 ## Agent Pipeline
 This command runs as an orchestrator. After collecting inputs in Phase 1, it delegates to <AGENT-ID-1> via the Task tool.
 # <TITLE>
@@ -211,11 +239,13 @@ Use the Task tool to invoke <AGENT-ID-1>. Pass collected slots as structured inp
 - <GUARDRAIL-1>
 ```
 
+The §0 block is required on every user-authored orchestrator command per CONSTITUTION §2 P8 B1 (Clarification-First, Default-Path). It must reference `agents/shared/user-question-protocol.md` verbatim — `hatch3r-creator` rejects orchestrator commands whose §0 block is missing the reference (strict gate, see D20 SA20.1 audit checklist).
+
 The strict gate `validateCommandOrchestratorFrontmatter` (`src/cli/commands/validate.ts:171`) rejects `orchestrator: true` without a non-empty `agentPipeline` array.
 
 ### 5. Hook Skeleton
 
-**Path:** `.agents/user/hooks/<NAME>.md`. **Required:** `id`, `type`, `event`, `agent`, `description`, `tags`. **Optional:** `globs` (file-save filtering), `condition`, `quality_charter` (auto-injected). **Event enum:** `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`, enforced by `isValidHookEvent` (`src/hooks/types.ts:30`).
+**Path:** `.hatch3r/overrides/hooks/<NAME>.md`. **Required:** `id`, `type`, `event`, `agent`, `description`, `tags`. **Optional:** `globs` (file-save filtering), `condition`, `quality_charter` (auto-injected). **Event enum:** `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`, enforced by `isValidHookEvent` (`src/hooks/types.ts:30`).
 
 ```yaml
 ---
@@ -244,14 +274,14 @@ When this hook fires, the assigned agent should:
 <DESCRIBES-WHAT-THE-AGENT-RETURNS-OR-WRITES>
 ```
 
-The `agent` field must reference an existing agent — canonical (e.g., `lint-fixer` resolves to `agents/hatch3r-lint-fixer.md`) or under `.agents/user/agents/`. Missing references are rejected at strict-gate time.
+The `agent` field must reference an existing agent — canonical (e.g., `lint-fixer` resolves to `agents/hatch3r-lint-fixer.md`) or under `.hatch3r/overrides/agents/`. Missing references are rejected at strict-gate time.
 
 ## Reference Implementations
 
-For each user type, mirror the canonical shape below — minus the `hatch3r-` filename prefix; the user-tier path is always under `.agents/user/{type}/`:
+For each user type, mirror the canonical shape below — minus the `hatch3r-` filename prefix; the user-tier path is always under `.hatch3r/overrides/{type}/`:
 
 - **Agent:** `agents/hatch3r-implementer.md` (full body) or `agents/hatch3r-fixer.md` (compact body).
 - **Skill:** `skills/hatch3r-bug-fix/SKILL.md` or `skills/hatch3r-feature/SKILL.md`.
 - **Rule:** `rules/hatch3r-deep-context.md` (`scope: always`) or `rules/hatch3r-component-conventions.md` (`scope: conditional`).
-- **Command:** `commands/hatch3r-recipe.md` (inline) or `commands/hatch3r-board-init.md` (orchestrator).
+- **Command:** `commands/hatch3r-debug.md` (inline) or `commands/hatch3r-board-fill.md` (orchestrator).
 - **Hook:** `hooks/hatch3r-pre-commit.md` (with globs) or `hooks/hatch3r-session-start.md` (always-fire).

package/{agents → dist/content/agents}/shared/user-question-protocol.md

@@ -6,6 +6,8 @@ tags: [shared, ux, p1, p4]
 cache_friendly: true
 ---
 
+> Last updated: 2026-05-26
+
 ## Purpose
 
 This protocol defines how hatch3r agents and commands surface clarifying or triage questions to the user across the 15 supported AI coding platforms. It is the single source of truth for the *how* of asking; the *whether* is governed by [quality-charter §3 "Question Unclear Requirements"](./quality-charter.md) and §8 "Escalate Ambiguity Early". Files that reference this protocol: the requirements-elicitation mode (`agents/modes/requirements-elicitation.md`), the five ASK-checkpoint commands, and the four ask-prone agents — researcher, fixer, architect, implementer.

package/{commands → dist/content/commands}/board/pickup-azure-devops.md

@@ -56,7 +56,7 @@ Follow the **Azure Boards Work Item State Sync** from `commands/board/shared-azu
 **Create PR:**
 `az repos pr create --org https://dev.azure.com/{namespace} --project {project} --source-branch {branch} --target-branch {base} --title "..." --description "..."` (fall back to `create_pull_request` MCP).
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link PR to epic:**
 `az boards work-item relation add --id {epic_id} --relation-type "ArtifactLink" --target-id {pr_id}` or link via PR description.

package/{commands → dist/content/commands}/board/pickup-delegation-multi.md

@@ -78,8 +78,8 @@ For each dependency level, starting at Level 1:
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
    - Documentation references relevant to this sub-issue.
    - Instruction to follow the hatch3r-implementer agent protocol.
-   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
    - Instruction to use GitHub MCP for issue reads, and follow the project's tooling hierarchy for external knowledge augmentation.
    - Explicit instruction: do NOT create branches, commits, or PRs.
    - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
@@ -147,8 +147,8 @@ For each dependency level, starting at Level 1:
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3).
    - Documentation references relevant to this issue.
    - Instruction to follow the **hatch3r-implementer agent protocol**.
-   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
    - Explicit instruction: do NOT create branches, commits, or PRs.
    - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 

package/{commands → dist/content/commands}/board/pickup-delegation.md

@@ -57,8 +57,8 @@ The implementer sub-agent prompt MUST include:
 - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
 - Documentation references relevant to this issue.
 - Instruction to follow the **hatch3r-implementer agent protocol**.
-- All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-- Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+- All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+- Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
 - Explicit instruction: do NOT create branches, commits, or PRs.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
@@ -97,7 +97,7 @@ Launch as many independent sub-agents in parallel as the platform supports.
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow (e.g., "Follow the hatch3r-reviewer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` (subagents do not inherit rules automatically).
+- All `scope: always` rule directives from `rules/` (subagents do not inherit rules automatically).
 - The diff or file changes to review.
 - The issue's acceptance criteria.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.

package/{commands → dist/content/commands}/board/pickup-github.md

@@ -56,7 +56,7 @@ Follow the **GitHub Projects V2 Sync** from `commands/board/shared-github.md` fo
 **Create PR:**
 `gh pr create -R {owner}/{repo} --head {branch} --base {base} --title "..." --body "..."` (fall back to `create_pull_request` MCP).
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link PR to epic:**
 `gh issue comment {epic} -R {owner}/{repo} --body "PR: #{pr_number}"` (fall back to `add_issue_comment` MCP).

package/{commands → dist/content/commands}/board/pickup-gitlab.md

@@ -56,7 +56,7 @@ Follow the **GitLab Board Label-Based Sync** from `commands/board/shared-gitlab.
 **Create MR:**
 `glab mr create -R {namespace}/{project} --source-branch {branch} --target-branch {base} --title "..." --description "..."`. Use `Closes #N` syntax in the description for auto-close on merge.
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link MR to epic:**
 Reference the epic issue number in the MR description. GitLab auto-links MRs to issues mentioned with `Closes #N`.

package/{commands → dist/content/commands}/board/pickup-post-impl.md

@@ -118,7 +118,7 @@ After the PR merges and `Closes #N` auto-closes the referenced issue(s), confirm
    ```
    Record the mutation in the run cache under `updated_issues`.
 
-2. **Board state check.** Read `board.workflows.itemClosedEnabled` from `.agents/hatch.json`:
+2. **Board state check.** Read `board.workflows.itemClosedEnabled` from `.hatch3r/hatch.json`:
    - **If true:** The V2 built-in "Item closed" workflow has already set the board status to Done. Skip to step 3.
    - **If false or absent:** The workflow is not enabled (board-init should have halted, but this is a defensive fallback). Apply the full **Board Sync Procedure** from `hatch3r-board-shared` for each issue, target status = Done.
 
@@ -142,7 +142,7 @@ After PR creation, capture learnings from this development session.
    - Were any pitfalls discovered that should be avoided next time?
 
 2. If learnings are identified:
-   - Create learning files in `.agents/learnings/` following the learning file format (see `hatch3r-learn` command).
+   - Create learning files in `.hatch3r/learnings/` following the learning file format (see `hatch3r-learn` command).
    - Include the issue number as `source-issue`.
    - Tag with relevant area labels from the issue.
    - **ASK:** "Learnings captured: {list}. Anything else to note? (add more / done)"

package/{commands → dist/content/commands}/board/shared-azure-devops.md

@@ -56,7 +56,7 @@ Use `az devops` / `az boards` / `az repos` CLI. Issues = Work Items. PRs = Pull
 
 ## Azure DevOps Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Organization:** top-level `owner` (maps to Azure DevOps organization name)
 - **Project:** top-level `repo` (maps to Azure DevOps project name)

package/{commands → dist/content/commands}/board/shared-github.md

@@ -56,7 +56,7 @@ Use `gh` CLI and GitHub MCP tools. Issues = GitHub Issues. PRs = Pull Requests.
 
 ## GitHub Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Owner:** top-level `owner` (fallback: `board.owner`)
 - **Repository:** top-level `repo` (fallback: `board.repo`)
@@ -89,7 +89,7 @@ If `board.projectNumber` is not null, verify via `gh project view {board.project
 
 **Status label → Projects v2 option mapping:**
 
-Read the mapping from `board.statusOptions` in `.agents/hatch.json`:
+Read the mapping from `board.statusOptions` in `.hatch3r/hatch.json`:
 
 | Label                | Option ID from hatch.json          |
 | -------------------- | ---------------------------------- |

package/{commands → dist/content/commands}/board/shared-gitlab.md

@@ -49,7 +49,7 @@ GitLab MCP tools are not currently available. All operations use the `glab` CLI.
 
 ## GitLab Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Namespace:** top-level `owner` (GitLab group or user namespace)
 - **Project:** top-level `repo` (GitLab project name)

package/{commands → dist/content/commands}/hatch3r-api-spec.md

@@ -10,8 +10,15 @@ efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 3
+  rationale: Three-stage pipeline per agentPipeline — researcher scans routes, docs-writer assembles the OpenAPI spec, reviewer validates structure; researcher and reviewer fanned out concurrently around the shared docs-writer dependency.
 ---
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 ## Agent Pipeline
 
 | Stage | Agent(s) | Parallel | Required |
@@ -29,7 +36,7 @@ Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 sp
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
 
 **Read the `hatch3r-api-design` rule** if it exists. This rule contains the project's API design conventions (naming, versioning, error shapes, pagination patterns) that the generated spec must conform to.
 

package/{commands → dist/content/commands}/hatch3r-benchmark.md

@@ -10,8 +10,15 @@ efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 3
+  rationale: Three-stage pipeline per agentPipeline — researcher gathers prior baselines, perf-profiler executes the suite, docs-writer assembles the report; each receives the run cache and emits a structured slice.
 ---
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 ## Agent Pipeline
 
 | Stage | Agent(s) | Parallel | Required |
@@ -29,7 +36,7 @@ Run performance benchmarks against a target (file, function, endpoint, or full s
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that may be useful for regression issue creation. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that may be useful for regression issue creation. Cache any values found.
 
 ## Token-Saving Directives
 

package/{commands → dist/content/commands}/hatch3r-board-fill.md

@@ -4,14 +4,21 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-reviewer, hatch3r-fixer]
 description: Create epics and issues/work items from todo.md, reorganize the board with dependency analysis, readiness assessment, and implementation ordering. Supports GitHub, Azure DevOps, and GitLab.
-tags: [board, team]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 2
+  rationale: Two specialist agents per issue — Step 7.9 fans out one hatch3r-reviewer per issue plus one hatch3r-fixer per accepted finding; batch mode scales reviewer count to N issues with serialization only on the per-issue reviewer→fixer hand-off.
 ---
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 ## Agent Pipeline
 
 | Stage | Agent(s) | Parallel | Required |
@@ -24,7 +31,7 @@ All issue operations MUST follow the Board Sync Enforcement rules defined in `ha
 
 # Board Fill -- Create Epics & Issues from todo.md + Board Reorganization
 
-Create epics (with sub-issues) or standalone issues/work items from items in `todo.md`, using the platform's CLI and MCP tools against **{owner}/{repo}** (read from `.agents/hatch.json` board config). The `platform` field determines whether to use GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Before creating anything, board-fill **triages each item through interactive questioning** to extract scope, intent, unknowns, and acceptance criteria from the user -- ensuring issues are genuinely ready for implementation, not just structurally complete. On every run, board-fill also performs a **full board reorganization**: grouping standalone issues into epics, decomposing oversized items, analyzing dependencies, setting implementation order, identifying parallel work, and marking issues as `status:ready` when all readiness criteria (structural + substantive) are met. AI proposes groupings, dependencies, and ordering; user confirms before anything is created or updated. Duplicate topics are detected and skipped.
+Create epics (with sub-issues) or standalone issues/work items from items in `todo.md`, using the platform's CLI and MCP tools against **{owner}/{repo}** (read from `.hatch3r/hatch.json` board config). The `platform` field determines whether to use GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Before creating anything, board-fill **triages each item through interactive questioning** to extract scope, intent, unknowns, and acceptance criteria from the user -- ensuring issues are genuinely ready for implementation, not just structurally complete. On every run, board-fill also performs a **full board reorganization**: grouping standalone issues into epics, decomposing oversized items, analyzing dependencies, setting implementation order, identifying parallel work, and marking issues as `status:ready` when all readiness criteria (structural + substantive) are met. AI proposes groupings, dependencies, and ordering; user confirms before anything is created or updated. Duplicate topics are detected and skipped.
 
 ---
 
@@ -45,7 +52,7 @@ GitHub Agentic Workflows and hatch3r are complementary: use agentic workflows fo
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 
@@ -79,7 +86,7 @@ If Tier 1, run only Steps 1–3, 5–6, and 7 (skip the heavy production-readine
 
 #### 1a. Product Vision Input (Optional)
 
-1. Check if a product vision document exists at `.agents/product-vision.md`.
+1. Check if a product vision document exists at `.hatch3r/product-vision.md`.
 2. If found, read and cache the vision document for use in Steps 2.5 and 4.
 3. If not found, check whether the user provided a vision statement inline with the board-fill invocation (e.g., as a quoted string or file path argument).
 4. If a vision is available from either source, note: "Product vision loaded — will use for triage context and issue scoping."
@@ -269,7 +276,7 @@ If the user flagged unresolved unknowns or research needs in triage, consider wh
 
 **Priority:** `priority:p0` (critical/security) / `priority:p1` (broken, no workaround) / `priority:p2` (degraded, default) / `priority:p3` (cosmetic, nice-to-have). Use the user's stated urgency and impact from triage (Value/Why answers) to override keyword defaults. Default `p2` only when both the todo text AND triage answers are ambiguous; security defaults to `p1`+.
 
-**Area:** Read area labels from `board.areas` in `.agents/hatch.json`. If the list is empty, infer areas from the repository's directory structure. Assign all relevant area labels.
+**Area:** Read area labels from `board.areas` in `.hatch3r/hatch.json`. If the list is empty, infer areas from the repository's directory structure. Assign all relevant area labels.
 
 **Risk:** `risk:low` (isolated, easy rollback) / `risk:med` (shared modules, moderate scope) / `risk:high` (architectural, security-critical). Incorporate triage context: if the user surfaced unknowns, external dependencies, or broad blast radius, escalate risk accordingly. Items with unresolved spikes default to `risk:med`+.
 
@@ -293,7 +300,7 @@ Use explore subagents or direct file reads to understand the current state of so
 
 #### 4b.5. Consult Project Learnings
 
-1. If `.agents/learnings/` exists, scan for learnings relevant to the areas touched by the todo items.
+1. If `.hatch3r/learnings/` exists, scan for learnings relevant to the areas touched by the todo items.
 2. Match by `area` and `tags` in learning frontmatter against the area labels assigned in Step 3.
 3. Surface relevant learnings in the Context Summary output:
    - **Pitfalls** for areas being touched (highest priority -- include specific warnings)
@@ -778,7 +785,7 @@ If yes, edit `todo.md` to remove lines for created issues. Preserve skipped/excl
 
 - **Never create issues for topics already covered** without explicit user approval.
 - **Never skip ASK checkpoints.**
-- **Use correct labels** from the label taxonomy defined in `.agents/hatch.json` (type, priority, area, risk, executor, status, has-dependencies, meta labels).
+- **Use correct labels** from the label taxonomy defined in `.hatch3r/hatch.json` (type, priority, area, risk, executor, status, has-dependencies, meta labels).
 - **Keep issue bodies concise.** Acceptance criteria must be grounded in user-stated requirements from triage, not fabricated from the todo text alone.
 - **No dependency cycles.** Flag and resolve before proceeding.
 - **Never downgrade issue status.** Only upgrade `status:triage` → `status:ready`.