hatch3r 1.7.1 → 1.8.0

package/agents/shared/quality-charter.md

@@ -105,3 +105,131 @@ Every user-facing iteration ends with the canonical Iteration Summary block defi
 Required fields: Status (closed enum: SUCCESS | PARTIAL | FAILED | BLOCKED), Outcome (one sentence), Done, Not Done / Deferred / Unverified, Open Questions / Blockers, Confidence + basis. Optional sections (Artifacts Touched, Verifications Run, Earliest Failure Point, Suggested Next Action) are appended only when they carry information.
 
 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.
+
+### 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.
+
+- **Accessibility:** WCAG 2.2 AA conformance verified by axe-core (0 serious/critical violations), with explicit checks for SC 2.5.8 (target size 24x24 + 24px spacing), SC 2.4.11 (focus not obscured), and SC 2.5.7 (drag operations have a single-tap alternative). Reference `rules/hatch3r-accessibility-standards.md`.
+- **Design-token reuse:** detect existing tokens before authoring via `skills/hatch3r-design-system-detect`; apply the precedence reuse > extend > create; achieve >=95% design-token adoption on color and spacing in generated code. Reference `rules/hatch3r-design-system-detection.md`.
+- **Four-state surface contract:** every async view ships loading, empty, error, and partial states with documented content structure that distinguishes cold-start from active-filter from network failure. Reference `rules/hatch3r-ux-states-and-flows.md`.
+- **Microcopy and tone:** plain language, second person, corrective verb on errors, no jargon visible to end users (`null`, `500`, `FIDO2`); ICU MessageFormat for plurals and gender. Reference `rules/hatch3r-i18n.md` Microcopy subsection and `rules/hatch3r-ux-states-and-flows.md`.
+- **AI-UX patterns (when applicable):** streaming responses via AI SDK UI hooks plus AI Elements; tool-call UI cards; human-approval gates for side-effectful tools; cancel, abort, and undo affordances; span-grounded citations. Reference `rules/hatch3r-ai-ux-patterns.md`.
+- **Verification gate:** a feature is not done until `skills/hatch3r-ui-ux-verify` passes all 9 gates — axe-core, keyboard trace, a11y-tree snapshot, four-state coverage, visual regression, microcopy lint, Core Web Vitals, AI-UX checks (when applicable), and one human screen-reader pass per release.
+
+Cross-reference: this section is audited under D10 SA10.9 (`governance/audit/domains/D10-documentation-devex.md`) and CONSTITUTION §2 P2 measurement.
+
+### Observability quality (for agent-produced services)
+
+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`.
+- **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.
+- **Verification gate:** a feature is not done until `skills/hatch3r-observability-verify` passes — span coverage on request path, log carries trace_id, RED metrics emitted, SLO file declared, error tracker wired with release tag.
+
+Cross-reference: AUDIT Directive 16 (a), CONSTITUTION §2 P2 production-readiness measurement (instrumented-route ratio = 100%), forthcoming D22.
+
+### Data integrity quality (for agent-produced schema and event changes)
+
+When an agent produces a schema migration, an event-schema change, or a backfill, the charter binds it to these criteria.
+
+- **Expand-contract:** every schema change uses the 3- or 4-deploy expand/migrate/contract pattern; no destructive change in a single deploy. Reference `rules/hatch3r-migrations.md`.
+- **Online DDL:** changes choose pt-online-schema-change, gh-ost, or platform-native online DDL on tables larger than the documented threshold; never naked `ALTER TABLE` on hot tables. Reference `rules/hatch3r-migrations.md`.
+- **Reversibility:** every forward migration has a documented rollback path; irreversible migrations are flagged and gated on explicit acknowledgement.
+- **Replica-lag awareness:** backfills are idempotent + resumable + throttled to a documented lag budget; reads after writes use primary or wait for replication where consistency is required.
+- **Event-schema compatibility:** event-driven changes declare BACKWARD, FORWARD, or FULL compatibility in a schema registry (Avro / Protobuf / JSON-schema); breaking events bump a major version. Reference `rules/hatch3r-event-schema-evolution.md`.
+- **Verification gate:** a change is not done until the schema diff has been classified against the expand-contract phases and the rollback path has been tested in a non-prod environment.
+
+Cross-reference: AUDIT Directive 16 (b), CONSTITUTION §2 P2 production-readiness measurement (expand-contract conformance = 100%), forthcoming D22.
+
+### API quality (for agent-produced services)
+
+When an agent produces an HTTP, gRPC, or GraphQL API, the charter binds it to these criteria.
+
+- **Error format:** every error response follows RFC 9457 `application/problem+json` with `type`, `title`, `status`, `detail`, `instance`. No bare strings, no leaked stack traces. Reference `rules/hatch3r-api-design.md`.
+- **Deprecation and sunset:** stable endpoints emit `Deprecation` (RFC 9745) + `Sunset` (RFC 8594) headers when scheduled for removal; deprecation timeline documented in the OpenAPI spec.
+- **Idempotency:** every non-idempotent endpoint accepts an `Idempotency-Key` header and stores the dedup result per Stripe's pattern.
+- **Spec-first:** OpenAPI 3.1 for REST, AsyncAPI 3.1.0 for events, GraphQL SDL for graphs; spec is the contract, code is generated or validated against it.
+- **Breaking-change CI gate:** oasdiff / buf breaking / graphql-inspector runs on every PR touching the spec; breaking change on a stable endpoint blocks merge. Reference `rules/hatch3r-api-design.md` and `rules/hatch3r-api-versioning.md`.
+- **Contract tests:** consumer-driven (Pact) + spec-driven (Schemathesis) tests run in CI for every API the service exposes or consumes.
+- **Verification gate:** a feature is not done until the spec diff is non-breaking on stable endpoints, contract tests pass, and the deprecation headers are correct.
+
+Cross-reference: AUDIT Directive 16 (c), CONSTITUTION §2 P2 production-readiness measurement (API breaking-change events = 0 per release), forthcoming D22.
+
+### AI feature quality (for agent-produced LLM features) — backend half
+
+When an agent produces an LLM-backed feature, the charter binds it to these backend criteria (frontend AI-UX patterns are covered in the UI/UX section).
+
+- **Eval harness mandate:** every AI feature ships an automated eval set (golden examples + adversarial cases + regression suite) that runs in CI on prompt or model changes. Reference `rules/hatch3r-ai-evals.md`.
+- **Prompt versioning:** prompts are versioned artifacts with a changelog; model + temperature + system prompt + tool definitions form the version key.
+- **Cost telemetry per request:** every LLM call emits a span with `input_tokens`, `output_tokens`, `cached_tokens`, `model`, and computed cost; cost dashboards per feature.
+- **Prompt caching:** prompts with stable prefixes use provider-native prompt caching; cache hit rate is a measured metric.
+- **Model fallback chain:** every production call has a documented fallback (primary → fallback → graceful-degraded response); circuit breaker on the primary model.
+- **Hallucination-as-SLI:** hallucination rate is measured on a labelled sample per release and tracked as an SLI; threshold breach blocks rollout. Reference `skills/hatch3r-ai-feature`.
+- **OTel GenAI semconv:** spans follow the OTel GenAI semantic conventions (`gen_ai.*` attributes) so cost, latency, and quality are queryable in one trace store.
+- **Verification gate:** a feature is not done until `skills/hatch3r-ai-feature` confirms eval set + cost telemetry + fallback + hallucination measurement.
+
+Cross-reference: AUDIT Directive 16 (d), CONSTITUTION §2 P2 production-readiness measurement (AI eval coverage = 100%), forthcoming D22.
+
+### Testing depth (for agent-produced code)
+
+When an agent produces code, the charter binds the test classes to the feature mandate map; one test class is not interchangeable with another.
+
+- **Per-feature mandate map:** parser code mandates fuzzing; payment code mandates mutation testing; RPC code mandates contract tests; state machines mandate property-based tests; UI code mandates visual regression. Reference `rules/hatch3r-testing.md`.
+- **Property-based tests:** every pure function with a stated invariant has a property-based test (fast-check, Hypothesis) covering the invariant across generated inputs.
+- **Mutation testing:** payment paths, auth paths, and any code labelled `critical` carry a mutation-testing budget with a documented kill-rate floor (Stryker for JS/TS, Pitest for JVM).
+- **Fuzz testing:** parsers, decoders, and any input boundary that consumes untrusted bytes carries a fuzz harness with a documented corpus.
+- **Contract tests:** every service-to-service boundary has consumer + provider contract tests; broken contract fails the PR.
+- **Determinism contract:** tests are deterministic; flaky tests are quarantined and assigned, not silenced. Flake hunting protocol documented per-repo.
+- **Verification gate:** a feature is not done until the feature's test class is correct for its mandate-map row and the test-class coverage matches the mandate.
+
+Cross-reference: AUDIT Directive 16 (e), CONSTITUTION §2 P2 production-readiness measurement (per-feature test-class mandate compliance = 100%), forthcoming D22.
+
+### Supply-chain floor (for releases agent-produced code participates in)
+
+When an agent produces release-touching changes (workflows, Dockerfiles, package manifests), the charter binds them to these floors.
+
+- **npm provenance:** publishes use OIDC trusted publishing with `--provenance`; consumers can verify the package was built from the claimed source. Reference `rules/hatch3r-dependency-management.md`.
+- **SBOM on every release:** CycloneDX 1.6 or SPDX 3.0.1 SBOM is generated for every release and attached as a release asset; consumed dependencies are queryable.
+- **SLSA v1.0+:** build provenance attestation reaches SLSA Build L3 where the CI provider supports it (GitHub Actions reusable workflows + provenance).
+- **Malicious-package detection beyond `npm audit`:** Socket, Snyk, or equivalent dependency-confusion + typosquat + install-script scanner runs on every install path.
+- **SHA-pinned GitHub Actions:** every action reference uses a 40-char commit SHA, not a tag; Dependabot or Renovate keeps SHAs current. Reference `rules/hatch3r-container-hardening.md` and `rules/hatch3r-dependency-management.md`.
+- **Cosign-signed digest-pinned containers:** container images are signed with cosign (keyless via OIDC) and consumed by digest, not tag, in production manifests.
+- **License allow-list:** every dependency's license is checked against a documented allow-list; copyleft license outside the allow-list blocks merge.
+- **Verification gate:** a release is not done until provenance, SBOM, signature verification, and license allow-list all pass.
+
+Cross-reference: AUDIT Directive 16 (f), D15 SA15.8 (supply-chain end-user floor), CONSTITUTION §2 P2 production-readiness measurement (supply-chain floor coverage = 100%).
+
+### Reliability quality (for agent-produced services)
+
+When an agent produces a service or a deploy artifact, the charter binds it to these criteria.
+
+- **Circuit breaker + retry with decorrelated jitter:** every outbound call has a circuit breaker with documented thresholds and retries with decorrelated jitter (AWS Architecture Blog pattern), not naked exponential backoff. Reference `rules/hatch3r-reliability.md`.
+- **Timeouts with deadline propagation:** every outbound call has a timeout strictly less than the inbound deadline; deadlines propagate via gRPC metadata or HTTP `traceparent` + `request-deadline`.
+- **Idempotency keys and bulkheads:** non-idempotent operations gate on idempotency keys; resource pools are bulkheaded so one slow dependency does not exhaust the whole service.
+- **Probes wired:** Kubernetes liveness, readiness, and startup probes are wired with documented commands; readiness gates on dependency health, not on liveness.
+- **Graceful shutdown with preStop hook:** SIGTERM handling drains in-flight requests; preStop hook waits for service mesh deregistration before kill.
+- **Runbook URL on every alert:** every alert rule includes a runbook URL; runbooks document detect/diagnose/mitigate/recover steps.
+- **Staged canary rollout with auto-rollback:** rollouts use 1% → 10% → 50% → 100% staging with auto-rollback on SLO error-budget burn (Argo Rollouts / Flagger pattern). Reference `skills/hatch3r-reliability-verify`.
+- **Verification gate:** a feature is not done until `skills/hatch3r-reliability-verify` confirms SLO defined, timeouts wired, probes correct, runbook attached.
+
+Cross-reference: AUDIT Directive 16 (g), CONSTITUTION §2 P2 production-readiness measurement (user-facing service SLO defined = 100%), forthcoming D22.
+
+### Authentication and identity quality (for agent-produced auth flows)
+
+When an agent produces an auth flow — sign-in, token exchange, session handling, authorization check — the charter binds it to these criteria.
+
+- **OAuth 2.1 with PKCE everywhere:** confidential and public clients use PKCE; refresh tokens rotate; refresh-token reuse detection invalidates the family. Reference `rules/hatch3r-auth-patterns.md`.
+- **OIDC validation:** every ID token validates `iss`, `aud`, `azp`, `exp`, `nonce`, and signature against the issuer's published JWKS; clock-skew window documented.
+- **DPoP for browser tokens:** browser-issued access tokens are DPoP-bound (RFC 9449) so token theft does not equal account takeover.
+- **JWT BCP (RFC 8725):** `alg` allow-list per issuer, `none` rejected, `kid` resolved against JWKS, `typ` checked; no symmetric secret bigger than 256 bits doubling as an HMAC key.
+- **Cookie flags:** session cookies set `__Host-` prefix + `HttpOnly` + `Secure` + `SameSite=Lax` (or `Strict` for state-changing flows) + `Partitioned` where cross-site cookies are required.
+- **MFA per NIST 800-63B-4 AAL:** authenticator strength matches the assurance level the resource requires; phishing-resistant authenticator for AAL3.
+- **RBAC/ABAC/ReBAC rubric:** authorization model is chosen with a documented rubric — RBAC for static roles, ABAC for attribute-driven decisions, ReBAC for relationship-driven systems (Zanzibar-class) — and the choice is justified in an ADR.
+- **WebAuthn server-side ceremony:** passkey flows implement the server-side ceremony in full (challenge generation, RP ID binding, attestation verification, sign-count monotonicity, transports). Reference `rules/hatch3r-passkey-server.md`.
+- **Verification gate:** a feature is not done until `agents/hatch3r-security-auditor.md` confirms OAuth 2.1 + OIDC validation + DPoP + cookie flags + MFA AAL alignment + RBAC/ABAC/ReBAC choice documented + WebAuthn server-side complete.
+
+Cross-reference: AUDIT Directive 16 (h), CONSTITUTION §2 P2 production-readiness measurement (auth depth coverage = 100%), forthcoming D22.

package/agents/shared/user-content-templates.md

@@ -55,8 +55,33 @@ 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).
@@ -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,6 +239,8 @@ 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

package/commands/hatch3r-agent-customize.md

@@ -10,6 +10,10 @@ cache_friendly: true
 parallel_tool_default: true
 ---
 
+## §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
 
 This command runs as a single orchestrator without sub-agent delegation. Customization file management is performed inline.

package/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 |

package/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 |

package/commands/hatch3r-board-fill.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: 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 |
@@ -165,6 +172,7 @@ If a product vision was loaded in Step 1a, apply these modifications to the tria
 2. **Reduce questioning.** Only ask triage questions for dimensions that the vision does not clearly address. If the vision states the target user, value proposition, and scope boundaries for an item's domain, mark those dimensions as "Clear (from vision)" and skip the corresponding questions.
 3. **Reference vision goals explicitly.** When classifying items or asking remaining triage questions, cite the specific vision goal or statement that informs the classification (e.g., "Per the product vision goal 'Zero-config onboarding', this item aligns with...").
 4. **Greenfield streamlining.** For greenfield projects where the vision covers all major work areas, batch all items into a single triage pass. Present the vision-derived context for each item and ask the user to confirm or override in one prompt rather than per-item questioning.
+5. **Tier-3 greenfield gate (P8 B2).** Vision-aware triage skips a readiness dimension ONLY when the product vision explicitly addresses it; otherwise mark the dimension `unresolved — needs user input` and ask via the platform-native question tool. If readiness gate (Step 5.6) reports unresolved external blockers, re-run triage per dimension.
 
 If no product vision is available, proceed with the full triage process below.
 

package/commands/hatch3r-board-groom.md

@@ -10,6 +10,10 @@ cache_friendly: true
 parallel_tool_default: true
 ---
 
+## §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
 
 This command runs as a single orchestrator without sub-agent delegation.

package/commands/hatch3r-board-init.md

@@ -10,6 +10,10 @@ cache_friendly: true
 parallel_tool_default: true
 ---
 
+## §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
 
 This command runs as a single orchestrator without sub-agent delegation.
@@ -65,6 +69,53 @@ This command runs in two phases: **Planning** (collect all answers) then **Execu
 
 ---
 
+### Step 0: Prerequisites
+
+Run BEFORE Phase 1. Halt on the first failure with an actionable fix command. Do not prompt for board configuration choices until every prerequisite below succeeds.
+
+1. **Run the shared Prerequisite Check.** Execute the `Prerequisite Check` block in `hatch3r-board-shared` §"Prerequisite Check (run at the start of every board command)" — verifies `.agents/hatch.json` exists, owner/repo configured, and platform CLI authenticated (`gh auth status` / `az account show` / `glab auth status`).
+
+2. **Verify platform credentials at the env-var layer.** The shared prereq check confirms the CLI is authenticated; this step additionally verifies the underlying credential is present for non-interactive runs:
+
+   **If platform is `github`:**
+   - Run `gh auth status` first. If the CLI is already authenticated with the `project` scope, the env var fallback is not required and this step passes.
+   - If `gh auth status` fails or the `project` scope is missing, check for `GITHUB_TOKEN` (preferred for CI) or `GH_TOKEN`. If neither is set, ASK the user using the `agents/shared/user-question-protocol.md` plain-text fallback shape:
+
+     ```
+     **Question:** GitHub CLI is not authenticated and no GITHUB_TOKEN is set. How should I obtain credentials?
+
+     1. Run `gh auth login` interactively now — opens the GitHub OAuth flow in your browser.
+     2. Provide a Personal Access Token here — paste a PAT with the `project` scope; I will set GITHUB_TOKEN for this session only.
+     3. Abort — exit and configure credentials externally; re-run `hatch3r-board-init` afterward.
+
+     Default if no response: 1
+     ```
+
+   **If platform is `azure-devops`:**
+   - Run `az account show`. If it fails, check for `AZURE_DEVOPS_PAT`. If neither is configured, ASK using the same plain-text fallback shape with options: (1) `az login` interactively, (2) provide AZURE_DEVOPS_PAT, (3) abort. Default: 1.
+
+   **If platform is `gitlab`:**
+   - Run `glab auth status`. If it fails, check for `GITLAB_TOKEN`. If neither is configured, ASK using the same plain-text fallback shape with options: (1) `glab auth login` interactively, (2) provide GITLAB_TOKEN, (3) abort. Default: 1.
+
+3. **Verify owner/repo identity.** Read `.agents/hatch.json` and confirm both top-level `owner`/`repo` (or `board.owner`/`board.repo` as fallback) are set and non-empty. If either is empty, ASK using the user-question-protocol plain-text fallback shape:
+
+   ```
+   **Question:** Owner/repo are not configured in `.agents/hatch.json`. How should I capture them?
+
+   1. Provide owner and repo now — paste in this turn; I will write them to `.agents/hatch.json` after Phase 1 confirmation.
+   2. Run `npx hatch3r config` first — abort, configure repo identity, then re-run `hatch3r-board-init`.
+
+   Default if no response: 1
+   ```
+
+4. **Set pager-bypass env vars.** Before the first CLI invocation, export `GH_PAGER=cat` and `PAGER=cat` per `hatch3r-board-shared` §"Pager-Bypass Directive". Required for reliable `gh api --jq` output capture.
+
+5. **Record prerequisite outcomes.** Write each check's outcome (passed / failed-then-resolved / aborted) to the run cache `errors` entry so the end-of-run summary can surface auth-related warnings.
+
+This step is mandatory and non-skippable. Quick / Defaults Mode (§"Quick / Defaults Mode" above) skips Phase 1 ASKs but does NOT skip Step 0 — credential and identity verification run unconditionally before any board mutation.
+
+---
+
 ### Phase 1 — Planning
 
 Collect all configuration choices upfront. No GitHub API calls or file writes in this phase (except reads needed to present options).

package/commands/hatch3r-board-pickup.md

@@ -10,7 +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: 10
+  rationale: Full delivery pipeline — researcher, implementer (one per independent issue in batch mode), reviewer ↔ fixer review loop, then a parallel final-quality batch (test-writer, security-auditor, docs-writer, lint-fixer, a11y-auditor, perf-profiler) bounded by max_phase4_parallel.
 ---
+
+## §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.
+
 # Board Pickup -- Develop Issues from the Project Board
 
 Pick up an epic (with all sub-issues), a single sub-issue, a standalone issue, or **a batch of independent issues** from **{owner}/{repo}** (read from `.agents/hatch.json` board config) for development. The `platform` field determines whether to interact with GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Supports single-issue and multi-issue batch modes. When no specific issue is referenced, auto-picks the next best candidate(s). Respects dependency order and readiness status. Performs collision detection, creates a branch, then delegates implementation via one sub-agent per issue running in parallel.

package/commands/hatch3r-board-refresh.md

@@ -10,6 +10,10 @@ cache_friendly: true
 parallel_tool_default: true
 ---
 
+## §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
 
 This command runs as a single orchestrator without sub-agent delegation.

package/commands/hatch3r-board-shared.md

@@ -21,7 +21,7 @@ This command provides shared context and procedures for board commands. It does
 
 ## Prerequisite Check (run at the start of every board command)
 
-Before reading configuration, validate that prerequisites are met. If any check fails, stop immediately with an actionable error message.
+Before reading configuration, validate that prerequisites are met. If any check fails, stop immediately with an actionable error message. For interactive sessions where credentials are missing, use the `agents/shared/user-question-protocol.md` plain-text fallback shape to offer the user a numbered choice (interactive login / paste-token / abort) instead of a bare stop message.
 
 1. **hatch.json exists:** If `.agents/hatch.json` is missing or unreadable, stop with:
    > "Board commands require a hatch3r project. Run `npx hatch3r init` to set up your project first."
@@ -29,10 +29,10 @@ Before reading configuration, validate that prerequisites are met. If any check
 2. **owner/repo configured:** If both top-level `owner`/`repo` and `board.owner`/`board.repo` are empty, stop with:
    > "Board commands require owner and repo. Run `npx hatch3r config` to set your repository identity, or provide them in `.agents/hatch.json` under the top-level `owner` and `repo` fields."
 
-3. **Platform authentication:** Verify CLI authentication for the configured platform:
-   - **GitHub:** Run `gh auth status`. If it fails, stop with: "GitHub CLI not authenticated. Run `gh auth login` and confirm your PAT has the `project` scope for Projects V2 access. See: https://docs.github.com/en/issues/planning-and-tracking-with-projects"
-   - **Azure DevOps:** Run `az account show`. If it fails, stop with: "Azure CLI not authenticated. Run `az login` or set AZURE_DEVOPS_PAT. Confirm access to organization `{namespace}`."
-   - **GitLab:** Run `glab auth status`. If it fails, stop with: "GitLab CLI not authenticated. Run `glab auth login` or set GITLAB_TOKEN. Confirm access to project `{namespace}/{project}`."
+3. **Platform authentication:** Verify CLI authentication for the configured platform. On failure, ASK via user-question-protocol with three numbered options (interactive login / paste-token / abort) and default to option 1 if no response.
+   - **GitHub:** Run `gh auth status`. If it fails or the `project` scope is missing, check `GITHUB_TOKEN`/`GH_TOKEN` env vars first; if absent, ASK: (1) `gh auth login` interactively, (2) paste a PAT with `project` scope (set GITHUB_TOKEN for this session only), (3) abort. Reference: https://docs.github.com/en/issues/planning-and-tracking-with-projects
+   - **Azure DevOps:** Run `az account show`. If it fails, check `AZURE_DEVOPS_PAT`; if absent, ASK: (1) `az login` interactively, (2) provide AZURE_DEVOPS_PAT, (3) abort. Confirm access to organization `{namespace}`.
+   - **GitLab:** Run `glab auth status`. If it fails, check `GITLAB_TOKEN`; if absent, ASK: (1) `glab auth login` interactively, (2) provide GITLAB_TOKEN, (3) abort. Confirm access to project `{namespace}/{project}`.
 
 4. **projectNumber set (for commands other than board-init):** For `board-fill`, `board-groom`, `board-pickup`, and `board-refresh`, if `board.projectNumber` is null, stop with:
    > "No project board configured. Run the `board-init` command first to create or connect a project board. This sets up the board.projectNumber in `.agents/hatch.json`."
@@ -40,7 +40,7 @@ Before reading configuration, validate that prerequisites are met. If any check
 5. **GitHub PAT project scope (GitHub only, for board-init/fill/groom/pickup):** If GitHub mutations fail with permission errors, surface:
    > "GitHub Projects V2 requires the `project` scope on your PAT. Run `gh auth refresh -s project` to add it. Classic PATs need `admin:org` for org-owned projects."
 
-Report each failed prerequisite with the specific fix command. Do not proceed past the first failure.
+Report each failed prerequisite with the specific fix command. Do not proceed past the first failure. Record each check's outcome (passed / failed-then-resolved / aborted) in the run cache `errors` entry for the end-of-run summary.
 
 ---
 

package/commands/hatch3r-bug-plan.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: 4
+  rationale: Four parallel hatch3r-researcher modes per bug brief — symptom-trace, root-cause-hypothesis, impact-assessment, regression-research — dispatched concurrently in Step 3; a docs-writer assembles the investigation report on their merged output.
 ---
 
+## §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 |

package/commands/hatch3r-codebase-map.md

@@ -10,7 +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: 8
+  rationale: Eight parallel analyzer domains in Step 3 across business + technical dimensions (modules, dependencies, conventions, stack, technical-debt, business-domain, market-context, production-readiness); docs-writers fan out in a second parallel batch in Step 7 (one per document category).
 ---
+
+## §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.
+
 # Codebase Map — Brownfield Codebase Analysis & Spec Generation
 
 Analyze an existing codebase to reverse-engineer project documentation across **two dimensions**: business domain analysis and technical architecture analysis. Discovers modules, dependencies, conventions, tech stack, technical debt, business logic, domain models, and production readiness using parallel analyzer sub-agents. Outputs structured specs to `docs/specs/business/` (business domain, market context, production readiness) and `docs/specs/technical/` (modules, conventions, stack, debt), plus inferred architectural decision records to `docs/adr/`. Optionally generates a root-level `AGENTS.md` as the project's "README for agents." This command is **purely read-only** until the final write step — all analysis is static (file reading, pattern matching). Works for any language or framework.

package/commands/hatch3r-command-customize.md

@@ -10,6 +10,10 @@ cache_friendly: true
 parallel_tool_default: true
 ---
 
+## §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
 
 This command runs as a single orchestrator without sub-agent delegation. Customization file management is performed inline.

package/commands/hatch3r-context-health.md

@@ -9,6 +9,11 @@ efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 ---
+
+## §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
 
 This command monitors context health and recommends delegation. It does not spawn sub-agents directly — it recommends when the orchestrator should delegate to sub-agents due to context degradation.

package/commands/hatch3r-create.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: 1
+  rationale: Single hatch3r-creator delegation in Phase 2 — body composition plus the strict + gentle gate funnel run as one atomic Task per artifact; multi-artifact runs invoke one creator per artifact in parallel.
 ---
 
+## §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
 
 This command runs as an orchestrator. After collecting inputs in Phase 1, it delegates artifact composition and the strict + gentle gate funnel to `hatch3r-creator` via the Task tool. Phase 3 runs `hatch3r validate` and surfaces results inline.
@@ -86,6 +93,26 @@ Present the known tag set: `core, customization, planning, implementation, revie
 
 Cache as `tags` (array).
 
