@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/python-testing/references/mocking.md

@@ -0,0 +1,71 @@
+# Mocking and patching in pytest
+
+Read this when a test needs to replace a dependency and the short rules in `SKILL.md` aren't enough.
+
+## Where to patch
+
+```python
+# app/http.py
+def post(url, data): ...
+
+# app/billing.py
+from app.http import post
+def charge(amount): return post("/charge", {"amount": amount})
+```
+
+- `patch("app.billing.post")` works: `charge` looks up `post` in `app.billing`.
+- `patch("app.http.post")` does nothing for `charge`, because `app.billing` already holds its own reference.
+- If the module does `import app.http` and calls `app.http.post(...)`, then patch `app.http.post`.
+
+## monkeypatch vs unittest.mock
+
+| Need | Use |
+|---|---|
+| Set or remove an env var | `monkeypatch.setenv` / `monkeypatch.delenv` |
+| Replace a function with a simple fake | `monkeypatch.setattr("app.billing.post", fake_post)` |
+| Assert how a boundary was called | `mocker.patch(...)` (pytest-mock) or `unittest.mock.patch(...)` |
+| Fake an object with a real class's signature | `create_autospec(RealClass, instance=True)` |
+| Fake an `async def` | `AsyncMock`, or `patch(..., autospec=True)` on the coroutine function |
+
+Both monkeypatch and `patch` used as a context manager or decorator undo themselves. A `patch(...).start()` without `.stop()` leaks into later tests; use `mocker` (pytest-mock) or a fixture with `yield` instead.
+
+## Asserting calls
+
+```python
+from unittest.mock import patch
+
+def test_charge_posts_amount():
+    with patch("app.billing.post", autospec=True) as post:
+        post.return_value = {"ok": True}
+        charge(500)
+    post.assert_called_once_with("/charge", {"amount": 500})
+```
+
+- A plain `Mock` raises `AttributeError` for misspelled names starting with `assert` / `assret` / `asert` / `aseert` / `assrt`. On Python before 3.12, `post.called_once_with(...)` (no `assert_`) just creates a child mock and the test passes without checking anything; 3.12 also rejects that. Autospecced mocks reject unknown attributes on every version, so prefer `autospec=True`.
+- `side_effect=Exception("boom")` to test error paths; `side_effect=[1, 2, StopIteration]` for sequences.
+
+## Fakes over mocks
+
+For repositories, caches and queues, an in-memory fake is clearer than a mock:
+
+```python
+class FakeUserRepo:
+    def __init__(self): self.users = {}
+    def get(self, uid): return self.users.get(uid)
+    def save(self, user): self.users[user.id] = user
+```
+
+Inject it through the constructor or a fixture. The test then asserts on state (`repo.users`) instead of call sequences.
+
+## HTTP
+
+- httpx: `respx` (`respx.mock` fixture or decorator) or `httpx.MockTransport`.
+- requests: `responses` (`@responses.activate`) or `requests-mock`.
+- Block accidental real calls in CI: the project's choice, for example pytest-socket's `--disable-socket`.
+
+## Common pitfalls
+
+- Patching `datetime.datetime.now` directly fails (built-in type). Inject a clock or use `time-machine` / `freezegun`.
+- `MagicMock` is truthy and returns more mocks for any attribute, so code under test can "succeed" on nonsense. Autospec, or use a fake.
+- Mocks in a `session`-scoped fixture are shared by every test; keep mocks `function`-scoped.
+- Over-mocking: if a test patches more than two or three things, test a smaller unit or use a fake.

