fdeops 3.17.0 → 3.21.0

package/skills/fde/references/rescue.md

@@ -1,4 +1,4 @@
-# rescue - production fire, trust fire, or wrong-brief mid-build
+# rescue - Resolve the incident
 
 **Enter when:** production is down, something's bleeding - OR a stakeholder went quiet, confidence is slipping, or three weeks into the build the brief turned out to be wrong. Trust fires get the same urgency as outages.
 
@@ -13,7 +13,8 @@ Open by narrowing time, like a human: "Walk me through the last couple hours - d
 git log --since="6 hours ago" --format="%ad %an %s" --date=relative
 ```
 
-**The sequence:**
+**The sequence:** no fix until the cause is named. A symptom patch is the second incident.
+
 1. **Stabilise first.** Roll back? Disable the broken path? Route around it? Buy time before diagnosing. The instinct to fix fast causes the second incident.
 2. **Name the unknowns.** "We don't know if the queue is corrupted / if this hits all users / if the cache is stale." Written down. Named unknowns are safer than assumed knowns.
 3. **Assume maximum blast radius.** The unrecognised integration in the stack trace is load-bearing until proven otherwise.

package/skills/fde/references/review.md

@@ -1,6 +1,6 @@
-# review - two stages, always in order
+# review - Review the change
 
-**Enter when:** a change needs review before merge - "is this safe," "does it match what we agreed."
+**Enter when:** a change needs review before merge - "is this safe," "does it match what we agreed." Their team commented on the PR: same skill. Comments are to check, not to obey.
 
 **Read first:** `context.md`, `decisions.md`, `trust-profile.md`, `terrain.md`. Not `reality.md`/`stakeholders.md` - irrelevant to reviewing code against agreed scope.
 
@@ -52,7 +52,7 @@ Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock
 
 1. Read the full diff before commenting.
 2. Verdicts: **Stage 1: Pass / Blocked (reason)** · **Stage 2: Pass / Concerns (line-specific)**.
-3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why.
+3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why. Their comments are to check, not to obey. Restate each against the one-line intent and `trust-profile.md`. One item unclear → ask before changing any of them. If it breaks a signed constraint, a sacred system, or nothing calls it: one-sentence pushback, then wait.
 4. Add or update a test per bug found where possible.
 5. Re-run tests/typechecks - state what ran.
 6. Re-review. Repeat until Pass/Pass or a human must decide scope/product.

package/skills/fde/references/rollback.md

@@ -1,4 +1,4 @@
-# rollback - test the escape route before you need it
+# rollback - Rehearse rollback
 
 **Enter when:** a deploy is planned for the next 48 hours, the FDE says "we can always revert," a previous rollback failed or took too long, or the engagement involves regulated/critical systems.
 

package/skills/fde/references/runbook.md

@@ -1,4 +1,4 @@
-# runbook - making yourself replaceable is the goal
+# runbook - Write the runbook
 
 **Enter when:** the engagement is entering its final phase, the customer team needs to operate without the FDE, a new FDE is taking over, or the sponsor asks "what happens when you leave?"
 
@@ -60,6 +60,7 @@ Rollback: <exact command and expected time>
 |---------|-------|-----------|----------|--------|
 | **Architecture walkthrough** | Why, not what. The decisions, the trade-offs, the things that almost went wrong. | Full team | 60-90 min | Recording + Q&A log |
 | **Operational drill** | Deploy, rollback, incident response. They do it, you watch. | On-call team | 60 min | Drill report with confidence level |
+| **Floor drill** | They run the real job (the exception on the operating map) while you watch, hands off. Then they teach the next person. If they cannot, the runbook is a PDF. | Named operator on the floor | 45-60 min | They used the 2am doc during the drill, or the embed is not closed |
 | **Edge-case handover** | The things that aren't in any document. The workarounds, the fragile spots, the "ask Sarah because she's the only one who knows." | Team lead + 1 | 30 min | Additions to `handoff.md` |
 
 **4. The confidence check.** After the knowledge transfer, score the team's readiness:
@@ -68,11 +69,12 @@ Rollback: <exact command and expected time>
 |------|------------------|----------|
 | Daily operations | | Can they deploy and rollback without help? |
 | Incident response | | Did they complete the drill within acceptable time? |
+| Floor job | | Did the named operator complete Tuesday's real exception without you at the keyboard? |
 | Architecture decisions | | Can they explain why the system is built this way? |
 | AI components (if any) | | Do they know how to monitor, retrain, and disable? |
 | Stakeholder management | | Do they know who to update and how? |
 
-**Average below 3.5 → the handoff is not complete.** Extend if possible; if not, document the gaps and name the risk.
+**Average below 3.5 → the handoff is not complete.** Extend, or tell the sponsor the embed is not closed. Do not document the gap and leave.
 
 **5. The successor brief.** If a new FDE is taking over, write a brief that gets them operational in one hour:
 
@@ -132,7 +134,7 @@ If you see 2+: accelerate the handoff immediately. The longer you stay past usef
 
 - The goal of every engagement is to make yourself replaceable.
 - The 2am document is the real handoff - everything else supports it.
-- Knowledge transfer is three sessions, not a doc dump.
+- Knowledge transfer is four sessions, not a doc dump. The floor drill is the named operator completing Tuesday's real job from the 2am doc, hands off. If they cannot, do not close.
 - A confidence score below 3.5 means the handoff isn't done.
 - The successor brief gets the next FDE operational in one hour or it's too long.
 - Clean exit: no personal credentials left behind, ever.

package/skills/fde/references/score-use-cases.md

@@ -1,4 +1,4 @@
-# score-use-cases - pick the right battle, not the interesting one
+# score-use-cases - Score use cases
 
 **Enter when:** multiple potential use cases compete for attention, the customer says "we want to do everything," a transformation engagement needs a starting point, or the FDE needs to recommend which problem to solve first.
 

package/skills/fde/references/ship.md

@@ -1,4 +1,4 @@
-# ship - on their site, then live
+# ship - Deliver the increment
 
 **Enter when:** you are writing or updating on their codebase, they need to see something real, or you are going live.
 
@@ -12,7 +12,7 @@ Do not ask them to pick a mode. Name where you are, then start at the matching s
 
 If going live, opening question: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
 
-A same-day throwaway that kills an assumption is `poc`. This method is the real change on a repo they will own, then production.
+A same-day throwaway that kills an assumption is `poc`. This skill is the real change on a repo they will own, then production.
 
 ## Field (name it once, then the same loop)
 
@@ -25,6 +25,10 @@ A same-day throwaway that kills an assumption is `poc`. This method is the real
 
 Skip POC only when the killer assumption already lives in the repo (typical brownfield). If the bet is unproven, `poc` first.
 
+**Done means:** the signer in `success.md` can reject this on staging they operate. A green check on your laptop is not delivery. Do not start the next change until this one is rejectable.
+
+If `terrain.md` **Data estate** lists a **Blocker** this change depends on (source or pipe): stop. That is discover, not ship. Do not build a path they cannot feed.
+
 ## Method - one change they can see
 
 One change = one thing a user can do, with a test, that you can revert on its own. Not "all the APIs, then all the UI." Not a 2,000-line dump. A PR is how this often lands. It is not the job. The job is the change they can see.
@@ -68,10 +72,12 @@ Read existing code in the area (search before creating)
 
 **Prove it on their staging.** A green check on your laptop is not delivery.
 
-- Run **their** test command, typecheck, or smallest proving path. Write the command and the result in `delivery.md`.
+- Run **their** test command, on **their** CI, with **their** fixtures. Write the command and the result in `delivery.md`. You do not add a runner they will not keep. If you have not run their command in this turn, you cannot write that it passed. Last session's green, "should pass," and "looks correct" are not a receipt.
 - If the signer in `success.md` cannot reject this on a screen they already use, it is not proven.
 - Staging they operate beats a local demo. If you have no staging: `unknown - ask:` who owns an environment, then stop pretending it shipped.
+- **Monday-shaped data.** Staging that is empty, synthetic, or last quarter is not next Tuesday. Before go-live, write what staging is missing (volume, PII, the batch that only runs in prod, the account that only exists in the warehouse) and what that means for the kill test. If the signer cannot reject it on a screen they already operate, with data that looks like next Tuesday, it is not proven.
 - Model in the path: `eval-pack` until `evals.md` says SHIP. Do not skip because "it looked right in chat."
+- A model drafts. A named human on their side ships. No unsupervised loop on their production. If the brief demands lights-out write-access, that is `who-decides` / `hold-scope`, not ship.
 
 The proof is whatever this client already believes, plus one new receipt they can replay.
 
@@ -210,6 +216,8 @@ grep -rnE "(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][^'\"]{8,}" \
 
 **Canary:** 1-5% of traffic, ≥10 minutes. Watch error rate, latency, and **the business metric this change affects**. Anything looks wrong → roll back immediately; investigate safely; redeploy when confident. Never investigate during the canary. Then stage up: 5% → 25% → 100%, each confirmed stable.
 
+**Canary receipt** (write it, or the canary did not happen): what was watched, on whose dashboard, for how long, and that the next change did not start in the window. If prod is a CAB console, vendor button, or their pipeline, write the owner and the click path - the host agent does not get to pretend it shipped.
+
 **Programme-scale rollout (transformations)** - different problem from one service:
 1. **Pilot** - one team, one use case; success metrics defined *before* it starts (after = fitting metrics to results).
 2. **Limited release** - 3-5 teams, real load; this is where the failure modes the pilot hid show up.

package/skills/fde/references/switch-clients.md

@@ -1,4 +1,4 @@
-# switch-clients - juggling engagements without dropping any
+# switch-clients - Switch engagements
 
 **Enter when:** the FDE is running 2+ engagements simultaneously, context-switching is causing mistakes or delays, a new customer is being onboarded while existing engagements are active, or the FDE says "I'm losing track."
 

package/skills/fde/references/test-assumptions.md

@@ -1,4 +1,4 @@
-# test-assumptions - pressure-test the brief before building on it
+# test-assumptions - Test assumptions
 
 **Enter when:** the brief feels too neat, the customer is very confident about the solution (not the problem), someone says "we just need…" about a complex system, or discover surfaced contradictions between what was said and what the codebase shows.
 
@@ -8,7 +8,7 @@ Every engagement is built on assumptions. Most are invisible until they're wrong
 
 ## Method (you do this work)
 
-**1. Extract the assumptions.** Read `brief.md` and `reality.md` line by line. Every statement that isn't backed by evidence is an assumption. Common hiding places:
+**1. Extract the assumptions.** Read `brief.md`, `reality.md`, and `terrain.md` `## Parts` line by line. Every statement that isn't backed by evidence is an assumption. Treat every "obvious" block as a convention until a receipt proves it. Common hiding places:
 
 | Where assumptions hide | Example | The real question |
 |----------------------|---------|-------------------|
