@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/harmonyos-arkts/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My ArkUI list doesn't refresh when I change a field inside an item object, I'm using @State",
+    "Migrate this HarmonyOS component from @Component with @Link to @ComponentV2 with @Param and @Event",
+    "hvigorw assembleHap fails with arkts-no-untyped-obj-literals errors after upgrading the SDK",
+    "Where should I load the first page and release timers in a HarmonyOS UIAbility?",
+    "Set up a CI job that runs ohpm install and builds a signed HAP for our HarmonyOS NEXT app"
+  ],
+  "should_not_trigger": [
+    "Build an Android screen in Jetpack Compose with a ViewModel and StateFlow",
+    "Our Flutter app needs to call native Android code through a platform channel",
+    "Convert this TypeScript React component to use hooks instead of a class",
+    "Share business logic between Android and iOS with Kotlin Multiplatform",
+    "Translate our mobile app into Simplified Chinese with plural rules"
+  ]
+}

package/skills/harmonyos-arkts/references/build-errors.md

@@ -0,0 +1,42 @@
+# HarmonyOS build errors and fixes
+
+Exact error wording changes between SDK and hvigor versions. Match on the meaning and the rule tag, then confirm the fix in the official docs for your API level.
+
+## ArkTS compiler errors
+
+| Error (rule tag) | Cause | Fix |
+|---|---|---|
+| Use explicit types instead of "any", "unknown" (`arkts-no-any-unknown`) | Untyped variable, parameter or `JSON.parse` result | Declare a class or interface and annotate; for loose JSON use `Record<string, Object>` and check fields |
+| Object literal must correspond to some explicitly declared class or interface (`arkts-no-untyped-obj-literals`) | `{ a: 1 }` passed where no declared type matches | Declare an `interface`, annotate the variable or parameter |
+| Indexed access is not supported for fields (`arkts-no-props-by-index`) | `obj[key]` on a class instance | Use a `Map<string, T>` or named fields |
+| Decorator not allowed / V1 and V2 mixed | `@State` in `@ComponentV2`, or `@Local` in `@Component` | Use one decorator family per struct (see SKILL.md table) |
+| `@Param` cannot be assigned | Child writes to its input | Add an `@Event` callback and let the parent change the value |
+| Page not found at runtime after `loadContent` or navigation | Page missing from `main_pages.json` or wrong path | Add `"pages/Name"` to `resources/base/profile/main_pages.json` |
+
+For every other rule tag, search the official "Adaptation Cases" page of the ArkTS migration guide for the tag; it gives a before and after for each.
+
+## Dependency errors
+
+| Symptom | Fix |
+|---|---|
+| Cannot find module `@ohos/...` or a third-party package | Run `ohpm install` in the project root (and in the module if it has its own `oh-package.json5`); check the registry in `.ohpmrc` |
+| Package installs but fails to compile | It targets OpenHarmony or an older API; find a HarmonyOS NEXT version or replace it |
+| hvigor plugin download fails in CI | Configure the npm registry used by `hvigor/hvigor-config.json5` |
+
+## SDK and configuration errors
+
+| Symptom | Fix |
+|---|---|
+| API not available at the compatible SDK version | Gate the call with `canIUse('SystemCapability.<name>')` or raise `compatibleSdkVersion` in `build-profile.json5` (ask the user first) |
+| Product or target not found | Use a product name that exists under `products` in `build-profile.json5` (`-p product=<name>`) |
+| Module not found by `--mode module` | Check the module is listed under `modules` in the root `build-profile.json5` |
+
+## Signing and install errors
+
+| Symptom | Fix |
+|---|---|
+| Unsigned HAP, install rejected | Add a `signingConfigs` entry and reference it from the product; DevEco Studio can generate debug signing for a connected device |
+| Install fails with a signature or bundle mismatch | Uninstall the old app (`hdc uninstall <bundleName>`) or use the same signing profile |
+| Install fails, device not found | `hdc list targets` to see devices; start the emulator or reconnect |
+
+Never paste keystore passwords into config committed to git; inject them in CI.

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.