package/skills/pytorch-patterns/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: pytorch-patterns
+description: Writes and fixes PyTorch training code, covering nn.Module and training loop structure, device and dtype placement, DataLoader setup, torch.amp mixed precision, checkpoint save and resume, seeding for reproducibility, and tracking down NaN losses and tensor shape errors. Use when building or debugging a PyTorch model, a training or evaluation loop, or a checkpoint that will not load.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python and PyTorch 2.x; GPU sections assume CUDA but the rules hold for CPU and MPS.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# PyTorch patterns
+
+Write training code that runs the same way twice, fails loudly on bad shapes, and can resume after a crash. For how to design the experiment itself (splits, baselines, metrics), use the `ml-experiment-workflow` skill instead.
+
+## 0. Before you write code
+
+1. Find the PyTorch version (`python -c "import torch; print(torch.__version__)"`) and the target device. Write for that version.
+2. Find the existing training entry point, config and data code. Extend them; do not start a second training script.
+3. **Stop and ask the user** if the target device, the metric being optimised, or the expected input shape is unclear.
+
+## 1. Structure
+
+- One `nn.Module` per model. `__init__` builds layers; `forward` only computes. No data loading, logging or `.to(device)` inside `forward`.
+- Keep three separate functions: `train_one_epoch(model, loader, optimizer, ...)`, `evaluate(model, loader)`, and a `main()` that wires config, data, model and checkpoints.
+- Put hyperparameters in one config object (dataclass, YAML, argparse). Save it next to every checkpoint.
+- Register non-trainable tensors with `self.register_buffer(...)` so they move with `.to()` and land in `state_dict`. Store sub-modules in `nn.ModuleList`/`nn.ModuleDict`, never a plain list or dict, or their parameters are invisible to the optimizer.
+
+## 2. The training step
+
+```python
+use_amp = device.type == "cuda"
+scaler = torch.amp.GradScaler("cuda", enabled=use_amp and amp_dtype == torch.float16)
+model.train()
+for x, y in loader:
+    x, y = x.to(device, non_blocking=True), y.to(device, non_blocking=True)
+    optimizer.zero_grad(set_to_none=True)
+    with torch.amp.autocast(device_type=device.type, dtype=amp_dtype, enabled=use_amp):
+        loss = criterion(model(x), y)
+    scaler.scale(loss).backward()
+    scaler.unscale_(optimizer)                      # only if clipping
+    torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm)
+    scaler.step(optimizer)
+    scaler.update()
+    scheduler.step()                                # per-step schedulers only
+```
+
+Evaluation:
+
+```python
+model.eval()
+with torch.inference_mode():
+    for x, y in loader: ...
+```
+
+Rules:
+
+- Always pair `model.train()` / `model.eval()`. Forgetting `eval()` leaves dropout on and batch norm updating running stats.
+- Log `loss.item()` (or `.detach()`) not `loss`, or you keep the whole graph alive and leak memory.
+- Call `scheduler.step()` after `optimizer.step()`. Decide once whether the scheduler steps per batch or per epoch and match the schedule's length to that.
+- For gradient accumulation, divide the loss by the number of accumulation steps and only step/zero the optimizer every N batches.
+
+## 3. Device and dtype
+
+- Pick the device once: `device = torch.device("cuda" if torch.cuda.is_available() else "cpu")` (add `"mps"` if the project targets Apple silicon). Pass it down; do not call `.cuda()` in scattered places.
+- Move the model to the device **before** creating the optimizer.
+- Create new tensors on the right device and dtype: `torch.zeros(n, device=x.device, dtype=x.dtype)`, not `torch.zeros(n).to(...)` later.
+- Classification targets for `CrossEntropyLoss` are `long` class indices of shape `(N,)` (or probabilities of shape `(N, C)`); logits are raw, no softmax first. `BCEWithLogitsLoss` takes float targets the same shape as the logits.
+
+## 4. Data loading
+
+- `Dataset.__getitem__` returns one sample; batching is the `DataLoader`'s job.
+- Training loader: `shuffle=True`, `num_workers>0`, `pin_memory=True` on CUDA, `persistent_workers=True` when `num_workers>0`, `drop_last=True` if batch norm sees tiny last batches.
+- Eval loader: `shuffle=False`, `drop_last=False`, so every sample is scored once.
+- Fit normalisation statistics, vocabularies and tokenizers on the training split only.
+- First debug step for a slow loop: time an epoch with the model step removed. If the loader alone is slow, fix the loader before touching the model.
+
+## 5. Mixed precision
+
+- Use the device-generic API: `torch.amp.autocast("cuda", dtype=...)` and `torch.amp.GradScaler("cuda")`. `torch.cuda.amp.*` is deprecated.
+- `float16` needs a `GradScaler`. `bfloat16` (Ampere-class GPUs and newer, and CPU) has float32's range and is normally run without one; pass `enabled=False` to the scaler so the loop stays the same.
+- Wrap only the forward pass and loss in `autocast`. Run `backward()` outside it.
+- Use built-in ops for precision-sensitive maths (`log_softmax`, `cross_entropy`, `mse_loss`, `binary_cross_entropy_with_logits`): autocast runs these in float32. Hand-written `exp`/`log`/sum chains get no such protection.
+
+## 6. Checkpoints
+
+Save everything needed to resume, not just the weights:
+
+```python
+torch.save({
+    "model": model.state_dict(), "optimizer": optimizer.state_dict(),
+    "scheduler": scheduler.state_dict(), "scaler": scaler.state_dict(),
+    "epoch": epoch, "step": step, "config": asdict(cfg),
+    "rng": {"torch": torch.get_rng_state(), "cuda": torch.cuda.get_rng_state_all()},
+}, tmp_path)
+os.replace(tmp_path, path)      # atomic: a crash never leaves a half-written file
+```
+
+- Load with `torch.load(path, map_location=device)`. Since PyTorch 2.6 the default is `weights_only=True`, so a checkpoint holding custom objects fails to load. Store plain types (dicts, lists, tensors, numbers) instead, or allowlist the class with `torch.serialization.add_safe_globals([...])`. Only pass `weights_only=False` for files you created yourself.
+- If the model was wrapped (`DistributedDataParallel`, `torch.compile`), save the unwrapped module's `state_dict` (`model.module` or `model._orig_mod`) so keys have no `module.` / `_orig_mod.` prefix.
+- Keep the best checkpoint (by validation metric) separate from the latest one.
+
+## 7. Reproducibility
+
+```python
+def seed_everything(seed: int):
+    random.seed(seed); np.random.seed(seed); torch.manual_seed(seed)  # seeds all devices
+```
+
+- DataLoader workers: pass `generator=torch.Generator().manual_seed(seed)` and a `worker_init_fn` that seeds NumPy and `random` from `torch.initial_seed() % 2**32`.
+- For bit-exact runs: `torch.use_deterministic_algorithms(True)`, `torch.backends.cudnn.benchmark = False`, and set the environment variable `CUBLAS_WORKSPACE_CONFIG=:4096:8` before CUDA starts. This costs speed; turn it on for debugging and comparisons, not by default.
+- Log the seed, the git commit and the library versions with each run.
+
+## 8. Debugging
+
+Read `references/debugging.md` for the full NaN and shape checklists. The short version:
+
+- **Shape errors**: print `x.shape` at each layer boundary for one batch, or assert expected shapes (`assert x.shape[1:] == (3, 224, 224), x.shape`). Watch for silent broadcasting: `(N,)` minus `(N, 1)` gives `(N, N)` without an error.
+- **NaN or inf loss**: check the input batch first (`torch.isfinite(x).all()`), then the learning rate, then the loss (log of zero, division by zero), then fp16 overflow. Turn on `torch.autograd.set_detect_anomaly(True)` for one short run to find the op that produced it; it is slow, never leave it on.
+- **Loss does not go down**: overfit a single batch of 2 to 32 samples. If the model can't drive loss near zero on one batch, the bug is in the model, loss or labels, not in the hyperparameters.
+
+## Never
+
+- Never call `model(x)` for evaluation without `model.eval()` and `inference_mode()`/`no_grad()`.
+- Never apply softmax before `CrossEntropyLoss` or sigmoid before `BCEWithLogitsLoss`.
+- Never `torch.load` an untrusted file with `weights_only=False`.
+- Never compare runs that used different seeds, data splits or eval code without saying so.
+
+## Report
+
+When you change training code, end with:
+
+```
+Changed: <files and what changed>
+Verified: <command run, e.g. one-batch overfit or 1-epoch smoke run, and its result>
+Not checked: <e.g. multi-GPU, full-length run>
+```

