hatch3r 1.8.0 → 2.0.0

package/dist/content/rules/hatch3r-flutter-patterns.mdc

@@ -0,0 +1,83 @@
+---
+description: Flutter and Dart conventions covering null safety, state management (Riverpod/Bloc), Material 3, FFI, performance, platform channels, and integration testing
+globs: ["**/*.dart", "**/pubspec.yaml", "**/pubspec.lock", "**/analysis_options.yaml", "**/build.yaml", "**/lib/**", "**/test/**", "**/integration_test/**", "**/ios/Runner/**", "**/android/app/**", "**/windows/runner/**", "**/macos/Runner/**", "**/linux/**", "**/web/index.html"]
+alwaysApply: false
+---
+# Flutter Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a Flutter app or Dart package. Detection signals: `pubspec.yaml` with `flutter:` block, `lib/main.dart` entrypoint, or `pubspec.yaml` at repo root.
+
+## Dart Language Floor
+
+- Use Dart 3.5+ with sound null safety. Every nullable field is explicit (`String?`), every late variable initialized before access. No `!` (bang operator) outside of test fixtures or proven-non-null hot paths.
+- Records and patterns: prefer records (`(int, String)`) and pattern matching (`switch (value) { ... }`) over tuple classes and visitor patterns for simple variant returns.
+- Sealed classes for closed-set hierarchies (state, events, errors): `sealed class AuthState { ... }` + `final class Authenticated extends AuthState { ... }` so the analyzer enforces exhaustive switches.
+- Enable strict analyzer mode in `analysis_options.yaml` with `flutter_lints` plus `very_good_analysis`. Treat warnings as errors in CI.
+
+## Project Structure
+
+- Feature-first layout under `lib/`: `lib/features/<feature>/{data,domain,presentation}/` with a `lib/core/` for shared utilities. Avoid `lib/widgets/` / `lib/screens/` flat layouts beyond toy apps.
+- Single entrypoint per flavor: `lib/main_dev.dart`, `lib/main_staging.dart`, `lib/main_prod.dart`. Each delegates to a shared `lib/bootstrap.dart` after environment binding.
+- Public APIs documented with `///` doc comments. `dartdoc` runs in CI for the `lib/` public surface — undocumented public APIs are a warning.
+
+## State Management
+
+- Pick ONE state-management approach per app and document it in `docs/architecture.md`:
+  - **Riverpod 2.x** (`flutter_riverpod` + `riverpod_generator`) — recommended default. Code-gen typed providers via `@riverpod` annotations.
+  - **Bloc** (`flutter_bloc`) — when the team prefers event-sourcing semantics.
+  - **InheritedNotifier / ChangeNotifier** — only for trivial widget-local state. Provider package is in maintenance — do not adopt for new code.
+- Riverpod: prefer `@riverpod`-generated providers over manual `Provider`/`StateProvider`. Async providers return `AsyncValue<T>` — surface `loading` / `error` / `data` states in the UI.
+- Bloc: separate events (input) from states (output). Avoid `setState` inside `BlocBuilder` — all mutation flows via `add(event)` to the bloc.
+- Never call `notifyListeners()` inside `build()`. Never read providers in a constructor.
+
+## UI & Material 3
+
+- Material 3 (Material You) is the default for Android-leaning apps: `ThemeData(useMaterial3: true)`. Configure `colorSchemeSeed` rather than ad-hoc primary/accent colors so dynamic color works.
+- For iOS-leaning apps, use Cupertino widgets directly or `flutter_platform_widgets` for hybrid surfaces. Do not use `Material` on a `CupertinoPageScaffold`.
+- Responsive layout: use `LayoutBuilder`, `MediaQuery.sizeOf(context)`, and `Flexible`/`Expanded` for breakpoints. Avoid hard-coded pixel widths.
+- Accessibility: every interactive widget has a `Semantics(label: ...)` wrapper or uses a built-in widget that emits semantics. Test with TalkBack (Android) and VoiceOver (iOS); the `flutter_test` semantics tester catches static violations.
+
+## Performance
+
+- Avoid expensive work in `build()`. Lift `MaterialPageRoute` factories, regex literals, and constant widgets to `const` constructors so Flutter can skip the rebuild.
+- Use `const` constructors aggressively — `const SizedBox(height: 8)` is allocation-free and a major frame-budget win.
+- For long scrollable lists, use `ListView.builder` with `itemExtent` set when row height is uniform. `ListView()` (default) builds every child up-front.
+- Image loading: `cached_network_image` or `flutter_image_compress` for network images. The default `Image.network` does not persist a disk cache.
+- Profile with DevTools: target 60fps on mid-range Android (Pixel 4a class). Frame times above 16ms are regressions; profile the Timeline view for jank.
+
+## Platform Channels & FFI
+
+- Native interop: prefer `dart:ffi` for synchronous C/C++ bindings (≥10x faster than channels). Use platform channels only when the API is event-driven or requires UI-thread context.
+- `package:ffigen` generates Dart bindings from C headers — never hand-roll `Pointer<Native...>` signatures.
+- Pigeon (`package:pigeon`) generates type-safe platform-channel code from a Dart interface declaration. Stop writing raw `MethodChannel` calls — Pigeon-generated code prevents schema drift.
+
+## Testing
+
+- Three test layers in `test/` (unit + widget) and `integration_test/` (full app on real device or emulator):
+  - Unit tests: pure Dart logic, no Flutter binding. Run with `flutter test`.
+  - Widget tests: pumped `WidgetTester` flows with mocked dependencies. Use `find.byKey` over `find.text` for resilience to copy changes.
+  - Integration tests: `integration_test/` with `IntegrationTestWidgetsFlutterBinding`. Run on devices via `flutter drive` and on CI matrices.
+- Coverage: `flutter test --coverage` + `lcov` reports. Floor: 80% line coverage in `lib/features/**`; critical features (auth, payments) 90%.
+- Golden tests for visual regressions: `goldenFileComparator` with the `alchemist` package for multi-platform/multi-device goldens. Update goldens via PR review, never blanket-update.
+- Mock HTTP: `package:http_mock_adapter` for Dio, `nock` for `package:http`. Never hit real network in tests.
+
+## Builds & Distribution
+
+- Flavors via `--flavor` flag + matching Android/iOS configs (`android/app/build.gradle` flavors, `ios/Runner/Configurations`). Bake the API base URL per flavor.
+- App size: enable `--obfuscate --split-debug-info=<path>` for release builds. Track size regressions via `flutter build apk --analyze-size` in CI.
+- Use Codemagic, Bitrise, or Fastlane for store deploys. Sign Android with Play App Signing; iOS via App Store Connect API keys (avoid Apple ID password auth — deprecated).
+
+## References
+
+- Dart 3 release notes: https://dart.dev/guides/whats-new (accessed 2026-05-27, official-docs)
+- Flutter Material 3: https://docs.flutter.dev/ui/design/material (accessed 2026-05-27, official-docs)
+- Riverpod 2.x: https://riverpod.dev/docs/introduction/getting_started (accessed 2026-05-27, official-docs)
+- Pigeon: https://pub.dev/packages/pigeon (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to Flutter `AsyncValue` patterns.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to Dart tests.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for `Semantics` widget usage.

