@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/go-patterns/references/concurrency.md

@@ -0,0 +1,162 @@
+# Go concurrency patterns
+
+Each pattern stops cleanly when the context is cancelled and waits for every goroutine it starts.
+
+## Fan-out with errgroup and a concurrency limit
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func fetchAll(ctx context.Context, ids []string) ([]Item, error) {
+	items := make([]Item, len(ids)) // each goroutine writes its own index: no lock needed
+	g, ctx := errgroup.WithContext(ctx)
+	g.SetLimit(8)
+	for i, id := range ids {
+		g.Go(func() error {
+			it, err := fetch(ctx, id)
+			if err != nil {
+				return fmt.Errorf("fetch %s: %w", id, err)
+			}
+			items[i] = it
+			return nil
+		})
+	}
+	if err := g.Wait(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+```
+
+Since Go 1.22 each loop iteration has its own `i` and `id`, so capturing them is safe. On a module whose `go` directive is older than 1.22, copy them first (`i, id := i, id`).
+
+## Worker pool over a channel
+
+```go
+func process(ctx context.Context, jobs []Job, workers int) error {
+	in := make(chan Job)
+	g, ctx := errgroup.WithContext(ctx)
+
+	g.Go(func() error { // producer owns and closes in
+		defer close(in)
+		for _, j := range jobs {
+			select {
+			case in <- j:
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+		}
+		return nil
+	})
+
+	for range workers {
+		g.Go(func() error {
+			for j := range in {
+				if err := handle(ctx, j); err != nil {
+					return err
+				}
+			}
+			return nil
+		})
+	}
+	return g.Wait()
+}
+```
+
+`for range workers` (ranging over an int) needs Go 1.22+; use `for i := 0; i < workers; i++` on older modules.
+
+## Pipeline stage that cannot leak
+
+```go
+func squares(ctx context.Context, in <-chan int) <-chan int {
+	out := make(chan int)
+	go func() {
+		defer close(out)
+		for v := range in {
+			select {
+			case out <- v * v:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+	return out
+}
+```
+
+The `select` on `ctx.Done()` is what prevents the leak: without it the goroutine blocks forever on `out <-` once the consumer stops reading.
+
+## First result wins (with no leak)
+
+```go
+func first(ctx context.Context, replicas []string) (Result, error) {
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	ch := make(chan Result, len(replicas)) // buffered: losers never block
+	for _, r := range replicas {
+		go func() {
+			if res, err := query(ctx, r); err == nil {
+				ch <- res
+			}
+		}()
+	}
+	select {
+	case res := <-ch:
+		return res, nil
+	case <-ctx.Done():
+		return Result{}, ctx.Err()
+	}
+}
+```
+
+If every replica fails this waits for the parent context; add a timeout or count failures if that is not acceptable.
+
+## Mutex-guarded state
+
+```go
+type Counter struct {
+	mu sync.Mutex
+	n  map[string]int // guarded by mu
+}
+
+func (c *Counter) Inc(k string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.n == nil {
+		c.n = make(map[string]int)
+	}
+	c.n[k]++
+}
+```
+
+Methods use a pointer receiver so the mutex is never copied. `go vet` (copylocks) flags copies.
+
+## Graceful HTTP shutdown
+
+```go
+func run(ctx context.Context) error {
+	ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	srv := &http.Server{Addr: ":8080", Handler: routes(), ReadHeaderTimeout: 5 * time.Second}
+	errCh := make(chan error, 1)
+	go func() { errCh <- srv.ListenAndServe() }()
+
+	select {
+	case err := <-errCh:
+		return err
+	case <-ctx.Done():
+	}
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	return srv.Shutdown(shutdownCtx)
+}
+```
+
+`ListenAndServe` returns `http.ErrServerClosed` after `Shutdown`; treat that as success if you read `errCh` afterwards. The shutdown context is deliberately new: the signal context is already cancelled.
+
+## Detecting leaks and races
+
+- `go test -race ./...` on every change that touches goroutines or shared state.
+- `go.uber.org/goleak` (`defer goleak.VerifyNone(t)` or `goleak.VerifyTestMain(m)`) catches goroutines still running at test end, if the project accepts the dependency.
+- A goroutine dump (`SIGQUIT`, or `net/http/pprof` at `/debug/pprof/goroutine?debug=2`) shows where leaked goroutines are blocked.

package/skills/go-testing/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: go-testing
+description: Writes and fixes Go tests with the standard testing package, including table-driven tests with t.Run subtests, t.Helper and t.Cleanup, httptest servers and recorders, hand-written fakes instead of mock frameworks, the race detector, native fuzzing, benchmarks and golden files. Use when adding or repairing _test.go files, making flaky Go tests deterministic, testing an HTTP handler or client in Go, or writing a Go fuzz target or benchmark.
+license: MIT
+compatibility: Any Agent Skills host. Needs the go toolchain.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "go"
+  kete-loom/owner: "Kete-org"
+---
+
+# Go testing
+
+Use the standard `testing` package and the project's existing test style. Add an assertion library only if the project already uses one.
+
+## 0. Before you write
+
+1. Find the test command (Makefile, CI workflow, README). Default: `go test ./...`.
+2. Run the package's tests once and record the result. If they already fail, **stop and tell the user** which ones before changing anything.
+3. Read the `go` directive in `go.mod`; do not use testing APIs newer than it.
+4. Look at a neighbouring `_test.go` file for naming, helpers, fixtures and whether tests are in `package foo` (white-box) or `package foo_test` (black-box). Prefer `foo_test` for testing the public API.
+
+## 1. Table-driven tests with subtests
+
+```go
+func TestParseDuration(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      string
+		want    time.Duration
+		wantErr bool
+	}{
+		{name: "minutes", in: "5m", want: 5 * time.Minute},
+		{name: "empty", in: "", wantErr: true},
+		{name: "negative", in: "-1s", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseDuration(tt.in)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("ParseDuration(%q) error = %v, wantErr %v", tt.in, err, tt.wantErr)
+			}
+			if got != tt.want {
+				t.Errorf("ParseDuration(%q) = %v, want %v", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+```
+
+Rules:
+- Every case has a `name`; run one with `go test -run 'TestParseDuration/negative' ./pkg`.
+- Failure messages say `Func(input) = got, want want`. Use `t.Errorf` to keep going, `t.Fatalf` only when later checks would be meaningless.
+- Compare structs and slices with `github.com/google/go-cmp/cmp` (`cmp.Diff(want, got)`) if available, otherwise `reflect.DeepEqual`. Check errors with `errors.Is`, not string equality.
+- `t.Parallel()` only when cases share no mutable state. On modules with a `go` directive before 1.22, copy the loop variable (`tt := tt`) before a parallel subtest.
+
+## 2. Helpers and cleanup
+
+- Call `t.Helper()` first in every helper that calls `t.Fatal`/`t.Error`, so failures point at the caller.
+- Helpers take `t *testing.T` (or `testing.TB` to share with benchmarks) and fail directly instead of returning errors.
+- Use `t.Context()` (Go 1.24+, cancelled just before cleanup runs) instead of `context.Background()` in tests where available.
+- Use `t.Cleanup(fn)` for teardown, `t.TempDir()` for files, `t.Setenv` for environment variables (it cannot be combined with `t.Parallel`).
+- Put fixture files in `testdata/`; the go tool ignores that directory when building.
+
+## 3. Fakes over mocks
+
+- Depend on a small interface at the consumer, then write a fake by hand in the test file: a struct with fields recording calls and returning canned results.
+- Prefer real implementations when they are cheap: `bytes.Buffer` for `io.Writer`, `fstest.MapFS` for `fs.FS`, `httptest` for HTTP, an in-memory store.
+- Do not add a mock generator to a project that does not already use one. Never mock the unit under test.
+- Inject time and randomness (`now func() time.Time`, a seeded `*rand.Rand`) instead of sleeping or relying on wall time.
+
+## 4. HTTP
+
+- Handlers: `rec := httptest.NewRecorder(); req := httptest.NewRequest(http.MethodGet, "/items/1", nil); h.ServeHTTP(rec, req)`, then check `rec.Code`, headers and `rec.Body`.
+- Clients: `srv := httptest.NewServer(http.HandlerFunc(...)); defer srv.Close()` and point the client at `srv.URL`. Use `httptest.NewTLSServer` with `srv.Client()` for TLS.
+- Assert the request the fake server received (method, path, body) as well as the client's result.
+- No real network calls in unit tests.
+
+## 5. Concurrency and the race detector
+
+- Run `go test -race ./...` for any package with goroutines or shared state. A race report is a bug to fix, not a flake.
+- Never use `time.Sleep` to wait for a goroutine. Wait on a channel, a `sync.WaitGroup`, or poll a condition with a deadline.
+- For code built on timers and goroutines, the `testing/synctest` package (`synctest.Test`, Go 1.25+) runs the test in a bubble with a fake clock; use it if the module's Go version allows.
+- Find flakes with `go test -race -count=50 -run TestName ./pkg`. Use `-shuffle=on` to expose order dependence.
+
+## 6. Fuzzing
+
+```go
+func FuzzParseDuration(f *testing.F) {
+	for _, s := range []string{"5m", "", "1h30m", "-1s"} {
+		f.Add(s)
+	}
+	f.Fuzz(func(t *testing.T, s string) {
+		d, err := ParseDuration(s)
+		if err != nil {
+			return
+		}
+		if again, err := ParseDuration(d.String()); err != nil || again != d {
+			t.Fatalf("round trip %q -> %v -> %v, %v", s, d, again, err)
+		}
+	})
+}
+```
+
+- Run with `go test -fuzz=FuzzParseDuration -fuzztime=30s ./pkg`. Only one fuzz target per package per run.
+- Assert properties (round trip, no panic, invariants), not exact outputs.
+- Failing inputs are written to `testdata/fuzz/FuzzName/`. Commit them: they become regression cases run by a plain `go test`.
+
+## 7. Benchmarks
+
+- Name `BenchmarkXxx(b *testing.B)`. On Go 1.24+ write the loop as `for b.Loop() { ... }`; setup before the loop is excluded automatically. On older versions use `for i := 0; i < b.N; i++` with `b.ResetTimer()` after setup.
+- Run with `go test -run '^$' -bench BenchmarkName -benchmem -count=10 ./pkg`.
+- Compare before and after with `golang.org/x/perf/cmd/benchstat old.txt new.txt`. Never claim a speed-up from a single run.
+
+## 8. Golden files
+
+```go
+var update = flag.Bool("update", false, "rewrite golden files")
+
+func TestRender(t *testing.T) {
+	got := Render(input)
+	golden := filepath.Join("testdata", t.Name()+".golden")
+	if *update {
+		if err := os.WriteFile(golden, got, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	want, err := os.ReadFile(golden)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if diff := cmp.Diff(string(want), string(got)); diff != "" {
+		t.Errorf("Render mismatch (-want +got):\n%s", diff)
+	}
+}
+```
+
+Regenerate with `go test ./pkg -run TestRender -update`, then **read the diff** before committing. Subtest names contain `/`; sanitise or create directories when using `t.Name()` in a path.
+
+## 9. Coverage
+
+`go test -coverprofile=cover.out ./... && go tool cover -func=cover.out`. Cover the error paths and boundaries the user cares about; do not chase a percentage.
+
+## Never
+
+- Delete, skip (`t.Skip`) or weaken an existing test to get green without the user's agreement.
+- Sleep to synchronise, hit the real network, or depend on test execution order.
+- Leave goroutines running after a test returns.
+
+## Report back
+
+End with: tests added or changed (names), the exact commands run (including `-race`), pass/fail counts, and anything left untested.

package/skills/go-testing/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Write table-driven tests with subtests for my Go ParseAmount function",
+    "This Go test is flaky under -race and uses time.Sleep, make it deterministic",
+    "Test my Go HTTP handler for POST /orders using httptest without a real server",
+    "Add a fuzz target for the Go URL normaliser and commit any crashing inputs",
+    "Benchmark these two Go JSON encoders properly and compare them with benchstat",
+    "Replace the gomock mocks in this _test.go file with a simple hand-written fake"
+  ],
+  "should_not_trigger": [
+    "How should I structure packages and interfaces in my new Go service?",
+    "Review this Go diff for data races and context misuse before I merge",
+    "go vet reports 'copylocks: call of foo copies lock value', fix the build",
+    "Write pytest fixtures and parametrized tests for my Flask app",
+    "Add Playwright end-to-end tests for the signup page"
+  ]
+}

package/skills/hexagonal-architecture/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: hexagonal-architecture
+description: Applies ports and adapters (hexagonal, clean or onion architecture) pragmatically, keeping domain rules and use cases free of framework, database and HTTP imports, pointing dependencies inward, and untangling an existing codebase one seam at a time. Use when business logic is mixed into controllers or ORM models, when a core module must be testable without a database, when deciding whether layering is worth it for a project, or when carving a use case out of legacy code.
+license: MIT
+compatibility: Any Agent Skills host. Language neutral; needs the project's test command to verify each step.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Hexagonal architecture (ports and adapters)
+
+One rule matters: **source code dependencies point inward.** The domain knows nothing about HTTP, the database, queues or the framework. Everything else is detail.
+
+## Is it worth it here?
+
+Decide before you add a single interface.
+
+| Signal | Verdict |
+|---|---|
+| Real business rules (pricing, eligibility, state machines) that change often | Worth it for that module |
+| Two or more delivery mechanisms (HTTP + queue + CLI) for the same logic | Worth it |
+| Need to swap or fake an external system (payments, email, a vendor API) | Worth it at that boundary only |
+| CRUD over a table with validation, nothing else | Overkill. Use the framework directly |
+| Prototype, script, or a service you expect to throw away | Overkill |
+| Team unfamiliar with it and no rule above applies | Overkill |
+
+Apply it **per module**, not per repo. A CRUD admin area and a ports-and-adapters billing core can live side by side. If the verdict is unclear, **stop and ask the user** what they want to be able to test or swap.
+
+## The shape
+
+```
+adapters (driving)          core                         adapters (driven)
+HTTP controller ─┐   ┌───────────────────────────┐   ┌─ PostgresOrderRepository
+CLI command  ────┼──▶│ use case (application)    │──▶├─ StripePaymentGateway
+queue consumer ──┘   │   uses domain + ports     │   └─ SmtpMailer
+                     │ domain (entities, rules)  │
+                     └───────────────────────────┘
+```
+
+- **Domain**: entities, value objects, domain rules. Pure code. No I/O, no framework, no ORM annotations if you can avoid them.
+- **Use cases (application services)**: one per user intention (`PlaceOrder`, `CancelSubscription`). Orchestrate domain objects and call ports. Own the transaction boundary.
+- **Ports**: interfaces the core defines, in core terms. Driven ports: `OrderRepository`, `PaymentGateway`, `Clock`. Driving ports: the use case's input/output types.
+- **Adapters**: implement driven ports (Postgres, Stripe, SMTP) or call driving ports (HTTP, CLI, consumers). All framework code lives here.
+- **Composition root**: one place (main, DI container config) wires adapters into use cases.
+
+## Rules
+
+1. The core imports only the language standard library and its own code. Enforce it with a check (an import-lint rule, an architecture test such as ArchUnit, dependency-cruiser or import-linter, or package visibility), not with good intentions.
+2. Ports are named for what the core needs (`PaymentGateway.charge(amount, customer)`), not for the technology (`StripeClient`). Vendor DTOs never cross into the core; adapters translate.
+3. One port per real external dependency. Don't wrap things you'll never replace or fake (the standard library, pure utility libraries).
+4. Use cases take and return plain data or domain types, never HTTP request objects or ORM entities.
+5. Validation of input shape happens in the driving adapter; business invariants live in the domain.
+6. Tests: domain and use cases are unit-tested with in-memory fakes for ports; each adapter has its own integration test against the real thing (test database, sandbox API). Few end-to-end tests on top.
+7. Don't create a folder per layer per entity with one-line pass-through classes. If a use case only forwards to a repository, the module is probably CRUD; see the table above.
+
+## Migrating a tangled codebase
+
+Never do a big-bang rewrite. Move one use case at a time, keeping the suite green after each step.
+
+1. **Pick the seam**: the use case with the most business logic and the most pain (bugs, hard to test). Read every caller.
+2. **Pin behaviour**: add characterisation tests at the current entry point (HTTP or function level) before moving anything. If you can't test it, stop and tell the user what blocks it.
+3. **Extract the use case**: move the logic out of the controller/model into a use-case function or class that takes its dependencies as parameters. Keep calling the same database code for now.
+4. **Introduce ports**: replace each direct infrastructure call in the use case with an interface defined next to the use case. The existing code becomes the first adapter.
+5. **Move domain rules** out of ORM models or services into domain types, one rule at a time.
+6. **Thin the controller**: it parses input, calls the use case, maps the result to a response. Nothing more.
+7. **Add the dependency check** so the extracted module can't regress.
+8. Run the test command after every step. Commit each step separately.
+
+Stop and ask the user before: changing a public API or database schema as part of the move, introducing a DI framework, or moving more than one use case in one change.
+
+## Never
+
+- Leak ORM entities, HTTP requests or vendor SDK types into the domain.
+- Add an interface with exactly one implementation and no fake "for flexibility" outside a real boundary.
+- Let the domain call the database "just this once."
+- Restructure the whole repo into layers before a single use case benefits.
+
+## Report back
+
+```
+Verdict: apply | partial (modules) | skip, and why
+Core modules: paths, and the dependency check that guards them
+Ports added: name → adapter(s)
+Steps done: list, each with test command result
+Next seam: the next use case worth extracting
+```

package/skills/hexagonal-architecture/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "All our pricing logic lives inside the Django views, how do I pull it out so I can test it without a database?",
+    "Set up ports and adapters for the billing module so we can swap Stripe for Paystack later",
+    "Is clean architecture overkill for our small CRUD admin service?",
+    "Our domain classes import the ORM everywhere. Help me fix the dependency direction step by step",
+    "Carve the order placement use case out of this 2000-line legacy service without a rewrite"
+  ],
+  "should_not_trigger": [
+    "Design the REST endpoints and error format for the new orders API",
+    "Rename this long method and split it into smaller functions, keeping behaviour",
+    "Compare a monolith versus microservices for our new platform and recommend one",
+    "Write an ADR documenting that we adopted hexagonal architecture",
+    "Implement the Stripe webhook handler for subscription renewals",
+    "Delete the dead code and unused exports in the utils folder"
+  ]
+}

package/skills/hipaa-compliance/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: hipaa-compliance
+description: Engineering rules for US HIPAA work on protected health information (PHI and ePHI), covering whether HIPAA applies, Security Rule safeguards such as role-based access, audit trails, encryption and automatic logoff, business associate agreements with cloud, email, SMS and AI vendors, the minimum necessary standard, de-identification, PHI-free logging, and breach readiness, with a clear not-legal-advice line. Use when building or reviewing a health, telehealth, clinic, pharmacy or insurance system in the US, choosing a vendor that will touch patient data, or scrubbing PHI from logs and analytics.
+license: MIT
+compatibility: Any Agent Skills host. Works on any codebase; no CLI needed. Rule detail lives in references/safeguards.md and must be checked against current HHS guidance.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# HIPAA compliance
+
+Engineer a system that protects electronic protected health information (ePHI) by default: only the right people see it, every access is recorded, it never leaks into logs or vendors without a contract, and a breach can be scoped quickly.
+
+## Boundary: this is not legal advice
+
+- You help design and build safeguards. You do not decide whether the organisation is a covered entity or business associate, whether an incident is a reportable breach, or whether a vendor contract is adequate. The privacy officer, security officer or counsel decides.
+- Say so once, plainly, when the user asks a legal question, and continue with the engineering.
+- No code or vendor can make a system "HIPAA compliant" on its own. Never write that claim in code, docs or marketing copy.
+
+## Step 1: does HIPAA apply, and to what data?
+
+Ask the user, and **stop and ask** if the answer is unclear:
+
+1. Is the organisation a covered entity (health plan, health care clearinghouse, or a provider that conducts standard electronic transactions such as claims), or a business associate (a vendor that creates, receives, keeps or sends PHI for one)? A consumer wellness app that patients use on their own, with no covered entity involved, is often outside HIPAA but may fall under other laws (for example the FTC Health Breach Notification Rule or state health privacy laws). Flag this to the user; do not decide it.
+2. Which data is PHI: individually identifiable health information (past, present or future health, care, or payment for care) that is linked to an identifier. Names, dates (except year) tied to a person, phone, email, addresses below state level, record and account numbers, device ids, IPs, full-face photos and biometrics are all identifiers. `references/safeguards.md` lists the 18 Safe Harbor identifiers.
+3. Data that has been de-identified by Safe Harbor or expert determination is not PHI. Treat it as PHI until someone has done that properly.
+
+## Step 2: map where ePHI lives and flows
+
+Search the codebase and infrastructure for ePHI: database tables, file storage, message queues, caches, search indexes, logs, error trackers, analytics, email and SMS, backups, exports, BI tools, support tooling and AI or LLM calls. Record each in a table:
+
+| System | ePHI fields | Who can access | Encrypted at rest | Vendor | BAA in place |
+|---|---|---|---|---|---|
+
+This map feeds the organisation's risk analysis, which the Security Rule requires and which OCR most often finds missing.
+
+## Step 3: vendors and business associate agreements
+
+1. Every vendor that stores, processes or transmits ePHI for you needs a signed BAA before any ePHI reaches it. That includes cloud hosting, databases, email, SMS, video, error tracking, logging, analytics, support desks and AI APIs.
+2. A vendor's BAA often covers only listed services or a specific plan. Check that the exact service and configuration you use is in scope.
+3. If there is no BAA, **stop**: keep ePHI away from that vendor (strip it, or pick another vendor). Tell the user which integration is blocked and why.
+4. Typical traps: client-side analytics or session replay on logged-in pages, crash reporters capturing request bodies, marketing pixels on appointment pages, and support tools that receive screenshots.
+
+## Step 4: technical safeguards to build
+
+Follow `references/safeguards.md` for the rule mapping. In code:
+
+- **Access control**: unique user ids (no shared accounts), role-based access scoped to the patient relationship, an emergency ("break glass") access path that is logged and reviewed, automatic session timeout, and MFA for workforce and admin access.
+- **Minimum necessary**: APIs return only the fields the role and task need. Lists show summaries; full records load on purpose. Internal tools mask identifiers by default.
+- **Audit controls**: an append-only audit log of every create, read, update, delete and export of ePHI: actor id, patient or record id, action, timestamp, source IP, and reason for break-glass access. Store it apart from the app database, protect it from edits, and keep it for the retention period counsel sets (HIPAA documentation is kept six years; confirm what applies to logs).
+- **Integrity**: validate input, use database constraints, and keep versions or history for clinical records instead of overwriting.
+- **Transmission security**: TLS for every connection, including internal service calls and database connections. No ePHI in email or SMS bodies unless the organisation's policy allows it; send a "you have a new message" link instead.
+- **Encryption at rest**: encrypt databases, volumes, object storage and backups, with keys in a managed key service and access to keys logged. Encryption is "addressable" under the current rule, but encrypted data is what lets a lost laptop or leaked bucket fall outside breach notification, so treat it as required.
+
+## Step 5: logging and telemetry without PHI
+
+- Log record ids and request ids, never names, dates of birth, diagnoses, notes, medications, insurance ids or free-text fields.
+- Add a redaction layer to the logger, the error tracker (scrub request bodies, headers, query strings) and the APM agent. Test it with a fixture that contains fake PHI.
+- URLs and analytics event names must not contain PHI (no `/patients/jane-doe/hiv-results`). Use opaque ids.
+- Never paste real patient data into tickets, chat, prompts or test fixtures. Use synthetic data in every non-production environment.
+
+## Step 6: breach readiness
+
+- The Breach Notification Rule sets deadlines measured from discovery; see `references/safeguards.md`. Engineering must be able to answer quickly: what was accessed, whose records, from when to when.
+- Keep audit logs queryable by patient and by actor, and keep a way to produce an affected-patient list with contact details.
+- On a suspected incident: contain, preserve logs and snapshots, record the discovery time, and escalate to the security or privacy officer. Do not notify patients, regulators or the press yourself, and do not delete evidence.
+
+## Never
+
+- Never send ePHI to a vendor without a BAA, including "just for debugging".
+- Never put ePHI in logs, URLs, analytics, push notification text or email subjects.
+- Never use real patient data in development, testing, demos or AI prompts.
+- Never weaken access checks for convenience (shared admin logins, disabled timeouts, wildcard roles).
+- Never state that the system or a vendor "is HIPAA compliant" or "HIPAA certified" (there is no official certification).
+
+## Report format
+
+```
+HIPAA engineering review: <system or feature>
+Applies because: <covered entity / business associate, as stated by the user>
+ePHI map: <path or inline table>
+Findings (highest risk first):
+  1. [High|Medium|Low] <safeguard> at <file:line or system>: <gap> -> <fix>
+Vendors without a confirmed BAA: <list>
+Questions for the privacy or security officer: <list>
+Not checked: <systems you could not see>
+This is engineering guidance, not legal advice.
+```

package/skills/hipaa-compliance/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "We're building a telehealth app for US clinics, what HIPAA safeguards do we need in the backend?",
+    "Can we use Sentry and Twilio in our patient portal or do we need a BAA first?",
+    "Our logs are full of patient names and diagnoses, help me scrub PHI out of them",
+    "Design an audit log for who viewed or exported each patient record in our EHR",
+    "Is a hashed email plus visit date still PHI if we send it to our analytics vendor?",
+    "Review our pharmacy refill service for HIPAA minimum necessary and access control gaps"
+  ],
+  "should_not_trigger": [
+    "Our EU users want their data deleted under GDPR, build the erasure flow",
+    "Which SAQ do we need if we use Stripe Checkout for payments?",
+    "Write unit tests for the appointment booking service",
+    "Do a security review of our new password reset endpoint",
+    "Set up role-based access control with OAuth scopes in our NestJS API",
+    "Build a PyTorch model that predicts hospital readmission from tabular data"
+  ]
+}

package/skills/hipaa-compliance/references/safeguards.md

@@ -0,0 +1,68 @@
+# HIPAA rule map for engineers
+
+Engineering summary only, not legal advice. Check HHS (hhs.gov/hipaa) and the regulation text (45 CFR Parts 160 and 164) before relying on any detail, and have the privacy or security officer confirm.
+
+## Status of the Security Rule
+
+- HHS published a proposed overhaul of the Security Rule in January 2025. It would remove the "required" versus "addressable" split and make controls such as encryption and MFA mandatory. It is still a proposal: in July 2026 the federal regulatory agenda moved its final action date to July 2027 and listed it under long-term actions. The current Security Rule stays in force until a final rule takes effect; check HHS for its status.
+- Build to the stricter proposed bar anyway (encrypt everything, MFA everywhere, asset inventory, network map), because it is cheap to do in new systems and expensive to retrofit.
+
+## Security Rule safeguards (45 CFR 164.308 to 164.312)
+
+| Safeguard | Section | What engineering builds |
+|---|---|---|
+| Risk analysis and risk management | 164.308(a)(1) | ePHI map, threat list, tracked remediation |
+| Workforce access management | 164.308(a)(4) | Role definitions, joiner/mover/leaver process, access reviews |
+| Security incident procedures | 164.308(a)(6) | Incident runbook, alerting, evidence preservation |
+| Contingency plan | 164.308(a)(7) | Encrypted backups, tested restores, disaster recovery plan |
+| Business associate contracts | 164.308(b), 164.314(a) | BAA register per vendor and service |
+| Device and media controls | 164.310(d) | Disk encryption, secure wipe, no ePHI on unmanaged devices |
+| Access control | 164.312(a) | Unique user ids, emergency access, automatic logoff, encryption (addressable) |
+| Audit controls | 164.312(b) | Tamper-resistant audit log of ePHI activity |
+| Integrity | 164.312(c) | Controls against improper alteration or destruction |
+| Person or entity authentication | 164.312(d) | Strong authentication, MFA |
+| Transmission security | 164.312(e) | TLS everywhere, integrity checks, encryption (addressable) |
+
+"Addressable" does not mean optional: implement it, or document why an equivalent measure is reasonable.
+
+Documentation of policies and actions is kept for six years from creation or last effective date (164.316(b)(2)).
+
+## Privacy Rule points that shape code
+
+- **Minimum necessary** (164.502(b), 164.514(d)): limit uses, disclosures and requests to the minimum needed. Does not apply to disclosures to the patient or for treatment between providers.
+- **Business associates** (164.502(e), 164.504(e)): a BAA must be in place before a business associate handles PHI, and subcontractors of business associates need one too.
+- **Patient right of access** (164.524): patients can get copies of their records, electronically if held electronically. Build an export.
+
+## De-identification (164.514(b))
+
+Two methods: expert determination, or Safe Harbor. Safe Harbor removes these 18 identifiers of the individual and of relatives, employers and household members, and the entity has no actual knowledge that the rest could identify the person:
+
+1. Names
+2. Geographic subdivisions smaller than a state (street, city, county, ZIP; the first three ZIP digits may stay if that area has more than 20,000 people)
+3. All elements of dates (except year) related to the person, and all ages over 89
+4. Telephone numbers
+5. Fax numbers
+6. Email addresses
+7. Social Security numbers
+8. Medical record numbers
+9. Health plan beneficiary numbers
+10. Account numbers
+11. Certificate or license numbers
+12. Vehicle identifiers and serial numbers, including license plates
+13. Device identifiers and serial numbers
+14. Web URLs
+15. IP addresses
+16. Biometric identifiers, including finger and voice prints
+17. Full-face photographs and comparable images
+18. Any other unique identifying number, characteristic or code
+
+Hashing an identifier is not de-identification by itself.
+
+## Breach Notification Rule (164.400 to 164.414)
+
+- Applies to unsecured PHI. PHI encrypted to HHS guidance, with the key not compromised, is "secured".
+- Individuals: without unreasonable delay and no later than 60 calendar days after discovery.
+- HHS: for 500 or more individuals, at the same time as individual notice; for fewer than 500, in an annual log submitted within 60 days after the end of the calendar year.
+- Media: when more than 500 residents of a state or jurisdiction are affected.
+- Business associates notify the covered entity without unreasonable delay and no later than 60 days after discovery.
+- Whether an incident is a reportable breach is a legal decision based on a risk assessment. Engineering provides the facts.