@@ -19,7 +19,17 @@ Every engagement is built on assumptions. Most are invisible until they're wrong
 | **The data claim** | "We have good data for this" | Defined how? Validated when? By whom? Sample checked? |
 | **The "just"** | "We just need to add a feature" | On what system? With what dependencies? What breaks? |
 
-**2. Classify each assumption by blast radius:**
+**2. Kind first, then blast radius.** For each row, classify:
+
+| Kind | Meaning |
+|------|---------|
+| **FACT** | A dated receipt, a measurement, or the repo. You can point at it. |
+| **CONVENTION** | How they have always done it. The playbook. "We just…" |
+| **UNKNOWN** | No evidence either way. |
+
+Order the list load-bearing first. For each CONVENTION or UNKNOWN, one line: what breaks if it is wrong, and what opens if you **invert** it (stop obeying it). A FACT with no receipt is UNKNOWN - do not promote it to protect the brief.
+
+Then classify blast radius:
 
 ```
 CRITICAL - if wrong, the engagement fails or the approach changes fundamentally
@@ -55,11 +65,11 @@ Evidence first, then the question. Let them reach the conclusion.
 **`assumptions.md`** - this IS the register (create if land did not). Keep one live table; do not only bury results in `reality.md`:
 
 ```markdown
-| # | Assumption | Blast radius | How we test | Status | Evidence |
-|---|------------|--------------|-------------|--------|----------|
-| 1 | API is the bottleneck | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
-| 2 | Team will adopt new tool | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
-| 3 | Data clean enough for ML | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
+| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
+|---|------------|------|--------------|-------------|--------|----------|
+| 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
+| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
+| 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
 ```
 
 Status values: `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`. A CRITICAL row still `OPEN` blocks plan.
@@ -85,6 +95,7 @@ Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and th
 ## Principles
 
 - Every "just" is an assumption. Every "should" is an assumption.
+- Kind before blast radius. A FACT with no receipt is UNKNOWN.
 - Kill the riskiest, cheapest-to-test assumption first.
 - Evidence first, then the question. Let the customer reach the conclusion.
 - A brief with zero disproved assumptions wasn't audited - it was accepted.

package/skills/fde/references/three-options.md

@@ -1,8 +1,8 @@
-# three-options - three paths, not one recommendation
+# three-options - Generate options
 
 **Enter when:** a significant technical or strategic decision needs to be made, the FDE is asked "what should we do?", the team is stuck between approaches, or a fork in the engagement requires the sponsor's input.
 
-**Read first:** `reality.md`, `terrain.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
+**Read first:** `reality.md`, `terrain.md`, `assumptions.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
 
 One option is a request for trust. Two options is a false choice. Three options is a conversation between professionals. The FDE who presents three genuine options earns the decision-maker's respect - and their protection when things get hard.
 
@@ -12,24 +12,30 @@ One option is a request for trust. Two options is a false choice. Three options
 
 > "Decision: approach for the payment migration. Decided by: CTO. Needed by: Friday. Deferral cost: blocks the next sprint and delays the pilot by two weeks."
 
-**2. Generate three genuine options.** Not "good / medium / bad" - three approaches with real trade-offs:
+**2. Generate three genuine options from what survived.** Read `assumptions.md` (CONFIRMED / DISPROVED) and `terrain.md` `## Parts`. The playbook is unavailable. Assemble from those blocks only.
 
