fdeops 3.11.1 → 3.15.0

package/skills/fde/references/build.md

@@ -1,154 +0,0 @@
-# build - safe implementation on someone else's codebase
-
-**Enter when:** an agreed slice is ready to implement - feature, fix, integration, legacy change. Includes the review gate before merge.
-
-**Read first:** `context.md`, `terrain.md`, `decisions.md`. Load `trust-profile.md` when touching regulated areas. No map or no plan → route to discover/plan first; say it plainly: "We're not ready to touch code until we know what's connected to this module."
-
-## Validation gate (confirm understanding, clarify where it elevates)
-
-Before starting, state what you're working with in 2-4 lines - a brief playback that invites correction, not a question:
-
-> "Building: [task name]. Blast radius: [files/systems]. Terrain is [X days] fresh. [Any risk or concern worth naming, or 'clear to proceed']."
-
-Then check - probe ONLY if it prevents a mistake:
-
-1. **Acceptance criteria are falsifiable.** If the criteria are vague ("should work well", "handle errors gracefully") → rephrase them specifically: "I'm reading 'works well' as: responds in <500ms, retries 3x, alerts on failure. That right?"
-2. **Terrain is current.** If terrain.md is significantly older than the plan → one line: "Terrain is from Day 3, plan from Day 8 - assuming nothing shifted in between."
-3. **No open CRITICAL risk on the module.** If found → name it: "There's an open risk on this module (rate limiting). Building around it unless you say otherwise."
-
-Don't interrogate. State your read, let the FDE correct if needed, then move.
-
-## Spec generation (AI generates, human approves)
-
-Before writing code, generate the implementation spec for this task and present it to the FDE:
-
-```
-Spec: [task name from decisions.md]
-Inputs: [what triggers this - event, request, user action, data shape]
-Outputs: [what the user/system sees when it works]
-Accepts:
-  - [scenario 1: specific testable outcome]
-  - [scenario 2: specific testable outcome]
-Edge cases:
-  - [boundary condition]: [what happens]
-  - [error scenario]: [what happens]
-Constraints: [performance, security, compliance bounds from trust-profile.md]
-```
-
-Present this to the FDE: "Here's what I'm about to build. Any open questions or changes before I start?"
-
-- FDE says "yes" / "go" / "approved" → build against the spec exactly
-- FDE modifies → update spec, confirm, then build
-- Fast-track: if the task is under 30 minutes and the FDE has established trust (week 2+), state the spec inline and proceed unless they object
-
-The spec becomes the test list - every line is something to verify after build.
-
-## The loop (you do this work, in this order)
-
-1. **Confirm scope in writing.** The task exists in `decisions.md` with acceptance criteria. Not there → plan first or name the scope creep.
-2. **Declare blast radius.** Read the full dependency chain of what you're about to change. State: which files, which users, which systems. The change that breaks something always looked small.
-3. **Confirm the rollback path exists** before writing a line. "We can always revert" is not a rollback path.
-4. **Legacy code: characterisation tests first.** Tests for what the code *actually does right now* - including the parts that seem wrong; those behaviours are the contract the system depends on. Then wrap with Strangler Fig: new interface around old code, deprecate gradually, never rewrite in place.
-5. **Search before creating.** Read the existing code in the area; don't add parallel helpers where a service exists. Integrating an SDK/vendor API → read real source (local `reference/repos/...` or official repo) before guessing names; record the files used in `decisions.md`. If an API looks invented, stop and search source.
-6. **Build the minimal working path.** Thin vertical slice the customer can see. No opportunistic refactors. Every changed line traces to the task.
-7. **Verify with evidence.** Run tests/typechecks/smallest proving script. State what ran and what didn't. "Seems right" is never evidence.
-8. **Convergence check (spec vs. reality).** Walk through every acceptance scenario and edge case from the spec. State each one explicitly with its result:
-   - `[PASS]` scenario verified with evidence
-   - `[FAIL]` scenario not met - fix before proceeding
-   - `[DEFERRED]` intentionally left for a later task (state which one)
-   Surface the results to the FDE. If any scenario fails, fix it before cleanup. This is not optional - the spec is the contract.
-9. **Cleanup pass after it works.** Dedupe repeated mechanics into the smallest service module; behavior unchanged; re-run the same tests. If you wrote 200 lines and 50 would do, rewrite before review.
-10. **Review gate (before merge):** three beats, in order - (a) **session digest**: TL;DR + decisions/why + scope/verification into `.fde/` so the PR carries thinking, not just code (memory contract On exit; see `review.md`); (b) **intent vs diff**: every path KEEP / JUSTIFY / SPLIT / DROP against the stated slice in `decisions.md` (see `review.md` Stage 1); (c) **safety**: blast radius honest, tests meaningful, rollback real, secrets absent. Fix real findings, re-verify, repeat until clean or blocked on a human decision.
-11. **Log and deliver.** Update the artifacts (below). Visible progress beats invisible perfection - every 2–3 tasks something shown to a stakeholder.
-
-**Touching existing code - classify before changing:**
-- **Fix now:** actively failing or blocking.
-- **Fix when touched:** will bite when surrounding code changes - fix as part of this change.
-- **Document and leave:** ugly but uninvolved. The hardest discipline. Opportunistic refactors create diffs nobody asked for and regressions nobody expected.
-
-**AI components:** build the fallback path *before* the AI path (model slow? garbage? down?). Add observability before deploy: log inputs, outputs, confidence - hallucinations don't throw exceptions. Confirm the data processing agreement covers customer data before it goes to an external model; in regulated environments this is a blocker, not a detail.
-
-**Regulated environments:** check the AI code policy in `trust-profile.md` first. Some modules require human review of AI-generated code or prohibit it. Find out before building, not after showing the code.
-
-## Mid-build scope requests
-
-"Also can you add…" → "That's worth looking at - let me place it." Current phase, future phase, or separate engagement? If it's outside `success.md`, name it: "Outside what we agreed; future phase or rescope conversation." Absorbed scope sets the precedent that the boundary doesn't exist - and in commercial engagements it silently moves billing and liability. Surface it to whoever owns the commercials.
-
-## Method - integration design (connecting systems)
-
-FDEs spend 40%+ of build time on integrations. Connecting system A to system B is where projects die quietly - wrong assumptions about APIs, missing auth, schema mismatches, rate limits.
-
-**The integration checklist (before writing code):**
-
-1. **Contract first.** Define what crosses the boundary: request shape, response shape, error shape. Write it down before calling anything. An undocumented contract changes without warning.
-2. **Auth model.** OAuth2, API key, mTLS, SAML? Who provisions the credential? Who rotates it? What's the expiry? One expired token at 2am = production down.
-3. **Rate limits and quotas.** Every external API has them, most aren't documented. Test with a burst early - don't discover the 429 on launch day.
-4. **Error taxonomy.** Retryable (timeout, 503) vs. fatal (401, 422). Build retry with exponential backoff for the first, circuit-breaker for the second.
-5. **Data transformation.** Their schema ≠ your schema. Map fields explicitly. Null handling rules. Timezone assumptions. Currency/locale. One unmapped field = silent data corruption.
-6. **Idempotency.** Can you safely retry? If not, you need deduplication. Double-charges, double-posts, double-notifications - all integration bugs.
-7. **Observability at the boundary.** Log every outbound call: request (redacted), response code, latency. The integration is the first thing to blame and the last thing instrumented.
-
-**The integration contract template (write to `decisions.md`):**
-```
-Integration: [System A] → [System B]
-Direction: push / pull / bidirectional
-Auth: [method] - provisioned by [who] - expires [when]
-Rate limit: [n] req/[period]
-Retry: [strategy]
-Data mapping: [field map or link to schema]
-Failure mode: [what happens when B is down]
-Owner: [who gets paged]
-```
-
-## Method - team amplification (making their engineers better)
-
-The FDE's job is to make themselves replaceable. Not at handoff - every day. A client team that can only ship when the FDE is present is a dependency, not a success.
-
-**Daily practices:**
-- **Pair, don't take over.** When a client engineer is stuck, pair for 30 minutes rather than solving it alone in 10. The 10-minute fix creates dependency; the 30-minute pair creates capability.
-- **Review their PRs with teaching intent.** Not "fix this" - "here's why this approach creates risk, and here's the pattern I'd use instead." Link to their own codebase for examples, not external docs.
-- **Make decisions visible.** When you make an architecture choice, write a 3-line rationale in `decisions.md`. The team sees your reasoning, not just your output.
-- **Name patterns, not just fixes.** "This is a circuit breaker pattern - here's when to use it again" converts one fix into a reusable skill.
-
-**Weekly practices:**
-- **One 30-min knowledge session per week.** Not a lecture - pick the hardest thing you built this week, walk through the thinking with the team. Answer: "why this approach and not the obvious one?"
-- **Track the team's solo wins.** When a client engineer ships without FDE help, note it. This is the metric that proves the engagement is working.
-
-**The independence signal:** When the team stops asking "how should we do X?" and starts asking "we're thinking X because Y - does that sound right?" - the engagement is succeeding.
-
-## Stop signals - reassess immediately
-
-- "I'll add tests after this works" - the regression is already in.
-- "Small change, no need to declare blast radius" - famous last words.
-- "I'll refactor this while I'm here" - unasked-for risk in an unrelated change.
-- **Three fixes in and still broken - the diagnosis is wrong.** No fourth fix: state your current model of the problem, name the evidence that would disprove it, test that first (see `debug.md`).
-
-## Artifact (logged as you go, not after)
-
-- **`decisions.md`** - each significant choice: what, alternatives considered, why this one. For non-trivial architecture decisions, present three options to the FDE (safe / pragmatic / aggressive) with costs and a recommendation - three options is a real decision; one option is a request for trust. Integration contracts go here too.
-- **`risks.md`** - new risks discovered while building.
-- **`delivery.md`** - append a **value ledger** row for every ship: Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback. Bucket is `cost-save` / `risk-mitigation` / `revenue-uplift`. "Measured" may be `pending` until the pulse exists - never skip the promised column. Narrative under Shipped is optional color; the ledger is the record status and close read.
-
-  **Measured is not the same as accepted.** A number the FDE calculated is `claimed` until a named customer-side owner agrees it is real - their finance lead, their ops manager, the person whose budget it moves. Write the name and the date in **Accepted by**; leave it empty and the row reads `claimed`, never "delivered". This is the difference between a benefit that survives the renewal conversation and one the sponsor's CFO deletes in the review.
-
-## Checkpoint
-
-Before merge: the two-stage review (scope, then safety) has run clean, verification evidence is stated, and the slice is demonstrable. If `trust-profile.md` requires human sign-off on AI-generated code, that sign-off exists.
-
-## Worked example
-
-Acme task 1: route reconciliation failures to a named on-call.
-
-Characterisation first — a test that captures what the job does *today* when it exits non-zero (silently succeeds from the caller's perspective). That test fails after the fix, which is the point: it documents the behaviour being changed rather than trusting the diff.
-
-Mid-build, Tom asks to "just also fix the retry logic while you're in there." That is a scope decision, not a request: logged in `decisions.md` with the blast radius (retry touches the settlement path — not in this slice's declared radius) and routed to the plan's Next lane.
-
-Ledger row on ship: `Jun 18 | failure routing | risk-mitigation | 4h → 15min detection | pending | — | staging kill test, PR #212 | disable alert route`. **Accepted by** stays empty until Marco confirms from a real incident — until then the number is claimed, and the status update says so.
-
-## Principles
-
-- Characterisation tests before modification. Every time.
-- Blast radius declared before every change; rollback confirmed before every deploy.
-- Scope creep is a decision, not a request. Name it.
-- Build the fallback before the AI feature.
-- Small diffs, objective verification, no thousand-line hope PRs.

package/skills/fde/references/debug.md

@@ -1,55 +0,0 @@
-# debug - systematic, never guessing
-
-**Enter when:** something is broken, can't be reproduced, or "shouldn't be happening" - and production is NOT down (that's `rescue.md`).
-
-**Read first:** `context.md`, `terrain.md`, `chaos-log.md` (if this happened before, the cause is probably the same). Nothing else - noise kills focus.
-
-Debugging on an engagement differs from debugging your own code: no full context, no history, high pressure to "just fix it." That pressure causes the second incident. The sequence below is the protection.
-
-## Method (you do this work - never skip a step)
-
-**1. Reproduce.** Get a consistent repro before looking at any code. Can't reproduce → instrument first (logging, narrowing) - not fixes. An unreproducible bug that gets "fixed" comes back.
-
-**2. Isolate to the smallest failing case.** Strip everything that isn't the failure. Payment flow bug → does one hard-coded test transaction fail? Smallest case = smallest context = smallest blast radius for the fix.
-
-**3. Ask "what changed?" before reading code.** Last 2 hours, 24 hours, last deploy - this one question solves most production bugs:
-```bash
-git log --since="48 hours ago" --format="%ad %an %s" --date=relative
-git log --stat -5 --format="%h %s"   # works on any history depth
-```
-Don't read the codebase like a book. Write a script that answers one specific question - one execution, one answer.
-
-**4. One hypothesis.** Not three. State it explicitly:
-> "Hypothesis: X. If right, changing Y fixes it. If wrong, the symptom persists."
-A hypothesis that can't be falsified isn't one.
-
-**5. Fix the root cause, not the symptom.** A 500 is a symptom; an NPE is a symptom; the cause is upstream. Patch the symptom and you're back in a week.
-
-**6. Verify the fix holds.** Repro case passes; tests covering the changed code + downstream callers green; no new errors in logs for N minutes. Define done *before* declaring it - "seems fixed" requires another cycle.
-
-## Talking to the customer mid-debug (you coach)
-
-They'll ask for status before there is one. The FDE gives: what's narrowed, what's ruled out, what's being tested next, and **a specific time** they'll hear back. Proactive update if past that time - never make them chase. Skip the phrases that add heat: "weird one," "never seen this," "might be…". Partial clarity beats raw uncertainty. Fixed without root cause → stabilise honestly, don't close the story until the why is explainable.
-
-## Artifact
-
-**`chaos-log.md`** - append, same day:
-```markdown
-## <date> - <symptom>
-**Root cause:** <not the symptom>
-**What changed to fix it:** <change>
-**Hypotheses tested:** <in order, results>
-**Recurrence risk:** <where this can happen again>
-```
-Update `terrain.md` if the investigation disproved something the map claimed.
-
-## Checkpoint
-
-Before closing: repro passes, root cause stated in one sentence, chaos log written. If the root cause is still unknown, the incident stays open - say so.
-
-## Principles
-
-- Reproduce before touching anything. Always.
-- "What changed?" is the first question, not the last.
-- One hypothesis at a time. Three fixes failed = wrong mental model - stop.
-- Fix upstream. Symptoms patched are incidents scheduled.

package/skills/fde/references/observability.md

@@ -1,103 +0,0 @@
-# observability - if you can't see it running, you can't operate it
-
-**Enter when:** shipping a feature to production, the customer says "we don't know when things break," a post-incident review revealed gaps in monitoring, or the handoff needs the team to operate what was built.
-
-**Read first:** `terrain.md`, `delivery.md`, `context.md`. Load `trust-profile.md` if the data flowing through logs contains sensitive information.
-
-Code without observability is code you can't operate. The FDE who ships a feature without telemetry creates a callback in six weeks when it breaks and nobody can tell why. Observability is built alongside the feature, not after - the same way tests are.
-
-## Method (you do this work)
-
-**1. Define "working" before instrumenting.** Write 2–4 questions that the person on call will ask about this feature:
-
-```
-FEATURE: payment retry logic
-QUESTIONS ON-CALL WILL ASK:
-1. What fraction of payments succeed on first attempt vs after retry?
-2. When a payment fails permanently, why? (provider error? timeout? validation?)
-3. Is the payment provider slower than usual?
-4. Are retries causing duplicate charges?
-→ Every signal below must help answer one of these.
-```
-
-If you can't name the questions, you're not ready to instrument - you'll log everything and learn nothing.
-
-**2. Pick the right signal for each question:**
-
-| Signal | Answers | When to use |
-|--------|---------|-------------|
-| **Structured log** | "What happened in this specific case?" | Individual request debugging, audit trails |
-| **Metric** | "How often / how fast, in aggregate?" | Dashboards, alerting, trend detection |
-| **Trace** | "Where did time go across services?" | Cross-service latency, bottleneck identification |
-
-Rule of thumb: metrics tell you **that** something is wrong, traces tell you **where**, logs tell you **why**.
-
-**3. Structured logging - events, not prose.**
-
-```
-BAD:  logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`)
-      → Unqueryable, inconsistent format, buried in noise
-
-GOOD: logger.info({ event: "payment_failed", payment_id: id, user_id: userId,
-        retry_count: n, error_code: "PROVIDER_TIMEOUT", duration_ms: elapsed })
-      → Queryable, alertable, structured for dashboards
-```
-
-Every log line: a stable event name + machine-readable fields. Human-readable messages are for debugging sessions; structured events are for production operations.
-
-**4. The four metrics every FDE feature needs:**
-
-| Metric | What it measures | Alert threshold |
-|--------|-----------------|-----------------|
-| **Error rate** | Failures / total requests | >2x baseline for 5 minutes |
-| **Latency (p95/p99)** | How long the operation takes | >2x normal for 5 minutes |
-| **Throughput** | Requests per second/minute | <50% of normal for 10 minutes (demand drop = upstream problem) |
-| **Business metric** | The thing the feature is supposed to improve | Direction reverses for 1 hour |
-
-The business metric is the one most FDEs skip and the one the sponsor cares about most. "Error rate is fine" means nothing if payments processed per hour dropped.
-
-**5. Alert design - avoid noise, ensure action:**
-
-| Principle | How |
-|-----------|-----|
-| **Every alert has an owner** | If nobody is named, nobody responds |
-| **Every alert has a runbook** | "Error rate spiked" → "Check these three things in this order" |
-| **Severity maps to response time** | Critical: 15 min. Warning: next business day. Info: weekly review. |
-| **No alert without action** | If the response is "ignore it" three times, delete the alert |
-
-**6. AI component observability.** AI features fail differently - they degrade, they don't crash:
-
-| What to observe | Why |
-|----------------|-----|
-| Model input/output pairs (sampled, privacy-respecting) | Detect drift: outputs changing without code changing |
-| Latency per model call | Provider degradation is gradual, not binary |
-| Fallback activation rate | If fallback fires >5%, the primary path has a problem |
-| Confidence/quality score trend | A score that slowly drops = model drift |
-| Token usage / cost per request | Cost creep is invisible until the bill arrives |
-
-**7. The sacred-data boundary.** Before shipping any observability:
-
-- Check `trust-profile.md` for `<private>` tagged data.
-- PII in logs = a breach, not a debug aid. Mask, hash, or exclude.
-- In healthcare: PHI in logs violates HIPAA. In fintech: PANs in logs violate PCI-DSS.
-- Default: log IDs, not values. `user_id: 12345` not `user_email: jane@...`
-
-## Artifact
-
-**`delivery.md`** - under each shipped feature: what's observable, where to look, alert thresholds, the runbook.
-
-**`handoff.md`** (when close approaches) - the on-call guide: "what each alert means and what to do."
-
-**`risks.md`** - if observability gaps were found in existing code: what's unobserved and the risk it carries.
-
-## Checkpoint
-
-Before marking a feature shipped: the four metrics are emitting, alerts have owners and runbooks, sacred data is not in logs. If any gap: "Observability incomplete - <specific gap> - shipping without it means <specific risk>."
-
-## Principles
-
-- Define the questions before choosing the signals. Unquestioned telemetry is noise.
-- Metrics for detection, traces for location, logs for explanation.
-- Every alert has an owner and a runbook, or it's noise.
-- AI features need observability for drift, not just failures.
-- PII in logs is a breach. Default to IDs, not values.

package/skills/fde/references/qa-live.md

@@ -1,113 +0,0 @@
-# qa-live - test it like a user, not like an engineer
-
-**Enter when:** a feature is built and needs to be verified from the user's perspective, the team says "it works on my machine," a demo is coming and the feature hasn't been clicked through, or a post-deploy smoke test is needed.
-
-**Read first:** `delivery.md` (what was built), `decisions.md` (acceptance criteria), `success.md` (what the customer expects to see), `context.md`.
-
-Unit tests prove the code works. QA proves the *feature* works - from the user's chair, on a real browser, with real data patterns. The FDE who ships a feature that passes all tests but fails the first user click has shipped a defect.
-
-## Method (you do this work)
-
-**1. Write the test script from the user's story, not the code.**
-
-Start with `success.md` and `decisions.md` acceptance criteria. For each acceptance criterion, write the human steps:
-
-```markdown
-## Test: User can retry a failed payment
-Precondition: User has a failed payment in their history
-Steps:
-  1. Navigate to payment history
-  2. Click the failed payment
-  3. Click "Retry payment"
-  4. Confirm the retry dialog
-  5. Observe the result
-Expected: Payment processes successfully, status updates to "Completed"
-Also check: Error message if retry fails, loading state during processing
-```
-
-**2. The five perspectives.** Test each feature from five angles that unit tests can't reach:
-
-| Perspective | What to test | Common FDE finding |
-|------------|-------------|-------------------|
-| **Happy path** | Does the main flow work end-to-end? | Works locally, fails with real data volumes |
-| **Error path** | What happens when things go wrong? | Error messages are developer-facing, not user-facing |
-| **Edge cases** | Empty states, max lengths, special characters, concurrent users | The empty state shows "undefined" instead of a helpful message |
-| **Performance** | Is it fast enough for real use? | Works fine with 10 records, unusable with 10,000 |
-| **Accessibility** | Can it be used with keyboard only? Does the screen reader make sense? | Tab order is broken, focus traps in modals |
-
-**3. Real browser testing.** Open the actual application in a browser and click through:
-
-```
-Before each test:
-  - Clear relevant caches/state
-  - Use realistic test data (not "test test test")
-  - Note the browser and viewport size
-
-During each test:
-  - Open DevTools console - watch for errors
-  - Open DevTools network tab - watch for failed requests
-  - Time the critical actions (user-perceivable latency)
-
-After each test:
-  - Screenshot the result (before/after when relevant)
-  - Note any console errors even if the test "passed"
-  - Note any UX friction even if technically correct
-```
-
-**4. The health score.** Rate the feature across five dimensions, 1–5:
-
-| Dimension | 1 (broken) | 3 (acceptable) | 5 (polished) |
-|-----------|-----------|----------------|--------------|
-| **Functionality** | Critical path fails | Happy path works, errors unhandled | All paths work, errors graceful |
-| **Performance** | >5s load time | <2s load time | <500ms load time, no layout shifts |
-| **Error handling** | Crashes or shows stack trace | Shows error message | Shows actionable error with recovery option |
-| **Data handling** | Corrupts or loses data | Handles normal data correctly | Handles edge cases (empty, large, special chars) |
-| **User experience** | Confusing or broken layout | Functional but rough | Intuitive, consistent with the rest of the app |
-
-**Overall health = average of five scores.** Below 3.0 → not ready to ship. 3.0–4.0 → shippable with known issues. 4.0+ → confident to demo.
-
-**5. The bug report format.** For each issue found:
-
-```markdown
-## Bug: <one-line summary>
-Severity: critical / high / medium / low
-Steps to reproduce:
-  1. <exact steps>
-  2. <exact steps>
-Expected: <what should happen>
-Actual: <what happened>
-Evidence: <screenshot, console error, network request>
-Environment: <browser, viewport, data state>
-```
-
-**6. Re-verify after fixes.** After each bug is fixed:
-- Re-run the exact reproduction steps
-- Check that the fix didn't break adjacent functionality
-- Update the health score
-- Screenshot the fixed state
-
-## Artifact
-
-**`delivery.md`** - the health score and test results for each shipped feature:
-```markdown
-## QA: <feature name> - <date>
-Health score: 4.2 / 5.0
-Tests run: 8 passed, 1 failed (fixed), 1 known issue (low severity)
-Bugs found: 2 (1 fixed, 1 deferred to next sprint)
-Ready to demo: YES / NO
-```
-
-**`decisions.md`** - bugs deferred with rationale (why it's acceptable to ship with this known issue).
-
-## Checkpoint
-
-One line: "Feature tested from user perspective. Health score: <N>/5. <N> bugs found, <N> fixed, <N> deferred. Ready to demo: yes/no." If not ready: the specific blocker.
-
-## Principles
-
-- Test from the user's chair, not the developer's IDE.
-- Real browser, real data patterns, real network conditions.
-- Console errors during a "passing" test are still findings.
-- Health score below 3.0 = not ready to ship, regardless of test suite.
-- Every bug gets a reproduction recipe, not a description.
-- A feature that passes all unit tests but fails the first click is a defect.

package/skills/fde/references/security-audit.md

@@ -1,105 +0,0 @@
-# security-audit - find the holes before someone else does
-
-**Enter when:** the engagement touches auth, payments, user data, or external integrations; the customer mentions compliance (SOC2, PCI, HIPAA); a new API endpoint is being shipped; or the FDE is asked "is this secure?"
-
-**Read first:** `trust-profile.md` (data classification, AI policy, compliance requirements), `terrain.md`, `context.md`. Load the relevant regulated overlay (fintech/healthcare/gov) if the signal is present.
-
-On an FDE engagement, security mistakes are twice as dangerous: you break someone else's system, with their users' data, under their compliance obligations. The FDE who finds the vulnerability before production earns trust that lasts the entire engagement.
-
-## Method (you do this work)
-
-**1. Threat model in five minutes.** Not a ceremony - five questions before looking at code:
-
-| Question | What it reveals |
-|----------|----------------|
-| Where does untrusted data enter? | HTTP requests, file uploads, webhooks, LLM outputs, message queues |
-| What's worth stealing? | Credentials, PII, payment data, API keys, session tokens |
-| What's worth breaking? | Auth system, payment flow, admin actions, data integrity |
-| Who's the attacker? | External (internet), internal (employee), adjacent (other tenant), automated (bot) |
-| What's the worst realistic outcome? | Data breach, financial loss, regulatory fine, reputation damage |
-
-Write the answers before scanning code. The threat model tells you where to look; code scanning without a threat model is reading every room in a building instead of checking the doors.
-
-**2. The STRIDE pass.** For each trust boundary (where data crosses from untrusted to trusted):
-
-| Threat | Check | Common FDE finding |
-|--------|-------|-------------------|
-| **Spoofing** | Can someone impersonate a user/service? | Missing auth on internal endpoints ("it's behind the VPN" is not auth) |
-| **Tampering** | Can data be altered in transit or at rest? | Unparameterised SQL, unsigned webhooks, client-side validation as sole gate |
-| **Repudiation** | Can an action be denied later? | No audit log on admin actions, no timestamp on state changes |
-| **Information disclosure** | Can data leak? | Stack traces in production errors, PII in logs, verbose error messages |
-| **Denial of service** | Can it be overwhelmed? | No rate limiting on auth endpoints, unbounded file uploads, no pagination |
-| **Elevation of privilege** | Can a user gain access they shouldn't? | IDOR (changing user ID in URL), missing role checks on endpoints |
-
-**3. The automated scan.** Run these - they catch what manual review misses:
-
-```bash
-# Secrets in code (repeat --include per extension)
-grep -rnE "(api[_-]?key|secret|password|token|private[_-]?key)\s*[:=]\s*['\"][^'\"]{8,}" \
-  --include="*.js" --include="*.ts" --include="*.py" --include="*.env" \
-  --include="*.yaml" --include="*.json" . | grep -vE "example|template|test|mock" | head -20
-
-# Dependency vulnerabilities
-npm audit 2>/dev/null || pip audit 2>/dev/null || echo "no package audit available"
-
-# SQL injection patterns
-grep -rnE "(SELECT|INSERT|UPDATE|DELETE).*\+.*\"|f['\"].*{.*}.*SELECT" \
-  --include="*.js" --include="*.ts" --include="*.py" . | head -10
-
-# Dangerous patterns
-grep -rnE "eval\(|innerHTML\s*=|document\.write\(|exec\(|__import__" \
-  --include="*.js" --include="*.ts" --include="*.py" . | head -10
-```
-
-**4. The AI security check.** If the system uses AI/LLM components:
-
-| Check | Finding if yes |
-|-------|---------------|
-| Is model output used in SQL, shell commands, or HTML without sanitisation? | Injection via prompt - treat model output as untrusted input |
-| Is the system prompt relied on as a security boundary? | Prompt injection bypasses it - enforce permissions in code |
-| Are secrets or cross-tenant data in the context window? | Data leakage via prompt extraction |
-| Are tool/agent permissions scoped? | Excessive agency - model can take actions it shouldn't |
-| Are token/rate/recursion limits set? | Unbounded consumption or infinite loops |
-
-**5. Classify findings by severity and action:**
-
-| Severity | Criteria | Action |
-|----------|----------|--------|
-| **Critical** | Exploitable now, real data at risk | Stop other work. Fix before next merge. |
-| **High** | Exploitable with effort, or compliance violation | Fix this phase. Track in `risks.md`. |
-| **Medium** | Defense-in-depth gap, no immediate exploit | Log it. Fix when the module is next touched. |
-| **Low** | Best practice gap, no exploit path | Note for the handoff document. |
-
-**6. Present findings as protection, not criticism.**
-
-The internal team built this system under constraints. Frame findings as shared wins:
-
-> "Found three endpoints without rate limiting - adding that now prevents the bot attack that hit [company in their industry] last quarter. Here's the fix."
-
-Not: "Your auth is broken." Even if it is.
-
-## Artifact
-
-**`risks.md`** - each finding with severity, evidence, remediation, and status:
-```markdown
-## Security finding: <title> - <severity>
-Where: <file:line or endpoint>
-Evidence: <what you found>
-Risk: <what an attacker could do>
-Remediation: <specific fix>
-Status: fixed / in-progress / logged-for-handoff
-```
-
-**`trust-profile.md`** - update if new sensitive data paths, AI components, or compliance requirements were discovered.
-
-## Checkpoint
-
-Summary to the FDE: findings by severity count, the one critical/high finding that needs immediate attention (if any), and the overall security posture in one sentence. If no critical findings: "No exploitable issues found in this pass - next audit at <trigger>."
-
-## Principles
-
-- Threat model first, scan second. Know where to look before looking everywhere.
-- Treat model output as untrusted input - always.
-- Frame findings as protection, not criticism. The team built under constraints.
-- Secrets in code outrank every other finding. Check first.
-- A security audit with no findings either found nothing or didn't look hard enough - state which.

package/skills/fde/references/test-on-legacy.md

@@ -1,108 +0,0 @@
-# test-on-legacy - making changes safe on code that has no tests
-
-**Enter when:** the codebase has little or no test coverage, you need to change code where tests are absent or misleading, or `terrain.md` flagged high-churn modules with no test neighbours.
-
-**Read first:** `terrain.md` (the churn heat map), `decisions.md` (the current slice), `context.md`. This skill is the safety net for building on someone else's untested codebase.
-
-Legacy code without tests is a minefield. You can't refactor it because you don't know what it does. You can't add features because you don't know what you'll break. The way through: characterise what exists, wrap the change, prove it works - in that order.
-
-## Method (you do this work)
-
-**1. Characterisation tests first.** Before changing anything, write tests that describe what the code *actually does right now* - including the parts that seem wrong:
-
-```
-The code truncates names at 50 characters.
-  → That seems like a bug, but it might be a contract another system depends on.
-  → Write a test: "truncates names at 50 characters" - that's the characterisation.
-  → NOW you can change the code and know exactly what you've broken.
-```
-
-Characterisation tests answer: "What does this code do?" not "What should this code do?" They're the honest documentation that the README isn't.
-
-**How to write them:**
-1. Pick the function/module you're about to change.
-2. Call it with representative inputs (from production if possible, from logs, from the team's knowledge).
-3. Record what comes back - that's your expected output.
-4. Turn that into an assertion.
-
-```
-# The pattern:
-result = function_under_test(real_input)
-assert result == whatever_it_actually_returned  # characterisation, not specification
-```
-
-**2. The Strangler Fig pattern - wrap, don't rewrite.**
-
-Never rewrite legacy code in place. Instead:
-
-```
-Step 1: New interface wraps the old code (calls through to it)
-  → All existing callers work exactly as before
-  → Your characterisation tests pass
-
-Step 2: New implementation behind the new interface
-  → Old code still there, still callable
-  → Feature flag or config switches between old and new
-
-Step 3: Gradually migrate callers to the new path
-  → Each migration is a small, testable change
-  → Old path remains as fallback
-
-Step 4: Remove old code only when:
-  → No callers remain
-  → New path has been stable for N days
-  → Team agrees it's safe
-```
-
-**3. The test pyramid for legacy engagement work:**
-
-| Level | What to write | How many | Why |
-|-------|-------------|---------|-----|
-| **Characterisation** | What the code does now | 3–5 per module you're changing | Safety net before any change |
-| **Unit** | Your new code's behaviour | 1 per new function/method | Proves your addition works |
-| **Integration** | The seam between old and new | 1–2 per boundary | Proves old and new cooperate |
-| **Smoke** | The critical user path end-to-end | 1 per feature | Proves the user can still do the thing |
-
-**4. Spot the lying tests.** Worse than no tests are tests that pass but verify nothing:
-
-```
-# This test passes and proves nothing:
-def test_process_payment():
-    result = process_payment(mock_everything())
-    assert result is not None  # what does "not None" prove?
-
-# This test is actually testing something:
-def test_process_payment_deducts_from_balance():
-    account = create_account(balance=100)
-    process_payment(account, amount=30)
-    assert account.balance == 70
-```
-
-When you find a lying test: note it in `terrain.md`. Don't fix it unless it's in your slice - but name it, because the next person needs to know.
-
-**5. The "safe to change" checklist.** Before modifying any legacy code:
-
-- [ ] Characterisation tests written for the module being changed
-- [ ] All characterisation tests pass before your change
-- [ ] Your change is wrapped (Strangler Fig), not a rewrite-in-place
-- [ ] New tests cover your new behaviour
-- [ ] All tests (characterisation + new) pass after your change
-- [ ] The diff shows only what you intended to change
-
-## Artifact
-
-**`terrain.md`** - update test-gap assessment: which modules now have characterisation tests, which still don't, which tests are lying.
-
-**`decisions.md`** - log: "Added characterisation tests for <module> before changing <feature>. Coverage state: <before/after>."
-
-## Checkpoint
-
-Before merging any change to legacy code: characterisation tests existed before the change (state which), new tests cover the new behaviour, all pass. If characterisation tests were skipped: that's a finding - state why (time pressure? inaccessible code?) and log the risk.
-
-## Principles
-
-- Characterise before changing. What the code does > what it should do.
-- Wrap, don't rewrite. The Strangler Fig is the safest pattern on legacy code.
-- A lying test is worse than no test. Name it when you find it.
-- The ugly behaviour in the characterisation test might be someone else's contract. Don't "fix" it without asking.
-- Test coverage on legacy code is insurance - buy it before you need it, not after.