package/skills/pytorch-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My PyTorch training loss turns into NaN after about 300 steps, help me find out why",
+    "Add bf16 mixed precision and gradient clipping to this torch training loop",
+    "RuntimeError: mat1 and mat2 shapes cannot be multiplied (64x2048 and 512x10) in my nn.Module",
+    "Make my PyTorch checkpoints resumable, including optimizer and scheduler state",
+    "Two runs of the same torch script with seed 42 give different accuracy, make it deterministic"
+  ],
+  "should_not_trigger": [
+    "Set up a proper train/validation/test split and a baseline before we try the transformer",
+    "Review this training notebook for data leakage and wrong metrics before we publish the results",
+    "Write pytest unit tests for the Python utility module that parses CSV files",
+    "Build a retrieval pipeline that chunks our docs and stores embeddings in pgvector",
+    "Write an eval harness that scores our chatbot's answers against a golden set"
+  ]
+}

package/skills/pytorch-patterns/references/debugging.md

@@ -0,0 +1,39 @@
+# PyTorch debugging checklists
+
+Read this when a run produces NaN/inf, a shape error, or a loss that will not move.
+
+## NaN or inf loss
+
+Work top to bottom and stop at the first thing that is wrong.
+
+1. **Inputs.** For the failing batch: `torch.isfinite(x).all()`, `x.min()`, `x.max()`. Missing values in tabular data, empty images and divide-by-zero in preprocessing are the most common cause.
+2. **Labels.** Class indices must be in `[0, num_classes)`. An out-of-range label on CUDA often shows as a device-side assert; rerun on CPU, or with `CUDA_LAUNCH_BLOCKING=1`, to get a readable traceback.
+3. **Learning rate.** Drop it by 10x. If the NaN disappears, add warmup or gradient clipping (`clip_grad_norm_`) rather than keeping the smaller rate blindly.
+4. **Loss maths.** Replace hand-written `log(softmax(x))` with `log_softmax` or the built-in loss; add `eps` to denominators and to `sqrt`/`log` arguments.
+5. **Mixed precision.** Rerun with autocast disabled. If fp32 is stable, switch to bfloat16 or check that the `GradScaler` is used and that its scale is not collapsing (`scaler.get_scale()`).
+6. **Find the op.** Wrap one short run in `torch.autograd.set_detect_anomaly(True)`; the error names the backward op that produced the NaN. Or register forward hooks that assert `torch.isfinite(output).all()` per module.
+
+## Shape errors
+
+1. Print the shapes at the error line, and the shapes of the inputs to the module that raised it.
+2. Check the layer's expected layout: `Conv2d` wants `(N, C, H, W)`, `nn.Linear` acts on the last dimension, `nn.LSTM`/`nn.MultiheadAttention` default to `batch_first=False` (`(T, N, E)`).
+3. A `Linear` input-size mismatch after a conv stack: compute it from a dummy forward (`model.features(torch.zeros(1, *input_shape)).shape`) or use `nn.LazyLinear`.
+4. **Silent broadcasting.** These run without error and give wrong numbers:
+   - `pred` of shape `(N, 1)` with `target` of shape `(N,)` in `MSELoss` or arithmetic: result is `(N, N)`. PyTorch warns for `MSELoss`; it does not warn for plain arithmetic.
+   - `x.sum()` or `x.mean()` without `dim=` collapsing the batch.
+   - `view` after `permute`/`transpose` on a non-contiguous tensor raises; `reshape` silently copies. Neither is wrong, but a `view(N, -1)` over the wrong axis order scrambles data. Check with a small hand-made tensor.
+5. Add shape asserts at module boundaries in the fixed code, so the next regression fails loudly.
+
+## Loss does not decrease
+
+1. Overfit one small batch for a few hundred steps. Failure means a bug, not tuning.
+2. Check the optimizer sees the parameters: `sum(p.numel() for g in optimizer.param_groups for p in g["params"])` equals the model's trainable count.
+3. Check gradients flow: after `backward()`, every trainable parameter has a non-None, non-zero `.grad`. A `None` grad usually means a `.detach()`, `.item()`, `torch.no_grad()` or a NumPy round-trip broke the graph.
+4. Check `optimizer.zero_grad()` is called each step, and that `requires_grad` is not off on layers you meant to train.
+5. Check the labels line up with the inputs (shuffle applied to one but not the other, off-by-one in a sequence target).
+
+## Out of memory
+
+1. Log `torch.cuda.max_memory_allocated()` per step.
+2. Look for tensors kept across steps: accumulating `loss` instead of `loss.item()`, appending outputs to a list during training.
+3. Then reduce batch size with gradient accumulation, enable mixed precision, or use activation checkpointing (`torch.utils.checkpoint.checkpoint`).

