docs: enhance AGENTS.md files with Go linting, DI patterns, barrel re-export, TS best practices [guardrail-change]

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

AGENTS.go.md

@@ -105,11 +105,38 @@ func TestIACEService_Create(t *testing.T) {
 
 ## Tooling
 
-- `golangci-lint` with: `errcheck, govet, staticcheck, revive, gosec, gocyclo (max 15), gocognit (max 20), unused, ineffassign, errorlint, nilerr, nolintlint, contextcheck`.
+Run lint before pushing:
+
+```bash
+golangci-lint run --timeout 5m ./...
+```
+
+The `.golangci.yml` at the service root (`ai-compliance-sdk/.golangci.yml`) enables: `errcheck, govet, staticcheck, gosec, gocyclo (≤20), gocritic, revive, goimports, unused, ineffassign`. Fix lint violations in new code; legacy violations are tracked but not required to fix immediately.
+
 - `gofumpt` formatting.
 - `go vet ./...` clean.
 - `go mod tidy` clean — no unused deps.
 
+## File splitting pattern
+
+When a Go file exceeds the 500-line hard cap, split it in place — no new packages needed:
+
+- All split files stay in **the same package directory** with the **same `package <name>` declaration**.
+- No import changes are needed anywhere because Go packages are directory-scoped.
+- Naming: `store_projects.go`, `store_components.go` (noun + underscore + sub-resource).
+- For handlers: `iace_handler_projects.go`, `iace_handler_hazards.go`, etc.
+- Before splitting, add a characterization test that pins current behaviour.
+
+## Error handling
+
+Domain errors are defined in `internal/domain/<aggregate>/errors.go` as sentinel vars or typed errors. The mapping from domain error to HTTP status lives exclusively in `internal/platform/httperr/httperr.go` via `errors.Is` / `errors.As`. Handlers call `httperr.Write(c, err)` — **never** directly call `c.JSON` with a status code derived from business logic.
+
+## Context propagation
+
+- Always pass `ctx context.Context` as the **first parameter** in every service and repository method.
+- Never store a context in a struct field — pass it per call.
+- Cancellation must be respected: check `ctx.Err()` in loops; propagate to all I/O calls.
+
 ## Concurrency
 
 - Goroutines must have a clear lifecycle owner (struct method that started them must stop them).
@@ -122,5 +149,8 @@ func TestIACEService_Create(t *testing.T) {
 - Add a new top-level package directly under `internal/` without architectural review.
 - `import "C"`, unsafe, reflection-heavy code.
 - Use `init()` for non-trivial setup. Wire it in `internal/app`.
+- Use `interface{}` / `any` in new code without an explicit comment justifying it.
+- Call `log.Fatal` outside of `main.go`; panicking in request handling is also forbidden.
+- Shadow `err` with `:=` inside an `if`-block when the outer scope already declares `err` — use `=` or rename.
 - Create a file >500 lines.
 - Change a public route's contract without updating consumers.