hatch3r 1.8.0 → 2.0.0

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

@@ -10,9 +10,13 @@ cache_friendly: true
 
 Canonical reference for the body and frontmatter shapes `hatch3r-creator` produces when a user invokes `/hatch3r-create`. Five sections, one per artifact type. Each provides the minimum frontmatter (YAML), a body skeleton with `<PLACEHOLDER>` substitution slots, and notes on required versus optional fields. Placeholder convention: `<NAME>` is replaced at composition time; `[<TAG-1>, <TAG-2>]` indicates an array.
 
+The `type` field appears in the Required list and skeleton of all five sections, but the author never sets it by hand: `composeArtifactFile` (`src/content/userContent.ts`) re-pins `derived.type = artifact.type` from the type branch the user already selected at Step 1.1, so a user-supplied value is authoritatively overridden. It is listed as Required because every on-disk artifact carries it, not because the user types it (D20-SA20.1-F20.1.C1).
+
 ### 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`, `type`, `description`, `model`, `tags`. **Optional:** `protected` (always `false` for user agents), `quality_charter` (auto-injected), `adapters` (restricts adapter propagation when present), `tools` (per-agent allow/deny allowlist — when `tools.allow` cardinality exceeds 3, a **Security baseline:** body reference is required, see below).
+
+**Security baseline (tool-grant inheritance).** A user agent that grants more than 3 tools in `tools.allow` MUST cite `rules/hatch3r-security-patterns.md` in a `**Security baseline:**` body line and inherit its deny-by-default posture (no unscoped `Bash`, no destructive subcommands, secrets via `${env:VAR}` only). `hatch3r-creator` surfaces a gentle warning when a wide `tools.allow` ships without this citation; at maturity tier `team`/`scaleup`/`enterprise` the warning is promoted to a strict gate per F20.2.A1's tier-aware floor (gate path: `src/content/userContent.ts`). Without this slot a broad tool grant is an unbounded-grant risk (audit Cycle 10 F20.2.A3).
 
 ```yaml
 ---
@@ -21,15 +25,21 @@ type: agent
 description: <DESCRIPTION>
 model: <MODEL>
 tags: [<TAG-1>, <TAG-2>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
 
+The `pillars:` array carries the governance-axis (P1–P8) or content-quality-axis (CQ1–CQ9) ids the artifact serves. Required by the strict pillar-declaration gate in `runUserContentGates` (`src/content/userContent.ts`); omit the field only if the body carries a `**Pillars:**` line instead. Values outside the P1–P8 ∪ CQ1–CQ9 union are rejected at save time (`validateStructuredPillars`).
+
 ```markdown
 You are <ROLE-STATEMENT> for the project. You receive <INPUT-SUMMARY> and produce <OUTPUT-SUMMARY>.
 
 Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<context>`, `<rules>` tags wrap role, runtime state, and constraints.
 
+## §0 Detect Ambiguity (P8 B1)
+Before any action, scan the request for unresolved scope, target, irreversibility, or constraint conflicts. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` before proceeding — default path, not exception. Proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable.
+
 <task>
 ## Your Role
 - <BULLET-1>
@@ -54,10 +64,11 @@ Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<con
 ## Boundaries
 - **Always:** <ALWAYS-1>
 - **Never:** <NEVER-1>
+- **Security baseline:** inherits `rules/hatch3r-security-patterns.md` (deny-by-default tools, no destructive subcommands, secrets via `${env:VAR}`). Required line when `tools.allow` grants more than 3 tools.
 </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).
+Per `agents/shared/quality-charter.md` §1 and `agents/shared/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.
@@ -82,9 +93,11 @@ This agent inherits `agents/shared/quality-charter.md` via the frontmatter `qual
 
 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.
 
+**§0 ambiguity gate (D13-10).** The `## §0 Detect Ambiguity` block above (or any `user-question-protocol.md` reference) is required so a user agent opens with a clarification-first gate, matching CONSTITUTION §2 P5 ambiguity-gate coverage (agents/skills/commands) at 100%. `hatch3r-creator` surfaces a gentle warning when a user agent ships without it; at maturity tier `team`/`scaleup`/`enterprise` the warning is promoted to a strict gate per F20.2.A1's tier-aware floor (gate path: `src/content/userContent.ts`, the agent/skill branch of `runUserContentGates`).
+
 ### 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`, `type`, `description`, `tags`. **Optional:** `quality_charter` (auto-injected).
 
 ```yaml
 ---
@@ -92,6 +105,7 @@ id: <NAME>
 type: skill
 description: <DESCRIPTION>
 tags: [<TAG-1>, <TAG-2>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -101,11 +115,15 @@ quality_charter: agents/shared/quality-charter.md
 
 ## Quick Start
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: <STEP-1-TITLE>
 - [ ] Step 2: <STEP-2-TITLE>
 - [ ] Step 3: <STEP-3-TITLE>
 - [ ] Step 4: Verification
 
+## §0 Detect Ambiguity (P8 B1)
+Before any action, scan the request for unresolved scope, target, irreversibility, or constraint conflicts. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` before proceeding — default path, not exception. Proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable.
+
 ## Step 1: <STEP-1-TITLE>
 <STEP-1-BODY>
 