+#### 1.4a: Pillar Declaration (C9-H80, D20-F20.1.2)
+
+Every user artifact must declare at least one Binding Pillar — strict-gate enforced at `saveUserContent` (`src/content/userContent.ts`). Present the 8 pillars with one-line descriptors:
+
+```
+Which pillar(s) does this artifact serve? (one or more — comma-separated)
+  P1 — CLI UI/UX Excellence
+  P2 — Scientific & Practical Quality
+  P3 — Adapter & External Tool Currency
+  P4 — Comprehensive Lean Coverage
+  P5 — Governance Self-Quality
+  P6 — Security & Trust Governance
+  P7 — Speed & Token Efficiency
+  P8 — Clarification & Fan-out Discipline
+```
+
+**ASK:** "Select pillar(s) (e.g., `P4, P6`). At least one is required."
+
+Reject empty input and re-ask. Validate every entry against the `P1..P8` enum. Cache as `pillars` (array). The frontmatter emitter writes the array as `pillars: [P1, P4]`; the strict gate also accepts a `**Pillars:** ...` line in the body.
+
 #### 1.5: Adapter Scope (Optional)
 
 **ASK:** "Restrict this artifact to specific adapters? Press Enter to default to ALL enabled adapters (full parity), or list adapter names like `claude, cursor`."