-| Option archetype | Description | When it fits |
-|-----------------|-------------|-------------|
-| **Conservative** | Lowest risk, smallest change, longest timeline | When trust is thin or the system is fragile |
-| **Pragmatic** | Balanced risk/reward, proven patterns, moderate timeline | When the team is competent and the deadline is real |
-| **Ambitious** | Highest reward, most change, highest risk | When the sponsor has appetite and the team has capacity |
+Not "good / medium / bad." Not three speeds of the same plan (Conservative / Pragmatic / Ambitious of one architecture). Three approaches that differ in **structure** - rearrange the same surviving parts.
 
-Each option must be one the FDE would genuinely recommend under different circumstances. If you can't defend an option, replace it - padding is visible.
+Each option must be one the FDE would genuinely recommend under different circumstances. If you cannot defend an option, replace it - padding is visible.
+
+For each option, name:
+- which surviving blocks it is built from
+- which CONVENTION it refuses to obey
+- its single biggest point of failure
+- any new building block, labelled as a new assumption (`UNKNOWN` in `assumptions.md`) - do not smuggle one in as a fact
+
+If all three are the same system at different risk levels, you wrote the playbook. Start over.
 
 **3. Structure each option identically.** Same dimensions, same format - so comparison is instant:
 
 ```markdown
-### Option A: <name> (Conservative)
+### Option A: <name>
+- **Blocks:** <which surviving assumptions / parts it is built from>
+- **Convention refused:** <the "we just…" it will not obey>
 - **What:** <the approach in one paragraph>
 - **Timeline:** <estimate with basis>
 - **Cost:** <effort, infrastructure, external>
-- **Risk:** <what could go wrong and the mitigation>
+- **Biggest failure:** <the single point that kills this option>
 - **Trade-off:** <what you give up by choosing this>
 - **Best when:** <the condition that makes this the right choice>
 ```