@@ -121,11 +139,13 @@ Run `<VERIFICATION-COMMAND>`. The skill is complete when:
 2. <ACCEPTANCE-CRITERION-2>
 ```
 
-Recommended step count: 3-7. Skills with more than 7 steps trigger a gentle warning suggesting decomposition.
+Recommended step count: 3-7 (the §0 ambiguity gate does not count toward the limit). Skills with more than 7 steps trigger a gentle warning suggesting decomposition.
+
+**§0 ambiguity gate (D13-10).** The `## §0 Detect Ambiguity` block above (or any `user-question-protocol.md` reference) is required so a user skill that drives an agentic workflow opens with a clarification-first gate, matching CONSTITUTION §2 P5 ambiguity-gate coverage (agents/skills/commands) at 100%. `hatch3r-creator` surfaces a gentle warning when a user skill ships without it; at maturity tier `team`/`scaleup`/`enterprise` the warning is promoted to a strict gate per F20.2.A1's tier-aware floor (gate path: `src/content/userContent.ts`, the agent/skill branch of `runUserContentGates`).
 
 ### 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 implemented in `src/content/userContent.ts`. **Required:** `id`, `type`, `description`, `scope`, `tags`. **Required when scope=conditional:** `globs`. **Optional:** `precedence` (default `normal`), `quality_charter` (auto-injected).
 
 Three scope shapes (pick one):
 
@@ -144,6 +164,7 @@ scope: <SHAPE-A-VALUE-OR-SHAPE-B-CSV-OR-conditional>
 globs: "<GLOB-CSV>"          # required for Shape C; omit for A/B
 precedence: <PRECEDENCE>     # Shape C only; default normal
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -164,26 +185,27 @@ quality_charter: agents/shared/quality-charter.md
 <POSITIVE-AND-NEGATIVE-EXAMPLES>
 ```
 
-The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a strict gate). The `.mdc` companion has different frontmatter — `saveUserContent` derives it from the `.md` scope shape per the table in `rules/hatch3r-content-authoring.md`.
+The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a strict gate). The `.mdc` companion has different frontmatter — `saveUserContent` derives it from the `.md` scope shape per the transform implemented in `src/content/userContent.ts`.
 
 ### 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
 orchestrator: false
 description: <DESCRIPTION>
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 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
@@ -191,6 +213,7 @@ orchestrator: true
 agentPipeline: [<AGENT-ID-1>, <AGENT-ID-2>]
 description: <DESCRIPTION>
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -239,13 +262,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).
+Every user-authored orchestrator command MUST contain the §0 block above per CONSTITUTION §2 P8 B1 (Clarification-First, Default-Path), and the block should reference `agents/shared/user-question-protocol.md` verbatim. This is a live runtime strict gate: `runUserContentGates` (`src/content/userContent.ts`) rejects any `orchestrator: true` command whose body lacks a `## §0` / `## Step 0` heading or a `user-question-protocol` reference, at every maturity tier (D20-F20.1.B1, shipped). `hatch3r-creator` also emits the skeleton above at composition time, so authoring discipline and the runtime gate reinforce each other. The same §0 gate extends to user agents and skills (gentle at `solo`, strict at `team`+) per D13-10 — see the agent and skill skeleton notes above and the agent/skill branch of `runUserContentGates`.
 
 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 | worktree-create | worktree-remove` (8 values), enforced by `isValidHookEvent` (`src/hooks/types.ts:30`).
 
 ```yaml
 ---
