hatch3r 1.7.1 → 1.7.5

package/rules/hatch3r-container-hardening.mdc

@@ -0,0 +1,127 @@
+---
+description: Container image hardening — digest pinning, distroless / Wolfi base, non-root user, SBOM-in-image, cosign signing + verification, multi-stage builds, CVE scanning
+globs: ["**/Dockerfile*", "**/docker-compose*", "**/*.containerfile", "**/charts/**", "**/k8s/**", "**/kubernetes/**", "**/manifests/**"]
+alwaysApply: false
+---
+# Container Hardening
+
+## Base Image: Wolfi / Chainguard Images
+
+The 2026 baseline for container images is Wolfi-OS via Chainguard Images — rebuilt nightly from source, granular per-package versions, no kernel, distroless philosophy. Distroless (Google) remains a valid fallback when Chainguard's commercial offering is out of scope.
+
+- Pin every base image by digest, never by tag. Mutable tags (`latest`, `1`, `1.2`) are an attack vector — the registry can serve a different image under the same tag at any time.
+- Example: `FROM cgr.dev/chainguard/node:latest@sha256:<64-hex-digest>` (the `latest` tag is acceptable only when paired with a `@sha256:` digest pin; the digest is the authority).
+- Drift detection: a scheduled CI job re-resolves base-image tags and opens a PR when a newer digest publishes; reviewer inspects CVE delta before merging.
+
+## Multi-Stage Builds
+
+Separate the builder from the runtime image. The builder carries the full toolchain (compilers, package managers, dev headers); the runtime carries only the produced artifact plus a distroless or Wolfi base.
+
+- Builder stage: install build deps, compile, run tests. May be heavy.
+- Runtime stage: `FROM cgr.dev/chainguard/static:latest@sha256:...` (for static binaries) or `cgr.dev/chainguard/node:latest@sha256:...` (for Node services). `COPY --from=builder` only the artifacts needed at runtime.
+- Result: smaller image, fewer CVEs at runtime, no source code or build tools shipped to production.
+
+## Non-Root User
+
+Production containers run as a non-root user. Root-in-container plus container-escape-CVE equals root-on-host.
+
+- `USER 65532:65532` (the `nobody` UID on most distros) or a named non-root user declared in the Dockerfile.
+- Kubernetes pod security: `runAsNonRoot: true`, `runAsUser: 65532`, `runAsGroup: 65532`, `readOnlyRootFilesystem: true`, `allowPrivilegeEscalation: false`, `capabilities.drop: [ALL]`.
+- Writable paths use `emptyDir` or `persistentVolumeClaim` mounts, not the root filesystem.
+
+## No Shell, Minimal Binaries
+
+Distroless `:nonroot` variants and Chainguard `static` images ship without `/bin/sh`. A compromised process cannot fall back to a shell for lateral movement.
+
+- Production image set is `:nonroot` or `static`. Debug variants (`:debug`, `:debug-nonroot`) include `sh` and `busybox` and are pulled only for local troubleshooting.
+- `kubectl debug --image=cgr.dev/chainguard/wolfi-base` provides ephemeral debug containers without baking shells into production images.
+
+## SBOM-in-Image
+
+Every image carries a CycloneDX 1.6 SBOM, generated at build time and either embedded in the image or attached as an OCI artifact in the registry.
+
+- Generation: `syft <image> -o cyclonedx-json` or BuildKit `--attest type=sbom`. Chainguard Images already ship with attached SBOMs.
+- Attachment: `cosign attach sbom --sbom sbom.cdx.json <image>:<tag>` or BuildKit attestation in the OCI manifest.
+- Deploy-time consumers fetch the SBOM via `cosign download sbom <image>` and match against the CVE feed before admission.
+
+## Image Signing — cosign
+
+Every image is signed with cosign keyless mode via OIDC. Sigstore Fulcio issues a short-lived signing certificate scoped to the workflow identity; Rekor records the signature for tamper-evident audit.
+
+- Sign in CI: `cosign sign --yes <registry>/<image>@<digest>`. Workflow grants `id-token: write` permission; no long-lived signing key.
+- Verify at deploy: `cosign verify <image> --certificate-identity-regexp 'https://github\.com/org/repo/\.github/workflows/.*' --certificate-oidc-issuer https://token.actions.githubusercontent.com`.
+- Admission enforcement: Sigstore Policy Controller (native admission with CUE or Rego), Kyverno (`verifyImages` rule), or OPA Gatekeeper + Ratify. Unsigned images rejected at admission, not just warned.
+
+## CVE Scanning in CI
+
+Two scanners are run per image build: `trivy` for breadth (Wolfi advisory database, OS+language deps) and `grype` for Chainguard parity. Release is blocked on unpatched Critical or High CVEs without a documented suppression record.
+
+- `trivy image --severity HIGH,CRITICAL --exit-code 1 <image>:<tag>` fails the job on any High/Critical.
+- Periodic re-scan: a nightly job re-pulls each production image digest and rescans — newly-disclosed CVEs in already-deployed images surface here.
+- Suppressions documented in `.trivyignore` with CVE ID, justification, expiry date, and owner. Expired suppressions fail the build.
+
+## Digest Pinning Everywhere
+
+The same digest-not-tag rule extends beyond `FROM` lines to every place the image is referenced.
+
+- Kubernetes manifests: `image: <registry>/<image>@sha256:<digest>` in Deployment, StatefulSet, Job, CronJob.
+- Helm charts: `appVersion` references the digest; `image.tag` is the digest, not a semver tag.
+- GitOps repos (Argo CD, Flux): the source of truth is the digest; image-update controllers (`flux image-update`) bump the digest on signed-image admission events.
+- Pull policy: `imagePullPolicy: IfNotPresent` (digests are immutable so pull-once is safe); `Always` is only required when tags are used.
+
+## Reproducible Builds
+
+Build inputs are pinned so the same `git checkout` produces the same image digest.
+
+- `# syntax=docker/dockerfile:1.<minor>.<patch>` — pin to a specific BuildKit syntax version.
+- Package installs pin versions: `apk add --no-cache nodejs=20.11.1-r0` (Wolfi/Alpine), `apt-get install -y nodejs=20.11.1*` (Debian).
+- Deterministic `COPY` order: copy lockfile and install deps before copying source, so layer caching is stable.
+- `SOURCE_DATE_EPOCH` set from git commit timestamp strips filesystem timestamps.
+- Verify with `reproducible-containers/repro-build`: rebuild and compare digests; mismatches fail.
+
+## Secrets Handling in Images
+
+Secrets never enter the image at build time. Runtime injection only.
+
+- Forbidden: `COPY .env`, `ARG NPM_TOKEN`, `ENV API_KEY=...`. Build args persist in image history and are recoverable by anyone with image pull access.
+- Build-time secrets (private registry tokens, SSH keys) use BuildKit `--mount=type=secret,id=<name>` — mounted at build, never persisted.
+- Runtime secrets injected via container env (from Kubernetes Secret or vault sidecar), mounted file (CSI Secret Store driver), or IAM role / Workload Identity for cloud auth.
+
+## Health Checks
+
+Every long-running container declares readiness, liveness, and startup probes. Cross-reference `rules/hatch3r-operability.md`.
+
+- Dockerfile `HEALTHCHECK CMD <command>` for non-orchestrated deployments.
+- Kubernetes `livenessProbe`, `readinessProbe`, `startupProbe` with HTTP, TCP, or exec checks. Startup probe allows slow boots (e.g., JVM warmup) without failing liveness during startup.
+- Probe endpoints implemented at the application layer; `/healthz` (liveness), `/readyz` (readiness), `/startz` (startup) is the conventional split.
+
+## Image Size Budget
+
+Runtime image targets under 200 MB compressed. Builds exceeding 500 MB compressed page the platform team for review.
+
+- Strip debug symbols and source maps from production artifacts in the builder stage.
+- Single-binary services (Go, Rust) target Chainguard `static` images — typical runtime under 20 MB.
+- Multi-arch images do not multiply the size budget — each architecture is measured independently.
+
+## Verification Gate at Release
+
+Every release pipeline executes the following gates before publish, all green:
+
+- `cosign verify` against the workflow OIDC identity.
+- `trivy image` and `grype` zero Critical, zero High (or all High suppressed with documented expiry).
+- Image digest pinned in every consuming manifest (rejected if any `image:` line uses a tag without digest).
+- Pod spec runs as non-root (`runAsNonRoot: true`), read-only root filesystem, dropped capabilities.
+- SBOM attached and downloadable via `cosign download sbom`.
+
+Cross-reference `agents/hatch3r-security-auditor.md` for runtime security audit; `agents/hatch3r-devops.md` for delivery integration; `rules/hatch3r-secrets-management.md` for OIDC trust-policy conditions; `rules/hatch3r-dependency-management.md` for SBOM tooling and SLSA provenance.
+
+## References
+
+- Chainguard Images: https://edu.chainguard.dev/chainguard/chainguard-images/overview/
+- Distroless: https://github.com/GoogleContainerTools/distroless
+- Sigstore cosign: https://docs.sigstore.dev/cosign/overview/
+- Sigstore Policy Controller: https://docs.sigstore.dev/policy-controller/overview/
+- Kyverno image verification: https://kyverno.io/docs/policy-types/verify-images/sigstore/
+- SLSA v1.0 spec: https://slsa.dev/spec/v1.0/
+- Trivy: https://trivy.dev/latest/docs/target/container_image/
+- CISA tj-actions advisory (CVE-2025-30066): https://www.cisa.gov/news-events/alerts/2025/03/18/supply-chain-compromise-third-party-github-action

