fdeops 3.17.0 → 3.21.0

package/bin/fde.js

@@ -740,11 +740,11 @@ function appendLogEntry(eng, type, entry, opts = {}) {
 // degrading to "nothing found" rather than guessing when the shape does not
 // match. Never fabricate a number, a name, or a signal that is not in the text.
 
-const PHASES = ['land', 'discover', 'plan', 'ship', 'prove', 'close']
-const PHASE_ALIASES = { build: 'ship' } // legacy SDLC name; public map is ship
+const PHASES = ['land', 'discover', 'plan', 'ship', 'outcome', 'close']
+const PHASE_ALIASES = { build: 'ship', prove: 'outcome' } // legacy names; public map is ship / outcome
 const PHASE_LABELS = {
   land: 'Land', discover: 'Discover', plan: 'Plan',
-  ship: 'Ship', prove: 'Prove', close: 'Close',
+  ship: 'Ship', outcome: 'Outcome', close: 'Close',
 }
 function canonicalPhase(phase) {
   const p = String(phase).toLowerCase()
@@ -1412,7 +1412,7 @@ function cmdLog(args) {
   const eng = resolveEngagement({ forWrite: true })
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
 
-  // fde log phase <land|discover|plan|ship|prove|close> - advances portfolio phase
+  // fde log phase <land|discover|plan|ship|outcome|close> - advances portfolio phase (prove → outcome)
   if (type === 'phase') {
     const phase = canonicalPhase((text || '').toLowerCase().trim())
     if (!PHASES.includes(phase)) {
@@ -2237,7 +2237,7 @@ function collectDoctorIssues(eng) {
     }
   }
   const success = readClean(eng, 'success.md')
-  if (!firstLine(success, 80)) issues.push('success.md has no stated done-definition - fill before plan/build')
+  if (!firstLine(success, 80)) issues.push('success.md has no stated done-definition - fill before plan/ship')
   const ctxMd = readClean(eng, 'context.md')
   if (!sectionBody(ctxMd, 'Next action', { lastNonEmpty: true })) {
     issues.push('no ## Next action in context.md - Monday morning has nothing to drive')
@@ -2278,7 +2278,7 @@ function collectDoctorIssues(eng) {
   }
   // Failure-path (exception-led operating map): required once past discover.
   // Land seeds; discover fills; plan+ without a real break→owner row is wallpaper.
-  if (/^(plan|ship|prove|close)$/.test(s.phase) && !hasOperatingMapContent(eng)) {
+  if (/^(plan|ship|outcome|close)$/.test(s.phase) && !hasOperatingMapContent(eng)) {
     issues.push(
       `phase is ${s.phase} with empty operating map - fill terrain.md ## Operating map (exception-led): break → who notices → workaround → evidence`
     )
@@ -3324,7 +3324,7 @@ function printUsage() {
   fde triage               TRIAGE block only (hooks / Cursor session entry)
   fde log <type> <text>    append decision|risk|delivery|contact (contact takes --signal red|amber|green; delivery "a|b|c" writes the value ledger; --force to allow secret-like text)
   fde log risk --retire    move matching open-risk bullets to ## Retired
-  fde log phase <phase>    set engagement phase (land|discover|plan|ship|prove|close)
+  fde log phase <phase>    set engagement phase (land|discover|plan|ship|outcome|close)
   fde log --undo           remove the last CLI log/debrief entry from memory
   fde debrief [file]       meeting notes → memory (prefixed lines; --dry-run; --force)
   fde debrief --smart      heuristic propose (prints decision:/risk:/delivery:/contact:/next:); --apply after confirm

package/bin/lib/trust.js

@@ -98,9 +98,11 @@ function createTrustApi(deps) {
     if (!m) return '?'
     const raw = m[1].replace(/\*/g, '').trim()
     if (!raw || /\|/.test(raw) || /^unset$/i.test(raw) || /^[\[(]/.test(raw)) return '?'
-    const one = raw.toLowerCase().match(/^(land|discover|plan|build|ship|prove|close)\b/)
+    const one = raw.toLowerCase().match(/^(land|discover|plan|build|ship|prove|outcome|close)\b/)
     if (!one) return '?'
-    return one[1] === 'build' ? 'ship' : one[1]
+    if (one[1] === 'build') return 'ship'
+    if (one[1] === 'prove') return 'outcome'
+    return one[1]
   }
 
   function countOpenRisks(eng) {

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "3.17.0",
+  "version": "3.21.0",
   "private": true,
   "description": "Thin stdio MCP sink for FDEOps ingest (stage → propose → apply). Zero runtime dependencies.",
   "bin": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fdeops",
-  "version": "3.17.0",
-  "description": "Forward deployed engineering skills for AI coding agents. Your agent forgets the client every morning - the sponsor, the promise, who signed off. FDEOps keeps that as dated markdown on your laptop: one @fde skill, a deterministic local CLI, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
+  "version": "3.21.0",
+  "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code: who can say yes, what went live, whether they signed off. Dated markdown on your laptop. You confirm each write.",
   "bin": {
     "fdeops": "bin/install.js",
     "fde": "bin/fde.js"

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "3.17.0",
-  "description": "Forward deployed engineering skills for AI coding agents: per-client memory in local .fde/ files, one @fde skill. Local-only, no network.",
+  "version": "3.21.0",
+  "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code. You confirm; then it lands in .fde/ on your laptop.",
   "author": {
     "name": "Subash Natarajan",
     "url": "https://github.com/suboss87"

package/skills/fde/SKILL.md

@@ -7,7 +7,7 @@ description: Keeps the engagement record for client work. Use when they name a c
 
 ## Purpose
 
-The **engagement record** for one client, from first meeting to signed outcome. One skill; six stages (land → close). You route; they never pick a skill. Confirm, then write `.fde/`. The workspace still compiles and commits. `@fde` does not leave.
+The **engagement record** for one client, from first meeting to signed outcome. One skill; six stages (land → close). Same map at any scale, on greenfield or brownfield, in any industry (overlays). You route; they never pick a skill. Confirm, then write `.fde/`. The workspace still compiles and commits. `@fde` does not leave.
 
 ## When to use
 
@@ -77,7 +77,7 @@ Writes need a bind (`FDEOPS_ENGAGEMENT` or registry). Never install fdeops on in
 
 ## The memory contract
 
-1. **On entry:** `fde resume` only. Pull other `.fde/` files when the method needs them.
+1. **On entry:** `fde resume` only. Pull other `.fde/` files when the skill needs them.
 2. **Deliverable = memory.** The work *is* the `.fde/` file. The reference names which one.
 3. **Evidence.** Every claim has a source. Traceable beats plausible.
 4. **No invented facts.** People, quotes, meetings, numbers: they said it or the repo shows it. Else `unknown - ask: <question>`.
@@ -107,83 +107,83 @@ CLI is local (`git` + files, no network). You see their code only when they poin
 
 Direct. Their words. No "Certainly." Playback 2-4 lines, then act. One question only when a missing fact changes the next move.
 
-New embed: sprint / standard / programme changes depth, not which methods exist. Before first code: safe place to break things, plus AI-code policy. Before go-live: who needs to know, what's the rollback. Before a sponsor artifact: as-is or gut-check first.
+New embed: sprint / standard / programme changes depth, not which skills exist. Before first code: safe place to break things, plus AI-code policy. Before go-live: who needs to know, what's the rollback. Before a sponsor artifact: as-is or gut-check first.
 
 Muddy signal: name it ("discover or rescue - leaning X"). Never a phase-picker interview. Default: land if new, audit if takeover.
 
 ## Routing - 6 stages
 
-Read **one** reference and follow it. Do not improvise from memory.
+Work names (engage, diagnose, align, deliver, realize, transfer) are the same map. Read **one** reference and follow it. Do not improvise from memory.
 
 ### Land
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| Starting fresh, new customer, first meeting, just got the brief | land | `references/land.md` |
+| Engage, onboarding, starting fresh, new customer, first meeting, just got the brief, set product strategy, define success metrics, scope the brief | land | `references/land.md` |
 | Taking over, previous consultant left, joining mid-project | audit | `references/audit.md` |
-| Need to understand who matters, who decides, who blocks quietly | who-decides | `references/who-decides.md` |
+| Need to understand who matters, who decides, map decision rights, who blocks quietly | who-decides | `references/who-decides.md` |
 | Need to earn access, navigate AI policy, build credibility | earn-trust | `references/earn-trust.md` |
-| "Also can you…", scope expanding, timeline unchanged | hold-scope | `references/hold-scope.md` |
+| "Also can you…", scope expanding, timeline unchanged, hold scope, scope the brief after kickoff | hold-scope | `references/hold-scope.md` |
 
 ### Discover
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| Don't know the real problem, brief feels wrong, shadow processes | discover | `references/discover.md` |
-| The brief feels too neat, assumptions untested, "we just need…" | test-assumptions | `references/test-assumptions.md` |
-| Multiple use cases competing, "we want to do everything" | score-use-cases | `references/score-use-cases.md` |
-| Need to validate a direction, prototype, demo to de-risk, **POC**, spike, killer assumption | poc | `references/poc.md` |
+| Diagnose, don't know the real problem, brief feels wrong, shadow processes, frame discovery, understand the problem space, data not ready, data estate, catalog the data, parts of the problem, decompose | discover | `references/discover.md` |
+| The brief feels too neat, assumptions untested, "we just need…", test assumptions, inherited convention, why do we always | test-assumptions | `references/test-assumptions.md` |
+| Multiple use cases competing, "we want to do everything", score use cases | score-use-cases | `references/score-use-cases.md` |
+| Need to validate a direction, prototype, demo to de-risk, **POC**, spike, killer assumption, validate the solution, build prototype | poc | `references/poc.md` |
 
 ### Plan
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| Break this down, what order, sequence the build | plan | `references/plan.md` |
-| Sponsor needs justification, need to defend budget or timeline | business-case | `references/business-case.md` |
-| Significant decision, multiple approaches, "what should we do?" | three-options | `references/three-options.md` |
-| 20 things are "urgent," need to pick the 3 that matter | pick-three | `references/pick-three.md` |
+| Align, break this down, what order, sequence the build, plan the roadmap, create user stories, write the tasks | plan | `references/plan.md` |
+| Sponsor needs justification, need to defend budget or timeline, build the business case | business-case | `references/business-case.md` |
+| Significant decision, multiple approaches, "what should we do?", generate solutions, generate options, not the playbook, from the surviving facts | three-options | `references/three-options.md` |
+| 20 things are "urgent," need to pick the 3 that matter, prioritize three | pick-three | `references/pick-three.md` |
 
 ### Ship
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| What could go wrong, touching shared infrastructure, need to assess impact | what-breaks | `references/what-breaks.md` |
-| Production down, urgent - OR stakeholder gone quiet, trust slipping | rescue | `references/rescue.md` |
-| Start building, update their checkout, first module, visible progress, their tests, POC follow-through, ready to deploy, going live, pre-flight | ship | `references/ship.md` |
-| Review this change, is it safe, does it match what we agreed | review | `references/review.md` |
+| What could go wrong, touching shared infrastructure, need to assess impact, assess impact, provision, IaC, shared infra | what-breaks | `references/what-breaks.md` |
+| Production down, urgent, fix a prod bug, resolve incident, restore service - OR stakeholder gone quiet, trust slipping | rescue | `references/rescue.md` |
+| Deliver, start building, update their checkout, first module, visible progress, their tests, POC follow-through, ready to deploy, going live, pre-flight, deliver the increment, build the increment, create the launch plan, design their UI | ship | `references/ship.md` |
+| Review this change, review the pull request, is it safe, does it match what we agreed | review | `references/review.md` |
 | Diff grew / scope creep in the PR / "did we only build what we said" / KEEP JUSTIFY SPLIT DROP | review (+ ship if going live) | `references/review.md` Stage 1 · `references/ship.md` Intent vs diff |
 | Wrap the session / share the thinking / catch teammates up / before I open the PR | (memory contract - session digest) | SKILL.md **On exit** - write TL;DR + decisions/why into `.fde/`; no transcript sync |
-| "We can always revert" - need to actually test the escape route | rollback | `references/rollback.md` |
+| "We can always revert" - need to actually test the escape route, rehearse rollback | rollback | `references/rollback.md` |
 
-### Prove
+### Outcome
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| Weekly update due, "need to send the sponsor something" | readout | `references/readout.md` |
-| Demo coming up, show-and-tell, exec walkthrough | demo-prep | `references/demo-prep.md` |
-| Just out of a meeting, raw notes, "they said…", "debrief" | debrief | the debrief verb (above) + `references/debrief.md` |
+| Realize, weekly update due, "need to send the sponsor something", report the outcome | readout | `references/readout.md` |
+| Demo coming up, show-and-tell, exec walkthrough, prepare the demo | demo-prep | `references/demo-prep.md` |
+| Just out of a meeting, raw notes, "they said…", "debrief", user interviews, workshop notes, capture the meeting | debrief | the debrief verb (above) + `references/debrief.md` |
 | Make sure we're up to date, pull what's relevant, fetch from Granola/Slack/Gmail/transcript | ingest | `references/ingest.md` (capability check → stage → propose → confirm → apply) |
 | Connect a new MCP / connect Granola Slack or Notion / what can you pull | connect | `references/connect.md` (+ `mcp/recipes/`) |
 | Prep me for a meeting / walk-in brief / "what should I know before I talk to…" | - | run `fde prep "<label>"`, present in plain language |
-| Sponsor's boss needs a summary, board update, justify continued investment | board-memo | `references/board-memo.md` |
-| Status across all my customers | dashboard | `references/dashboard.md` |
+| Sponsor's boss needs a summary, board update, brief the board, justify continued investment | board-memo | `references/board-memo.md` |
+| Status across all my customers, view the portfolio | dashboard | `references/dashboard.md` |
 
 ### Close
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| Juggling 2+ customers, losing track, context-switching | switch-clients | `references/switch-clients.md` |
-| Wrapping up, handoff, making yourself replaceable | close | `references/close.md` |
-| Engagement ending, team needs to operate without you | runbook | `references/runbook.md` |
-| Something worked well and will apply to future engagements | encode-pattern | `references/encode-pattern.md` |
-| "Red-team this," "stress-test my plan," poke holes, what am I missing | red-team | `references/red-team.md` |
+| Juggling 2+ customers, losing track, context-switching, switch engagements | switch-clients | `references/switch-clients.md` |
+| Transfer, wrapping up, handoff, making yourself replaceable, transfer operations | close | `references/close.md` |
+| Engagement ending, team needs to operate without you, write the runbook | runbook | `references/runbook.md` |
+| Something worked well and will apply to future engagements, encode the pattern | encode-pattern | `references/encode-pattern.md` |
+| "Red-team this," "stress-test my plan," poke holes, challenge the plan, what am I missing | red-team | `references/red-team.md` |
 | "What did we agree about X?", scope dispute, receipts | - | run `fde receipts <term>`, answer with dates |
 
 **Overlays - activate alongside any skill on signal, don't wait to be told:**
 
 | Signal | Overlay |
 |--------|---------|
-| AI, ML, LLM, model, embeddings, RAG, agents, fine-tuning, inference, drift | `references/ai.md` |
+| AI, ML, LLM, model, embeddings, RAG, agents, fine-tuning, inference, drift, train the model | `references/ai.md` |
 | Golden set, eval suite, eval pack, pass/fail before AI ship, HITL gate for model, POC the model | `references/eval-pack.md` (+ `ai.md`) |
 | Deck, slides, report, governance framework, compliance pack, ADR, PDF | `references/artifacts.md` |
 | Patient data, PHI, HIPAA, EHR, clinical | `references/healthcare.md` |
@@ -195,7 +195,9 @@ Ready to build with no `terrain.md` / plan: discover or plan first. Takeover wit
 ## Principles
 
 - Never ask the FDE to pick a phase. That's your job.
+- Same six stages at any scale. Overlays carry the industry. Greenfield and brownfield change the first move inside ship, not the map.
 - Ground loop on a bound client: name → characterise → prove on their staging → go live → log. Do not hand their repo to a generic coding pack.
+- Do not call a change done until the signer in `success.md` can reject it on staging they operate.
 - Read `context.md` before speaking. One sharp question - never a barrage.
 - Never invent people, meetings, or numbers - `unknown - ask:` beats a polished lie.
 - Every phase ends with its artifact written. No artifact, no "done."

package/skills/fde/references/ai.md

@@ -38,7 +38,7 @@ Write model selection rationale to `decisions.md`. Include: models tested, test
 
 ## Engagement eval pack (before AI ships)
 
-When any slice touches a model, embeddings, RAG, or an agent: create or update `.fde/evals.md` **before** ship. Full method: `references/eval-pack.md`. This is the engagement-local test set - not unit tests.
+When any slice touches a model, embeddings, RAG, or an agent: create or update `.fde/evals.md` **before** ship. Full skill: `references/eval-pack.md`. This is the engagement-local test set - not unit tests.
 
 **Minimum pack (do not grow until the minimum exists):**
 1. **Component + quality bar** - one sentence each; kill switch / fallback named.
@@ -47,7 +47,7 @@ When any slice touches a model, embeddings, RAG, or an agent: create or update `
 4. **Pass/fail** - dated run; Verdict **SHIP** or **NO-SHIP**; critical fails must be 0.
 5. **HITL gate** - which decisions need human review before action (align with `trust-profile.md`). Empty when policy requires review → NO-SHIP.
 
-**When to write:** plan seeds the pack; poc/build grows goldens; ship requires Verdict SHIP and a receipt in `delivery.md` → `## Ship receipts`. Non-AI work skips this file entirely.
+**When to write:** plan seeds the pack; poc/ship grows goldens; ship requires Verdict SHIP and a receipt in `delivery.md` → `## Ship receipts`. Non-AI work skips this file entirely.
 
 ## RAG architecture (retrieval-augmented generation)
 

package/skills/fde/references/audit.md

@@ -1,4 +1,4 @@
-# audit - taking over mid-engagement
+# audit - Verify inherited claims
 
 **Enter when:** picking up someone else's work - previous consultant left, joining mid-project, half-done system.
 
@@ -9,7 +9,7 @@
 Before forming any opinion:
 
 1. **Inherit the paper.** Any previous `.fde/`, docs, README claims, ADRs, ticket history the FDE can export. Read it all - the previous FDE's decisions are evidence, not verdicts.
-2. **Run the discover scans** (see `discover.md` method part 1: churn, test gaps, "temporary" grep, AI components). On a takeover, add:
+2. **Run the discover scans** (see `discover.md` part 1: churn, test gaps, "temporary" grep, AI components). On a takeover, add:
 ```bash
 git log --format="%an" | sort | uniq -c | sort -rn | head   # who actually built this
 git log --since="60 days ago" --format="%ad %s" --date=short | head -20  # what was happening when they left

package/skills/fde/references/board-memo.md

@@ -1,4 +1,4 @@
-# board-memo - the story that gets the next phase funded
+# board-memo - Brief the board
 
 **Enter when:** the sponsor's boss needs a summary, a board update mentions the engagement, the FDE needs to justify continued investment, or a quarterly review is approaching.
 

package/skills/fde/references/business-case.md

@@ -1,4 +1,4 @@
-# business-case - the economics that get the sponsor to say yes
+# business-case - Build the business case
 
 **Enter when:** the sponsor needs justification for the next phase, the FDE needs to defend budget or timeline, a feature decision needs cost/benefit evidence, or poc produced a direction that needs funding.
 

package/skills/fde/references/close.md

@@ -1,4 +1,4 @@
-# close - handoff and pattern extraction
+# close - Transfer operations
 
 **Enter when:** the engagement is ending - the customer team must run this without the FDE.
 

package/skills/fde/references/connect.md

@@ -1,4 +1,4 @@
-# connect - wire a source MCP in plain language
+# connect - Connect a source
 
 **Enter when:** the FDE says "I want to connect a new MCP", "connect Granola / Slack / Notion", "how do I pull from …", or a pull request fails because no source tools exist.
 

package/skills/fde/references/dashboard.md

@@ -1,4 +1,4 @@
-# dashboard - the portfolio view
+# dashboard - View the portfolio
 
 **Enter when:** the FDE runs several customers and asks "where am I across everything?"
 
@@ -8,7 +8,7 @@ The visual artifact is rendered by code, not by you. `fde dashboard` reads every
 
 ## Method (you do this work)
 
-0. **First move: `fde status`** - instant heuristic triage (trust-first ordering) across every engagement. Use it as the index; then deep-read only the folders that are red/amber or that the FDE asks about, and apply the full card method below.
+0. **First move: `fde status`** - instant heuristic triage (trust-first ordering) across every engagement. Use it as the index; then deep-read only the folders that are red/amber or that the FDE asks about, and apply the full card below.
 1. **Find the engagements:** `~/fde-engagements/*/.fde/` (primary) · workspace `./.fde/` if present · paths the FDE names. Read each folder **separately** - never merge two customers.
 2. **Per engagement, read the card the way a human would:**
    - Name, phase, week

package/skills/fde/references/debrief.md

@@ -1,4 +1,4 @@
-# debrief - capture the meeting before it evaporates
+# debrief - Capture the meeting
 
 **Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". Highest-frequency moment in FDE life. Capture within the hour.
 

package/skills/fde/references/demo-prep.md

@@ -1,4 +1,4 @@
-# demo-prep - the demo is the heartbeat of the engagement
+# demo-prep - Prepare the demo
 
 **Enter when:** a demo, show-and-tell, or exec walkthrough is coming. FDE engagements live demo-to-demo; a flat demo costs more than a slipped task.
 

package/skills/fde/references/discover.md

@@ -1,4 +1,4 @@
-# discover - find the real problem, map the terrain
+# discover - Frame the problem
 
 **Enter when:** the brief feels wrong, the real problem is unclear, shadow processes are suspected, or any phase found that the map is missing.
 
@@ -54,6 +54,16 @@ Tests on **Question** - rewrite until all five hold:
 
 Cannot write the Question → keep interrogating. Do not `fde scan`. Every later output of this phase aims at that Question. Sub-questions go to the operating map or `assumptions.md`, not into the Question.
 
+## Parts of the problem (decompose only)
+
+After the Question is locked, and **before** `fde scan` or any option: write what the problem is made of. No advice, no playbook, no solution.
+
+If the stated brief hides a deeper job, name that deeper job in one sentence and **wait**. Do not silently replace their problem with yours.
+
+In `terrain.md` under `## Parts`, list the smallest useful pieces that still change what you examine next. Typical cuts: people, process step, system, data, time, cost. For each piece: what it contains, and how it connects to the Question. Stop when a further split would not change where you dig.
+
+Do not mark pieces as facts or assumptions here. That is `test-assumptions`. Do not assemble options here. That is `three-options`.
+
 ## Method - part 1: the codebase (you do this work)
 
 **First move: `fde scan`** - it runs everything below deterministically in seconds (churn×tests, "temporary" archaeology, AI components, secrets redacted, previous attempts). Your job is then **interpretation**: read its output against the brief, follow the hotspots into the code, and connect the technical findings to the human signals in part 2.
@@ -105,7 +115,7 @@ The real spec is what people **do** when the system fails - not what the slide d
 - **The hesitation.** When someone says "well, there's also this other thing we do…" - stop them, ask them to finish. The main story is what they're comfortable explaining; the hesitation is the real problem.
 - **"Which part of the codebase do you least want to touch?"** The answer is unanimous and it's the load-bearing wall. Check it against your churn scan - when the human answer and the churn data agree, that's your first map landmark.
 - **Shadow AI.** Someone pasting data into ChatGPT to cope = a real unmet need + an uncontrolled data risk. Note both.
-- **Exception-led operating map.** For each real break (not the slide-deck process): what fails, who notices first, what they do today, and which artifact is trusted in that moment. Prefer exceptions over happy-path swimlanes - the workaround is the operating system. Write rows under `terrain.md` → `## Operating map (exception-led)`. If the section is missing on an older engagement, add it; never regenerate the rest of terrain. When AI is in play, also fill `## Intelligence placement` (deterministic vs LLM judgement vs human approve). **`fde doctor` requires at least one filled exception row before plan/build/ship/close** - empty map after discover is a hygiene fail, not optional polish.
+- **Exception-led operating map.** For each real break (not the slide-deck process): what fails, who notices first, what they do today, and which artifact is trusted in that moment. Prefer exceptions over happy-path swimlanes - the workaround is the operating system. Write rows under `terrain.md` → `## Operating map (exception-led)`. If the section is missing on an older engagement, add it; never regenerate the rest of terrain. When AI is in play, also fill `## Intelligence placement` (deterministic vs LLM judgement vs human approve). **`fde doctor` requires at least one filled exception row before plan/ship/outcome/close** - empty map after discover is a hygiene fail, not optional polish.
 
 ## Method - part 3: workshop facilitation
 
@@ -127,9 +137,11 @@ When discovery requires a structured session with multiple stakeholders (alignme
 
 **After the room:** Summary in `decisions.md` within 2 hours. Decisions decay - what felt clear at 3pm is debatable by 5pm if unwritten.
 
-## Method - part 4: data estate assessment
+## Method - part 4: data estate and the pipe
+
+Always map the estate before you score a use case - not only when someone said "AI." A path they cannot feed is a discover miss, not a ship surprise.
 
-When the engagement involves AI, analytics, or data-heavy automation, assess the data estate before scoring use cases:
+**Their words first.** In `terrain.md`, write the names the floor uses for the workaround, the sheet, the exception path, and the person who left. Later plan/ship/review sentences use those names. Do not translate their floor into generic product language.
 
 **The 5 questions (ask the data owner, not the sponsor):**
 1. **Where does data live?** - List every source: databases, warehouses, SaaS exports, spreadsheets, S3 buckets, vendor APIs. Map it.
@@ -138,13 +150,15 @@ When the engagement involves AI, analytics, or data-heavy automation, assess the
 4. **What's the quality?** - Sample 100 rows from each critical source. Check: nulls, duplicates, format consistency, semantic correctness. A 60% null rate in a key field = that source is fiction.
 5. **What are the governance constraints?** - PII classification, retention policies, cross-border rules, consent basis. One missed constraint = a compliance stop later.
 
+**The pipe (what talks to what).** For each source that a use case depends on, write: the system it flows from and to, the contract (object, table, file, API), whose credentials, what happens when the vendor 500s or the Monday file does not land, and whether the join the sponsor described actually exists. Their IdP, CRM, and warehouse are delivery work when the path needs them - policy questions in `trust-profile.md` are not a substitute.
+
 **The data readiness matrix:**
 
-| Source | Location | Freshness | Owner | Quality (sample) | Governance | Verdict |
-|--------|----------|-----------|-------|-----------------|------------|---------|
-| _fill per source_ | | | | | | Ready / Needs work / Blocker |
+| Source | Location | Freshness | Owner | Quality (sample) | Governance | Pipe | Verdict |
+|--------|----------|-----------|-------|-----------------|------------|------|---------|
+| _fill per source_ | | | | | | | Ready / Needs work / Blocker |
 
-A use case that depends on a "Blocker" source doesn't get scored - it gets a data remediation conversation first. Write this to `terrain.md` under a `## Data estate` section.
+A use case that depends on a "Blocker" source **or a Blocker pipe** doesn't get scored - it gets a remediation conversation first. `what-breaks` finding an invisible integration at ship is already too late. Write this to `terrain.md` under a `## Data estate` section.
 
 ## When scope is a transformation, not a single problem
 
@@ -171,7 +185,7 @@ Score every candidate use case before anything gets prototyped:
 **Complication:** <what forces a decision now>
 **Question:** <one decision-shaped sentence>
 **Answer-space:** confirm brief / descope / rescope / pause - and what a yes looks like
-**Implication for build:** <first small PR>
+**Implication for build:** <first change they can see>
 **Validated with:** <who, when>
 ```
 

package/skills/fde/references/earn-trust.md

@@ -1,4 +1,4 @@
-# earn-trust - earning commit access one move at a time
+# earn-trust - Earn access
 
 **Enter when:** new engagement where you don't have full access yet, trust is thin, the customer said "let's start small," or you need to navigate "we don't trust AI-generated code."
 

package/skills/fde/references/encode-pattern.md

@@ -1,4 +1,4 @@
-# encode-pattern - if you did it twice, encode it
+# encode-pattern - Encode the pattern
 
 **Enter when:** the engagement is closing and reusable patterns exist, a technique worked well and will apply to future clients, the FDE notices themselves doing the same thing on a second engagement, or close identified a pattern worth preserving.
 
@@ -47,8 +47,9 @@ The difference between a 5-year FDE and a 15-year FDE is not talent - it's encod
 | **Specific enough?** | Contains concrete steps, not just principles | "Build trust" / "Communicate well" - too vague to act on |
 | **Repeatable?** | Applies to a class of situations, not just this one | Only worked because of a unique circumstance |
 | **Falsifiable?** | You can tell when the pattern is working or not | No way to measure whether applying it helped |
+| **Monday bag?** | You would refuse the next similar embed without this in your bag - a named move plus an artifact you can drop on day one (pipe questions, CAB dance, eval golden shape, floor-drill script) | "We learned to communicate." Patterns that only live in this client's `.fde/` do not compound |
 
-**4. Classify by stage.** Patterns sort into the same stages as the methods:
+**4. Classify by stage.** Patterns sort into the same stages as the skills:
 
 | Stage | Pattern type | Example |
 |--------|-------------|---------|
@@ -56,7 +57,7 @@ The difference between a 5-year FDE and a 15-year FDE is not talent - it's encod
 | **Discover** | Investigative / analytical | "The cron-job discovery checklist for legacy systems" |
 | **Plan** | Structural / strategic | "The three-option presentation for nervous sponsors" |
 | **Ship** | Technical / safety | "The Strangler Fig on financial transaction code" |
-| **Prove** | Operational / process | "The regulated-environment change-approval timeline buffer" |
+| **Outcome** | Operational / process | "The regulated-environment change-approval timeline buffer" |
 | **Close** | Knowledge / handoff | "The 2am document format that actually gets used" |
 
 **5. Version and evolve.** Patterns are living documents:

package/skills/fde/references/eval-pack.md

@@ -1,4 +1,4 @@
-# eval-pack - prove the system before it acts
+# eval-pack - Gate the model before it acts
 
 **Enter when:** the work touches AI/LLM/agents/RAG, or they need to POC a model, or ship/close is blocked because there is no evidence the non-deterministic path is safe. Activate alongside `ai.md`, `poc`, or `ship` - not instead of them.
 
@@ -22,9 +22,9 @@ Intelligence without evidence is token-maxing with a nicer name. An FDE earns tr
 
 **3. Score pass/fail, not vibes.** Run the suite. Record count pass / fail. Failures get a failure-mode tag (missing data, wrong record, format drift, hallucination, retrieval miss, unsafe action, other).
 
-**4. Human-in-the-loop gate.** Name which outcomes require human approve before side effects. If none, write why that is allowed under `trust-profile.md` AI policy - do not invent permission.
+**4. Human-in-the-loop gate.** Name which outcomes require human approve before side effects. Judgement that has a side effect (write, send, transfer, ticket, deploy, pay, page) is **NO-SHIP** without a named human on their side in the loop. Do not write "none - allowed under policy" to bless lights-out write-access. Staging may run a supervised loop with a kill switch, a cost cap, and a golden set from **their** failures. Production stays gated until they have a written policy, a named owner, and dated eval receipts on real traffic.
 
-**5. Ship rule.** Until `evals.md` shows Verdict **SHIP** with a dated run (critical fails = 0) and HITL filled when policy requires it, AI-touching ship stays **fix-first**. Log a one-line eval receipt in `delivery.md` → `## Ship receipts`.
+**5. Ship rule.** Until `evals.md` shows Verdict **SHIP** with a dated run (critical fails = 0) and HITL filled, AI-touching ship stays **fix-first**. Eval fails do not sit in a backlog - they reopen plan (descope, move the judgement, or kill the path). Log a one-line eval receipt in `delivery.md` → `## Ship receipts`. No "probably fine."
 
 ## Artifact - `evals.md`
 
@@ -39,5 +39,5 @@ Present to the FDE: suite size, pass rate, top failure mode, HITL gate, Verdict
 - No golden set, no AI ship.
 - Pass/fail beats “looks good.”
 - Failure modes are the product - the happy path is table stakes.
-- HITL is a gate, not a slide.
+- HITL is a gate, not a slide. Side effects without a named human on their side are NO-SHIP.
 - Non-AI work does not need this file.

package/skills/fde/references/hold-scope.md

@@ -1,4 +1,4 @@
-# hold-scope - holding the line without losing the relationship
+# hold-scope - Hold scope
 
 **Enter when:** "also can you…" mid-build, a stakeholder adds requirements without adjusting timeline, the FDE feels scope creeping but can't name it, or `success.md` no longer matches what's being asked.
 

package/skills/fde/references/ingest.md

@@ -1,4 +1,4 @@
-# ingest - pull large artifacts into the fieldbook loop
+# ingest - Ingest sources
 
 **Enter when:** the FDE wants to catch the engagement up from external sources - "make sure Acme is up to date," "pull what's relevant," "grab today's Granola and Denise's last email." Raw transcripts and long emails that are too big to paste usefully.
 

package/skills/fde/references/land.md

@@ -1,4 +1,4 @@
-# land - first 48 hours
+# land - Interrogate the brief
 
 **Enter when:** new customer, first meeting, just got the brief, nothing started yet.
 
@@ -99,12 +99,12 @@ If `stakeholders.md` already has a `## Signal history` section (it does from the
 
 **`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: skip for status reads; use CLI/redacted surfaces; never paste raw `<private>` into prompts or subagents.
 
-**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with blast radius CRITICAL / LOAD-BEARING / CONVENIENCE and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
+**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with Kind `UNKNOWN` (or `CONVENTION` if they said "we always"), blast radius CRITICAL / LOAD-BEARING / CONVENIENCE, and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
 
 ```markdown
-| # | Assumption | Blast radius | How we test | Status | Evidence |
-|---|------------|--------------|-------------|--------|----------|
-| 1 | <claim from brief> | CRITICAL | <cheapest falsifying test> | OPEN | (stated, unverified) |
+| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
+|---|------------|------|--------------|-------------|--------|----------|
+| 1 | <claim from brief> | UNKNOWN | CRITICAL | <cheapest falsifying test> | OPEN | (stated, unverified) |
 ```
 
 One falsifiable hypothesis about the real problem also goes at the bottom of `brief.md` - discover / test-assumptions will test it.

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

@@ -1,4 +1,4 @@
-# pick-three - when 20 things are "urgent," pick the 3 that matter
+# pick-three - Prioritize three
 
 **Enter when:** a transformation engagement with a long list of initiatives, the customer's roadmap has more items than weeks, competing teams want different things, or the FDE needs to recommend what to do *first* across a complex programme.
 

package/skills/fde/references/plan.md

@@ -1,4 +1,4 @@
-# plan - sequence the work
+# plan - Sequence the work
 
 **Enter when:** scope is understood and the work needs breaking down - a slice, a phase, or the whole delivery.
 

package/skills/fde/references/poc.md

@@ -1,12 +1,16 @@
-# poc - kill or confirm a direction in a day
+# poc - Validate the solution
 
 **Enter when:** a direction needs validating before committing real build time - POC, spike, show something, de-risk, pick between use cases. The output is something a sponsor can reject in a room this week, not a polished product.
 
-**Read first:** `context.md`, `reality.md`. Load `terrain.md` only if the prototype touches the existing codebase.
+**Read first:** `context.md`, `reality.md`. Load `terrain.md` only if the prototype touches the existing codebase. If `terrain.md` **Data estate** has a Blocker source this prototype needs, stop - that is discover, not a day's demo.
+
+A green check on synthetic data is not a validated solution. The person who can say no has to see it on evidence they already believe.
 
 ## Method (you do this work)
 
-**0. Name the killer assumption.** With the FDE: "What's the belief that kills the project if it's wrong?" Prototype **that** - not the pretty demo.
+**0. Name the killer assumption.** With the FDE: "What's the belief that kills the project if it's wrong?" Prototype **that** - not the pretty demo. If `three-options` just ran: the cheapest test is for the recommended option first, unless they pick another.
+
+**0b. Pass / fail before you build.** For the test you will run, write three lines in `prototype-log.md` first: what you will actually do (who you talk to, what you show, on whose screen); the result that **kills** this option; the result that keeps it alive. What you would learn either way. If every option's test would fail, name which `assumptions.md` block to reopen - do not invent a fourth playbook.
 
 **1. Pick by score when several use cases compete.** Use the scoring model from `discover.md` - (Value × Data readiness) / Complexity. If discover already scored, reuse; never re-score independently.
 
@@ -35,6 +39,7 @@ Tell the FDE: did the riskiest assumption hold · what the customer's reaction a
 ## Principles
 
 - Speed of learning beats code quality. Never more than a day.
+- Write pass/fail before you build. A demo with no kill line is a show.
 - Show it rough. Polish misleads.
 - Prototype the killer assumption, not the demo.
 - Kill fast; log the learning.

package/skills/fde/references/readout.md

@@ -1,4 +1,4 @@
-# readout - the sponsor update that keeps the engagement alive
+# readout - Report the outcome
 
 **Enter when:** the weekly update is due, an exec asks "where are we," or the FDE says "I need to send Dana something." This artifact decides renewals; engineers underinvest in it.
 
@@ -12,15 +12,16 @@
 
 | Block | What to write | Source |
 |-------|---------------|--------|
-| **S - Situation** | Where we are against `success.md`, in their words | success.md, delivery value ledger |
+| **S - Situation** | Where we are against `success.md`, in their words - including whether the floor still uses the old path | success.md, delivery value ledger, reality.md workaround |
 | **C - Complication** | What changed, what is at risk, or what we learned (bad news first) | risks.md, assumptions DISPROVED/OPEN, stakeholders signal |
 | **Q - Question / Ask** | The one decision or help you need from them | decisions.md, access/sign-off needs |
 | **A - Answer** | What you recommend / what happens next week (≤3 bullets) | plan Now lane, delivery promised→measured |
 
 Then add, still on the same page:
 1. **Value this week** - from the value ledger: promised → measured (or "pending") → **accepted by whom**, with evidence citation. A measured number nobody on the customer side has agreed to is written as `claimed`, and the Ask never rests on it - if the whole case for the next phase is a claimed number, the real ask this week is "who signs off that this is real?".
-2. **Kill / defer reminder** - one line from the plan kill list so scope fights stay visible.
-3. **Hostile Q prep** - three questions a skeptical sponsor will ask, with one-line answers from memory.
+2. **Are they using it?** - Situation must say whether the workaround is still open: spreadsheet still running, shadow paste still happening, named operator completed Tuesday's job on the new path without you at the keyboard. A measured metric with the old path still live is `claimed`. That week's Ask is not "fund phase 2." It is "who on their side stops the old way, by when."
+3. **Kill / defer reminder** - one line from the plan kill list so scope fights stay visible.
+4. **Hostile Q prep** - three questions a skeptical sponsor will ask, with one-line answers from memory.
 
 Exec voice: no jargon, no hedging, every claim traceable (`(shipped Tue, delivery.md)`). Draft in the **FDE's voice, for the FDE to send** - never send anything yourself.
 

package/skills/fde/references/red-team.md

@@ -1,4 +1,4 @@
-# red-team - adversarial stress-test of your plan, position, or deliverable
+# red-team - Challenge the plan
 
 **Enter when:** the FDE says "red-team this," "stress-test my thinking," "poke holes in this," "what am I missing," "challenge my plan" - or anytime they are about to walk into a high-stakes conversation (sponsor meeting, accumulation conversation, handoff, go-live) and want their blind spots exposed first.