@@ -96,16 +123,41 @@ Cache as `adapters` (array, or `null` for full parity).
 
 Branch on the cached `type`:
 
-- **agent:** Ask for `model` preference (default: `standard`; options: `fast | standard | reasoning`). Ask for an optional tool-allowlist hint (free-text). Cache as `model` and `toolHint`.
+- **agent:** Ask for `model` preference (default: `standard`; options: `fast | standard | reasoning`). Ask for an optional tool-allowlist hint (free-text). Cache as `model` and `toolHint`. Then ask for a structured `tools` declaration (see §1.6a below) and cache as `tools`.
 - **skill:** Confirm the subdirectory layout. Show: "Skill files are stored as `.agents/user/skills/{name}/SKILL.md` (a new directory will be created). Continue?" — ASK Y/n.
 - **rule:** Ask for scope: `always` (loaded every session) or `conditional` (loaded by glob match). If `conditional`, ASK for a comma-separated glob list (e.g., `src/**/*.ts, src/**/*.tsx`). Then ASK for `precedence` (one of `critical | high | normal | low`, default `normal`). Cache as `ruleScope`, `ruleGlobs`, `rulePrecedence`.
 - **command:** ASK whether this is an orchestrator command. If yes, ASK for the agent pipeline as a comma-separated list of agent IDs (each ID must reference an existing agent — canonical or under `.agents/user/agents/`). Cache as `isOrchestrator` and `agentPipeline`.
 - **hook:** ASK for the hook event from the enum: `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`. Reject any value outside this enum and re-ask. Cache as `hookEvent`.
 