@@ -256,6 +279,7 @@ agent: <AGENT-ID>
 description: <DESCRIPTION>
 globs: "<GLOB-CSV>"
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -274,14 +298,16 @@ 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.
+
+**Transitive trust warning (D20-M6).** A hook fires its referenced agent with that agent's declared tool grants. When `agent: <AGENT-ID>` resolves to a user-authored agent under `.hatch3r/overrides/agents/`, the hook inherits whatever `tools.allowed` set that user agent declared — a broad allowlist on the referenced agent silently widens the hook's blast radius. `hatch3r-creator` surfaces a gentle warning when a hook references a user-authored agent (rather than a canonical `agents/hatch3r-*.md` agent) so authors verify the downstream tool grants are intentional. Mitigation: prefer canonical agents for hooks, or pin the referenced user agent to a narrow `tools.allowed` list with a cited `**Security baseline:**` per §1.
 
 ## 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/dist/content/agents/shared/user-question-protocol.md

@@ -0,0 +1,139 @@
+---
+id: shared-user-question-protocol
+type: reference
+description: Protocol for how hatch3r agents and commands ask the user clarifying questions — when to ask, native-tool preference, and a plain-text fallback shape.
+tags: [shared, ux, p1, p4]
+cache_friendly: true
+---
+
+## Purpose
+
+> Last updated: 2026-06-09
+
+This protocol defines how hatch3r agents and commands surface clarifying or triage questions to the user across the 3 supported AI coding tools (Claude Code, Cursor, GitHub Copilot per `governance/CONSTITUTION.md` §6 Decision 12). 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". Coverage is a 100% floor, not a fixed file list: every framework-dev workflow that can mutate canonical artifacts routes its ASK through this protocol — the requirements-elicitation mode (`agents/modes/requirements-elicitation.md`), the shared §0 gate block (`agents/shared/clarification-default-block.md`), and every `agents/hatch3r-*.md` agent and `commands/hatch3r-*.md` command that detects ambiguity (counts: `governance/inventory.json` `counts.agents`, `counts.commands`, `counts.skills`). The "3 supported AI coding tools" figure above is drift-guarded against `inventory.json` `counts.adapters` by `scripts/inventory.ts` (`npm run inventory:check-docs`).
+
+## When To Ask
+
+- **Ambiguous requirement** — the request maps to two or more reasonable interpretations that produce different code.
+- **Irreversible decision** — deleting data, renaming a public API, dropping a column, force-pushing a branch.
+- **Branching path** — two or more viable approaches with materially different cost, scope, or risk.
+- **Conflicting constraints** — requirements that cannot all hold (e.g., "no new dependencies" and "use library X").
+- **Missing acceptance criteria** — no testable definition of done for the requested change.
+- **Architectural premise concern** — request is well-specified and single-interpretation, but the chosen approach is architecturally misguided (wrong pattern for the constraint, mis-applied abstraction, foreseeable scaling failure). Surface the concern as a §0.5 Challenge the Premise question per quality-charter §3 — phrase it constructively ("Before I implement this, I want to confirm the approach because [specific concern]"), then offer 2-4 options (proceed as requested / proposed alternative / hybrid). Default-if-no-response: proceed as requested (lowest-blast-radius assumption is that the user has context the agent lacks).
+
+## When NOT To Ask
+
+- The user already decided scope in this turn or an earlier turn of the same session.
+- You are in free-text discussion, planning, or a status update — questions belong inside actionable workflows.
+- The answer is verifiable by reading code, running a test, or grepping the repo — verify first, ask only if verification fails.
+- The choice is reversible, low-stakes, and the safer default is obvious — pick the default and note it.
+
+## How To Ask
+
+1. Check whether your target platform exposes a native question or triage tool (see Platform-Native Tool below).
+2. If yes, use the native tool — it produces better UX than free-text replies and is structured for the host runtime.
+3. If no native tool exists on this platform, use the Plain-Text Fallback Template.
+4. Ask at most one question per turn. Bundle related sub-questions into a single multiple-choice prompt rather than firing multiple turns.
+
+## Platform-Native Tool
+
+The marker below is replaced at canonical-write time with the enumeration table generated from `src/pipeline/adapterToolTranslator.ts::ASK_USER_TOOLS`. Look up your runtime platform and follow its row. If your platform's row reads "No documented native tool", use the Plain-Text Fallback Template defined in the next section.
+
+<!-- HATCH3R:PLATFORM-TOOL -->
+
+When viewing this file in the source repo (pre-generation), the marker is unsubstituted — refer to the adapter map in `src/pipeline/adapterToolTranslator.ts` for the same mappings.
+
+**Sub-agent caveat (Claude Code).** The native `AskUserQuestion` tool is a main-agent / orchestrator affordance only. Claude Code filters it out of every Task-tool sub-agent context (foreground and background) regardless of the agent's `tools` declaration, so a spawned `hatch3r-*` sub-agent cannot call it (upstream-confirmed via `anthropics/claude-code` issues #18721, #12890, #34592; verified 2026-06-06 @ https://code.claude.com/docs/en/sub-agents). A sub-agent that hits an ASK trigger therefore does NOT use the native tool: it RETURNS Status `BLOCKED_AMBIGUITY` (`agents/shared/quality-charter.md` §17) with the question rendered via the Plain-Text Fallback Template below, and the orchestrator owns the live ASK (`agents/shared/clarification-default-block.md` → Protocol). This exclusion is re-verified each audit cycle against the date stamp on `src/pipeline/adapterToolTranslator.ts::ASK_USER_TOOLS` (`claude` entry) — a date drift there is a D09 Medium finding.
+
+## Plain-Text Fallback Template
+
+Use this exact shape when no native tool is available:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules for the template:
+
+- Two to four numbered options. One option is too few; five or more signals you have not narrowed the design.
+- Each option carries a one-line trade-off so the user can pick without re-deriving the problem.
+- The default-if-no-response line is mandatory — it removes the deadlock when the user is away or replies "you decide".
+- The default option is the safest reversible choice, not the most ambitious one.
+
+### Optional preview attachment (orchestrator-scoped, platform-conditional)
+
+For questions whose options differ along a **visual or layout dimension** — a color/spacing/typography choice, two candidate component arrangements, a copy-tone A/B, a before/after of an async-view state — a rendered preview alongside the numbered options lets the user decide from the artifact instead of from prose. This is most useful for the UI (CQ1) and UX (CQ2) ASK gates, where "which of these reads better" is the decision.
+
+Attach a preview only when BOTH hold:
+
+- **You are the orchestrator** (main-conversation `commands/hatch3r-*.md`), not a Task-tool sub-agent. Sub-agents cannot call the native question tool at all (see the Sub-agent caveat above); they render the question — and any preview snippet — in the `BLOCKED_AMBIGUITY` structured result, and the orchestrator owns the live ASK.
+- **The runtime's native question tool supports rich/rendered option content.** Capability is per-platform; look up your runtime's row in the adapter map (`src/pipeline/adapterToolTranslator.ts::ASK_USER_TOOLS`) before relying on a preview, exactly as you would for the question tool itself. When the platform's native tool is text-only (or absent), embed the preview as a fenced code block inside the Plain-Text Fallback Template instead — never assume a rendering affordance the platform row does not document.
+
+**Concrete affordance (Claude Code orchestrator).** On the `claude` platform, populate the per-option `markdown` field of the `AskUserQuestion` tool: when any option carries a `markdown` value, Claude Code switches to a side-by-side preview layout (numbered options on the left, the rendered markdown on the right), so a diagram, code/diff block, or token-swatch table renders inline with the choice. The field accepts markdown only (no HTML), and long content is truncated to a scrollable panel — keep each option's preview to about one screen of markup. One documented constraint: supplying a `markdown` field suppresses the free-text "Other / Type something" option on that question, so reserve the preview layout for closed-option visual decisions. Other platforms expose no documented preview field (their `ASK_USER_TOOLS` row is `null` — `cursor`, `copilot` as of 2026-06-09); on those, fall back to the fenced-code-block-in-plain-text shape above.
+
+The preview is an enrichment, not a replacement: the numbered options and the mandatory `Default if no response:` line are still required. Keep the preview small (one screen of markup or a single mock) so it does not bury the decision.
+
+## Examples
+
+**Example 1 — Ambiguous requirement.** Request: "Add caching to the user profile endpoint."
+
+```
+**Question:** Which cache scope matches your needs for the profile endpoint?
+
+1. Per-user, 60s TTL — fastest response, stale data tolerated up to 60s.
+2. Per-user, write-through invalidation — fresh data, +1 cache write per profile update.
+3. Edge cache only — no app changes, but TTL is fixed by the CDN config.
+
+Default if no response: 2
+```
+
+**Example 2 — Branching path.** Request: "Migrate the build to Vite."
+
+```
+**Question:** Should the Vite migration land in one PR or staged behind a feature flag?
+
+1. Single PR — shorter total time, larger blast radius if a regression ships.
+2. Staged with VITE_BUILD flag — two PRs, lets you A/B locally before flipping.
+
+Default if no response: 2
+```
+
+## Operationalising Default-if-no-Response
+
+The "Default if no response" line is mandatory in every plain-text fallback question (per the rules above) and is the canonical deadlock-breaker for every ASK gate across the framework. To operationalise the default at runtime rather than leaving it as documented prose:
+
+1. **Detect non-response.** If a question goes unanswered within the host runtime's question window (Claude Code: idle session timeout; Cursor: AskUserQuestion timeout; Copilot Workspace: prompt-cycle gap), or if the user replies "you decide" / "default" / empty, treat as non-response.
+2. **Apply the safe default.** Pick the option declared on the `Default if no response: <option number>` line — the lowest-blast-radius reversible choice the question's author named.
+3. **Log the default-taken decision.** Emit in the Iteration Summary §8 (Open Questions / Blockers) a single line: `Default applied: <question summary> → option <N> (<one-line reason>)`. This is the operational counterpart to the prose mandate — every agent / command ASK output that exercises the default MUST log the decision. The §8 line is a required field of the canonical Iteration Summary template (`rules/hatch3r-iteration-summary.md` → The 9 Sections, item 8), and the catching-gate ownership is named in `rules/hatch3r-clarification-default.md` → How to ask — those two files are the enforcing surface for this step.
+4. **Never silent-pick.** If no `Default if no response: <option>` line was emitted with the question (an authoring bug per the rules in this file), return `BLOCKED_AMBIGUITY` in the structured result rather than guessing.
+
+The §8 log is the audit-visible evidence that the default-if-no-response contract was honored; absence of the log when a default was applied is a P8 B1 gate failure. Runtime emission of the §8 line is orchestrator-produced interpreted markdown, so no static gate can verify it fired — D05 (prompt-engineering) and D13 (human-AI collaboration) audit-cycle spot checks plus the per-run Iteration Summary validation gate are the enforcement, not a compiled check.
+
+The contract has a single named owner so it is not re-declared per command: the always-on, `precedence: high` rule `rules/hatch3r-clarification-default.md` (`scope: always`) binds every `commands/hatch3r-*.md` orchestrator and mutating skill corpus-wide, and that rule's "How to ask" section is the catching gate. An individual command body therefore need not repeat the default-handling vocabulary to be bound by it — the rule + this protocol + the Iteration Summary §8 template are the three-anchor owner set, and a command inherits the contract by being in scope. Treat a command that *does* restate it as a convenience, not the source of truth.
+
+## Cross-Phase Aggregation
+
+This protocol defines the *shape* of a single question (numbered options, mandatory default). It does not define where pending questions accumulate when several fire across one pipeline run. That cross-phase aggregation layer is the `PipelineContext.pendingUserInputs: PendingUserInput[]` field (`src/pipeline/pipelineContext.ts`, Finding D7-SA7.1-F-10): each phase pushes a `PendingUserInput` — whose `options` + `defaultIfNoResponse` mirror the Plain-Text Fallback Template above — instead of emitting a direct prompt mid-phase. The orchestrator drains the array between phases, paginating when more than three accumulate, so a Tier 3 run's multiple ASK checkpoints are batched rather than each rendered independently. Per-question UX (this file) and cross-phase batching (the field) are complementary: author each request to this template, enqueue it on the field.
+
+## Anti-Patterns
+
+- **Multi-question barrage** — asking five questions in one turn. Ask the highest-leverage one first; the answer often collapses the rest.
+- **Options-free questions** — "What should I do?" forces the user to design the prompt. Always supply 2–4 candidate options with trade-offs.
+- **Silent assumption** — proceeding when ambiguity is real. Apply quality-charter §8: log the ambiguity in structured output even if you decide to proceed under a default.
+- **Echo-as-question** — restating the user's request back as a question ("So you want me to add caching?"). Confirm only when you have a specific decision point with options to offer.
+- **Inflated default** — choosing the most disruptive option as the no-response default. Defaults must be the reversible, lowest-blast-radius choice.
+
+## References
+
+The `markdown`-field preview affordance documented in "Optional preview attachment" above is corroborated by:
+
+- `anthropics/claude-code` issue #27348 — names the `markdown` field on `AskUserQuestion` options as the trigger for the preview layout and the "Other / Type something" suppression constraint (accessed 2026-06-09; trust tier: official-vendor issue tracker). https://github.com/anthropics/claude-code/issues/27348
+- `anthropics/claude-code` issue #33062 — documents the side-by-side preview panel and its scroll/truncation behavior for long content (accessed 2026-06-09; trust tier: official-vendor issue tracker). https://github.com/anthropics/claude-code/issues/33062
+
+Per-platform tool names and the `null`-means-no-native-tool convention are sourced in `src/pipeline/adapterToolTranslator.ts::ASK_USER_TOOLS` (each entry carries its own `// verified <date> @ <docs URL>` stamp, refreshed on the D09 per-cycle web-research pass).