package/skills/hl7v2-integration/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: hl7v2-integration
+description: Parses, generates and routes pipe-delimited HL7 version 2.x messages such as ADT admit/discharge/transfer events, ORM and OML orders and ORU results, handling MSH encoding characters and escape sequences, repeating fields and components, MSH-10 control IDs, original and enhanced ACK/NACK modes, MLLP framing over TCP, interface engines like Mirth Connect (NextGen Connect), and mapping v2 segments to FHIR resources. Use when receiving or sending HL7 v2 feeds from a hospital, lab or EHR, debugging a rejected message or missing ACK, writing an MLLP listener, or converting PID, PV1, OBR and OBX data into FHIR.
+license: MIT
+compatibility: Any Agent Skills host. Live feeds need network access to the interface engine or MLLP endpoint. Rules apply to any language or HL7 library (for example HAPI HL7v2, python-hl7, hl7apy).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# HL7 v2 integration
+
+Build an HL7 v2 interface that never loses a message, never files a result against the wrong patient, and tells the sender exactly why it rejected something. For the FHIR REST API use `fhir-integration`; for HIPAA safeguards around the feed use `hipaa-compliance`.
+
+This is engineering guidance, not clinical advice. Every live interface is validated with the sending site before go-live.
+
+## Ground rules
+
+1. **The interface specification wins.** Every site customises v2 (Z-segments, optional fields made required, local code tables). Get the sender's or receiver's interface spec and sample messages before writing a parser. If there is none, stop and ask for it.
+2. **Read encoding characters from MSH, never hard-code them.** MSH-1 is the field separator (normally `|`), MSH-2 holds component `^`, repetition `~`, escape `\`, subcomponent `&` (and truncation `#` from v2.7). Segments end with carriage return `\r` (0x0D), not `\n`.
+3. **Unescape and escape.** `\F\` `\S\` `\R\` `\E\` `\T\` stand for the separators inside data; `\X..\` is hex and `\.br\` a line break in formatted text. Escape on output; a name with `^` or `&` must not split fields.
+4. **Fields repeat.** PID-3 (identifiers), PID-5 (names), PID-13 (phones) and OBX-5 can repeat with `~`. Pick the identifier by its assigning authority and type code (PID-3.4, PID-3.5 such as `MR`), never "the first one".
+5. **Persist before you ACK.** Write the raw message to durable storage (queue or database) in the same step that decides the ACK. Send `AA`/`CA` only once it is stored. If storage fails, send `AR` with ERR-3 code `207` (application internal error) or send no ACK so the sender retries; `AE` means the content is wrong and senders usually don't resend it unchanged.
+6. **MSH-10 is the idempotency key.** Senders resend when an ACK is lost. Deduplicate on sending facility (MSH-4) plus MSH-10 and return the same ACK again for a duplicate.
+7. **Preserve order per patient.** ADT events (A01 admit, A02 transfer, A03 discharge, A08 update, A40 merge) must be processed in order for a patient. Process one connection serially, or partition by patient identifier; never parallelise blindly.
+8. **Merges and corrections are first-class.** Handle A40 (merge patient), A11/A13 (cancel admit/discharge), A08 updates, and ORU results with OBX-11 result status `C` (corrected) or `D` (delete). Never treat them as new records.
+9. **Never log full messages.** Messages contain PHI. Log message type, MSH-10, MSH-4, processing outcome and error location (segment, field) only. Keep raw messages in access-controlled storage with a retention policy.
+
+## Steps
+
+1. **Collect the spec and samples:** versions (MSH-12, for example `2.3`, `2.5.1`), message types and trigger events (MSH-9, for example `ADT^A01^ADT_A01`, `ORU^R01^ORU_R01`), required segments, Z-segments, code tables, ACK mode (MSH-15/MSH-16), and character set (MSH-18).
+2. **Transport.** For MLLP use the framing in `references/messages-and-ack.md`. Run MLLP over a VPN or TLS tunnel; MLLP itself has no encryption or authentication. Restrict the listener port to the sender's IPs.
+3. **Parse** with a maintained library, configured to read separators from MSH. Validate: required segments present, MSH-9 is a type you accept, MSH-11 processing ID (`P` production, `T` test, `D` debug) matches the environment. Reject `T` messages in production and `P` messages in test.
+4. **Acknowledge** with the ACK format in `references/messages-and-ack.md`. On a rejected message set MSA-1 to `AE` (a problem in the message content, such as a missing required field; the sender must fix it before resending) or `AR` (rejected for reasons not about the content: unsupported message type, version or processing ID, or a receiver failure), and fill ERR with the segment and field location and a code.
+5. **Map** fields to your model or to FHIR using the table in `references/messages-and-ack.md` and the HL7 Version 2 to FHIR IG (hl7.org/fhir/uv/v2mappings). Keep the original identifiers and the raw message ID on every mapped record for traceability.
+6. **Produce** outbound messages with a fresh MSH-10 per message, MSH-7 timestamp with timezone, correct MSH-3/4/5/6 sending and receiving application and facility, and wait for the ACK before sending the next on that connection. Retry with the same MSH-10 on timeout.
+7. **Test** with de-identified sample messages from the site, plus edge cases: escaped separators, repeating identifiers, missing optional segments, Z-segments, a duplicate MSH-10, a merge (A40), a corrected result, an empty OBX-5, a message with `\n` line endings.
+
+## Interface engines
+
+If the organisation runs an engine (Mirth Connect by NextGen Healthcare, commercially licensed from 4.6; Rhapsody; Cloverleaf; InterSystems HealthShare; or a cloud service such as Google Cloud Healthcare API HL7v2 stores with its MLLP adapter), put routing, filtering and transformation there rather than in each application, and keep transformations in source control. Your application then gets one well-defined feed.
+
+## Stop and ask the user
+
+- Before connecting to a production feed, or replaying messages into production.
+- When identifiers in PID-3 don't match the agreed assigning authority, or a message would update a patient that can't be matched uniquely.
+- When the sample messages contradict the interface spec.
+- Before discarding or "fixing up" messages that fail validation.
+
+## Never
+
+- Never split on `|` and `^` with hard-coded indices without handling escapes and repetitions.
+- Never ACK before the message is durably stored.
+- Never drop OBX segments you don't understand from a result; store them and flag them.
+- Never reuse an MSH-10 for a different message.
+- Never mix test and production feeds on one listener.
+
+## Report format
+
+When asked to review or design an interface, finish with:
+
+```
+Feed: <sender → receiver, message types and versions, transport>
+ACK mode: <original | enhanced>, persisted before ACK: <yes/no>
+Findings: <ranked list, file:line, rule broken, fix>
+Open questions for the interface analyst: <list>
+```

package/skills/hl7v2-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write an MLLP listener in Node that receives ADT messages and sends back an ACK",
+    "The lab says our ORU^R01 parser files results under the wrong patient when PID-3 has two identifiers",
+    "Our interface engine keeps resending messages because it never gets an AA back, help me debug the ACK",
+    "Map OBX segments from incoming HL7 v2 lab results into FHIR Observation resources",
+    "Generate outbound ORM order messages with proper MSH-10 control IDs and escaping of the ^ character in names"
+  ],
+  "should_not_trigger": [
+    "Query a FHIR server for all Encounters in the last week using _include for the patient",
+    "Design drug-interaction alerts so clinicians don't get alert fatigue",
+    "Set up a Kafka consumer with exactly-once processing for our order events",
+    "Check our hospital feed handler for patient data written to application logs",
+    "Write the HIPAA audit logging requirements for our EHR export feature"
+  ]
+}

package/skills/hl7v2-integration/references/messages-and-ack.md

@@ -0,0 +1,78 @@
+# HL7 v2 messages, ACKs, MLLP and FHIR mapping
+
+Sources: HL7 v2.5.1 and later chapters 2 (control) and 3 (ADT), the MLLP transport spec (HL7 v2 Appendix C / Transport Specification MLLP Release 2), and the HL7 Version 2 to FHIR IG 1.0.0. Field positions below are the common ones; the site's interface spec overrides them.
+
+## Example ADT^A01
+
+```
+MSH|^~\&|ADT1|GOOD HEALTH HOSPITAL|RCV|RCVFAC|20240612083000+0100||ADT^A01^ADT_A01|MSG00001|P|2.5.1
+EVN|A01|20240612083000+0100
+PID|1||12345^^^GHH^MR~987654321^^^NHS^NH||DOE^JANE^A||19800101|F|||1 MAIN ST^^LEEDS^^LS1 1AA^GBR
+PV1|1|I|WARD1^ROOM2^BED3||||1234^SMITH^JOHN|||MED
+```
+
+Segments are separated by `\r`. The line breaks above are for reading only.
+
+## Key fields
+
+| Field | Meaning |
+|---|---|
+| MSH-3 / MSH-4 | sending application / facility |
+| MSH-5 / MSH-6 | receiving application / facility |
+| MSH-7 | message date/time |
+| MSH-9 | message type ^ trigger event ^ structure |
+| MSH-10 | message control ID (unique per message from a sender) |
+| MSH-11 | processing ID: P, T, D |
+| MSH-12 | version ID |
+| MSH-15 / MSH-16 | accept / application acknowledgment type (AL, NE, ER, SU); blank means original mode |
+| PID-3 | patient identifier list (ID ^^^ assigning authority ^ type code) |
+| PID-5 / PID-7 / PID-8 | name / birth date / administrative sex |
+| PV1-2 / PV1-3 | patient class / assigned location |
+| ORC-1 / ORC-2 / ORC-3 | order control / placer order number / filler order number |
+| OBR-4 | universal service identifier (ordered test) |
+| OBX-2 / OBX-3 / OBX-5 / OBX-6 | value type / observation identifier / value / units |
+| OBX-8 / OBX-11 | abnormal flags / result status (F final, P preliminary, C corrected, D delete, X cannot obtain) |
+
+## ACK
+
+Original mode: the receiving application replies once.
+
+```
+MSH|^~\&|RCV|RCVFAC|ADT1|GOOD HEALTH HOSPITAL|20240612083001+0100||ACK^A01^ACK|ACK00001|P|2.5.1
+MSA|AA|MSG00001
+```
+
+- MSA-1: `AA` accepted, `AE` error, `AR` rejected.
+- MSA-2: the MSH-10 of the message being acknowledged.
+- On `AE`/`AR`, add `ERR` with location (ERR-2, for example `PID^1^3`), HL7 error code (ERR-3, from table 0357, for example `101` required field missing, `200` unsupported message type, `207` application internal error) and severity (ERR-4: `E`, `W`, `I`).
+- Swap sending and receiving application/facility relative to the inbound MSH.
+
+Enhanced mode (MSH-15/16 set): a commit ACK (`CA`, `CE`, `CR`) confirms safe receipt, and an optional application ACK (`AA`, `AE`, `AR`) follows later as a separate message.
+
+## MLLP framing
+
+```
+<VT> message <FS><CR>
+VT = 0x0B   FS = 0x1C   CR = 0x0D
+```
+
+- Read bytes until `0x1C 0x0D`; strip the leading `0x0B`. A TCP read can contain part of a message or several messages: buffer and split on the trailer.
+- One message at a time per connection: send, wait for the ACK, then the next.
+- Set an ACK timeout (often 30 to 60 seconds, agree it with the partner) and resend with the same MSH-10 on timeout.
+- Keep connections open; reconnect with backoff.
+- MLLP has no security. Use a VPN, TLS wrapper or engine-to-engine secure channel.
+
+## Mapping to FHIR (summary of the v2-to-FHIR IG)
+
+| v2 | FHIR R4 |
+|---|---|
+| PID | Patient (PID-3 → identifier, PID-5 → name, PID-7 → birthDate, PID-8 → gender via a concept map) |
+| PV1 | Encounter (PV1-2 → class, PV1-3 → location, PV1-19 visit number → identifier) |
+| ORC + OBR | ServiceRequest (placer/filler numbers → identifier) and DiagnosticReport for results |
+| OBX | Observation (OBX-3 → code, OBX-5 by OBX-2 type → value[x], OBX-6 → valueQuantity.unit, OBX-11 → status) |
+| AL1 | AllergyIntolerance |
+| DG1 | Condition |
+| NK1 | RelatedPerson or Patient.contact |
+| MSH, EVN | Provenance / MessageHeader (keep MSH-10 for traceability) |
+
+Code tables map through ConceptMaps; local codes need a site-specific map. Map OBX-11 `C` to Observation `status = corrected` and update the existing Observation rather than creating a new one; `D` maps to `entered-in-error`.