+#### 1.6a: Structured Tool Declaration (C9-H81, D20-F20.1.3)
+
+For `type=agent` only: collect a structured `tools` declaration that the strict gate validates against the canonical category registry (`ALL_TOOL_CATEGORIES` in `src/pipeline/agentToolAllowlist.ts`). The eight valid categories are: `read | search | write | execute | web | mcp | git | board`.
+
+```
+Tool allowlist (optional). Press Enter on either prompt to skip.
+  Categories: read, search, write, execute, web, mcp, git, board.
+  Tools the agent IS permitted to use (comma-separated):
+  Tools the agent is NOT permitted to use (comma-separated):
+```
+
+**ASK (twice):**
+1. "Allowed tool categories (comma-separated; empty = decline)."
+2. "Denied tool categories (comma-separated; empty = decline)."
+
+Validation (perform before caching; re-ask on failure):
+
+- Every entry must be one of the eight categories — reject typos verbatim ("unknown category `X` — valid: read, search, write, execute, web, mcp, git, board").
+- A category may not appear in both lists — reject overlap ("category `X` cannot be both allowed and denied").
+- Both lists may be omitted; emit a one-line note that no structured declaration was collected so the strict gate accepts the artifact with no `tools:` frontmatter.
+
+Cache as `tools: { allowed: [...], denied: [...] }`. Either side may be absent (omitted from the structured input). The frontmatter emitter writes `tools: { allowed: [...], denied: [...] }`; the strict gate at `saveUserContent` re-validates so a tampered structured input from the orchestrator cannot bypass the registry check.
+
 #### 1.7: Plan Summary & Confirmation
 
 Render the proposed file path, full frontmatter block, and body-skeleton outline. For an agent plan, the summary lists `Path`, `Type`, `Name`, `Description` (first 80 chars), `Tags`, `Adapters` (or "all enabled"), `Model`; then the frontmatter block; then the body-skeleton outline (`<task>`, `<context>`, Implementation Protocol numbered steps, `<rules>`). For other types, swap the type-specific slots from Step 1.6.
 