package/{checks → dist/content/checks}/README.md

@@ -1,3 +1,8 @@
+---
+id: checks-readme
+type: documentation
+description: Authoring guide and directory contract for the checks/ review-criteria files. Not a check itself — excluded from check enumeration by its documentation type.
+---
 # Checks
 
 Review criteria definitions for automated and agent-assisted code review. Each check file defines a set of criteria that agents reference when reviewing code changes.

package/{checks → dist/content/checks}/accessibility.md

@@ -1,19 +1,20 @@
 ---
 id: accessibility
 type: check
-description: Accessibility review criteria covering WCAG compliance, semantic HTML, keyboard navigation, screen reader support, and inclusive design patterns
+description: Accessibility review criteria covering WCAG 2.2 AA compliance, semantic HTML, keyboard navigation, screen reader support, and inclusive design patterns
+tags: [accessibility]
 cache_friendly: true
 ---
 # Accessibility Check
 
-> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+> **Severity vocabulary:** see [agents/shared/severity-mapping.md](../agents/shared/severity-mapping.md) for canonical 5-column mapping.
 
 Review criteria for evaluating accessibility in pull requests.
 
 ## Semantic HTML and ARIA
 
 - `[CRITICAL]` Interactive elements use native HTML controls (`<button>`, `<a>`, `<input>`, `<select>`) rather than styled `<div>` or `<span>` elements with click handlers.