package/{rules → dist/content/rules}/hatch3r-git-conventions.md

@@ -2,13 +2,16 @@
 id: hatch3r-git-conventions
 type: rule
 description: Conventional Commits type list, subject line rules, breaking-change footer format, and branch naming template for type/short-description
-scope: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
-tags: [core]
+scope: conditional
+globs: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Git Conventions
 
+**Pillars:** P2 (Scientific & Practical Quality), P5 (Governance Self-Quality)
+
 ## Commit Messages
 
 Follow [Conventional Commits](https://www.conventionalcommits.org/):

package/{rules → dist/content/rules}/hatch3r-git-conventions.mdc

@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Git Conventions
 
+**Pillars:** P2 (Scientific & Practical Quality), P5 (Governance Self-Quality)
+
 ## Commit Messages
 
 Follow [Conventional Commits](https://www.conventionalcommits.org/):

package/dist/content/rules/hatch3r-go-patterns.md

@@ -0,0 +1,98 @@
+---
+id: hatch3r-go-patterns
+type: rule
+description: Go 1.23+ conventions covering modules, error wrapping, context propagation, generics, testing with table-driven tests, and the standard library net/http + log/slog
+scope: conditional
+globs: "**/*.go,**/go.mod,**/go.sum,**/go.work,**/go.work.sum,**/Makefile,**/.golangci.yml,**/.golangci.yaml"
+tags: [implementation, lang:go]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Go Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a Go module or binary. Detection signals: `go.mod` at repo root, `*.go` source files, or `go.work` for multi-module workspaces.
+
+## Go Language Floor
+
+- Target Go 1.23+ (range-over-int and range-over-func now stable). Use Go modules — `GO111MODULE=on` is the default and `GOPATH` mode is end-of-life for new code.
+- Treat `go vet` and `staticcheck` errors as build failures. Configure `golangci-lint` with `errcheck`, `gosimple`, `govet`, `ineffassign`, `staticcheck`, `unused`, `gosec`, `gocritic` enabled.
+- Use generics (Go 1.18+) for collection / container utilities. Prefer the standard library `slices` / `maps` packages over hand-rolled helpers. Do not retrofit generics onto existing interface-based code without measurable benefit.
+- Format with `gofumpt` (stricter than `gofmt`) in CI. `goimports` for import ordering.
+
+## Project Layout
+
+- Follow the Standard Project Layout pattern (community convention, not an official Go spec):
+  - `cmd/<binary>/main.go` — entrypoints per binary.
+  - `internal/` — code not importable outside this module (compiler-enforced).
+  - `pkg/` — reusable code imported by other modules. Only create when there is a concrete external consumer; default is `internal/`.
+  - `api/` — `.proto` or OpenAPI specs.
+  - `web/` — static assets if any.
+- Public API lives in `pkg/`; everything else under `internal/`. Internal-by-default reduces surface area and prevents accidental coupling.
+- Avoid deep nesting. Three levels under `internal/` is a refactor signal.
+
+## Error Handling
+
+- Always handle errors at the call site. Never use `_ = err` to discard.
+- Wrap with `fmt.Errorf("context: %w", err)` to preserve the chain. Use `errors.Is` / `errors.As` to inspect at the boundary — never compare error strings.
+- Define sentinel errors as `var ErrXyz = errors.New("xyz")` package variables for stable error contracts. For richer payloads, define typed error structs implementing `error` + a `Code() string` method.
+- The error is part of the function signature — design it deliberately. Returning `error` from every function is fine; returning generic `error` when callers need to distinguish causes is a smell.
+
+## Concurrency
+
+- Use `context.Context` as the first parameter of every function that does I/O or blocking work. Propagate cancellation through every layer.
+- Never call `context.Background()` in library code — accept a context from the caller. `context.TODO()` is only acceptable as a temporary stand-in marked with a `// TODO:` comment.
+- Goroutine lifecycle: every `go func()` has a clear shutdown path. Use `errgroup.Group` for fan-out with error propagation, or `sync.WaitGroup` for fire-and-forget patterns.
+- Channels for ownership-transfer / signaling, mutexes for shared state. Do not chain channels into pseudo-state-machines — use a sync package primitive when the operation is "read/modify/write".
+- Race detector enabled in CI: `go test -race ./...`. A failing race-detector run blocks merge.
+
+## HTTP Servers
+
+- Use the standard `net/http` + `ServeMux` (Go 1.22+) for new services. The 1.22 `ServeMux` supports method-scoped routes (`POST /users/{id}`) — no third-party router needed for typical APIs.
+- For complex routing requirements: chi (`go-chi/chi`) — minimal, std-lib-compatible. Avoid frameworks that hide `net/http` semantics (gin, fiber) unless the team has explicit performance evidence.
+- Middleware: function composition pattern — `func(http.Handler) http.Handler`. Order matters: logging → recovery → auth → rate-limit → handler.
+- Server timeouts: always set `ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout` on `http.Server`. Default timeouts are 0 (unbounded) — production servers must override.
+- Graceful shutdown: `server.Shutdown(ctx)` on `SIGTERM` / `SIGINT`. Bound shutdown with a context timeout (e.g., 30s) and force-close on expiry.
+
+## Logging & Observability
+
+- Use `log/slog` (standard library, Go 1.21+) for structured logging. Configure a JSON handler in production, text handler in development.
+- Always emit a request-scoped logger from middleware: `logger := slog.With("request_id", id)` and store in `context`. Handlers retrieve via `slog.Default()` from context. Never use the package-level logger inside request paths.
+- Tracing: OpenTelemetry Go SDK (`go.opentelemetry.io/otel`). Wrap HTTP handlers with `otelhttp.NewHandler` and outbound HTTP clients with `otelhttp.NewTransport`. Avoid handcrafted span creation in business logic.
+
+## Testing
+
+- Table-driven tests are the floor: `tests := []struct { name string; ... }` + `for _, tc := range tests { t.Run(tc.name, ...) }`. Subtests give per-case isolation.
+- Use `t.Parallel()` inside subtests for I/O-bound suites. Race-detector in CI catches data races introduced by parallelism.
+- Mocking: prefer hand-rolled fakes implementing the interface. `gomock` / `mockery` only when the interface surface is wide (>5 methods) and stable.
+- HTTP tests with `httptest.NewServer` for integration, `httptest.NewRecorder` + handler call for unit tests. Never start a real network listener for unit tests.
+- Coverage: `go test -coverprofile=cover.out ./...`. Floor: 80% statement coverage in `pkg/` and `internal/`; critical paths (auth, billing) at 90%.
+- `go test -fuzz=Fuzz` for fuzz testing untrusted-input parsers — at least one fuzz target per public parser.
+
+## Concurrency Idioms
+
+- Errgroup for parallel work that must all succeed or fail together: `g, ctx := errgroup.WithContext(ctx)`; on first error, the context cancels remaining workers.
+- Semaphore (`golang.org/x/sync/semaphore`) for bounded concurrency: limit DB connections, HTTP calls, file handles.
+- Singleflight (`golang.org/x/sync/singleflight`) to deduplicate concurrent fetches of the same key (cache miss storms).
+- Avoid `time.Sleep` for backoff — use `time.NewTimer` with context-aware cancellation. Sleep cannot be interrupted by context cancellation.
+
+## Dependency Hygiene
+
+- `go mod tidy` on every PR — drift between `go.mod` and imports is a merge blocker.
+- Pin dependencies via `go.sum`. Use `go mod verify` in CI to catch supply-chain tampering.
+- Vulnerability scanning: `govulncheck` (official Go tool) in CI. Block merge on known CVE matches in the dependency graph.
+- Avoid `replace` directives in `go.mod` for production builds — they suggest unresolved upstream issues. Acceptable in development with a `// TODO: remove when upstream merges PR#X` comment.
+
+## References
+
+- Go 1.23 release notes: https://go.dev/doc/go1.23 (accessed 2026-05-27, official-docs)
+- log/slog: https://pkg.go.dev/log/slog (accessed 2026-05-27, official-docs)
+- net/http ServeMux 1.22+: https://go.dev/blog/routing-enhancements (accessed 2026-05-27, official-docs)
+- Effective Go: https://go.dev/doc/effective_go (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to Go services.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `go test -cover`.
+- `rules/hatch3r-observability-logging.md` — slog integration with the canonical logging contract.

package/dist/content/rules/hatch3r-go-patterns.mdc

@@ -0,0 +1,93 @@
+---
+description: Go 1.23+ conventions covering modules, error wrapping, context propagation, generics, testing with table-driven tests, and the standard library net/http + log/slog
+globs: ["**/*.go", "**/go.mod", "**/go.sum", "**/go.work", "**/go.work.sum", "**/Makefile", "**/.golangci.yml", "**/.golangci.yaml"]
+alwaysApply: false
+---
+# Go Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a Go module or binary. Detection signals: `go.mod` at repo root, `*.go` source files, or `go.work` for multi-module workspaces.
+
+## Go Language Floor
+
+- Target Go 1.23+ (range-over-int and range-over-func now stable). Use Go modules — `GO111MODULE=on` is the default and `GOPATH` mode is end-of-life for new code.
+- Treat `go vet` and `staticcheck` errors as build failures. Configure `golangci-lint` with `errcheck`, `gosimple`, `govet`, `ineffassign`, `staticcheck`, `unused`, `gosec`, `gocritic` enabled.
+- Use generics (Go 1.18+) for collection / container utilities. Prefer the standard library `slices` / `maps` packages over hand-rolled helpers. Do not retrofit generics onto existing interface-based code without measurable benefit.
+- Format with `gofumpt` (stricter than `gofmt`) in CI. `goimports` for import ordering.
+
+## Project Layout
+
+- Follow the Standard Project Layout pattern (community convention, not an official Go spec):
+  - `cmd/<binary>/main.go` — entrypoints per binary.
+  - `internal/` — code not importable outside this module (compiler-enforced).
+  - `pkg/` — reusable code imported by other modules. Only create when there is a concrete external consumer; default is `internal/`.
+  - `api/` — `.proto` or OpenAPI specs.
+  - `web/` — static assets if any.
+- Public API lives in `pkg/`; everything else under `internal/`. Internal-by-default reduces surface area and prevents accidental coupling.
+- Avoid deep nesting. Three levels under `internal/` is a refactor signal.
+
+## Error Handling
+
+- Always handle errors at the call site. Never use `_ = err` to discard.
+- Wrap with `fmt.Errorf("context: %w", err)` to preserve the chain. Use `errors.Is` / `errors.As` to inspect at the boundary — never compare error strings.
+- Define sentinel errors as `var ErrXyz = errors.New("xyz")` package variables for stable error contracts. For richer payloads, define typed error structs implementing `error` + a `Code() string` method.
+- The error is part of the function signature — design it deliberately. Returning `error` from every function is fine; returning generic `error` when callers need to distinguish causes is a smell.
+
+## Concurrency
+
+- Use `context.Context` as the first parameter of every function that does I/O or blocking work. Propagate cancellation through every layer.
+- Never call `context.Background()` in library code — accept a context from the caller. `context.TODO()` is only acceptable as a temporary stand-in marked with a `// TODO:` comment.
+- Goroutine lifecycle: every `go func()` has a clear shutdown path. Use `errgroup.Group` for fan-out with error propagation, or `sync.WaitGroup` for fire-and-forget patterns.
+- Channels for ownership-transfer / signaling, mutexes for shared state. Do not chain channels into pseudo-state-machines — use a sync package primitive when the operation is "read/modify/write".
+- Race detector enabled in CI: `go test -race ./...`. A failing race-detector run blocks merge.
+
+## HTTP Servers
+
+- Use the standard `net/http` + `ServeMux` (Go 1.22+) for new services. The 1.22 `ServeMux` supports method-scoped routes (`POST /users/{id}`) — no third-party router needed for typical APIs.
+- For complex routing requirements: chi (`go-chi/chi`) — minimal, std-lib-compatible. Avoid frameworks that hide `net/http` semantics (gin, fiber) unless the team has explicit performance evidence.
+- Middleware: function composition pattern — `func(http.Handler) http.Handler`. Order matters: logging → recovery → auth → rate-limit → handler.
+- Server timeouts: always set `ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout` on `http.Server`. Default timeouts are 0 (unbounded) — production servers must override.
+- Graceful shutdown: `server.Shutdown(ctx)` on `SIGTERM` / `SIGINT`. Bound shutdown with a context timeout (e.g., 30s) and force-close on expiry.
+
+## Logging & Observability
+
+- Use `log/slog` (standard library, Go 1.21+) for structured logging. Configure a JSON handler in production, text handler in development.
+- Always emit a request-scoped logger from middleware: `logger := slog.With("request_id", id)` and store in `context`. Handlers retrieve via `slog.Default()` from context. Never use the package-level logger inside request paths.
+- Tracing: OpenTelemetry Go SDK (`go.opentelemetry.io/otel`). Wrap HTTP handlers with `otelhttp.NewHandler` and outbound HTTP clients with `otelhttp.NewTransport`. Avoid handcrafted span creation in business logic.
+
+## Testing
+
+- Table-driven tests are the floor: `tests := []struct { name string; ... }` + `for _, tc := range tests { t.Run(tc.name, ...) }`. Subtests give per-case isolation.
+- Use `t.Parallel()` inside subtests for I/O-bound suites. Race-detector in CI catches data races introduced by parallelism.
+- Mocking: prefer hand-rolled fakes implementing the interface. `gomock` / `mockery` only when the interface surface is wide (>5 methods) and stable.
+- HTTP tests with `httptest.NewServer` for integration, `httptest.NewRecorder` + handler call for unit tests. Never start a real network listener for unit tests.
+- Coverage: `go test -coverprofile=cover.out ./...`. Floor: 80% statement coverage in `pkg/` and `internal/`; critical paths (auth, billing) at 90%.
+- `go test -fuzz=Fuzz` for fuzz testing untrusted-input parsers — at least one fuzz target per public parser.
+
+## Concurrency Idioms
+
+- Errgroup for parallel work that must all succeed or fail together: `g, ctx := errgroup.WithContext(ctx)`; on first error, the context cancels remaining workers.
+- Semaphore (`golang.org/x/sync/semaphore`) for bounded concurrency: limit DB connections, HTTP calls, file handles.
+- Singleflight (`golang.org/x/sync/singleflight`) to deduplicate concurrent fetches of the same key (cache miss storms).
+- Avoid `time.Sleep` for backoff — use `time.NewTimer` with context-aware cancellation. Sleep cannot be interrupted by context cancellation.
+
+## Dependency Hygiene
+
+- `go mod tidy` on every PR — drift between `go.mod` and imports is a merge blocker.
+- Pin dependencies via `go.sum`. Use `go mod verify` in CI to catch supply-chain tampering.
+- Vulnerability scanning: `govulncheck` (official Go tool) in CI. Block merge on known CVE matches in the dependency graph.
+- Avoid `replace` directives in `go.mod` for production builds — they suggest unresolved upstream issues. Acceptable in development with a `// TODO: remove when upstream merges PR#X` comment.
+
+## References
+
+- Go 1.23 release notes: https://go.dev/doc/go1.23 (accessed 2026-05-27, official-docs)
+- log/slog: https://pkg.go.dev/log/slog (accessed 2026-05-27, official-docs)
+- net/http ServeMux 1.22+: https://go.dev/blog/routing-enhancements (accessed 2026-05-27, official-docs)
+- Effective Go: https://go.dev/doc/effective_go (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to Go services.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `go test -cover`.
+- `rules/hatch3r-observability-logging.md` — slog integration with the canonical logging contract.

package/{rules → dist/content/rules}/hatch3r-handoff-readiness.md

@@ -3,15 +3,15 @@ id: hatch3r-handoff-readiness
 type: rule
 description: Handoff readiness checklist — pre-write validation before persisting a canonical handoff document.
 scope: conditional
-globs: .agents/handoffs/active/**/*.md
+globs: .hatch3r/handoffs/active/**/*.md
 precedence: high
-tags: [core, maintenance]
+tags: [orchestration, maintenance]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Handoff Readiness Checklist
 
-Before writing a handoff to `.agents/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.
+Before writing a handoff to `.hatch3r/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.
 
 ## Required (fail = refuse write)
 
@@ -37,9 +37,19 @@ Before writing a handoff to `.agents/handoffs/active/`, verify each criterion. R
 
 The `hatch3r-handoff-preparer` agent applies this checklist before invoking `writeHandoff` in `src/content/handoffs/index.ts`. The `validateHandoffContent` function in `src/content/handoffs/validation.ts` runs criteria 1-7 as `errors[]` and 8-10 as `warnings[]`.
 
+## Retro-Discredit Rule (D13 — handoff self-assessment trust gate)
+
+Handoff confidence and completeness are self-rated by the preparing agent. When the resuming agent (or human) detects that the prior handoff overstated completeness — work flagged Done but reverted, tests claimed passing but failing on resume, blockers omitted — the resumer MUST:
+
+1. Append a `retro_discredit:` block to the handoff manifest (`.hatch3r/handoffs/active/<id>.md` frontmatter) with: `discredited_by: <resumer-id-or-human>`, `discredited_on: <ISO-8601>`, `discredit_reason: <one-sentence cause>`, `prior_confidence: <high|medium|low>`, `effective_confidence: <high|medium|low>` (downgraded post-discredit).
+2. Append a single line to `.hatch3r/handoffs/discredit-log.jsonl` (append-only, atomic append per `src/merge/safeWrite.ts`) with `{ts, handoff_id, discredited_by, prior_confidence, effective_confidence, reason}`.
+3. The `hatch3r-handoff-preparer` and `hatch3r-handoff-loader` agents consult the discredit-log on next write/read — if a handoff's preparer has a discredit ratio above 25% across the last 10 handoffs, downgrade the new handoff's preparer-rated confidence one band before accepting.
+
+Effect: self-assessed confidence becomes a track-record signal rather than a single-shot self-claim. Closes D13 SA13.4 F2 retro path (resumer undoes prior work but the handoff's confidence rating persists unchallenged).
+
 ## Cross-references
 
-- Body sections schema: `.agents/handoffs/README.md`
+- Body sections schema: `.hatch3r/handoffs/README.md`
 - Iteration Summary contract (populates Work Done / Work Remaining / Blockers): `rules/hatch3r-iteration-summary.md`
 - Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
 - Quality charter (confidence levels): `agents/shared/quality-charter.md`

package/{rules → dist/content/rules}/hatch3r-handoff-readiness.mdc

@@ -1,12 +1,12 @@
 ---
 description: Handoff readiness checklist — pre-write validation before persisting a canonical handoff document.
-globs: [".agents/handoffs/active/**/*.md"]
+globs: [".hatch3r/handoffs/active/**/*.md"]
 alwaysApply: false
 precedence: high
 ---
 # Handoff Readiness Checklist
 
-Before writing a handoff to `.agents/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.
+Before writing a handoff to `.hatch3r/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.
 
 ## Required (fail = refuse write)
 
@@ -32,9 +32,19 @@ Before writing a handoff to `.agents/handoffs/active/`, verify each criterion. R
 
 The `hatch3r-handoff-preparer` agent applies this checklist before invoking `writeHandoff` in `src/content/handoffs/index.ts`. The `validateHandoffContent` function in `src/content/handoffs/validation.ts` runs criteria 1-7 as `errors[]` and 8-10 as `warnings[]`.
 
+## Retro-Discredit Rule (D13 — handoff self-assessment trust gate)
+
+Handoff confidence and completeness are self-rated by the preparing agent. When the resuming agent (or human) detects that the prior handoff overstated completeness — work flagged Done but reverted, tests claimed passing but failing on resume, blockers omitted — the resumer MUST:
+
+1. Append a `retro_discredit:` block to the handoff manifest (`.hatch3r/handoffs/active/<id>.md` frontmatter) with: `discredited_by: <resumer-id-or-human>`, `discredited_on: <ISO-8601>`, `discredit_reason: <one-sentence cause>`, `prior_confidence: <high|medium|low>`, `effective_confidence: <high|medium|low>` (downgraded post-discredit).
+2. Append a single line to `.hatch3r/handoffs/discredit-log.jsonl` (append-only, atomic append per `src/merge/safeWrite.ts`) with `{ts, handoff_id, discredited_by, prior_confidence, effective_confidence, reason}`.
+3. The `hatch3r-handoff-preparer` and `hatch3r-handoff-loader` agents consult the discredit-log on next write/read — if a handoff's preparer has a discredit ratio above 25% across the last 10 handoffs, downgrade the new handoff's preparer-rated confidence one band before accepting.
+
+Effect: self-assessed confidence becomes a track-record signal rather than a single-shot self-claim. Closes D13 SA13.4 F2 retro path (resumer undoes prior work but the handoff's confidence rating persists unchallenged).
+
 ## Cross-references
 
-- Body sections schema: `.agents/handoffs/README.md`
+- Body sections schema: `.hatch3r/handoffs/README.md`
 - Iteration Summary contract (populates Work Done / Work Remaining / Blockers): `rules/hatch3r-iteration-summary.md`
 - Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
 - Quality charter (confidence levels): `agents/shared/quality-charter.md`

package/{rules → dist/content/rules}/hatch3r-i18n.md

@@ -4,12 +4,14 @@ type: rule
 description: Internationalization, localization, and RTL support conventions for the project
 scope: conditional
 globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx,src/**/*.ts,**/locales/**,**/i18n/**,**/*i18n*,**/*locale*"
-tags: [implementation, lang:typescript]
+tags: [implementation, floor:ui-ux, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Internationalization & RTL
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ2 (UX Quality)
+
 ## Locale Management
 
 - Detect locale via resolution chain: explicit user preference → `Accept-Language` header (server) → `navigator.language` (client) → default locale.

package/{rules → dist/content/rules}/hatch3r-i18n.mdc

@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Internationalization & RTL
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ2 (UX Quality)
+
 ## Locale Management
 
 - Detect locale via resolution chain: explicit user preference → `Accept-Language` header (server) → `navigator.language` (client) → default locale.

package/dist/content/rules/hatch3r-iteration-summary.md

@@ -0,0 +1,108 @@
+---
+id: hatch3r-iteration-summary
+type: rule
+description: 9-section iteration summary template emitted by every orchestrator command and meaningful skill run — status, outcome, done/not-done, fan-out + cost, verifications, gates, pillar impact, open questions, learnings captured.
+tags: [iteration, summary, telemetry, floor:content-quality]
+precedence: high
+scope: always
+---
+# hatch3r Iteration Summary
+
+**Pillars:** P5 (Governance Self-Quality), P7 (Speed & Token Efficiency — cost visibility)
+
+## When Required
+
+Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) AND every meaningful skill run (`/h4tcher-*` or `/hatch3r-*` that mutates state) MUST emit the 9-section block as the final user-facing output.
+
+## Pre-Execution Cost Preview
+
+Every orchestrator command MUST emit a one-block cost preview BEFORE its first sub-agent dispatch (Decision 24 at the user-facing surface), so the user sees the cost envelope before any agent spawns:
+
+```yaml
+cost_preview:
+  expected_sa_count: <integer>
+  estimated_input_tokens_static_frame: <integer>
+  triage_tier: 1 | 2 | 3
+  web_research_budget: <integer queries, 0 if none>
+  estimated_duration_min: <integer>
+```
+
+Calibrate the fields to the triage tier (see `rules/hatch3r-deep-context`); source token estimates from `src/pipeline/observability.ts` / `src/pipeline/costEstimator.ts`. The post-run §2 "Fan-out + Cost" section closes the loop by reporting actuals + `delta_percent` against this preview. Commands wire the preview as an explicit pre-dispatch step (e.g., `commands/hatch3r-workflow.md` Step 0.5).
+
+## The 9 Sections
+
+1. **Request** — verbatim restatement of the user's ask in one sentence
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` + `cost: { estimated_input_tokens, actual_input_tokens, estimated_duration_min, actual_duration_min, delta_percent }`
+3. **Web Research** — every URL fetched with access date + trust tier (per `agents/shared/rigor-contract.md`); count 0 acceptable if no research was needed
+4. **Files Mutated** — list with diff summary (lines added / removed / files created)
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per Decision 17
+7. **Verification Commands** — exact commands run with exit codes + key output lines (≤200 chars)
+8. **Open Questions / Blockers** — explicit None if fully closed. When an ASK gate's default-if-no-response was exercised this run, this section MUST carry one `Default applied: <question summary> → option <N> (<one-line reason>)` line per default taken (the operational counterpart to `agents/shared/user-question-protocol.md` → Operationalising Default-if-no-Response step 3); absence of the line when a default was applied is a P8 B1 gate failure
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run; cross-reference `rules/hatch3r-learning-system.md`
+
+## Required Fields per quality-charter §11
+
+- **Status:** closed enum SUCCESS | PARTIAL | FAILED | BLOCKED
+- **Outcome:** one sentence
+- **Done / Not Done / Deferred / Unverified:** explicit lists
+- **Confidence + basis:** one of direct measurement | sampled observation | inference from analogue
+- **Consulted Learnings:** IDs of `.hatch3r/learnings/` entries the bound agents (implementer / reviewer / researcher / fixer) read this run per the `rules/hatch3r-learning-system.md` Mandatory Consultation Gate; `none` when INDEX.md is absent or zero `applies-to` rows matched. Distinct from §9 Learnings Captured (entries written this run). Citing zero when `applies-to` matched is a gate failure.
+
+## Confidence-to-Action Mapping (D13)
+
+When a review loop ran this turn, the §5 Confidence line MUST append the action guidance for the loop's terminal confidence level (`reviewLoopConfidence` in `src/pipeline/reviewLoop.ts`). This is the canonical confidence-to-action text — `confidenceExplanation` in `src/pipeline/reviewLoop.ts` returns these exact three strings, so the typed helper and this user-facing rule stay byte-identical (the strings are no longer reachable only from a unit test, closing D13-SA13.2-F2):
+
+- **high** — The fix was correct on the first attempt. Human review is optional but recommended for critical code paths.
+- **medium** — The fix required one round of corrections, which is normal for moderately complex changes. A brief human review is recommended.
+- **low** — The fix required multiple attempts or was interrupted. A thorough human review is strongly recommended before merging.
+
+Omit the mapping when no review loop ran (e.g. a Tier 1 typo edit with no reviewer pass) — no confidence level is derived, so no action line applies.
+
+## Pattern Rationale (D13 in-flow teaching — default-ON at Tier ≥ 2)
+
+In-flow teaching is the default, not opt-in: at Tier ≥ 2 (non-trivial / novel orchestrations) the orchestrator MUST emit a `## Pattern Rationale` block before the Iteration Summary, teaching the user each framework pattern applied this turn — closing the knowledge-transfer gap surfaced by D13 SA13.4 (F5/F6: sub-agent reasoning is summarized away before it reaches the user, so the user learns nothing unless the orchestrator teaches at its own surface). One SHORT line per applied pattern with rule citation + pillar served + plain-language reason:
+
+```
+pattern_rationale:
+  - pattern: <name, e.g., "circuit-breaker for outbound DB call">
+    rule: <rules/hatch3r-*.md path or agents/shared/principles.md anchor>
+    pillar: <P1..P8 or CQ1..CQ9>
+    why: <≤1 sentence plain language>
+```
+
+Emission policy:
+
+- **Default-ON at Tier ≥ 2:** emit one line for each mutated file that applies a named rule the user did not request explicitly. A Tier ≥ 2 turn that applied at least one such pattern and omits the block is a P5 gate failure (same enforcement class as the §9 Validation Gate).
+- **Tier 1 exemption:** Tier 1 trivial edits (typo, frontmatter-only, single-line clarification) skip the block — no pattern is taught, so no field appears, preserving token budget. This mirrors the Tier-1 exemption in `rules/hatch3r-agent-orchestration.md` (Per-Turn Pipeline-State Header).
+- **No-pattern case:** when a Tier ≥ 2 turn applied no named rule beyond what the user requested, emit `pattern_rationale: none (no implicit pattern applied)` rather than dropping the field, so the block's absence is never ambiguous.
+- **`--quiet` opt-out:** the `--quiet` CLI flag suppresses the block at the user surface (same precedent as cost data in `rules/hatch3r-cost-visibility.md` → "appears in user-facing iteration summaries by default … suppressing via the `--quiet` CLI flag"). Suppression is user-surface only; it does not weaken the Tier ≥ 2 emission contract for default (non-`--quiet`) runs.
+
+## User-Accepted Bypass Record (D13)
+
+When the user explicitly accepts a low-confidence PASS at an ASK checkpoint (per the gate-failure rule in the Confidence Propagation Contract used by every core orchestrator), the orchestrator MUST:
+
+1. Emit `User-Accepted Bypass: yes` in §8 (Open Questions / Blockers) with the bypass reason verbatim from the user reply.
+2. Append a single line to `.hatch3r/bypass-log.jsonl` (one JSON object per line — append-only, never rewritten):
+
+```json
+{"ts": "<ISO-8601>", "command": "<hatch3r-* name>", "verdict": "low", "user_reason": "<verbatim ≤200 chars>", "files": ["<paths>"], "session_id": "<id>"}
+```
+
+Schema: `ts` ISO-8601 UTC timestamp; `command` the orchestrator command id; `verdict` always `low` (no bypass on high/medium per the contract); `user_reason` the user's verbatim acceptance string (truncated at 200 chars, no PII); `files` mutated file list; `session_id` the host runtime's session id when available, `unknown` otherwise. Atomic append via `src/merge/safeWrite.ts` pattern (temp+rename then concat). Absence of the line on a recorded bypass is a P5 gate failure.
+
+## Validation Gate
+
+A skill or command that omits the 9-section block fails the lifecycle gate (`.claude/rules/capability-lifecycle.md`). Prose substitution is rejected. The orchestrator catches the omission before declaring SUCCESS.
+
+## Emission-Rate Telemetry (current status: per-run gate only; cross-run rate not yet wired)
+
+The validation gate above asserts the 9-section block is present per run. It does NOT measure the emission rate across runs, and no automated cross-run measurement exists today.
+
+The SPACE-shaped activity/performance instrumentation (`src/pipeline/spaceTelemetry.ts`, Decision 24 sibling of cost-visibility) provides the recording primitive `recordSpaceMetric`, the in-process aggregator `getSpaceSummary`, and the across-runs reader `loadSpaceMetricsFromDisk`, but they are not invoked on the iteration-summary path: orchestrator commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, and no command, skill, hook, or `src/` code emits an `iterationSummaryEmitted` metric. The cross-run emission-rate loop is therefore unwired — a future capability, not a live measurement (origin: D10-SA10.8-F-6; gap corrected D10-18). The module records on the `activity` and `performance` axes only; its `satisfaction` and `communication` axes are reserved with no feeder, so "SPACE" names the data shape, not full five-axis coverage (D10-40).
+
+To wire it, a host-runtime bridge (a Claude Code / Cursor / Copilot post-turn hook or an MCP shim) would need to call `recordSpaceMetric({ metricId: "iterationSummaryEmitted", axis: "activity", value: <1 if the 9-section block was produced else 0> })` after each orchestrator/meaningful-skill turn, persisting one JSONL line per run to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; the audit cycle could then read the persisted JSONL across runs via `loadSpaceMetricsFromDisk` + `summarizeSpaceMetricRecords` (NOT `getSpaceSummary`, which sees only the current process's ring buffer) to check the CONSTITUTION §2 P5 "Sub-agent count emission on delegating artifacts: 100%" target against observed runs instead of only mandating it. `recordSpaceMetric` already honours the Silent Failure Contract (telemetry I/O routes through `src/pipeline/failureLog.ts` and never throws), so building the bridge adds no failure surface. Until that bridge ships, P5 emission compliance is enforced by the per-run validation gate above plus audit-cycle spot checks, not by an aggregate metric.
+
+## Pillar Service
+- P5 — standardised reporting prevents drift across orchestrators
+- P7 — cost section surfaces token + duration deltas to user per Decision 24