hatch3r 1.9.0 → 2.0.0

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

@@ -0,0 +1,88 @@
+---
+id: hatch3r-flutter-patterns
+type: rule
+description: Flutter and Dart conventions covering null safety, state management (Riverpod/Bloc), Material 3, FFI, performance, platform channels, and integration testing
+scope: conditional
+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"
+tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# 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/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/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"
+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/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/dist/content/rules/hatch3r-handoff-readiness.md

@@ -37,6 +37,16 @@ Before writing a handoff to `.hatch3r/handoffs/active/`, verify each criterion.
 
 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: `.hatch3r/handoffs/README.md`

package/dist/content/rules/hatch3r-handoff-readiness.mdc

@@ -32,6 +32,16 @@ Before writing a handoff to `.hatch3r/handoffs/active/`, verify each criterion.
 
 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: `.hatch3r/handoffs/README.md`

package/dist/content/rules/hatch3r-i18n.md

@@ -10,6 +10,8 @@ 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/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.