fdeops 3.9.20 → 3.10.0

package/bin/install.js

@@ -53,6 +53,49 @@ function slugify(name) {
     || 'engagement'
 }
 
+// Written into every skill directory this installer creates. Nothing is ever
+// removed or overwritten without it: `healthcare-fde` and `fintech-fde` are
+// plausible names for a skill the user wrote themselves, and a name collision
+// must be reported, not silently resolved by deleting their work.
+const MANAGED_MARKER = '.fdeops-managed'
+
+function markManaged(dir) {
+  let version = 'unknown'
+  try { version = require(path.join(__dirname, '..', 'package.json')).version } catch (_) {}
+  try {
+    fs.writeFileSync(
+      path.join(dir, MANAGED_MARKER),
+      `managed-by: fdeops\nversion: ${version}\ninstalled: ${new Date().toISOString()}\n` +
+      'Delete this file to make fdeops treat the directory as yours and leave it alone.\n',
+    )
+  } catch (_) {}
+}
+
+function isManaged(dir) {
+  return fs.existsSync(path.join(dir, MANAGED_MARKER))
+}
+
+// A skill "directory" that is really a symlink points somewhere outside
+// ~/.claude/skills that fdeops has no claim on. Writing through it would edit
+// files in the user's own tree - refuse even under --force, which is permission
+// to take over this location, not to follow it elsewhere.
+function isLink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink() } catch (_) { return false }
+}
+
+// Fingerprint of a skill fdeops itself wrote before markers existed. Anchored on
+// the shipped frontmatter, not a bare "fdeops" substring: a skill of the user's
+// that merely mentions fdeops in prose is theirs, not ours. Only consulted for a
+// directory whose name matches one we ship, and only to overwrite - never to delete.
+function wasInstalledByUs(dir) {
+  try {
+    const md = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8')
+    const fm = (md.match(/^---\n([\s\S]*?)\n---/) || [])[1]
+    if (!fm) return false
+    return /^description:\s*Engagement fieldbook for Forward Deployed Engineers\b/im.test(fm)
+  } catch (_) { return false }
+}
+
 // v2 shipped 16 standalone skills; v3 is one `fde` skill + references.
 // Leaving the old ones in place would route users to stale content.
 const LEGACY_SKILL_DIRS = [
@@ -62,22 +105,105 @@ const LEGACY_SKILL_DIRS = [
   'gov-fde',
 ]
 
-function removeLegacySkills() {
+function removeLegacySkills(opts = {}) {
   let removed = 0
+  const skipped = []
+  const links = []
   for (const dir of LEGACY_SKILL_DIRS) {
     const p = path.join(GLOBAL_SKILLS_DIR, dir)
-    if (fs.existsSync(path.join(p, 'SKILL.md'))) {
+    if (isLink(p)) { links.push(dir); continue }
+    if (!fs.existsSync(path.join(p, 'SKILL.md'))) continue
+    if (isManaged(p) || opts.force) {
       fs.rmSync(p, { recursive: true, force: true })
       removed++
+    } else {
+      skipped.push(dir)
     }
   }
-  return removed
+  return { removed, skipped, links }
 }
 
-function installSkills() {
-  const removed = removeLegacySkills()
-  if (removed > 0) console.log(`  Removed ${removed} v2 skill dir(s) (now covered by @fde)`)
-  copyDir(SKILLS_SRC, GLOBAL_SKILLS_DIR)
+// Copy each skill in, but never over a directory fdeops did not create.
+function installSkillDirs(opts = {}) {
+  const skipped = []
+  const links = []
+  const failed = []
+  fs.mkdirSync(GLOBAL_SKILLS_DIR, { recursive: true })
+  for (const entry of fs.readdirSync(SKILLS_SRC, { withFileTypes: true })) {
+    const src = path.join(SKILLS_SRC, entry.name)
+    const dest = path.join(GLOBAL_SKILLS_DIR, entry.name)
+    if (!entry.isDirectory()) { fs.copyFileSync(src, dest); continue }
+    if (isLink(dest)) { links.push(entry.name); continue }
+    if (fs.existsSync(dest) && !isManaged(dest) && !opts.force) {
+      // Installs predating the marker are still ours: adopt a same-named dir
+      // whose SKILL.md is recognizably fdeops', so upgrades keep working.
+      if (!wasInstalledByUs(dest)) {
+        skipped.push(entry.name)
+        continue
+      }
+      console.log(`  adopt  ~/.claude/skills/${entry.name} (earlier fdeops install)`)
+    }
+    // One unwritable skill dir must not abort the install with a stack trace:
+    // say it in human terms, place the rest, and exit non-zero at the end.
+    try {
+      copyDir(src, dest)
+      markManaged(dest)
+    } catch (e) {
+      failed.push({ name: entry.name, code: e.code || 'error', path: destPathFor(e.path, src, dest) })
+    }
+  }
+  return { skipped, links, failed }
+}
+
+// A failed copy can surface either side of the operation; the user can only fix
+// the destination, so never point them at a path inside the package.
+function destPathFor(failedPath, src, dest) {
+  if (!failedPath) return dest
+  if (failedPath === src || failedPath.startsWith(src + path.sep)) {
+    return path.join(dest, path.relative(src, failedPath))
+  }
+  return failedPath
+}
+
+function reportCollisions(paths, verb) {
+  if (!paths.length) return
+  console.log(`  skip   ${paths.length} skill dir(s) fdeops did not create - ${verb} would destroy your own work:`)
+  for (const name of paths) console.log(`           ~/.claude/skills/${name}`)
+  console.log('         move or delete them yourself, or re-run with --force to let fdeops take them over')
+}
+
+function reportLinks(names) {
+  if (!names.length) return
+  console.log(`  skip   ${names.length} skill path(s) that are symlinks - fdeops will not write through them:`)
+  for (const name of names) console.log(`           ~/.claude/skills/${name} -> ${readLinkQuiet(path.join(GLOBAL_SKILLS_DIR, name))}`)
+  console.log('         remove the link if you want fdeops to install at that path itself')
+}
+
+function readLinkQuiet(p) {
+  try { return fs.readlinkSync(p) } catch (_) { return '(unreadable)' }
+}
+
+// Anything here means part of the install did not land; cmdInstall exits non-zero.
+let installIncomplete = false
+function reportFailures(failures) {
+  if (!failures.length) return
+  installIncomplete = true
+  console.log(`  error  ${failures.length} skill dir(s) could not be written:`)
+  for (const f of failures) {
+    const why = f.code === 'EACCES' || f.code === 'EPERM' ? 'permission denied' : f.code
+    console.log(`           ~/.claude/skills/${f.name} - ${why} at ${f.path}`)
+  }
+  console.log('         fix the permissions (or remove the directory) and re-run - the rest of the install continued')
+}
+
+function installSkills(opts = {}) {
+  const legacy = removeLegacySkills(opts)
+  if (legacy.removed > 0) console.log(`  Removed ${legacy.removed} v2 skill dir(s) (now covered by @fde)`)
+  const placed = installSkillDirs(opts)
+  reportCollisions(legacy.skipped, 'removing them')
+  reportCollisions(placed.skipped, 'overwriting them')
+  reportLinks([...new Set([...legacy.links, ...placed.links])])
+  reportFailures(placed.failed)
   fs.mkdirSync(GLOBAL_HOOKS_DIR, { recursive: true })
   for (const name of HOOK_SCRIPTS) {
     const src = path.join(HOOKS_SRC, name)
@@ -138,7 +264,7 @@ function placePointer(destPath, content, label, appendable) {
   console.log(`  write  ${label}`)
 }
 
-function cmdAdapters(targetDir) {
+function cmdAdapters(targetDir, opts = {}) {
   const dest = path.resolve(targetDir || process.cwd())
   console.log('')
   console.log(`  fdeops cross-platform adapters → ${dest}`)
@@ -150,7 +276,7 @@ function cmdAdapters(targetDir) {
   // yet, a dangling reference for anyone following the documented Cursor/Codex
   // path. installSkills() is idempotent (safe to call every run).
   if (!fs.existsSync(path.join(GLOBAL_SKILLS_DIR, 'fde', 'SKILL.md'))) {
-    installSkills()
+    installSkills(opts)
     console.log('  Skills → ~/.claude/skills/  (installed - the pointers below need this)')
     console.log('')
   }
@@ -198,11 +324,11 @@ function cmdInit(engagementName) {
   console.log('')
 }
 
-function cmdInstall() {
+function cmdInstall(opts = {}) {
   console.log('')
   console.log('  fdeops - installs on YOUR machine only')
   console.log('')
-  installSkills()
+  installSkills(opts)
   console.log('  Skills → ~/.claude/skills/')
   console.log('  Hooks → ~/.claude/hooks/fdeops-*')
   console.log('  CLI → ~/.claude/fdeops/fde.js  (try: node ~/.claude/fdeops/fde.js scan)')
@@ -220,22 +346,99 @@ function cmdInstall() {
   console.log('  Then open your workspace and use @fde')
   console.log('  Docs: docs/install.md')
   console.log('')
+  // A partly-installed skill set is not success - a script that ran this must be
+  // able to tell, and the reason is already printed above.
+  if (installIncomplete) process.exit(1)
 }
 
 // `npx fdeops scan` must recon, not install - any fde subcommand passes straight
 // through to the CLI (fde.js reads process.argv itself, so require() is enough).
 const FDE_SUBCOMMANDS = [
-  'scan', 'resume', 'triage', 'log', 'debrief', 'ingest', 'prep', 'doctor', 'redact',
-  'garden', 'owner', 'receipts', 'capture', 'status', 'dashboard', 'help',
+  'demo', 'scan', 'resume', 'triage', 'log', 'debrief', 'ingest', 'prep', 'doctor', 'redact',
+  'garden', 'owner', 'receipts', 'capture', 'preserve', 'status', 'dashboard', 'help',
 ]
 
-const arg = process.argv[2]
-if (arg === 'init') {
-  cmdInit(process.argv[3])
-} else if (arg === 'adapters') {
-  cmdAdapters(process.argv[3])
-} else if (FDE_SUBCOMMANDS.includes(arg)) {
+const INSTALL_SUBCOMMANDS = ['init', 'adapters', 'install']
+
+function editDistance(a, b) {
+  let prev = [...Array(b.length + 1).keys()]
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = row
+  }
+  return prev[b.length]
+}
+
+function nearest(word, known) {
+  const w = word.toLowerCase()
+  let best = null
+  let bestScore = 3
+  for (const k of known) {
+    const d = editDistance(w, k)
+    if (d < bestScore) { best = k; bestScore = d }
+  }
+  return best
+}
+
+const argv = process.argv.slice(2)
+const force = argv.includes('--force')
+const positional = argv.filter(a => !a.startsWith('-'))
+const raw = positional[0]
+// `fdeops Demo` is a typo, not a request to rewrite ~/.claude: verbs match
+// case-insensitively, and anything unrecognized fails loudly instead of
+// falling through to a full install. Asking a question (`--help`, `--version`)
+// is not consent to write to the home directory either.
+const known = INSTALL_SUBCOMMANDS.concat(FDE_SUBCOMMANDS)
+const arg = raw ? known.find(k => k === raw.toLowerCase()) : undefined
+const askedHelp = argv.some(a => /^--?(h|help)$/i.test(a))
+const askedVersion = argv.some(a => /^--?(v|version)$/i.test(a))
+
+// Flags before the verb belong to fdeops, so an unknown one is a mistake worth
+// saying out loud - the alternative is honoring `fdeops --all status` by
+// quietly dropping --all.
+const FDEOPS_FLAGS = /^--?(force|h|help|v|version)$/i
+const leading = (raw === undefined ? argv : argv.slice(0, argv.indexOf(raw))).filter(a => !FDEOPS_FLAGS.test(a))
+if (leading.length) {
+  console.error(`  fdeops: unknown option '${leading[0]}'${raw ? ` before '${raw}' - put command options after the command: fdeops ${raw} ${leading[0]}` : ''}`)
+  console.error('  fdeops itself takes only --force, --help and --version.')
+  process.exit(1)
+}
+
+if (raw && !arg) {
+  const guess = nearest(raw, known)
+  console.error(`  fdeops: unknown command '${raw}'${guess ? ` - did you mean '${guess}'?` : ''}`)
+  console.error('  Run `npx fdeops help` for the command list, or `npx fdeops` with no arguments to install.')
+  process.exit(1)
+}
+
+// The verb the user typed may not be argv[0] (`fdeops --force redact ledger`),
+// and fde.js reads process.argv itself - hand it back the positional order it
+// expects with only the verb's case normalized.
+function handOffToCli(verb) {
+  // fde.js reads process.argv itself and takes the verb first, so hand it the
+  // verb (case-normalized) plus everything the user typed after it. A flag
+  // typed BEFORE the verb (`fdeops --force redact ledger`) belongs to fdeops,
+  // not to the command - passing it on would make it part of the command's own
+  // arguments (here: a search term of "--force ledger").
+  const at = raw === undefined ? -1 : argv.indexOf(raw)
+  const rest = at === -1 ? [] : argv.slice(at + 1)
+  process.argv = [process.argv[0], process.argv[1], verb, ...rest]
   require(path.join(__dirname, 'fde.js'))
+}
+
+if (!raw && askedVersion) {
+  console.log(require(path.join(__dirname, '..', 'package.json')).version)
+} else if (!raw && askedHelp) {
+  handOffToCli('help')
+} else if (arg === 'init') {
+  cmdInit(positional[1])
+} else if (arg === 'adapters') {
+  cmdAdapters(positional[1], { force })
+} else if (arg && arg !== 'install') {
+  handOffToCli(arg)
 } else {
-  cmdInstall()
+  cmdInstall({ force })
 }

package/bin/lib/memory.js

@@ -3,7 +3,7 @@
 const { execFileSync } = require('child_process')
 
 // Ephemeral sidecar files - never treated as "manual tamper" dirt.
-const MEMORY_EPHEMERAL = new Set(['.last-write', '.debrief-propose'])
+const MEMORY_EPHEMERAL = new Set(['.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal'])
 
 function createMemoryApi(deps) {
   const { fs, path, gitBinOk, writeOwnerIfMissing, atomicWriteFile } = deps
@@ -131,7 +131,7 @@ function createMemoryApi(deps) {
       execFileSync('git', ['init'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
       atomicWriteFile(
         path.join(eng, '.gitignore'),
-        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', ''].join('\n')
+        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal', ''].join('\n')
       )
       const owner = writeOwnerIfMissing(eng)
       configureMemoryGitIdentity(eng, owner)

package/bin/lib/render.js

@@ -196,6 +196,7 @@ strong{font-weight:600}
 .fb-log-date{font-family:'Geist Mono',monospace;font-size:11.5px;color:var(--ink-faint);flex:0 0 48px}
 .fb-log-kind{font-family:'Geist Mono',monospace;font-size:10px;letter-spacing:.03em;text-transform:uppercase;flex:0 0 62px}
 .fb-log-text{flex:1 1 auto;font-size:14px;line-height:1.5;color:var(--ink)}
+.fb-log-sig{font-family:'Geist Mono',monospace;font-size:10px;letter-spacing:.03em;text-transform:uppercase;white-space:nowrap}
 .fb-more{border-top:1px solid var(--line);padding:12px 0}
 .fb-more:first-child{border-top:none;padding-top:0}
 .fb-more-sum{cursor:pointer;list-style:none;display:flex;align-items:center;gap:6px}
@@ -537,6 +538,7 @@ ${e.log.map(g => `<div class="fb-row fb-log">
 <span class="fb-log-date">${escapeHtml(formatLogDate(g.date))}</span>
 <span class="fb-log-kind t-${g.kind === 'receipt' ? 'green' : g.kind === 'decision' ? 'accent' : 'faint'}">${escapeHtml(g.kind)}</span>
 <span class="fb-log-text">${inlineMd(g.text)}</span>
+${g.sig ? `<span class="fb-log-sig t-${g.sig}" title="trust signal ${escapeHtml(g.sig)}">●&nbsp;${escapeHtml(g.sig)}</span>` : ''}
 </div>`).join('\n')}
 </div>
 </div>` : ''

package/mcp/README.md

@@ -50,6 +50,4 @@ Source MCPs are **not** bundled in fdeops. To add Granola, Gmail, or another pro
 
 FDEOps credentials stay local to the CLI; source MCP credentials stay with that MCP.
 
-## Design reference
-
-See [`docs/plans/2026-07-29-ingest-mcp-design.md`](../docs/plans/2026-07-29-ingest-mcp-design.md) for the approved ingest MCP design.
+**Non-goals:** no bundled OAuth/connectors, no ambient sync, no unreviewed writes to `.fde/`. Method: [`skills/fde/references/ingest.md`](../skills/fde/references/ingest.md).

package/mcp/fdeops-ingest/README.md

@@ -22,7 +22,9 @@ Each tool returns `{ stdout, stderr, status }` from the CLI.
 
 ## Configure in Cursor / Claude
 
-Add to your MCP config (`~/.cursor/mcp.json`, Claude Desktop config, etc.):
+**Agent Plugins clients: nothing to configure.** fdeops ships a root [`mcp.json`](../../mcp.json) declaring this server as `stdio` with a `${PLUGIN_ROOT}`-relative path, so a client that supports [Agent Plugins 1.0.0](https://agent-plugins.org/specification) wires it on install - no absolute paths to edit.
+
+Everywhere else, add to your MCP config (`~/.cursor/mcp.json`, Claude Desktop config, etc.):
 
 ```json
 {

package/mcp/fdeops-ingest/package.json

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

package/mcp/fdeops-ingest/server.js

@@ -70,31 +70,41 @@ const TOOLS = [
 let readBuffer = Buffer.alloc(0)
 
 function writeMessage(obj) {
-  const body = JSON.stringify(obj)
-  process.stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`)
+  process.stdout.write(`${JSON.stringify(obj)}\n`)
 }
 
+// MCP stdio frames messages by newline. Content-Length headers are tolerated on
+// input only, so an LSP-style client still gets through.
 function parseMessages() {
   const messages = []
-  while (true) {
-    const headerEnd = readBuffer.indexOf('\r\n\r\n')
-    if (headerEnd === -1) break
-
-    const header = readBuffer.slice(0, headerEnd).toString('utf8')
-    const match = header.match(/Content-Length:\s*(\d+)/i)
-    if (!match) {
-      readBuffer = readBuffer.slice(headerEnd + 4)
+  while (readBuffer.length) {
+    if (/^Content-Length:/i.test(readBuffer.slice(0, 15).toString('utf8'))) {
+      const headerEnd = readBuffer.indexOf('\r\n\r\n')
+      if (headerEnd === -1) break
+      const header = readBuffer.slice(0, headerEnd).toString('utf8')
+      const match = header.match(/Content-Length:\s*(\d+)/i)
+      if (!match) {
+        readBuffer = readBuffer.slice(headerEnd + 4)
+        continue
+      }
+      const length = parseInt(match[1], 10)
+      const bodyStart = headerEnd + 4
+      if (readBuffer.length < bodyStart + length) break
+      const body = readBuffer.slice(bodyStart, bodyStart + length).toString('utf8')
+      readBuffer = readBuffer.slice(bodyStart + length)
+      try {
+        messages.push(JSON.parse(body))
+      } catch (_) {}
       continue
     }
 
-    const length = parseInt(match[1], 10)
-    const bodyStart = headerEnd + 4
-    if (readBuffer.length < bodyStart + length) break
-
-    const body = readBuffer.slice(bodyStart, bodyStart + length).toString('utf8')
-    readBuffer = readBuffer.slice(bodyStart + length)
+    const newline = readBuffer.indexOf('\n')
+    if (newline === -1) break
+    const line = readBuffer.slice(0, newline).toString('utf8').trim()
+    readBuffer = readBuffer.slice(newline + 1)
+    if (!line) continue
     try {
-      messages.push(JSON.parse(body))
+      messages.push(JSON.parse(line))
     } catch (_) {}
   }
   return messages

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "fdeops-ingest": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/mcp/fdeops-ingest/server.js"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.9.20",
+  "version": "3.10.0",
   "description": "Field kit for engineers embedded in client work - a real CLI (recon, memory, portfolio), one @fde skill with field judgment on top, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
   "bin": {
     "fdeops": "bin/install.js",
@@ -20,7 +20,9 @@
     "adapters/",
     "mcp/",
     "CLAUDE.md.template",
-    "AGENTS.md"
+    "AGENTS.md",
+    "plugin.json",
+    "mcp.json"
   ],
   "keywords": [
     "claude-code",

package/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "fdeops",
+  "version": "3.10.0",
+  "description": "Engagement fieldbook for Forward Deployed Engineers: per-client memory in local .fde/ files, one @fde skill, land to close methodology. Local-only, no network.",
+  "author": {
+    "name": "Subash Natarajan",
+    "url": "https://github.com/suboss87"
+  },
+  "homepage": "https://fdeops.io/",
+  "repository": "https://github.com/suboss87/FDEOps",
+  "license": "MIT",
+  "keywords": [
+    "fde",
+    "forward-deployed",
+    "engagement-memory",
+    "client-work",
+    "consulting",
+    "brownfield"
+  ]
+}

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

@@ -72,6 +72,16 @@ Status values: `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`. A
 
 Tell the FDE: how many assumptions extracted, how many critical, which ones were tested, which changed the direction. If a critical assumption is disproved: recommend the next move (rescope, pivot, or the conversation with the sponsor) before the FDE asks. If any CRITICAL remains OPEN: do not route to plan.
 
+## Worked example
+
+Acme's brief reads cleanly, which is the signal.
+
+Extracted assumptions include one nobody said aloud: *finance would act on an alert*. The whole plan rests on it, and the evidence behind it is a sentence in a kickoff. Blast radius CRITICAL — if false, alerting changes nothing and the engagement delivers a page nobody answers.
+
+Validation is a test, not a discussion, and it is cheap: send one real failure notification to the finance channel and watch what happens. It goes first because highest blast radius × cheapest test is the killer test.
+
+Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and the plan changes before six weeks are spent on it — the alert needs a rota with an owner, which is a different piece of work than the one that was funded. `assumptions.md` records the status, the evidence, and the date; the finding is presented to the FDE as a fact base, not as "the brief was wrong".
+
 ## Principles
 
 - Every "just" is an assumption. Every "should" is an assumption.

package/skills/fde/references/build.md

@@ -127,12 +127,24 @@ The FDE's job is to make themselves replaceable. Not at handoff - every day. A c
 
 - **`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 | 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.
+- **`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.

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

@@ -69,6 +69,16 @@ The sponsor who sees you've identified where the case could break trusts the cas
 
 Walk the FDE through: the cost of doing nothing (anchor), the investment, the return, and the one sensitivity that matters most. If the FDE says "the sponsor won't buy the ROI number" - ask what number they would believe and work backwards from there.
 
+## Worked example
+
+Acme phase 2 needs funding. The case starts with the cost of doing nothing, not the cost of building.
+
+Anchor: two silent failures since March, each one day of finance reconciliation by hand plus a late close (`reality.md`, Marco's sheet). That is the number the sponsor already believes because her own team reported it.
+
+Driver model the sponsor can trace: incidents/quarter × hours of manual reconciliation × loaded cost, plus the tail risk of a late regulatory close — stated separately, because mixing a certain small number with an uncertain large one is how a case loses credibility.
+
+Sensitivity names the two drivers that swing it: incident frequency (2/quarter → 1/quarter and the case halves) and whether the manual re-run continues in parallel (if Marco keeps re-running every morning, the saving is theoretical). The second one is the honest weakness, so it is in the case rather than waiting to be found in the room — with the condition that makes it hold: the morning re-run stops after two clean cycles, agreed with Marco.
+
 ## Principles
 
 - The cost of doing nothing is always the opening move. Anchor before proposing.

package/skills/fde/references/close.md

@@ -18,7 +18,7 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 - AI components: did they behave in production? What failure modes did the prototype hide? Is the team equipped to maintain them?
 
 **1b. Value + receipts close gate (refuse green close if any fail):**
-- Primary value bucket in `success.md` matches what the sponsor funded; at least one ledger row has **Measured** (not forever-`pending`) with evidence for that bucket — or the retrospective explicitly records “not measured; sponsor accepted pending.”
+- Primary value bucket in `success.md` matches what the sponsor funded; at least one ledger row has **Measured** (not forever-`pending`) with evidence **and a named customer-side owner in Accepted by** for that bucket — or the retrospective explicitly records “not measured; sponsor accepted pending.” A measured-but-unaccepted number closes as `claimed`; say so in the retrospective rather than closing green on arithmetic nobody signed.
 - Audit receipt exists for the final shipped path (exceptions/operating map walked; cite file).
 - Eval receipt: **n/a if no AI**, else final golden/eval result + HITL owner recorded; kill switch / fallback named in `handoff.md`.
 - One line in the retrospective: which bucket moved, by how much, vs baseline.
@@ -41,6 +41,16 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 
 Direct assessment to the FDE: did the engagement achieve `success.md` · 2–3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Also: value bucket + audit receipt green; eval **n/a or green**. Pending Measured without sponsor acceptance = gap, not green close. Honest - a gap named now is cheaper than a callback in six weeks.
 
+## Worked example
+
+Acme, twelve weeks in, the FDE is rolling off.
+
+Retrospective against the receipts: `brief.md` asked for monitoring, `reality.md` proved it was ownership — and the delta is the most useful paragraph in the file, because it is exactly the argument the next engagement will need.
+
+The close gate bites in a useful way. The ledger shows detection at 12 minutes measured across two real incidents, but **Accepted by** is empty — Marco confirmed it in Slack, Denise (finance) never did, and Denise is whose escalation started the engagement. So it closes as `claimed` with a one-line retrospective note and a named next step, rather than a green close on a number nobody with budget agreed to.
+
+`handoff.md` is written for the person woken at 2am: the three things that break, what the page means, how to re-run manually the way Marco does, and who holds the tribal knowledge (Raj, who built the original job — credited, because he protects it now). `patterns.md` gets *"unowned job" presents as "unmonitored job"* — it has now happened twice.
+
 ## Principles
 
 - Done = the customer operates without you.

package/skills/fde/references/discover.md

@@ -192,6 +192,16 @@ If discovery revealed the problem is 3× the brief: the FDE tells the customer *
 
 Stop. Don't form a fourth hypothesis. Three disproven reads means the brief is actively misleading - usually the person who briefed doesn't know, or knows and can't say. Change method: stop analysing the system, ask three people separately "if you had to bet on what's actually wrong here, what would you say?" The thing they all hesitate before saying is the real problem.
 
+## Worked example
+
+Acme's brief blamed missing monitoring. Discovery goes to the workaround first.
+
+`git log` shows the reconciliation module at 47 commits/90d with no tests, all from one author who left in February. Marco (ops lead) turns out to keep a spreadsheet: every morning he re-runs the job manually and eyeballs the totals — a habit nobody mentioned because to him it is just the job. That spreadsheet is the system of record when the job fails, which is the actual finding.
+
+`reality.md`: **Confirmed:** the job has no owner, and the manual re-run masks failures for a day (evidence: Marco's sheet, Day 5; two silent failures since March, finance escalation Mar 14). **Stated brief was wrong because:** alerting existed last year and was disabled — adding it again without an owner reproduces the same outcome. `terrain.md` gets the hotspot row and an operating-map row: `job fails silently → Marco notices next morning → re-runs by hand → spreadsheet is truth → LOAD-BEARING (Marco, Day 5)`.
+
+Checkpoint to the FDE names the sponsor decision this creates: fund ownership, or fund alerting and accept the same failure in six months.
+
 ## Principles
 
 - The brief is a hypothesis until evidence confirms it.

package/skills/fde/references/land.md

@@ -79,6 +79,16 @@ Before the end of day 1, ship one visible thing: a small bug fix, a cleanup the
 
 **`success.md`** - what done looks like, **primary value bucket** (`cost-save` | `risk-mitigation` | `revenue-uplift`), baseline → target, who actually signs off, what is explicitly out of scope. Agreed with the customer, not assumed.
 
+For every target number, run the **gaming check** before it is written down: *how could this metric hit its target without the customer being any better off?* There is always an answer, and the answer is what the org will drift toward under pressure. Write the guard next to the metric:
+
+```markdown
+| Metric | Baseline → target | Gamed by | Guard |
+|--------|-------------------|----------|-------|
+| reconciliation alert latency | 4h → 15min | alerting on everything, so nobody reads them | alerts acked by a named owner, ≤2/week |
+```
+
+A metric with no gaming check is a metric the FDE will be held to and cannot defend. If the customer resists the guard, that is the real conversation - they are attached to the number, not the outcome.
+
 **`stakeholders.md`**:
 ```markdown
 | Who | Role | Signal | Notes |
@@ -105,6 +115,16 @@ One page back to the FDE: success + value bucket + sign-off owner, out-of-scope
 
 If remote: trust-building takes ~40% longer - push for a short video call before anything asynchronous.
 
+## Worked example
+
+Kickoff at Acme payments. Priya (VP Eng) sponsors; the brief says "add monitoring to the reconciliation service."
+
+Asking what happens the week after a perfect delivery gets: "I stop hearing about it from finance." That is the real success statement — not monitoring. The previous attempt surfaces too: the platform team built alerting last year, it was turned off. Raj, who built it, is still there and was not in the kickoff — the passed-over team, found on day 1 rather than at the first standup.
+
+What gets written: `success.md` with bucket `risk-mitigation`, `reconciliation failures reach a named owner within 15 min (baseline: 4h, found by finance)`, gaming check `alerting on everything so nobody reads them` → guard `≤2 alerts/week, acked by name`, sign-off Priya. `brief.md` carries the gap list and the hypothesis: *the job is not unmonitored, it is unowned*. `assumptions.md` seeds `"finance would act on an alert" — CRITICAL — OPEN — (stated, unverified)`. `trust-profile.md` records the sacred thing Priya hesitated before naming.
+
+Day-1 deliverable: fix the log line that swallows the job's exit code. Small, visible, in their environment.
+
 ## Principles
 
 - Never start technical work before `success.md` exists.

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

@@ -72,6 +72,16 @@ The full option details in the same entry or linked to a section in `reality.md`
 
 Present the three options and the recommendation. One question to the FDE: "Which option matches what the sponsor can hear right now?" (A risk-averse sponsor after an incident → conservative. A founder pre-fundraise → ambitious.) If unsure: present all three and let the sponsor decide.
 
+## Worked example
+
+Acme: the reconciliation job needs to survive the FDE leaving. Priya asks "so what should we do?"
+
+Three real paths, not a strawman set. **Safe:** keep the job, add the rota and runbook — two weeks, no new failure modes, does nothing about the 47-commits/90d hotspot. **Pragmatic:** extract the settlement-matching step behind a tested interface — six weeks, retires the untested hotspot, needs Raj's time and he currently opposes it. **Aggressive:** rewrite the service — a quarter, fixes everything, and the same team already abandoned this once.
+
+Same dimensions on each, so comparison is instant, and every cost carries a source: the six-week figure is churn-based, not felt.
+
+Recommendation: pragmatic, conditional — *if* Raj is on the design, otherwise safe, because the aggressive path failed here before for exactly the reason it would fail again. `decisions.md` records the decision, who chose it, and the condition, so week 10's "why aren't we rewriting it" has an answer with a date on it.
+
 ## Principles
 
 - Three options, never one. One option is a request for trust; three is a real decision.