@@ -85,6 +91,7 @@ Recommendation: pragmatic, conditional - *if* Raj is on the design, otherwise sa
 ## Principles
 
 - Three options, never one. One option is a request for trust; three is a real decision.
+- Assemble from surviving blocks. Three speeds of the same plan is the playbook - start over.
 - Each option must be genuinely defensible - no straw men.
 - Same structure for each option. Comparison should take 30 seconds.
 - Recommend one. State why. Accept the override gracefully.

package/skills/fde/references/what-breaks.md

@@ -1,4 +1,4 @@
-# what-breaks - know what breaks before you touch it
+# what-breaks - Assess impact
 
 **Enter when:** about to make a change on a system you don't fully understand, touching a high-churn module from `terrain.md`, modifying shared infrastructure (auth, database, messaging), or the FDE asks "what could go wrong?"
 

package/skills/fde/references/who-decides.md

@@ -1,4 +1,4 @@
-# who-decides - reading the room before it reads you
+# who-decides - Map decision rights
 
 **Enter when:** new stakeholders appear, signals shift mid-engagement, a meeting felt off but you can't say why, or it's been two weeks and the map hasn't been updated.
 

package/templates/.fde/README.md

@@ -5,7 +5,7 @@
 Create with:
 
 ```bash
-node bin/install.js init <engagement-name>   # from fdeops repo; or npx fdeops@latest init when npm ≥ 3.0.0
+fde resume --init <engagement-name>   # or: npx fdeops resume --init <engagement-name>
 ```
 
 Stays on **your machine** - not in shared git by default.

package/templates/.fde/assumptions.md

@@ -2,9 +2,10 @@
 
 <!-- Brief claims that are not yet evidence. Land seeds; test-assumptions / discover update. -->
 
-| # | Assumption | Blast radius | How we test | Status | Evidence |
-|---|------------|--------------|-------------|--------|----------|
+| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
+|---|------------|------|--------------|-------------|--------|----------|
 
+**Kind:** `FACT` · `CONVENTION` · `UNKNOWN`  
 **Blast radius:** `CRITICAL` · `LOAD-BEARING` · `CONVENIENCE`  
 **Status:** `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`
 

package/templates/.fde/terrain.md

@@ -9,7 +9,7 @@
 ## Operating map (exception-led)
 
 <!-- How work actually runs when the happy path fails. Fill in discover; leave blank until heard/seen.
-     fde doctor requires ≥1 real exception row before plan/build/ship/close. -->
+     fde doctor requires ≥1 real exception row before plan/ship/outcome/close. -->
 
 | Exception / break | Who notices first | What they do today (workaround) | System of record then | Blast if wrong | Evidence |
 |-------------------|-------------------|---------------------------------|-----------------------|----------------|----------|