package/skills/quality-nonconformance/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: quality-nonconformance
+description: Nonconformance report (NCR) and corrective and preventive action (CAPA) workflow for regulated manufacturing such as medical devices under FDA's Quality Management System Regulation (21 CFR 820, which incorporates ISO 13485:2016) and automotive suppliers under IATF 16949, covering NCR intake and severity triage, containment and quarantine, root cause analysis with 5 Whys, Ishikawa diagrams and 8D, disposition decisions (use as is, rework, repair, scrap, return to supplier), CAPA plans, and effectiveness verification before closure. Use when a part, lot or process fails a specification, a customer complaint or audit finding needs a CAPA, you are writing or fixing an NCR or CAPA procedure or tracker, or a corrective action keeps failing to stop a repeat defect.
+license: MIT
+compatibility: Any Agent Skills host. Works from the user's NCR, inspection, complaint and production records. Quotes clause numbers, not licensed standard text; the user needs their own copies of ISO 13485 and IATF 16949. Not regulatory or legal advice.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Quality nonconformance and CAPA
+
+Stop bad product reaching the customer, find the cause that actually explains the defect, fix it so it does not come back, and leave a record an auditor can follow. This skill structures the work; the organisation's quality management system (QMS) procedures and its quality and regulatory staff decide.
+
+## Boundary: when a qualified person must decide
+
+**Stop and tell the user a qualified quality or regulatory person must decide**, and do not draft a conclusion for them, when:
+
+- The defect could affect patient or user safety, or a device already shipped: field action, recall, correction or removal, and Medical Device Reporting (21 CFR 803) or reports of corrections and removals (21 CFR 806) decisions belong to regulatory affairs.
+- A disposition would ship product outside specification (use as is, concession or deviation). Automotive: the customer must authorise it in writing under IATF 16949 and the customer's own requirements.
+- A design change, validated process change, or supplier change follows from the CAPA; it needs the change control and, where required, revalidation or customer approval (for example a PPAP resubmission).
+- Anyone asks to close a CAPA without objective evidence of effectiveness.
+
+## 1. Intake: open the NCR
+
+Record, from evidence, not memory:
+
+1. What failed: part number, revision, lot or serial numbers, quantity affected and quantity inspected.
+2. Requirement violated: drawing, specification, procedure or customer requirement, with revision.
+3. Where found (incoming, in process, final inspection, customer, field, audit) and by whom, when.
+4. Objective evidence: measurements, photos, test records.
+5. Severity and risk: link to the product's risk file (ISO 14971 risk management for devices; PFMEA and control plan for automotive). A failure mode not in the risk file is itself a finding.
+
+Number every NCR, never delete one, and keep its history (records and electronic signatures under 21 CFR Part 11 if records are electronic and the site is FDA-regulated).
+
+## 2. Containment, within hours
+
+1. Quarantine and tag all suspect material: in stock, in process, in transit, at suppliers, at distribution.
+2. Define the suspect range from the last known good to the first known good, using lot traceability. If you cannot bound it, widen it.
+3. Add a 100% check or sort at the point of detection until the fix is proven, and record results.
+4. Decide whether the customer must be told now (automotive customers usually require notification; device field impact goes to regulatory per the boundary above).
+
+Containment is not correction. Record both separately.
+
+## 3. Root cause
+
+Pick the method by the problem, and check the cause against the data:
+
+- **5 Whys** for a single, clear failure chain. Each "why" must be backed by evidence. Stop at a cause the organisation can control and that, if removed, would have prevented the defect.
+- **Ishikawa (fishbone)** when several causes are possible: list candidates under Man (people), Machine, Method, Material, Measurement, Environment, then test each one with data.
+- **8D** for customer complaints, recurring or cross-functional problems, and where the customer requires it (common in automotive). Steps and the report outline are in `references/8d-and-capa.md`.
+- Use is/is-not analysis, process data, and a test that turns the defect on and off when you can.
+
+Find two causes: why it **occurred** and why it **escaped** detection. Also ask why the system allowed it (systemic cause), for example a control plan that never covered the characteristic.
+
+Never accept "operator error" or "retrain the operator" as the root cause on its own. Ask what made the error possible and prefer error-proofing (IATF 16949 expects it in problem solving).
+
+Verify measurement before blaming the process: check that the gauge is calibrated and that measurement system analysis (gauge R&R) is acceptable for that characteristic.
+
+## 4. Disposition
+
+| Disposition | Needs |
+|---|---|
+| Use as is / concession | documented justification, authorised approver, customer authorisation where required |
+| Rework (back to specification) | approved rework instruction, re-inspection, record on the lot, batch or device production record (QMSR no longer uses the term device history record) |
+| Repair (still not fully to specification) | as concession, plus customer authorisation in automotive |
+| Scrap | controlled scrapping so it cannot re-enter stock |
+| Return to supplier | supplier NCR or SCAR, replacement or credit, supplier containment |
+
+Record who decided, when, and on what evidence.
+
+## 5. CAPA
+
+1. Decide whether a CAPA is needed by your procedure's rules (for example: safety impact, recurrence, customer complaint, audit finding, trend). Not every NCR needs one; record the decision either way.
+2. Corrective action removes the cause found in section 3; preventive action removes the cause of a potential problem elsewhere (similar products, lines or suppliers). ISO 13485 treats these as separate requirements (clauses 8.5.2 and 8.5.3).
+3. Each action has an owner, due date, and the evidence that will show it is done. Actions must not adversely affect product conformity or safety; check that before implementation.
+4. Update the documents the action touches: drawings, work instructions, PFMEA, control plan, risk file, training records, supplier requirements.
+
+## 6. Effectiveness check, then close
+
+1. Define the effectiveness criteria when the CAPA is opened, not when it is closed: for example zero recurrences in the next N lots or N weeks, a capability index above target, or complaint rate below a threshold.
+2. Wait long enough to see the result, then check against the criteria with data.
+3. Not effective: reopen the root cause analysis. Do not stack new actions on an unverified cause.
+4. Close only with objective evidence and the approver your procedure names. Feed the result into management review and trend analysis.
+
+Clause references and the records auditors expect are in `references/8d-and-capa.md`.
+
+## Rules
+
+- Never back-date, edit or delete a quality record; correct with a dated, signed amendment.
+- Never close a CAPA on "action completed" alone; closure needs verified effectiveness.
+- Never ship quarantined material without a recorded disposition.
+- Do not quote standard text you do not have; cite clause numbers and tell the user to check their licensed copy.
+
+## Report
+
+```
+NCR <id> | part <pn rev> | lots <range> | qty affected <n> | found at <stage> | severity <level>
+Requirement: <spec, rev>   Evidence: <refs>
+Containment: <actions, locations, qty quarantined, sort results>
+Root cause (occurrence): <cause + evidence>   Root cause (escape): <cause + evidence>   Method: <5 Whys | Ishikawa | 8D>
+Disposition: <type, approver, customer authorisation ref>
+CAPA <id>: actions (owner, due, evidence) | effectiveness criteria | check date | result
+Needs qualified decision: <reportability, concession, change control, other>
+```