-- `[CRITICAL]` Custom interactive components have appropriate ARIA roles, states, and properties (`role`, `aria-expanded`, `aria-selected`, `aria-disabled`, etc.).
+- `[CRITICAL]` Custom interactive components carry ARIA roles, states, and properties that match the WAI-ARIA 1.2 Authoring Practices pattern for the widget type (`role`, `aria-expanded`, `aria-selected`, `aria-disabled`, etc.); axe-core 4.5+ reports 0 `aria-required-attr` / `aria-allowed-role` violations.
 - `[CRITICAL]` Images have meaningful `alt` text, or `alt=""` and `aria-hidden="true"` if purely decorative.
 - `[CRITICAL]` Form inputs have associated `<label>` elements (via `for`/`id` or nesting). No input relies solely on placeholder text for identification.
 - `[RECOMMENDED]` Headings follow a logical hierarchy (`h1` > `h2` > `h3`) without skipping levels.
@@ -21,22 +22,28 @@ Review criteria for evaluating accessibility in pull requests.
 
 ## Keyboard Navigation
 
-- `[CRITICAL]` All interactive elements are reachable and operable via keyboard (Tab, Shift+Tab, Enter, Space, Arrow keys as appropriate).
+- `[CRITICAL]` All interactive elements are reachable and operable via keyboard (Tab, Shift+Tab, Enter, Space; Arrow keys for composite widgets per the WAI-ARIA APG keyboard-interaction table for that widget — menu, listbox, tablist, grid).
 - `[CRITICAL]` Focus is not trapped in a component unless it is a modal dialog with an explicit close mechanism.
 - `[CRITICAL]` Custom keyboard shortcuts do not conflict with screen reader or browser shortcuts.
 - `[RECOMMENDED]` Focus order follows the visual reading order (logical DOM order). No use of positive `tabindex` values.