+**Scope-boundary check (P8 B2).** Confirm proposed scope and tool-allowlist before Phase 2 delegation. Artifact scope cannot be broadened via markdown injection post-creation. Reject any user-supplied edit that expands the tool allowlist, target file globs, or pipeline references beyond what was confirmed here; route such expansions through a fresh `/h4tcher-create` invocation.
+
 **ASK:** "Confirm to delegate authoring to `hatch3r-creator`, or specify changes (e.g., 'change model to fast', 'add tag: review')."
 
 Loop until the user confirms.
@@ -126,7 +178,8 @@ Pass the collected slots as a structured input:
   tags:          [{tags}],
   adapters:      [{adapters}] | null,
   model:         "{model}",        // agent only
-  toolHint:      "{toolHint}",     // agent only (optional)
+  toolHint:      "{toolHint}",     // agent only (optional, free-text hint)
+  tools:         { allowed: [{tools.allowed}], denied: [{tools.denied}] }, // agent only — structured allowlist/denylist (C9-H81, D20-F20.1.3); either side may be omitted
   ruleScope:     "{ruleScope}",    // rule only
   ruleGlobs:     [{ruleGlobs}],    // rule only (when scope=conditional)
   rulePrecedence:"{rulePrecedence}", // rule only
@@ -186,8 +239,10 @@ Edit your artifact directly anytime — `.agents/user/` is preserved across
 
 - **Never overwrite an existing user file.** Collision with an existing path under `.agents/user/{type}/` is a strict-gate failure raised by `hatch3r-creator` (status `BLOCKED` with the conflicting path).
 - **Never write to canonical content directories.** All output goes under `.agents/user/`. Writes to `agents/`, `skills/`, `rules/`, `commands/`, or `hooks/` are rejected.