package/skills/quality-nonconformance/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Incoming inspection rejected 300 molded housings for a wall thickness out of tolerance, write the NCR and the containment plan",
+    "Our automotive customer wants an 8D for cracked brackets they found at their assembly line, help me run it",
+    "The FDA inspector flagged our CAPAs for closing without effectiveness checks, rewrite our CAPA procedure for the new QMSR",
+    "We keep getting the same burr defect even after three corrective actions, help me do a proper root cause with a fishbone",
+    "Should these out-of-spec catheter lots be reworked, scrapped or used as is, and who has to approve it?"
+  ],
+  "should_not_trigger": [
+    "Reschedule tomorrow's production after the CNC machine broke down",
+    "A customer wants to return a defective blender, set up the RMA and refund flow",
+    "Make our patient records system meet HIPAA audit logging requirements",
+    "Draft a mutual NDA with a new contract manufacturer from our standard template",
+    "Write unit tests for the function that calculates tolerance limits"
+  ]
+}

package/skills/quality-nonconformance/references/8d-and-capa.md

@@ -0,0 +1,46 @@
+# 8D steps and CAPA record checklist
+
+Read this when running an 8D, writing a CAPA procedure, or preparing CAPA records for an audit.
+
+## 8D (Eight Disciplines)
+
+| Step | Purpose | Output |
+|---|---|---|
+| D0 Plan | decide 8D is warranted, emergency response | symptom, emergency actions |
+| D1 Team | cross-functional team with process knowledge and a champion | names, roles |
+| D2 Describe the problem | what, where, when, how many, is/is-not | problem statement with data |
+| D3 Interim containment | protect the customer now | containment actions, verification |
+| D4 Root causes | occurrence and escape causes, verified | cause statements with evidence |
+| D5 Choose corrective actions | actions proven to remove each cause | selected actions, verification plan |
+| D6 Implement and validate | put actions in place, remove containment when proven | results data |
+| D7 Prevent recurrence | update systems: PFMEA, control plan, procedures, similar products | updated documents, lessons learned |
+| D8 Recognise the team | close formally | closure approval |
+
+Customers often impose their own 8D form and response times (for example containment within 24 hours, root cause within days). Use the customer's form and deadlines when they exist.
+
+## Clause map (check against licensed copies)
+
+| Topic | ISO 13485:2016 | IATF 16949:2016 (with ISO 9001:2015) |
+|---|---|---|
+| Control of nonconforming product or outputs | 8.3 (8.3.2 before delivery, 8.3.3 after delivery, 8.3.4 rework) | 8.7 and 8.7.1.x (customer authorisation for concession, rework, repair, disposition) |
+| Corrective action | 8.5.2 | 10.2 and 10.2.3 problem solving |
+| Preventive action | 8.5.3 | (ISO 9001 handles through risk-based thinking) |
+| Error-proofing | — | 10.2.4 |
+| Complaints, warranty | 8.2.2 complaint handling | 10.2.5 warranty, 10.2.6 customer complaints and field failure testing |
+| Analysis of data | 8.4 | 9.1.3 |
+
+FDA QMSR (effective 2 February 2026): 21 CFR 820 incorporates ISO 13485:2016 by reference (820.7) and adds FDA-specific requirements, including on records such as complaint and servicing records. Read the current 21 CFR 820 text on eCFR for the exact additions.
+
+## CAPA record checklist
+
+- Source (NCR, complaint, audit, trend, supplier) with link.
+- Problem statement with data and scope.
+- Investigation proportionate to risk, with root cause evidence.
+- Actions, owners, due dates, and verification that actions do not harm product safety or conformity.
+- Documents changed, with revision.
+- Training done, with records.
+- Effectiveness criteria set at opening, the check, the data, the result.
+- Approvals and dates, with signatures meeting the site's electronic records rules.
+- Link to management review and trend reports.
+
+Common audit findings: CAPAs closed without effectiveness evidence, root cause stated as "human error", overdue CAPAs with no escalation, preventive actions missing, and trend data not feeding the CAPA system.