-- `[RECOMMENDED]` Focus indicators are visible and meet contrast requirements. No `outline: none` without a custom visible focus style.
+- `[CRITICAL]` WCAG 2.2 SC 2.4.7 Focus Visible (AA): the keyboard focus indicator is visible on every operable element. No `outline: none` without a conforming custom focus style.
+- `[CRITICAL]` WCAG 2.2 SC 2.4.11 Focus Not Obscured (Minimum) (AA): the focused element is not entirely hidden by author-created content (sticky headers, footers, cookie banners, overlays). `[RECOMMENDED]` SC 2.4.13 Focus Appearance (AAA) as the enhanced target: the focus indicator has a contrast ratio of at least 3:1 against adjacent colors and a minimum area equal to a 1px-thick perimeter (or 4px-thick along the shortest side).
 
 ## Visual Design and Color
 
-- `[CRITICAL]` Text meets WCAG 2.1 AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold).
+- `[CRITICAL]` Text meets WCAG 2.2 AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold). Verify with axe-core 4.5+ `color-contrast` rule — 0 violations.
 - `[CRITICAL]` Information is not conveyed by color alone. Status indicators, errors, and required fields use icons, text, or patterns in addition to color.
 - `[CRITICAL]` UI remains functional and readable at 200% browser zoom without horizontal scrolling or content clipping.