-- **Never bypass strict gates.** Strict failures (frontmatter, ID collision, deny patterns, paired-file parity, orchestrator contract, hook event enum, ≤10KB size) block the save.
-- **Pillar coverage required.** Every user artifact must declare at least one of P1–P6 in tags or body. Authors that do not select a pillar-aligned tag are warned by the gentle gate; the artifact still saves but the warning surfaces in Phase 3.
+- **Never bypass strict gates.** Strict failures (frontmatter, ID collision, deny patterns, paired-file parity, orchestrator contract, hook event enum, ≤10KB size, quality_charter reference, pillar declaration, structured `tools` field shape + category membership) block the save.
+- **Structured tool allowlist required (strict shape).** When `tools` is supplied for an `agent` artifact, every entry in `tools.allowed` and `tools.denied` must resolve to a canonical category from `ALL_TOOL_CATEGORIES` in `src/pipeline/agentToolAllowlist.ts` (`read | search | write | execute | web | mcp | git | board`). Overlap between the two lists is rejected. Strict-gate enforced at `saveUserContent` (C9-H81, D20-F20.1.3; depends on C9-H49 Hybrid allowlist).
+- **Pillar coverage required (strict).** Every user artifact must declare at least one of P1–P8 — via `pillars: [...]` in frontmatter (collected at Step 1.4a) or a `**Pillars:** ...` line in the body. The strict gate at `saveUserContent` blocks the save when neither is present (C9-H80, D20-F20.1.2).
+- **Quality charter inheritance required (strict).** Every user artifact must reference `agents/shared/quality-charter.md` — via `quality_charter:` in frontmatter or a `quality_charter` mention in the body. Strict-gate enforced at `saveUserContent` (C9-H79, D20-F20.1.1, closes CD-12 partial).
 - **One artifact per invocation.** Re-run `/hatch3r-create` for additional artifacts.
 
 ---

package/commands/hatch3r-debug.md

@@ -10,7 +10,14 @@ efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 6
+  rationale: Six-stage pipeline per agentPipeline — researcher → implementer → reviewer ↔ fixer review loop (max 3 iterations) → parallel final-quality pass (test-writer + security-auditor); serialization only across true dependency edges (logs → root cause → fix → verify).
 ---
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's bug description and provided context for unresolved questions in scope, reproduction conditions, irreversibility, or constraint conflicts (contradictory symptoms, missing environment details, unknown affected area). 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 the bug is single-file, single-symptom, and the brief alone identifies the reproduction path. The Stage 1c "ASK" rule remains in force for residual ambiguity discovered mid-workflow.
+
 # Debug — Instrument, Diagnose, and Fix from Runtime Evidence
 
 Standalone debug-and-fix command that instruments the codebase with strategic debug logging, pauses for the user to reproduce the issue and provide runtime logs, performs root cause analysis from the collected evidence, implements the fix, and removes all debug artifacts. Five-stage workflow: Gather Context → Add Debug Logging → Collect Logs (user checkpoint) → Root Cause Analysis → Implement Fix. Works independently — no board integration, no GitHub issue required.