package/rules/hatch3r-contract-testing.md

@@ -0,0 +1,117 @@
+---
+id: hatch3r-contract-testing
+type: rule
+description: Consumer-driven and spec-driven contract testing between services — Pact, Schemathesis, Dredd, pact-broker can-i-deploy gate
+scope: "**/contracts/**,**/pacts/**,**/api/**,**/openapi*,**/asyncapi*,**/*.proto,**/__tests__/contract/**"
+tags: [review, implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Contract Testing
+
+Pairs `rules/hatch3r-api-design.md` (shape) and `rules/hatch3r-api-versioning.md` (lifecycle) with the verification gate that proves consumer-provider compatibility before deploy.
+
+## When To Use Contract Testing
+
+- **Mandatory** for any cross-team service boundary — two services owned by different teams that exchange messages or RPCs.
+- **Mandatory** for any service-to-service call across a deploy boundary (independent CI pipelines, independent release cadences).
+- **Optional** for in-team boundaries where strong types + integration tests already prove the contract.
+- **Not a substitute** for end-to-end tests — contract tests verify the protocol; E2E verifies the user flow.
+
+## Consumer-Driven Contract Testing (CDCT) — Pact
+
+Pact is the de facto CDCT framework. The flow:
+
+1. **Consumer test:** consumer writes expectations (`given`/`uponReceiving`/`willRespondWith`); Pact records the interactions to a `.pact.json` file and runs the consumer test against an in-process mock provider.
+2. **Publish:** consumer CI publishes the Pact file to a Pact Broker / PactFlow instance with the consumer's git SHA + branch tag.
+3. **Provider verification:** provider CI runs `pact-verifier` against every Pact published against its name; replays each interaction against the real provider implementation and asserts the response matches.
+4. **Deploy gate:** `pact-broker can-i-deploy --pacticipant <service> --version <sha> --to-environment production` returns non-zero if any consumer's verification is failing for the version being deployed.
+
+The `can-i-deploy` gate is the contract-testing equivalent of `npm test` — every production deploy passes it.
+
+## Bi-Directional Contract Testing (BDCT) — PactFlow
+
+When the provider already publishes OpenAPI (or AsyncAPI) and runs self-verification (Dredd/Schemathesis), BDCT avoids the cost of provider Pact verification:
+
+- Provider publishes its OpenAPI spec + self-verification results to PactFlow.
+- Consumer publishes Pact as usual.
+- PactFlow cross-verifies: every consumer expectation must match an OpenAPI operation; every operation field consumed must exist in the OpenAPI response schema.
+- Use BDCT for high-traffic providers where running Pact verification on every consumer PR is expensive; reverts to CDCT if drift is detected between OpenAPI and live behavior.
+
+## Spec-Driven Contract Testing — Schemathesis
+
+Schemathesis generates property-based tests from OpenAPI 3.0 / 3.1 (and GraphQL) schemas:
+
+- Runs against the live provider implementation; fuzzes inputs based on the spec; asserts every response conforms to the documented schema, status codes, and headers.
+- Catches drift between spec and implementation that CDCT alone misses (Pact only verifies the interactions consumers actually request).
+- Published research (`schemathesis.readthedocs.io` benchmark studies) shows Schemathesis finds 1.4-4.5x more defects than Pact-alone on the same providers.
+- Run on every provider PR; report property-based failures with reproducer URLs.
+
+## Other Tools
+
+- **Dredd** — executable contracts from OpenAPI / API Blueprint; declarative happy-path verification. Use for simple cases where Schemathesis is overkill; legacy.
+- **Hoverfly** — proxy-based service virtualization for stateful integration scenarios (record/replay). Useful when downstream dependencies cannot be mocked from a spec.
+
+## Coverage Policy
+
+Every cross-service interaction is covered by:
+
+1. **Consumer side:** Pact test in the consumer's `__tests__/contract/` directory, published to the broker on every consumer PR.
+2. **Provider side:** Schemathesis property-based tests against the provider's OpenAPI spec, run on every provider PR.
+3. **Cross-verification:** `pact-verifier` (CDCT) or PactFlow BDCT replays consumer expectations against the provider implementation on every provider PR + consumer PR (matrix verification — provider PRs verify against every consumer's latest tag; consumer PRs verify against the provider's `main`).
+
+GraphQL: consumers register persisted queries; the registry doubles as the contract — every operation in the manifest is verifiable against the schema via `graphql-inspector validate`.
+
+gRPC: `buf breaking` catches protocol-level breaks; pact-protobuf-plugin or grpcurl-based provider verification catches behavior-level breaks.
+
+## `can-i-deploy` Gate
+
+Every production deploy runs:
+
+```
+pact-broker can-i-deploy \
+  --pacticipant <service-name> \
+  --version <git-sha> \
+  --to-environment production
+```
+
+- Exit non-zero blocks the deploy via the CI gate.
+- Failure messages list which consumer's verification is missing or failing — the deploy operator can read which contract is incompatible.
+- Pair with PactFlow's `webhook` to trigger consumer verifications when the provider publishes a new tag.
+
+## Contract Evolution
+
+- Providers **may** add fields freely; consumers ignore unknown fields by default (Pact + Schemathesis verify that expected fields are present, not that the response contains only those fields).
+- Providers **may not** remove or rename fields without an RFC 9745 Deprecation + RFC 8594 Sunset cycle — cross-reference `rules/hatch3r-api-versioning.md` for the lifecycle.
+- Consumers may add new expectations; the next provider verification run reveals whether the provider supports them.
+- Pact files are immutable once published — never edit a published pact retroactively. Republish under a new consumer version.
+
+## Tooling Per Ecosystem
+
+| Ecosystem | Consumer SDK | Provider verifier |
+|-----------|--------------|-------------------|
+| Node / TS | `@pact-foundation/pact` (pact-js) | `pact-js` verifier or `pact-cli` |
+| Ruby | `pact` gem | `pact-provider-verifier` |
+| JVM | `au.com.dius.pact:pact-jvm-consumer` | `pact-jvm-provider` |
+| Go | `pact-go` | `pact-go verify` |
+| Python | `pact-python` + Schemathesis (spec-driven) | `pact-python` verifier |
+| Rust | `pact_consumer` / `pact_verifier` | `pact_verifier_cli` |
+| .NET | `PactNet` | `PactNet.Verifier` |
+
+Schemathesis is Python-only on the runner side but verifies any OpenAPI 3.x provider regardless of provider language.
+
+## Anti-Patterns
+
+- **Never** mock provider responses in consumer unit tests bypassing Pact — defeats the purpose of CDCT.
+- **Never** run consumer tests against the production provider — use the Pact mock; production data and contract drift get conflated.
+- **Never** edit a published pact retroactively — republish under a new consumer version. The broker keeps the original immutable.
+- **Never** skip `can-i-deploy` because "tests are green locally" — local Pact tests verify the mock, not the live provider.
+- **Never** use only Schemathesis without Pact (or vice versa) — they catch different failure classes (drift vs incompatibility); both are required for full coverage.
+
+## References
+
+- Pact — https://docs.pact.io
+- PactFlow BDCT — https://docs.pactflow.io/docs/bi-directional-contract-testing
+- Schemathesis — https://schemathesis.readthedocs.io
+- `pact-broker can-i-deploy` — https://docs.pact.io/pact_broker/can_i_deploy
+- Standard Webhooks (for webhook contract testing) — https://github.com/standard-webhooks/standard-webhooks

package/rules/hatch3r-contract-testing.mdc

@@ -0,0 +1,113 @@
+---
+description: Consumer-driven and spec-driven contract testing between services — Pact, Schemathesis, Dredd, pact-broker can-i-deploy gate
+globs: ["**/contracts/**", "**/pacts/**", "**/api/**", "**/openapi*", "**/asyncapi*", "**/*.proto", "**/__tests__/contract/**"]
+alwaysApply: false
+---
+# Contract Testing
+
+Pairs `rules/hatch3r-api-design.md` (shape) and `rules/hatch3r-api-versioning.md` (lifecycle) with the verification gate that proves consumer-provider compatibility before deploy.
+
+## When To Use Contract Testing
+
+- **Mandatory** for any cross-team service boundary — two services owned by different teams that exchange messages or RPCs.
+- **Mandatory** for any service-to-service call across a deploy boundary (independent CI pipelines, independent release cadences).
+- **Optional** for in-team boundaries where strong types + integration tests already prove the contract.
+- **Not a substitute** for end-to-end tests — contract tests verify the protocol; E2E verifies the user flow.
+
+## Consumer-Driven Contract Testing (CDCT) — Pact
+
+Pact is the de facto CDCT framework. The flow:
+
+1. **Consumer test:** consumer writes expectations (`given`/`uponReceiving`/`willRespondWith`); Pact records the interactions to a `.pact.json` file and runs the consumer test against an in-process mock provider.
+2. **Publish:** consumer CI publishes the Pact file to a Pact Broker / PactFlow instance with the consumer's git SHA + branch tag.
+3. **Provider verification:** provider CI runs `pact-verifier` against every Pact published against its name; replays each interaction against the real provider implementation and asserts the response matches.
+4. **Deploy gate:** `pact-broker can-i-deploy --pacticipant <service> --version <sha> --to-environment production` returns non-zero if any consumer's verification is failing for the version being deployed.
+
+The `can-i-deploy` gate is the contract-testing equivalent of `npm test` — every production deploy passes it.
+
+## Bi-Directional Contract Testing (BDCT) — PactFlow
+
+When the provider already publishes OpenAPI (or AsyncAPI) and runs self-verification (Dredd/Schemathesis), BDCT avoids the cost of provider Pact verification:
+
+- Provider publishes its OpenAPI spec + self-verification results to PactFlow.
+- Consumer publishes Pact as usual.
+- PactFlow cross-verifies: every consumer expectation must match an OpenAPI operation; every operation field consumed must exist in the OpenAPI response schema.
+- Use BDCT for high-traffic providers where running Pact verification on every consumer PR is expensive; reverts to CDCT if drift is detected between OpenAPI and live behavior.
+
+## Spec-Driven Contract Testing — Schemathesis
+
+Schemathesis generates property-based tests from OpenAPI 3.0 / 3.1 (and GraphQL) schemas:
+
+- Runs against the live provider implementation; fuzzes inputs based on the spec; asserts every response conforms to the documented schema, status codes, and headers.
+- Catches drift between spec and implementation that CDCT alone misses (Pact only verifies the interactions consumers actually request).
+- Published research (`schemathesis.readthedocs.io` benchmark studies) shows Schemathesis finds 1.4-4.5x more defects than Pact-alone on the same providers.
+- Run on every provider PR; report property-based failures with reproducer URLs.
+
+## Other Tools
+
+- **Dredd** — executable contracts from OpenAPI / API Blueprint; declarative happy-path verification. Use for simple cases where Schemathesis is overkill; legacy.
+- **Hoverfly** — proxy-based service virtualization for stateful integration scenarios (record/replay). Useful when downstream dependencies cannot be mocked from a spec.
+
+## Coverage Policy
+
+Every cross-service interaction is covered by:
+
+1. **Consumer side:** Pact test in the consumer's `__tests__/contract/` directory, published to the broker on every consumer PR.
+2. **Provider side:** Schemathesis property-based tests against the provider's OpenAPI spec, run on every provider PR.
+3. **Cross-verification:** `pact-verifier` (CDCT) or PactFlow BDCT replays consumer expectations against the provider implementation on every provider PR + consumer PR (matrix verification — provider PRs verify against every consumer's latest tag; consumer PRs verify against the provider's `main`).
+
+GraphQL: consumers register persisted queries; the registry doubles as the contract — every operation in the manifest is verifiable against the schema via `graphql-inspector validate`.
+
+gRPC: `buf breaking` catches protocol-level breaks; pact-protobuf-plugin or grpcurl-based provider verification catches behavior-level breaks.
+
+## `can-i-deploy` Gate
+
+Every production deploy runs:
+
+```
+pact-broker can-i-deploy \
+  --pacticipant <service-name> \
+  --version <git-sha> \
+  --to-environment production
+```
+
+- Exit non-zero blocks the deploy via the CI gate.
+- Failure messages list which consumer's verification is missing or failing — the deploy operator can read which contract is incompatible.
+- Pair with PactFlow's `webhook` to trigger consumer verifications when the provider publishes a new tag.
+
+## Contract Evolution
+
+- Providers **may** add fields freely; consumers ignore unknown fields by default (Pact + Schemathesis verify that expected fields are present, not that the response contains only those fields).
+- Providers **may not** remove or rename fields without an RFC 9745 Deprecation + RFC 8594 Sunset cycle — cross-reference `rules/hatch3r-api-versioning.md` for the lifecycle.
+- Consumers may add new expectations; the next provider verification run reveals whether the provider supports them.
+- Pact files are immutable once published — never edit a published pact retroactively. Republish under a new consumer version.
+
+## Tooling Per Ecosystem
+
+| Ecosystem | Consumer SDK | Provider verifier |
+|-----------|--------------|-------------------|
+| Node / TS | `@pact-foundation/pact` (pact-js) | `pact-js` verifier or `pact-cli` |
+| Ruby | `pact` gem | `pact-provider-verifier` |
+| JVM | `au.com.dius.pact:pact-jvm-consumer` | `pact-jvm-provider` |
+| Go | `pact-go` | `pact-go verify` |
+| Python | `pact-python` + Schemathesis (spec-driven) | `pact-python` verifier |
+| Rust | `pact_consumer` / `pact_verifier` | `pact_verifier_cli` |
+| .NET | `PactNet` | `PactNet.Verifier` |
+
+Schemathesis is Python-only on the runner side but verifies any OpenAPI 3.x provider regardless of provider language.
+
+## Anti-Patterns
+
+- **Never** mock provider responses in consumer unit tests bypassing Pact — defeats the purpose of CDCT.
+- **Never** run consumer tests against the production provider — use the Pact mock; production data and contract drift get conflated.
+- **Never** edit a published pact retroactively — republish under a new consumer version. The broker keeps the original immutable.
+- **Never** skip `can-i-deploy` because "tests are green locally" — local Pact tests verify the mock, not the live provider.
+- **Never** use only Schemathesis without Pact (or vice versa) — they catch different failure classes (drift vs incompatibility); both are required for full coverage.
+
+## References
+
+- Pact — https://docs.pact.io
+- PactFlow BDCT — https://docs.pactflow.io/docs/bi-directional-contract-testing
+- Schemathesis — https://schemathesis.readthedocs.io
+- `pact-broker can-i-deploy` — https://docs.pact.io/pact_broker/can_i_deploy
+- Standard Webhooks (for webhook contract testing) — https://github.com/standard-webhooks/standard-webhooks

package/rules/hatch3r-deep-context.md

@@ -51,6 +51,8 @@ Multi-file changes with clear scope. Run these researcher modes at `quick` depth
 
 Present findings to the user inline. Proceed after answers are received — no separate confirmation checkpoint required.
 
+**Tier 2 confirmation gate.** Before invoking Phase 2, the orchestrator lists any unresolved scope, acceptance, or constraint questions and asks the user to confirm or answer via the platform-native question tool (`agents/shared/user-question-protocol.md`). The orchestrator does not proceed under default-if-no-response for Tier 2 unless the question is single-option-reversible.
+
 ### Tier 3 — Deep
 
 Cross-module features, architectural changes, multi-layer implementations, or tasks with high ambiguity. Run these researcher modes at `deep` depth:

package/rules/hatch3r-deep-context.mdc

@@ -46,6 +46,8 @@ Multi-file changes with clear scope. Run these researcher modes at `quick` depth
 
 Present findings to the user inline. Proceed after answers are received — no separate confirmation checkpoint required.
 
+**Tier 2 confirmation gate.** Before invoking Phase 2, the orchestrator lists any unresolved scope, acceptance, or constraint questions and asks the user to confirm or answer via the platform-native question tool (`agents/shared/user-question-protocol.md`). The orchestrator does not proceed under default-if-no-response for Tier 2 unless the question is single-option-reversible.
+
 ### Tier 3 — Deep
 
 Cross-module features, architectural changes, multi-layer implementations, or tasks with high ambiguity. Run these researcher modes at `deep` depth:

package/rules/hatch3r-dependency-management.md

@@ -3,7 +3,7 @@ id: hatch3r-dependency-management
 type: rule
 description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, and bundle-size impact gates for package manifests
 scope: "**/package.json,**/package-lock.json,**/yarn.lock,**/pnpm-lock.yaml,**/Cargo.toml,**/Cargo.lock,**/requirements*.txt,**/pyproject.toml,**/go.mod,**/go.sum,**/Gemfile*"
-tags: [maintenance]
+tags: [maintenance, security]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -30,3 +30,75 @@ cache_friendly: true
 - Review changelogs and migration guides before upgrading major versions. Never blindly bump major versions and assume backward compatibility.
 - Run the full test suite after any dependency upgrade, including integration tests. A passing unit test suite does not guarantee compatibility with upgraded peer dependencies.
 - When upgrading a shared dependency used across multiple modules, upgrade all consumers in the same PR to avoid version skew within the monorepo or project.
+
+## npm Trusted Publishing (OIDC)
+
+For libraries published to npm, configure an npm Trusted Publisher with GitHub OIDC. The publishing workflow exchanges a per-run JWT for short-lived publish credentials — no long-lived `NPM_TOKEN` in secrets. Provenance attestations are auto-generated and signed by Sigstore Fulcio with the inclusion record in Rekor.
+
+- Requirements: npm CLI >=11.5.1, Node >=22.14.0, `repository` field set in `package.json` (provenance validation fails without it).
+- Workflow grants `id-token: write` permission at the job level.
+- Remove `NPM_TOKEN` from repository and organization secrets after migrating to trusted publishing.
+- PyPI, crates.io, and RubyGems offer equivalent OIDC trusted publishing — migrate at least one ecosystem per release pipeline.
+
+## Provenance Flag for Non-Trusted Publishing
+
+When trusted publishing is not yet enabled, publish with `npm publish --provenance`. The flag activates Sigstore-signed provenance even with token auth.
+
+- Verify provenance: `npm view <pkg> --json | jq .dist.attestations` returns Sigstore attestation URLs; the npm package page renders a Provenance section.
+- Consumers verify on install: `npm audit signatures` walks the attestation chain and confirms Rekor inclusion.
+
+## SBOM Generation
+
+Every release artifact ships a CycloneDX 1.6 or SPDX 3.0.1 SBOM, committed as a release asset and signed with the same Sigstore identity that signed the artifact. CycloneDX 1.6 is ECMA-424 ratified and broadly supported (Syft, Trivy, cdxgen, GitLab native). SPDX 3.0.1 is the BSI TR-03183-2 / EU CRA baseline.
+
+- Tooling baseline: `npm sbom --sbom-format=cyclonedx` (npm 10+), `cdxgen` (broad ecosystem coverage including Python, Java, Rust, Go), `syft` (containers + source repos).
+- CI step generates SBOM on every release tag and uploads as a release asset.
+- PR-time SBOM diff (`cyclonedx-cli diff` or `syft diff`) blocks PRs that introduce unexpected new transitive dependencies; reviewer approves the diff alongside the source diff.
+
+## SLSA v1.0 / v1.1 Build Provenance
+
+Target SLSA Build L3 for production release artifacts: ephemeral hosted runner, isolated builder identity, signed in-toto provenance, transparency log inclusion. SLSA v1.1 (April 2025) is incremental on the Build track — v1.0 L3 artifacts also meet v1.1 L3.
+
+- GitHub Actions implementation: `slsa-framework/slsa-github-generator` (language-agnostic generators for npm, container, generic artifact).
+- Deploy-time verification: `slsa-verifier` CLI confirms provenance, builder identity allow-list, and source-repo match before the artifact is consumed.
+- Pin the generator action to a 40-char commit SHA per the action-pinning policy below.
+
+## Malicious-Package Detection Beyond `npm audit`
+
+`npm audit` only flags published CVEs. The 2025-2026 incident class — Shai-Hulud (Sep-Nov 2025), Axios 1.14.1 maintainer hijack (Mar 2026), Mini-Shai-Hulud (May 2026), DevTap typosquat (Apr-May 2026) — never reaches a CVE filing. Layer install-time behavioral detection on top of `npm audit`:
+
+- Pre-install behavioral scan: `socket.dev`, `snyk`, or `osv-scanner` against the lockfile in CI. `npq` adds a pre-install gate at the developer workstation.
+- pnpm `minimumReleaseAge: 72` (3 days, raise to 7 for high-trust projects) blocks consumption of brand-new versions until the typosquat / maintainer-hijack window closes.
+- Disable lifecycle scripts in CI: `.npmrc` sets `ignore-scripts=true`; pnpm uses `strictDepBuilds: true` plus `allowBuilds: [explicit-list]`.
+- GitHub `dependency-review-action` on every PR blocks new dependencies with known advisories or disallowed licenses.
+
+## Lockfile Policy
+
+- Lockfile committed to the repository: `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`. Multi-language repos commit the per-ecosystem lockfile (`Cargo.lock`, `poetry.lock`, `go.sum`, `Gemfile.lock`).
+- CI installs from the lockfile only: `npm ci`, `yarn install --frozen-lockfile`, `pnpm install --frozen-lockfile`, `cargo build --locked`. Drift fails the build.
+- `lockfile-lint` enforces registry allow-list and integrity-hash presence on every entry. Run in CI alongside install.
+- Lockfile diffs receive the same review scrutiny as source diffs — reviewers inspect new transitive entries and version jumps.
+- Renovate or Dependabot configured with grouped weekly updates: one PR per ecosystem per week for non-security updates; security updates open immediately.
+
+## License Compliance
+
+- Allow-list (default): MIT, Apache-2.0, ISC, BSD-2-Clause, BSD-3-Clause, MPL-2.0, CC0-1.0. Project policy may extend.
+- Deny-list (default): GPL-2.0, GPL-3.0, AGPL-3.0, AGPL-3.0-or-later, SSPL-1.0, Commons Clause. AGPL triggers copyleft on network use — it is the SaaS landmine.
+- Override requires documented business justification in the PR description plus security/legal sign-off.
+- CI gate per ecosystem: `license-checker --onlyAllow "MIT;Apache-2.0;ISC;BSD-2-Clause;BSD-3-Clause;MPL-2.0;CC0-1.0"` (Node), `pip-licenses --allow-only` (Python), `cargo-license` (Rust). CI fails on detection of a denied license in direct or transitive deps.
+
+## Pinned GitHub Action SHAs
+
+Every action `uses:` line references a 40-character commit SHA, never a tag (`@v3`, `@main`, `@v44.5.1`). Tags are mutable; SHAs are not.
+
+- CVE-2025-30066 (tj-actions/changed-files, March 2025) compromised 23,000+ repositories — the attacker mutated existing version tags to point to a malicious commit that dumped secrets to workflow logs. Root cause: compromised PAT on `reviewdog/action-setup` (CVE-2025-30154). Tag pinning would not have prevented this; SHA pinning would have.
+- Annotate the SHA with the version: `uses: actions/checkout@<40-char-sha> # v4.2.2`.
+- Dependabot configured with `package-ecosystem: github-actions` updates SHAs while preserving the version comment. Renovate equivalent: `pinDigests: true`.
+- CI rejects PRs that introduce tag references via a linter step (e.g., `pinact` or a custom regex check).
+
+## OSV.dev and GHSA Feeds
+
+- `osv-scanner` runs on every PR and nightly against the lockfile. OSV.dev (Google) is the polyglot 2026 aggregator: npm, PyPI, crates.io, Maven, Go modules, RubyGems, Packagist, NuGet — single schema across all.
+- GitHub Security Advisories (GHSA) remain the npm-ecosystem authoritative feed; `npm audit` and OSV both consume GHSA.
+- NVD provides CPE-keyed CVE records for OS and language-stdlib vulnerabilities.
+- Renovate `vulnerabilityAlerts: { enabled: true }` plus `osvVulnerabilityAlerts: true` produce auto-PRs that force-update to fixed versions and bypass the normal cooldown for security fixes. Pair with auto-merge for patch-level fixes when tests pass.

package/rules/hatch3r-dependency-management.mdc

@@ -26,3 +26,75 @@ alwaysApply: false
 - Review changelogs and migration guides before upgrading major versions. Never blindly bump major versions and assume backward compatibility.
 - Run the full test suite after any dependency upgrade, including integration tests. A passing unit test suite does not guarantee compatibility with upgraded peer dependencies.
 - When upgrading a shared dependency used across multiple modules, upgrade all consumers in the same PR to avoid version skew within the monorepo or project.
+
+## npm Trusted Publishing (OIDC)
+
+For libraries published to npm, configure an npm Trusted Publisher with GitHub OIDC. The publishing workflow exchanges a per-run JWT for short-lived publish credentials — no long-lived `NPM_TOKEN` in secrets. Provenance attestations are auto-generated and signed by Sigstore Fulcio with the inclusion record in Rekor.
+
+- Requirements: npm CLI >=11.5.1, Node >=22.14.0, `repository` field set in `package.json` (provenance validation fails without it).
+- Workflow grants `id-token: write` permission at the job level.
+- Remove `NPM_TOKEN` from repository and organization secrets after migrating to trusted publishing.
+- PyPI, crates.io, and RubyGems offer equivalent OIDC trusted publishing — migrate at least one ecosystem per release pipeline.
+
+## Provenance Flag for Non-Trusted Publishing
+
+When trusted publishing is not yet enabled, publish with `npm publish --provenance`. The flag activates Sigstore-signed provenance even with token auth.
+
+- Verify provenance: `npm view <pkg> --json | jq .dist.attestations` returns Sigstore attestation URLs; the npm package page renders a Provenance section.
+- Consumers verify on install: `npm audit signatures` walks the attestation chain and confirms Rekor inclusion.
+
+## SBOM Generation
+
+Every release artifact ships a CycloneDX 1.6 or SPDX 3.0.1 SBOM, committed as a release asset and signed with the same Sigstore identity that signed the artifact. CycloneDX 1.6 is ECMA-424 ratified and broadly supported (Syft, Trivy, cdxgen, GitLab native). SPDX 3.0.1 is the BSI TR-03183-2 / EU CRA baseline.
+
+- Tooling baseline: `npm sbom --sbom-format=cyclonedx` (npm 10+), `cdxgen` (broad ecosystem coverage including Python, Java, Rust, Go), `syft` (containers + source repos).
+- CI step generates SBOM on every release tag and uploads as a release asset.
+- PR-time SBOM diff (`cyclonedx-cli diff` or `syft diff`) blocks PRs that introduce unexpected new transitive dependencies; reviewer approves the diff alongside the source diff.
+
+## SLSA v1.0 / v1.1 Build Provenance
+
+Target SLSA Build L3 for production release artifacts: ephemeral hosted runner, isolated builder identity, signed in-toto provenance, transparency log inclusion. SLSA v1.1 (April 2025) is incremental on the Build track — v1.0 L3 artifacts also meet v1.1 L3.
+
+- GitHub Actions implementation: `slsa-framework/slsa-github-generator` (language-agnostic generators for npm, container, generic artifact).
+- Deploy-time verification: `slsa-verifier` CLI confirms provenance, builder identity allow-list, and source-repo match before the artifact is consumed.
+- Pin the generator action to a 40-char commit SHA per the action-pinning policy below.
+
+## Malicious-Package Detection Beyond `npm audit`
+
+`npm audit` only flags published CVEs. The 2025-2026 incident class — Shai-Hulud (Sep-Nov 2025), Axios 1.14.1 maintainer hijack (Mar 2026), Mini-Shai-Hulud (May 2026), DevTap typosquat (Apr-May 2026) — never reaches a CVE filing. Layer install-time behavioral detection on top of `npm audit`:
+
+- Pre-install behavioral scan: `socket.dev`, `snyk`, or `osv-scanner` against the lockfile in CI. `npq` adds a pre-install gate at the developer workstation.
+- pnpm `minimumReleaseAge: 72` (3 days, raise to 7 for high-trust projects) blocks consumption of brand-new versions until the typosquat / maintainer-hijack window closes.
+- Disable lifecycle scripts in CI: `.npmrc` sets `ignore-scripts=true`; pnpm uses `strictDepBuilds: true` plus `allowBuilds: [explicit-list]`.
+- GitHub `dependency-review-action` on every PR blocks new dependencies with known advisories or disallowed licenses.
+
+## Lockfile Policy
+
+- Lockfile committed to the repository: `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`. Multi-language repos commit the per-ecosystem lockfile (`Cargo.lock`, `poetry.lock`, `go.sum`, `Gemfile.lock`).
+- CI installs from the lockfile only: `npm ci`, `yarn install --frozen-lockfile`, `pnpm install --frozen-lockfile`, `cargo build --locked`. Drift fails the build.
+- `lockfile-lint` enforces registry allow-list and integrity-hash presence on every entry. Run in CI alongside install.
+- Lockfile diffs receive the same review scrutiny as source diffs — reviewers inspect new transitive entries and version jumps.
+- Renovate or Dependabot configured with grouped weekly updates: one PR per ecosystem per week for non-security updates; security updates open immediately.
+
+## License Compliance
+
+- Allow-list (default): MIT, Apache-2.0, ISC, BSD-2-Clause, BSD-3-Clause, MPL-2.0, CC0-1.0. Project policy may extend.
+- Deny-list (default): GPL-2.0, GPL-3.0, AGPL-3.0, AGPL-3.0-or-later, SSPL-1.0, Commons Clause. AGPL triggers copyleft on network use — it is the SaaS landmine.
+- Override requires documented business justification in the PR description plus security/legal sign-off.
+- CI gate per ecosystem: `license-checker --onlyAllow "MIT;Apache-2.0;ISC;BSD-2-Clause;BSD-3-Clause;MPL-2.0;CC0-1.0"` (Node), `pip-licenses --allow-only` (Python), `cargo-license` (Rust). CI fails on detection of a denied license in direct or transitive deps.
+
+## Pinned GitHub Action SHAs
+
+Every action `uses:` line references a 40-character commit SHA, never a tag (`@v3`, `@main`, `@v44.5.1`). Tags are mutable; SHAs are not.
+
+- CVE-2025-30066 (tj-actions/changed-files, March 2025) compromised 23,000+ repositories — the attacker mutated existing version tags to point to a malicious commit that dumped secrets to workflow logs. Root cause: compromised PAT on `reviewdog/action-setup` (CVE-2025-30154). Tag pinning would not have prevented this; SHA pinning would have.
+- Annotate the SHA with the version: `uses: actions/checkout@<40-char-sha> # v4.2.2`.
+- Dependabot configured with `package-ecosystem: github-actions` updates SHAs while preserving the version comment. Renovate equivalent: `pinDigests: true`.
+- CI rejects PRs that introduce tag references via a linter step (e.g., `pinact` or a custom regex check).
+
+## OSV.dev and GHSA Feeds
+
+- `osv-scanner` runs on every PR and nightly against the lockfile. OSV.dev (Google) is the polyglot 2026 aggregator: npm, PyPI, crates.io, Maven, Go modules, RubyGems, Packagist, NuGet — single schema across all.
+- GitHub Security Advisories (GHSA) remain the npm-ecosystem authoritative feed; `npm audit` and OSV both consume GHSA.
+- NVD provides CPE-keyed CVE records for OS and language-stdlib vulnerabilities.
+- Renovate `vulnerabilityAlerts: { enabled: true }` plus `osvVulnerabilityAlerts: true` produce auto-PRs that force-update to fixed versions and bypass the normal cooldown for security fixes. Pair with auto-merge for patch-level fixes when tests pass.