-- `[RECOMMENDED]` Touch targets are at least 44x44 CSS pixels for mobile interfaces.
 - `[RECOMMENDED]` Animations respect the `prefers-reduced-motion` media query — reduce or remove motion for users who have requested it.
 
+## Touch and Pointer Targets (WCAG 2.2)
+
+- `[CRITICAL]` WCAG 2.2 SC 2.5.8 Target Size (Minimum): pointer targets are at least 24x24 CSS px, OR have 24px of spacing to adjacent targets, unless an inline/essential exception applies. Mobile interfaces target 44x44 CSS px (Apple HIG / Material).
+- `[CRITICAL]` WCAG 2.2 SC 2.5.7 Dragging Movements: any drag operation (slider, drag-to-reorder, map pan) provides a single-pointer alternative that does not require dragging (tap, click, or button control).
+
 ## Screen Reader Support
 
+- `[CRITICAL]` WCAG 2.2 SC 4.1.3 Status Messages: status messages (success/error/progress, search-result counts, loading state) are programmatically conveyed via `role="status"`, `role="alert"`, or an `aria-live` region without moving focus, so assistive tech announces them.
 - `[CRITICAL]` Dynamic content updates (toast notifications, live regions, inline validation) use `aria-live` regions (`polite` or `assertive`) to announce changes.
 - `[CRITICAL]` Modal dialogs trap focus, announce their title via `aria-labelledby`, and return focus to the trigger element on close.
 - `[CRITICAL]` Icon-only buttons and links have accessible names via `aria-label`, `aria-labelledby`, or visually hidden text.

package/{checks → dist/content/checks}/code-quality.md

@@ -6,7 +6,7 @@ cache_friendly: true
 ---
 # Code Quality Check
 
-> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+> **Severity vocabulary:** see [agents/shared/severity-mapping.md](../agents/shared/severity-mapping.md) for canonical 5-column mapping.
 
 Review criteria for evaluating code quality in pull requests.
 

package/{checks → dist/content/checks}/performance.md

@@ -2,11 +2,14 @@
 id: performance
 type: check
 description: Performance review criteria covering bundle size, render performance, memory usage, network optimization, database queries, and runtime efficiency
+tags: [performance]
 cache_friendly: true
 ---
 # Performance Check
 
-> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+> **Severity vocabulary:** see [agents/shared/severity-mapping.md](../agents/shared/severity-mapping.md) for canonical 5-column mapping.
+
+**Applies when:** the project declares performance budgets. Without declared budgets this check is advisory, not gating (per `rules/hatch3r-right-sizing.md`).
 
 Review criteria for evaluating performance in pull requests.
 
@@ -14,7 +17,7 @@ Review criteria for evaluating performance in pull requests.
 
 - `[CRITICAL]` New dependencies do not increase the total bundle size (gzipped) beyond the defined budget. Measure before and after.
 - `[CRITICAL]` No unintentional import of full libraries when a subpath import or tree-shakable alternative exists (e.g., `import _ from "lodash"` vs `import groupBy from "lodash/groupBy"`).
-- `[RECOMMENDED]` Images and static assets are optimized (compressed, appropriately sized, modern formats like WebP/AVIF).
+- `[RECOMMENDED]` Images and static assets are compressed and served in WebP or AVIF, with intrinsic dimensions no larger than the maximum rendered size at 2x device pixel ratio (no downscaling a >2x-oversized source in the browser).
 - `[RECOMMENDED]` CSS and JavaScript are minified and dead-code-eliminated in production builds.
 
 ## Render and Paint Performance
@@ -35,7 +38,7 @@ Review criteria for evaluating performance in pull requests.
 
 - `[CRITICAL]` No N+1 request patterns — batch or aggregate related requests instead of issuing one per item.
 - `[CRITICAL]` API response payloads return only required fields. No over-fetching of large objects when a subset is needed.
-- `[RECOMMENDED]` Cacheable responses include appropriate cache headers (`Cache-Control`, `ETag`). Client-side caching (query cache, service worker) is used where applicable.
+- `[RECOMMENDED]` Cacheable responses set `Cache-Control` with an explicit `max-age` (immutable static assets `max-age=31536000, immutable`; mutable API responses `no-cache` or a documented TTL) plus an `ETag` or `Last-Modified` validator. Responses that mutate state or carry per-user data set `Cache-Control: private` or `no-store`.
 - `[RECOMMENDED]` Request waterfalls are minimized — parallelize independent requests and preload critical resources.
 
 ## Database Query Performance