package/skills/quarkus-patterns/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: quarkus-patterns
+description: Quarkus service conventions for ArC CDI beans, Quarkus REST (formerly RESTEasy Reactive) endpoints, Hibernate ORM with Panache, @ConfigMapping and %dev/%test/%prod profiles, Dev Services containers, GraalVM native-image limits, and @QuarkusTest or @QuarkusIntegrationTest suites. Use when writing or debugging a Quarkus application, choosing blocking versus reactive endpoints, configuring a Quarkus extension, or getting a Quarkus build to work as a native executable.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Maven or Gradle wrapper (or the Quarkus CLI). Dev Services and container tests need Docker or Podman. Native builds need GraalVM/Mandrel or a container runtime. Written for Quarkus 3.x.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Quarkus patterns
+
+Quarkus moves work to build time. Most surprises come from forgetting that: beans, config and reflection are resolved when the app is built, not when it starts. Write code that the build can see.
+
+## 0. Before you start
+
+1. Read the Quarkus version and extensions from `pom.xml` (`quarkus-bom`) or `build.gradle(.kts)`. Note whether the project uses `quarkus-rest` (Quarkus REST) or the legacy `quarkus-resteasy` (Classic). **Never mix** `quarkus-rest*` and `quarkus-resteasy*` extensions; that causes duplicate-implementation startup errors.
+2. Find the build and test command: `./mvnw verify`, `./gradlew build`, or `quarkus build`. Run tests once and record the result; stop and tell the user if they already fail.
+3. Add extensions with `./mvnw quarkus:add-extension -Dextensions="..."` or `quarkus ext add ...`, not by guessing artifact ids.
+
+## 1. CDI (ArC)
+
+- Default to `@ApplicationScoped` for services. Use `@Singleton` only when you need no client proxy, and `@RequestScoped` for per-request state.
+- Use constructor injection; a single constructor needs no `@Inject`. Package-private field injection also works without reflection, but private field injection forces reflection; avoid it.
+- ArC discovers beans at build time. A class in a dependency jar without a Jandex index is invisible; add the index (`jandex-maven-plugin`) or `quarkus.index-dependency.*` config.
+- Unused beans are removed at build time. If a bean is only looked up programmatically, mark it `@Unremovable`.
+- Produce third-party objects with `@Produces` methods in an `@ApplicationScoped` class.
+- Use `@Startup` or `void onStart(@Observes StartupEvent ev)` for startup work; keep it fast.
+
+## 2. REST endpoints (Quarkus REST)
+
+- Resources use Jakarta REST annotations: `@Path`, `@GET`, `@POST`, `@Produces`, `@Consumes`. Add `quarkus-rest-jackson` (or `-jsonb`) for JSON.
+- **Threading rule**: a method returning a plain type or `Response` runs on a worker thread and may block. A method returning `Uni` or `Multi` runs on the event loop and **must never block** (no JDBC, no `Thread.sleep`, no blocking HTTP). Use `@Blocking` or `@NonBlocking` to override when needed. Blocking on the event loop logs a "blocked thread" warning; treat it as a bug.
+- Pick one model per service. Hibernate ORM (blocking) with plain return types is the simple default; use Hibernate Reactive with `Uni` only when the project already does.
+- Return DTO records, not entities. Validate input with `quarkus-hibernate-validator` and `@Valid`.
+- Map exceptions to responses with `@ServerExceptionMapper` methods (or an `ExceptionMapper`). Never leak stack traces.
+- Call other services with the REST client: an interface annotated `@RegisterRestClient(configKey = "orders-api")`, injected with `@RestClient`, base URL in `quarkus.rest-client.orders-api.url`.
+
+## 3. Panache
+
+- Choose one style per project and keep it:
+  - **Active record**: `class Order extends PanacheEntity` (gives a `Long id`), static finders like `Order.find("status", s).list()`.
+  - **Repository**: `class OrderRepository implements PanacheRepository<Order>`, injected into services. Easier to mock.
+- Panache entities use public fields; Quarkus rewrites access into getters and setters at build time.
+- Writes need a transaction: annotate the service or resource method with `@Transactional` (`jakarta.transaction`). Reads outside a transaction work but lazy loading after the method returns fails.
+- Page large queries: `find(...).page(Page.of(index, size))`. Never `listAll()` on a table that grows.
+- The fetch, N+1 and locking rules in the `jpa-hibernate` skill apply here too.
+
+## 4. Configuration and profiles
+
+- Group related settings in an interface with `@ConfigMapping(prefix = "payments")`; use `@ConfigProperty(name = "...")` only for one-off values. Missing required values fail startup, which is what you want.
+- Profiles prefix keys: `%dev.`, `%test.`, `%prod.` in `application.properties`, or `application-{profile}.properties`. A custom profile is set with `quarkus.profile`.
+- Know the two kinds of config: **build-time** properties (marked with a lock in the config reference, such as `quarkus.datasource.db-kind`) are fixed when you build and can't be changed by environment at runtime. Runtime properties can be set by env vars (`QUARKUS_DATASOURCE_JDBC_URL`).
+- Secrets come from environment variables or a config source like Vault or Kubernetes secrets, never committed properties.
+
+## 5. Dev Services
+
+- With an extension such as `quarkus-jdbc-postgresql` and **no** URL configured, dev and test mode start a container automatically. Don't configure `%dev`/`%test` datasource URLs unless you want to opt out.
+- Set `quarkus.datasource.devservices.image-name` to match the production database version.
+- Dev Services never runs in prod. Production config must set real URLs and credentials.
+- Use `quarkus dev` (or `./mvnw quarkus:dev`) for live reload and the Dev UI at `/q/dev-ui`.
+
+## 6. Native image constraints
+
+Build with `./mvnw install -Dnative`, `./gradlew build -Dquarkus.native.enabled=true`, or `quarkus build --native`. Add `-Dquarkus.native.container-build=true` when no local GraalVM is installed. Native code is closed-world:
+
+- Reflection, dynamic proxies and resources must be known at build time. Register classes used only reflectively (for example DTOs serialised by a library Quarkus doesn't know) with `@RegisterForReflection`; include resource files with `quarkus.native.resources.includes`.
+- Static initialisers run at build time by default. Code that reads the clock, randomness, env vars or opens connections in a static block must be moved to runtime init.
+- Prefer Quarkus extensions over plain libraries; extensions carry the native configuration.
+- Run `@QuarkusIntegrationTest` against the native build. Passing JVM tests prove nothing about native.
+- **Stop and ask the user** before switching a project to native: builds are slow and memory-hungry, and some libraries won't work.
+
+## 7. Testing
+
+- `@QuarkusTest` starts the app once per test run in JVM mode, with Dev Services, on the `test` profile. Use REST Assured (`given().when().get("/orders/1").then().statusCode(200)`).
+- `@QuarkusIntegrationTest` runs the packaged artifact (jar, native binary or container) as a black box; it can't inject beans.
+- Mock beans with `@InjectMock` (needs `quarkus-junit5-mockito`); it works for normal-scoped beans like `@ApplicationScoped`; a `@Singleton` bean can only be mocked with `@MockitoConfig(convertScopes = true)`, which changes its scope in the test, so prefer making the bean `@ApplicationScoped`. Beans used during startup are not mocked. Use `@TestProfile` for different config; each profile restarts the app, so use few.
+- Use `@TestTransaction` to roll back database changes after each test.
+- Use a test resource (`@QuarkusTestResource`, or `@WithTestResource` to group tests by resource) only for dependencies Dev Services can't provide.
+
+## Never
+
+- Blocking calls inside a `Uni`/`Multi` method or on the event loop.
+- `quarkus-rest` and `quarkus-resteasy` in the same build.
+- Private field injection or reflection-heavy libraries in a native build without registering them.
+- Hard-coded datasource URLs in `%dev`/`%test` that disable Dev Services by accident.
+
+## Before you finish
+
+Run the tests (and `-Dnative` integration tests if the project ships native). Report: extensions added, config keys and which profile they apply to, threading model of new endpoints, tests added, and the final test counts.

package/skills/quarkus-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Build a Quarkus REST endpoint backed by Panache and make it compile to a native image",
+    "Quarkus logs 'You have attempted to perform a blocking operation on an IO thread' in my Uni endpoint",
+    "How do Dev Services in Quarkus start Postgres for tests, and why did it stop after I set a JDBC url?",
+    "Set up %dev and %prod profiles with @ConfigMapping in our Quarkus microservice",
+    "My Quarkus native executable fails at runtime with a ClassNotFoundException for a Jackson DTO",
+    "Use @InjectMock in a @QuarkusTest to replace the payment client bean"
+  ],
+  "should_not_trigger": [
+    "Add a new REST endpoint to our Spring Boot order service with request validation and proper 404 responses",
+    "Write a Ktor route for uploading files with coroutines",
+    "Add a Flyway migration that adds a NOT NULL column to the orders table without downtime",
+    "Write the Dockerfile and Kubernetes deployment for our Java service",
+    "Explain idiomatic Java records and sealed interfaces for our domain model",
+    "Our Gradle build fails with a dependency resolution conflict in the Java module"
+  ]
+}