@@ -49,7 +52,7 @@ Review criteria for evaluating performance in pull requests.
 ## Runtime Performance
 
 - `[CRITICAL]` No synchronous blocking operations (heavy computation, synchronous I/O) on the main thread or event loop.
-- `[CRITICAL]` Hot-path code (called per-request, per-frame, or per-event) does not perform redundant computation — memoize or cache where appropriate.
+- `[CRITICAL]` Hot-path code (called per-request, per-frame, or per-event) does not recompute a pure result whose inputs are unchanged since the last call — memoize or cache any such repeated pure computation, and bound the cache with an eviction policy (size cap or TTL).
 - `[RECOMMENDED]` CPU-intensive work is offloaded to workers, background jobs, or streaming pipelines.
 - `[RECOMMENDED]` Object allocation in tight loops is minimized — reuse buffers and avoid creating short-lived objects per iteration.
 

package/{checks → dist/content/checks}/security.md

@@ -6,7 +6,7 @@ cache_friendly: true
 ---
 # Security Check
 
-> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+> **Severity vocabulary:** see [agents/shared/severity-mapping.md](../agents/shared/severity-mapping.md) for canonical 5-column mapping.
 
 Review criteria for evaluating security posture in pull requests.
 
@@ -20,10 +20,10 @@ Review criteria for evaluating security posture in pull requests.
 
 ## Authentication and Authorization
 
-- `[CRITICAL]` New endpoints have appropriate authentication guards. No accidental public exposure of protected resources.
+- `[CRITICAL]` New endpoints enforce authentication and resource-level authorization per an OAuth 2.1 / RBAC rubric — every non-public route rejects unauthenticated requests (401) and out-of-scope authenticated requests (403). No accidental public exposure of protected resources.
 - `[CRITICAL]` Authorization checks verify the authenticated user has access to the specific resource, not just that they're logged in.
 - `[CRITICAL]` Authentication tokens are not logged, included in URLs, or exposed in error messages.
-- `[RECOMMENDED]` Session tokens use secure attributes: `HttpOnly`, `Secure`, `SameSite=Strict`, appropriate `Max-Age`.
+- `[RECOMMENDED]` Session tokens use secure attributes: `HttpOnly`, `Secure`, `SameSite=Strict`, and a `Max-Age` no longer than the session policy (default ≤24h for access tokens, ≤30d for refresh tokens).
 - `[RECOMMENDED]` Rate limiting is applied to authentication endpoints (login, password reset, OTP verification).
 
 ## Secrets and Credentials
@@ -38,8 +38,8 @@ Review criteria for evaluating security posture in pull requests.
 
 - `[CRITICAL]` New dependencies are from trusted sources with active maintenance (recent commits, multiple maintainers).
 - `[CRITICAL]` No known critical or high vulnerabilities in new or updated dependencies (`npm audit`, `pip audit`, etc.).
-- `[RECOMMENDED]` Dependency count increase is justified — prefer standard library solutions when adequate.
-- `[RECOMMENDED]` New dependencies have appropriate licenses compatible with the project.
+- `[RECOMMENDED]` Each added runtime dependency is justified in the PR description; a standard-library or already-present-dependency equivalent that covers the same use case is preferred over a new transitive dependency tree.
+- `[RECOMMENDED]` New dependencies carry an OSI-approved license compatible with the project license (no GPL/AGPL copyleft in a permissively-licensed product unless legal-approved).
 
 ## Data Exposure
 
@@ -58,4 +58,4 @@ Review criteria for evaluating security posture in pull requests.
 ## Error Handling
 
 - `[CRITICAL]` Error responses to clients do not include stack traces, internal paths, or database details.
-- `[RECOMMENDED]` Security-relevant errors (auth failures, permission denials) are logged with sufficient context for incident investigation.
+- `[RECOMMENDED]` Security-relevant errors (auth failures, permission denials) are logged with the five fields an incident responder needs — timestamp, actor/subject identifier, action attempted, resource, and outcome — and never the secret or credential that was rejected.

package/{checks → dist/content/checks}/testing.md

@@ -6,7 +6,7 @@ cache_friendly: true
 ---
 # Testing Check
 
-> **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
+> **Severity vocabulary:** see [agents/shared/severity-mapping.md](../agents/shared/severity-mapping.md) for canonical 5-column mapping.
 
 Review criteria for evaluating test coverage and quality in pull requests.
 

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.