fdeops 3.26.0 → 3.27.1

package/bin/fde.js

@@ -36,6 +36,8 @@ const { createMemoryApi } = require('./lib/memory')
 const { createTrustApi } = require('./lib/trust')
 const vault = require('./lib/vault')
 const context = require('./lib/context')
+const { sourceReference, hasSource, datedDecisions } = require('./lib/provenance')
+const { deliverySummary } = require('./lib/delivery-gaps')
 
 const HOME = os.homedir()
 // FDEOPS_ENGAGEMENTS_ROOT isolates init/status/dashboard (and the registry) for
@@ -485,7 +487,11 @@ function formatFsError(err, action, target) {
   return `cannot ${action} ${where}${code ? ` (${code})` : ''}${err && err.message && !code ? ': ' + err.message : ''}`
 }
 
+let debriefTransactionActive = false
+const ownedDebriefLocks = new Set()
+
 function failFs(err, action, target) {
+  if (debriefTransactionActive || ownedDebriefLocks.size) throw new Error(formatFsError(err, action, target))
   console.error(formatFsError(err, action, target))
   process.exit(1)
 }
@@ -501,6 +507,7 @@ function refuseSymlinkWrite(p, opts = {}) {
       const msg = st.isSymbolicLink()
         ? `refused: ${path.basename(p)} is a symlink - write would leave the engagement tree. Replace it with a real file.`
         : `refused: ${path.basename(p)} is not a regular file - remove it and re-run; every write is refused while it is there.`
+      if ((debriefTransactionActive || ownedDebriefLocks.size) && !opts.soft) throw new Error(msg)
       if (opts.soft) return msg
       console.error(msg)
       process.exit(1)
@@ -516,6 +523,8 @@ function refuseSymlinkWrite(p, opts = {}) {
 // Exclusive create lock + retry. Two parallel agent sessions (or hook + CLI)
 // appending the same .fde file otherwise interleave/corrupt under load.
 function withFileLock(targetPath, fn, opts = {}) {
+  if (ownedDebriefLocks.has(targetPath)) return fn()
+  if (debriefTransactionActive || ownedDebriefLocks.size) opts = { ...opts, soft: true }
   const lockPath = targetPath + '.lock'
   const deadline = Date.now() + 5000
   while (true) {
@@ -1396,7 +1405,7 @@ function cmdResume(args) {
     console.log(`NO ENGAGEMENT for this workspace.\nexisting: ${list}\nAsk the human the client name (one question), then run: fde resume --init <client-name>\nDo not tell them to type that command.`)
     process.exit(2)
   }
-  const intro = [resumeTriage(eng), ...hygieneTriageLines(eng), ...recordDigest(eng)].join('\n')
+  const intro = [resumeTriage(eng), firstActionLine(eng), ...hygieneTriageLines(eng), ...recordDigest(eng)].join('\n')
   const ctx = readClean(eng, 'context.md')
   if (args.includes('--full')) {
     console.log(`${intro}\n\nENGAGEMENT: ${eng}\n\n${ctx || '(no context.md yet)'}`)
@@ -1408,10 +1417,11 @@ function cmdResume(args) {
   const success = readClean(eng, 'success.md')
   const risks = readClean(eng, 'risks.md')
   process.stdout.write(context.boundedSections([
-    `${intro}\n\nENGAGEMENT: ${eng}`,
     policy ? `CLIENT POLICY - trust-profile.md\n${policy}` : '',
+    `${intro}\n\nENGAGEMENT: ${eng}`,
     success ? `CURRENT GOALS & ACCEPTANCE - success.md\n${success}` : '',
-    risks ? `RECORDED RISKS - risks.md\n${risks}` : '',
+    risks ? `OPEN RISKS - risks.md\n${extractRisks(eng).map(r => r.text).join('\n') || '(none recorded)'}` : '',
+    `VALUE LEDGER - delivery.md\n${parseValueLedger(eng).rows.map(r => formatValueLedgerLine(r) + '; source: ' + (r.evidence || '(missing)')).join('\n') || '(none recorded)'}`,
     `WORKING CONTEXT - context.md\n${ctx ? resumeView(ctx) : '(no context.md yet)'}`,
   ], maxBytes))
 }
@@ -1631,7 +1641,10 @@ function smartProposeText(input) {
     // the original stays as context, so nothing is invented or lost.
     for (const sentence of bare.split(/(?<=[.!?])\s+/)) {
       const who = signerFromLine(sentence)
-      if (who) { out.push(`signer: ${who}`); break }
+      if (who) {
+        const source = (bare.match(/\[source:\s*[^\]]+\]/i) || [])[0] || ''
+        out.push(`signer: ${who}${source ? ` ${source}` : ''}`); break
+      }
     }
     if (/^(next action|follow-?ups?|action items?|todo):\s*/i.test(bare) ||
         /\b(next action|walk in with|follow up with)\b/i.test(bare)) {
@@ -1639,6 +1652,14 @@ function smartProposeText(input) {
       out.push(`next: ${next}`)
       continue
     }
+    if (/^(?:scope|proposed scope|out of scope):\s*/i.test(bare)) {
+      out.push(`scope: ${bare}`)
+      continue
+    }
+    if (/\b(?:we need|we want|customer asks?|customer asked|please|can you|could you)\b/i.test(bare)) {
+      out.push(`ask: ${bare}`)
+      continue
+    }
     if (/\b(we (decided|agreed)|decided:|decision:|descope|agreed to|agreement was|freeze scope|freeze prompts)\b/i.test(bare)) {
       out.push(`decision: ${bare}`)
     } else if (/\b(open question|who signs|unclear who|unresolved)\b/i.test(bare)) {
@@ -1674,7 +1695,7 @@ function looksLikePersonName(s) {
 
 function signerFromLine(text) {
   const t = String(text || '').replace(/^[-*+]\s+/, '').trim()
-  if (!t) return ''
+  if (!t || /\?|\b(?:not|nobody|unclear|maybe|might|whether|could|should|if|unless|pending|unconfirmed)\b/i.test(t)) return ''
   // "Priya (VP Eng) signs off" → Priya. "Finance controller (Helena) signs off" → Helena.
   const titled = t.match(new RegExp('\\b' + SIGNER_NAME + '\\s+\\(' + SIGNER_NAME + '\\)\\s+' + SIGNER_VERB + '\\b'))
   if (titled) {
@@ -1775,28 +1796,24 @@ function readDebriefInput(args) {
   if (args[0]) {
     const notesPath = args[0].replace(/^~/, HOME)
     let st
-    try { st = fs.statSync(notesPath) } catch (_) { console.error(`cannot read ${args[0]}`); process.exit(1) }
+    try { st = fs.statSync(notesPath) } catch (_) { throw new Error(`cannot read ${args[0]}`) }
     if (st.size > DEBRIEF_MAX_BYTES) {
-      console.error(`debrief refused: ${args[0]} is ${st.size} bytes (max ${DEBRIEF_MAX_BYTES}). Split the notes or paste the relevant section.`)
-      process.exit(1)
+      throw new Error(`debrief refused: ${args[0]} is ${st.size} bytes (max ${DEBRIEF_MAX_BYTES}). Split the notes or paste the relevant section.`)
     }
     let buf
-    try { buf = fs.readFileSync(notesPath) } catch (_) { console.error(`cannot read ${args[0]}`); process.exit(1) }
+    try { buf = fs.readFileSync(notesPath) } catch (_) { throw new Error(`cannot read ${args[0]}`) }
     if (buf.includes(0) || looksLikeBinaryNoise(buf.toString('utf8'))) {
-      console.error(`debrief refused: ${args[0]} looks binary or mostly non-printable. Paste text notes only.`)
-      process.exit(1)
+      throw new Error(`debrief refused: ${args[0]} looks binary or mostly non-printable. Paste text notes only.`)
     }
     input = buf.toString('utf8')
   } else {
     let buf
     try { buf = fs.readFileSync(0) } catch (_) { buf = Buffer.alloc(0) }
     if (Buffer.byteLength(buf) > DEBRIEF_MAX_BYTES) {
-      console.error(`debrief refused: stdin is over ${DEBRIEF_MAX_BYTES} bytes. Split the notes.`)
-      process.exit(1)
+      throw new Error(`debrief refused: stdin is over ${DEBRIEF_MAX_BYTES} bytes. Split the notes.`)
     }
     if (buf.includes(0) || looksLikeBinaryNoise(buf.toString('utf8'))) {
-      console.error('debrief refused: stdin looks binary or mostly non-printable. Paste text notes only.')
-      process.exit(1)
+      throw new Error('debrief refused: stdin looks binary or mostly non-printable. Paste text notes only.')
     }
     input = buf.toString('utf8')
   }
@@ -1809,15 +1826,29 @@ function previewLine(text, max = 240) {
   return `${t.slice(0, max)}… (${t.length} chars)`
 }
 
-function writeProposal(eng, text) {
+function writeProposal(eng, text, { replace = false, locked = false } = {}) {
+  if (!locked && ownedDebriefLocks.has(path.join(eng, DEBRIEF_PROPOSE))) return writeProposal(eng, text, { replace, locked: true })
+  if (!locked) return withFileLock(path.join(eng, DEBRIEF_PROPOSE), () => {
+    ownedDebriefLocks.add(path.join(eng, DEBRIEF_PROPOSE))
+    try { return writeProposal(eng, text, { replace, locked: true }) }
+    finally { ownedDebriefLocks.delete(path.join(eng, DEBRIEF_PROPOSE)) }
+  }, { soft: true })
+  if (!debriefTransactionActive) return withDebriefRecords(eng, () => writeProposal(eng, text, { replace, locked: true }), [DEBRIEF_PROPOSE, DEBRIEF_PRIVATE, DEBRIEF_SEAL])
   const { clean, blocks } = splitPrivate(text, { sealDangling: true })
   const proposePath = path.join(eng, DEBRIEF_PROPOSE)
   const privatePath = path.join(eng, DEBRIEF_PRIVATE)
+  if (fs.existsSync(proposePath) && !replace) {
+    const existing = fs.readFileSync(proposePath, 'utf8')
+    const existingPrivate = readSealedProposal(eng)
+    if (existing !== clean || JSON.stringify(existingPrivate) !== JSON.stringify(blocks)) {
+      throw new Error('pending proposal already exists. Review and apply it first, or explicitly replace it with fde debrief --smart <notes> --replace-proposal.')
+    }
+  }
   // Seal first. A refused or failed sidecar write must not leave behind a
   // proposal whose (private - redacted) marker has nothing left behind it.
   if (blocks.length) {
     const blocked = refuseSymlinkWrite(privatePath, { soft: true })
-    if (blocked) { console.error(blocked); process.exit(1) }
+    if (blocked) throw new Error(blocked)
     withFileLock(privatePath, () => { atomicWriteFile(privatePath, sealedText(blocks), { mode: 0o600 }) })
     try { fs.chmodSync(privatePath, 0o600) } catch (_) {}
   } else {
@@ -1844,12 +1875,12 @@ function stripApprovedStamp(text) {
 
 // One screen a human can confirm in two minutes. The file-by-file routing
 // still prints after this - agents edit prefixes; people read this.
-function printDebriefReview(text) {
-  const buckets = { decided: [], asked: [], open: [], next: [], signer: [] }
+function printDebriefReview(text, eng) {
+  const buckets = { decided: [], asked: [], scope: [], delivery: [], open: [], next: [], signer: [] }
   for (const raw of String(text || '').split('\n')) {
     const line = raw.trim().replace(/^[-*+]\s+/, '')
     if (!line) continue
-    const m = line.match(/^(decision|risk|delivery|contact|next|signer):\s*(.+)$/i)
+    const m = line.match(/^(decision|risk|delivery|contact|next|signer|ask|scope):\s*(.+)$/i)
     if (!m) continue
     const type = m[1].toLowerCase()
     const body = m[2]
@@ -1857,8 +1888,12 @@ function printDebriefReview(text) {
       const who = approvedStamp(body)
       const core = previewLine(stripApprovedStamp(body), 90)
       buckets.decided.push(who ? `${core}  (approved ${who})` : `${core}  (unconfirmed)`)
-    } else if (type === 'delivery') {
+    } else if (type === 'ask') {
       buckets.asked.push(previewLine(body, 100))
+    } else if (type === 'scope') {
+      buckets.scope.push(previewLine(body, 100))
+    } else if (type === 'delivery') {
+      buckets.delivery.push(previewLine(body, 100))
     } else if (type === 'risk') {
       buckets.open.push(previewLine(body, 100))
     } else if (type === 'next') {
@@ -1870,20 +1905,34 @@ function printDebriefReview(text) {
   console.log('REVIEW (one screen - confirm once, then apply)\n')
   const order = [
     ['decided', buckets.decided],
-    ['asked', buckets.asked],
+    ['stated asks', buckets.asked],
+    ['proposed scope', buckets.scope],
+    ['reported delivery (not customer acceptance)', buckets.delivery],
     ['open', buckets.open],
-    ['next', buckets.next],
-    ['signer', buckets.signer],
+    ['next action', buckets.next],
+    ['named signer (authority, not approval)', buckets.signer],
   ]
   let any = false
   for (const [label, items] of order) {
-    if (!items.length) continue
+    if (!items.length) {
+      if (['stated asks', 'proposed scope', 'next action', 'named signer (authority, not approval)'].includes(label)) console.log(`  ${label}: not detected - review the notes`)
+      continue
+    }
     any = true
     console.log(`  ${label}:`)
-    for (const item of items) console.log(`    - ${item}`)
+    for (const item of items.slice(0, 5)) console.log(`    - ${item}`)
+    if (items.length > 5) console.log(`    - ${items.length - 5} more omitted here; review the full proposal before applying.`)
   }
   if (!any) console.log('  (nothing prefixed yet - edit .debrief-propose, then apply)')
-  console.log('')
+  const recorded = eng ? parseValueLedger(eng).rows : []
+  const measured = recorded.some(row => row.state !== 'unmeasured')
+  const evidenced = recorded.some(row => !row.evidenceMissing)
+  const accepted = recorded.some(row => row.state === 'accepted')
+  console.log('  delivery picture (existing record; this proposal does not certify it):')
+  console.log(`    - measurement: ${measured ? 'recorded; check the value ledger' : 'missing - record the observed result'}`)
+  console.log(`    - evidence: ${evidenced ? 'recorded; review its source' : 'missing - cite the test, artifact, or source'}`)
+  console.log(`    - customer approval: ${accepted ? 'recorded for a prior outcome; not this proposal' : 'missing - request explicit acceptance after evidence review'}`)
+  console.log('  Saving this update confirms your record, not customer acceptance.\n')
 }
 
 function latestDatedDecision(md) {
@@ -1901,8 +1950,8 @@ function formatDecisionRecord(line) {
   const raw = String(line || '').trim().replace(/^[-*]\s*/, '')
   const who = approvedStamp(raw)
   const core = stripApprovedStamp(raw)
-  const stamp = who ? `(approved ${who})` : '(unconfirmed)'
-  return previewLine(`${core}  ${stamp}`, 110)
+  const stamp = !hasSource(raw) ? '(CLAIM - source missing)' : who ? `(approved ${who}; source recorded)` : '(unconfirmed; source recorded)'
+  return `${stamp} ${previewLine(core, 110)}`
 }
 
 function changeReviewIssues(eng) {
@@ -1941,7 +1990,79 @@ function readSealedProposal(eng) {
   } catch (_) { return [] }
 }
 
+// A debrief touches several records. Acquire every cooperating writer's lock
+// before the first append, and restore snapshots if an ordinary write fails.
+// This is not a power-loss transaction; no history is deleted or reset.
+function withDebriefRecords(eng, apply, files = ['decisions.md', 'risks.md', 'delivery.md', 'stakeholders.md',
+  'success.md', 'context.md', SIGNAL_LEDGER, LAST_WRITE, DEBRIEF_PROPOSE, DEBRIEF_PRIVATE, DEBRIEF_SEAL]) {
+  files = files.slice().sort()
+  const snapshots = new Map()
+  function lockAt(index) {
+    if (index < files.length) {
+      const target = path.join(eng, files[index])
+      if (ownedDebriefLocks.has(target)) return lockAt(index + 1)
+      return withFileLock(target, () => {
+        ownedDebriefLocks.add(target)
+        try { return lockAt(index + 1) } finally { ownedDebriefLocks.delete(target) }
+      }, { soft: true })
+    }
+    for (const file of files) {
+      const target = path.join(eng, file)
+      const blocked = refuseSymlinkWrite(target, { soft: true })
+      if (blocked) throw new Error(blocked)
+      snapshots.set(target, fs.existsSync(target) ? { bytes: fs.readFileSync(target), mode: fs.statSync(target).mode & 0o777 } : null)
+    }
+    debriefTransactionActive = true
+    try { return apply() } catch (error) {
+      const failed = []
+      for (const [target, previous] of snapshots) {
+        try {
+          if (previous) atomicWriteFile(target, previous.bytes, { mode: previous.mode, soft: true })
+          else if (fs.existsSync(target)) fs.unlinkSync(target)
+        } catch (_) { failed.push(path.basename(target)) }
+      }
+      if (failed.length) throw new Error(`${error.message}; recovery could not restore ${failed.join(', ')}. Inspect these records and the pending proposal before retrying.`)
+      throw new Error(`${error.message}; no record changes kept. The proposal is retained; retry after resolving the cause.`)
+    } finally { debriefTransactionActive = false }
+  }
+  return lockAt(0)
+}
+
+// Limit model-facing review output while preserving the full editable proposal.
+function boundedDebriefPreview(eng, render, { proposal = true, maxBytes = 12000 } = {}) {
+  const original = console.log, originalError = console.error
+  let bytes = 0, omitted = 0
+  const bounded = output => (...args) => {
+    const line = args.join(' ') + '\n'
+    const size = Buffer.byteLength(line)
+    if (bytes + size > maxBytes) { omitted++; return }
+    bytes += size; output(...args)
+  }
+  console.log = bounded(original)
+  console.error = bounded(originalError)
+  let result
+  try { result = render() } finally { console.log = original; console.error = originalError }
+  if (omitted) console.log(proposal
+    ? `\n${omitted} preview lines omitted. Review the complete proposal at ${path.join(eng, DEBRIEF_PROPOSE)} before applying.`
+    : `\n${omitted} preview lines omitted. Review the full input notes before applying.`)
+  return result
+}
+
 function routeDebriefInput(eng, input, { dry, force, sealed = [] }) {
+  if (!dry && !debriefTransactionActive) {
+    ensureMemoryGit(eng)
+    return withDebriefRecords(eng, () => {
+      const result = routeDebriefInput(eng, input, { dry, force, sealed })
+      // Consuming the review is part of the write. If cleanup fails, restoring
+      // both the records and proposal makes the next explicit apply safe.
+      for (const file of [DEBRIEF_PROPOSE, DEBRIEF_PRIVATE, DEBRIEF_SEAL]) {
+        try { fs.unlinkSync(path.join(eng, file)) } catch (error) {
+          if (error.code !== 'ENOENT') throw new Error(formatFsError(error, 'remove', file))
+        }
+      }
+      return result
+    })
+  }
   const d = new Date()
   const date = d.toISOString().slice(0, 10)
   const counts = { decision: 0, risk: 0, delivery: 0, contact: 0, next: 0, signer: 0 }
@@ -2013,6 +2134,18 @@ function routeDebriefInput(eng, input, { dry, force, sealed = [] }) {
 }
 
 function cmdDebrief(args) {
+  const eng = resolveEngagement({ forWrite: true })
+  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exitCode = 2; return }
+  const target = path.join(eng, DEBRIEF_PROPOSE)
+  try {
+    withFileLock(target, () => {
+      ownedDebriefLocks.add(target)
+      try { return runDebrief(args, eng) } finally { ownedDebriefLocks.delete(target) }
+    }, { soft: true })
+  } catch (error) { console.error(error.message); process.exitCode = 1 }
+}
+
+function runDebrief(args, eng) {
   args = args.slice()
   const dryIdx = args.indexOf('--dry-run')
   const dry = dryIdx !== -1
@@ -2027,35 +2160,45 @@ function cmdDebrief(args) {
   const forceIdx = args.indexOf('--force')
   if (forceIdx !== -1) { force = true; args.splice(forceIdx, 1) }
 
-  const eng = resolveEngagement({ forWrite: true })
-  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  const replaceIdx = args.indexOf('--replace-proposal')
+  const replace = replaceIdx !== -1
+  if (replace) args.splice(replaceIdx, 1)
+  if (replace && !smart) throw new Error('--replace-proposal requires --smart <notes>')
 
+  if (!smart && !apply && !dry && fs.existsSync(path.join(eng, DEBRIEF_PROPOSE))) {
+    throw new Error('pending proposal already exists. Review and apply it before writing another debrief.')
+  }
+  if (apply && !smart && args[0] && fs.existsSync(path.join(eng, DEBRIEF_PROPOSE))) {
+    throw new Error('pending proposal already exists. Use debrief --apply without a notes file to apply that review.')
+  }
   let input = ''
   let sealed = []
   if (apply && !smart && !args[0]) {
     try { input = stripControlChars(fs.readFileSync(path.join(eng, DEBRIEF_PROPOSE), 'utf8')) } catch (_) {
       console.error('nothing to apply - run: fde debrief --smart <notes.md>   then   fde debrief --apply')
-      process.exit(1)
+      return void (process.exitCode = 1)
     }
     sealed = readSealedProposal(eng)
     const expected = readSealCount(eng)
     if (expected === null ? (!sealed.length && input.includes(PRIVATE_MARKER)) : sealed.length < expected) {
       console.error(`refused: the proposal seals a private note but ${DEBRIEF_PRIVATE} is missing or unreadable - applying now would drop it silently.`)
       console.error('re-run the propose step (fde debrief --smart <notes> | fde ingest propose <id>).')
-      process.exit(1)
+      return void (process.exitCode = 1)
     }
   } else {
     input = readDebriefInput(args)
   }
 
     if (smart) {
-    const { proposePath, clean, blocks } = writeProposal(eng, smartProposeText(input))
+    const { proposePath, clean, blocks } = writeProposal(eng, smartProposeText(input), { replace })
+    boundedDebriefPreview(eng, () => {
     console.log('SMART PROPOSE (heuristic - review before apply; no new facts invented beyond line rewrites)\n')
-    printDebriefReview(clean)
+    printDebriefReview(clean, eng)
     console.log('Prefix vocabulary (lines that route): decision:  risk:  delivery:  contact:  next:  signer:')
     console.log('Optional on a decision: [approved: Name YYYY-MM-DD]. Missing means unconfirmed.')
     console.log('Everything else → context.md. Keep the prefixes; the preview gate stays.\n')
     routeDebriefInput(eng, clean, { dry: true, force, sealed: blocks })
+    }, { maxBytes: 8000 })
     if (!apply) {
       console.log(`\nproposal saved → ${proposePath}`)
       console.log('confirm:  fde debrief --apply')
@@ -2066,14 +2209,12 @@ function cmdDebrief(args) {
     sealed = blocks
   }
 
-  const { counts, ctxLines, privateBlocks } = routeDebriefInput(eng, input, { dry, force, sealed })
+  const route = () => routeDebriefInput(eng, input, { dry, force, sealed })
+  const { counts, ctxLines, privateBlocks } = boundedDebriefPreview(eng, route, { proposal: false, maxBytes: smart ? 4000 : 12000 })
   if (!dry) {
     const hash = commitMemory(eng, 'debrief', {
       files: ['decisions.md', 'risks.md', 'delivery.md', 'stakeholders.md', 'success.md', 'context.md', SIGNAL_LEDGER],
     })
-    try { fs.unlinkSync(path.join(eng, DEBRIEF_PROPOSE)) } catch (_) {}
-    try { fs.unlinkSync(path.join(eng, DEBRIEF_PRIVATE)) } catch (_) {}
-  try { fs.unlinkSync(path.join(eng, DEBRIEF_SEAL)) } catch (_) {}
     if (hash) console.log(`memory @${hash}`)
   }
   const plural = {
@@ -2193,10 +2334,14 @@ function cmdIngest(args) {
       console.error(`ingest propose refused: staged item is over ${DEBRIEF_MAX_BYTES} bytes after provenance. Split it.`)
       process.exit(1)
     }
-    const { proposePath, clean, blocks } = writeProposal(eng, smartProposeText(input))
+    let proposal
+    try { proposal = writeProposal(eng, smartProposeText(input)) } catch (error) { console.error(error.message); process.exitCode = 1; return }
+    const { proposePath, clean, blocks } = proposal
+    boundedDebriefPreview(eng, () => {
     console.log(`INGEST PROPOSE from ${path.basename(item)} (via:${source})\n`)
-    printDebriefReview(clean)
+    printDebriefReview(clean, eng)
     routeDebriefInput(eng, clean, { dry: true, force: false, sealed: blocks })
+    })
     console.log(`\nproposal saved → ${proposePath}`)
     console.log('confirm:  fde ingest apply')
     console.log('(agent: rewrite lines with decision:/risk:/contact:/next: prefixes before apply)')
@@ -2269,60 +2414,80 @@ function cmdIngest(args) {
 }
 
 function cmdReceipts(args) {
-  const term = args.join(' ')
-  if (!term) { console.error('usage: fde receipts <search term>'); process.exit(1) }
+  const term = args.join(' ').trim()
+  if (!term) { console.error('usage: fde receipts <search term>'); process.exit(2) }
   const eng = resolveEngagement()
-  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
-  const rx = new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
-  // "receipts" answers "what did we AGREE?" - so dated, agreed records are the
-  // receipt. brief.md is the client's hypothesis and reality.md/context.md are
-  // working notes; a hit there is a CLAIM, not an agreement. Keeping them in the
-  // same list let an FDE cite a sales promise as a receipt - so they get a
-  // separate, clearly-labelled section that is never mistaken for the record.
-  const AGREEMENTS = ['decisions.md', 'delivery.md', 'success.md', 'risks.md', 'stakeholders.md']
-  const CLAIMS = ['brief.md', 'assumptions.md', 'reality.md', 'context.md']
-  const collect = files => {
-    const hits = []
-    for (const f of files) {
-      if (!fs.existsSync(path.join(eng, f))) continue
-      // readClean, not raw read: receipts must not grep sealed <private> notes
-      // back out. Redaction can shift line numbers past a multi-line block; the
-      // file:line is advisory - not leaking a sealed secret is worth that.
-      readClean(eng, f).split('\n').forEach((l, i) => {
-        if (rx.test(l)) hits.push(`  ${f}:${i + 1}  ${l.trim().slice(0, 160)}`)
-      })
-    }
-    return hits
-  }
-  const agreed = collect(AGREEMENTS)
-  const claimed = collect(CLAIMS)
-  const dirty = memoryDirtyManual(eng)
-  const dirtySet = new Set(dirty)
-  const dirtyAgreedHits = [...new Set(
-    agreed.map(h => (h.match(/^\s*([^:]+):/) || [])[1]).filter(f => f && dirtySet.has(f))
-  )]
-  if (agreed.length) {
-    console.log('ON RECORD (dated):')
-    agreed.forEach(h => {
-      const file = (h.match(/^\s*([^:]+):/) || [])[1]
-      console.log(h + (file && dirtySet.has(file) ? '  ⚠ dirty file' : ''))
+  if (!eng) { console.error('no engagement - bind a client first'); process.exit(2) }
+  const recordFiles = ['decisions.md', 'delivery.md', 'success.md', 'risks.md', 'stakeholders.md']
+  const workingFiles = ['brief.md', 'assumptions.md', 'reality.md', 'context.md']
+  const dirty = new Set(memoryDirtyManual(eng))
+  const records = [], claims = []
+  for (const file of [...recordFiles, ...workingFiles]) {
+    const document = readClean(eng, file)
+    const decisionSources = new Map()
+    if (file === 'decisions.md') for (const entry of datedDecisions(document)) {
+      const source = sourceReference(entry.text)
+      for (let line = entry.line; line < entry.line + entry.text.split('\n').length; line++) decisionSources.set(line, source)
+    }
+    document.split('\n').forEach((line, i) => {
+      if (!line.toLowerCase().includes(term.toLowerCase())) return
+      const source = decisionSources.get(i + 1) || sourceReference(line)
+      const hit = `  ${file}:${i + 1}  ${line.trim().slice(0, 160)}${source ? ` [source: ${source.slice(0, 160)}]` : ' [source missing]'}${dirty.has(file) ? '  dirty file - review manual edits' : ''}`
+      ;(recordFiles.includes(file) && source ? records : claims).push(hit)
     })
-    if (dirtyAgreedHits.length) {
-      console.log(
-        `⚠ memory dirty (uncommitted manual edits: ${dirtyAgreedHits.join(', ')}) - dated lines above may not match the tamper-evident ledger until reviewed`
-      )
-    }
-  }
-  if (claimed.length) {
-    if (agreed.length) console.log('')
-    console.log('CLAIMS & working notes (stated, NOT an agreement - verify before citing):')
-    claimed.forEach(h => console.log(h))
   }
-  if (!agreed.length && !claimed.length) {
-    console.log(`no record of "${term}" - nothing was ever logged about it. A gap in the record, not proof of absence: if it WAS agreed, log it now, dated today.`)
-  } else if (!agreed.length) {
-    console.log('\n(no dated agreement matched - only unverified claims above. If this was agreed, log it: fde log decision "...")')
+  const sections = ['RECEIPTS: a cited record is not proof of customer approval. File line numbers refer to the redacted view.']
+  if (records.length) sections.push('ON RECORD (dated, source-backed):\n' + records.join('\n'))
+  if (claims.length) sections.push('CLAIMS & working notes (verify source and approval before citing):\n' + claims.join('\n'))
+  if (!records.length && !claims.length) sections.push(`no record of "${term}" - a gap in the record, not proof of absence`)
+  process.stdout.write(context.boundedSections(sections))
+}
+
+// Portable snapshot; stdout is read-only. --out creates a new file and never
+// overwrites an engagement record, existing file, or symlink.
+function cmdHandoff(args, label = 'Handoff') {
+  let parsed
+  try { parsed = context.budgetArgs(args) } catch (e) { console.error(e.message); process.exit(1) }
+  let out = ''
+  if (parsed.args.length) {
+    if (parsed.args.length !== 2 || parsed.args[0] !== '--out' || !parsed.args[1] || parsed.args[1].startsWith('--')) {
+      console.error('usage: fde handoff [--out new-file.md] [--max-bytes 4096..65536]'); process.exit(1)
+    }
+    out = path.resolve(parsed.args[1])
   }
+  const eng = resolveEngagement()
+  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  const success = stripTemplateNoise(readClean(eng, 'success.md'))
+  const signer = ((success.match(/^\*\*Stakeholder who signs off:\*\*[^\S\n]*(.*)$/m) || [])[1] || '').trim()
+  const ledger = parseValueLedger(eng).rows
+  const rowText = r => `- ${r.slice || 'Unnamed slice'}: promised ${r.promised || '(missing)'}; measured ${r.measured || '(missing)'}; accepted by ${r.accepted || '(missing)'}; evidence ${r.evidence || '(missing)'}`
+  const decisions = datedDecisions(readClean(eng, 'decisions.md'))
+  const selected = decisions.slice(-8)
+  const records = selected.filter(d => hasSource(d.text))
+  const claims = selected.filter(d => !hasSource(d.text))
+  const decisionText = d => `${d.text} (decisions.md:${d.line}, redacted view)`
+  const next = stripTemplateNoise(sectionBody(readClean(eng, 'context.md'), 'Next action', { lastNonEmpty: true }))
+  const gaps = collectDoctorIssues(eng, { readiness: true })
+  const report = context.boundedSections([
+    `# ${label}: ${engagementSlugFromPath(eng)}\nSnapshot: ${new Date().toISOString()} · memory ${memoryHead(eng) || 'unversioned'}\nRead-only record, not proof of approval. Confirm sources with the named customer before relying on a claim. Private blocks are excluded; review remaining client information before sharing.`,
+    `## Constraints - trust-profile.md\n${stripTemplateNoise(readClean(eng, 'trust-profile.md')) || '(missing)'}`,
+    `## Signer and success - success.md\nSigner: ${signer || '(missing; do not infer)'}\n${success || '(missing)'}`,
+    `## Next action - context.md\n${next || '(missing)'}\n\n## Open risks - risks.md\n${extractRisks(eng).map(r => '- ' + r.text).join('\n') || '(none recorded; not proof of no risk)'}`,
+    `## Accepted value - recorded assertion with source\nOnly structured value-ledger rows are summarized here; review other notes in delivery.md before presenting or handing over this record.\n${ledger.filter(r => r.state === 'accepted').map(rowText).join('\n') || '(none)'}\n\n## CLAIMS and unmeasured promises\n${ledger.filter(r => r.state !== 'accepted').map(r => rowText(r) + ' [' + r.state + ']').join('\n') || '(none)'}`,
+    `## ON RECORD decisions - source supplied, not automatic approval\n${records.map(decisionText).join('\n') || '(none)'}\n\n## CLAIM decisions - source missing\n${claims.map(decisionText).join('\n') || '(none)'}\nSelected ${selected.length} of ${decisions.length} dated decisions. Retrieve older or conflicting decisions with fde recall.`,
+    `## Gaps before relying on this packet\n${gaps.map(g => '- ' + g).join('\n') || '(no deterministic lint gaps; human review still required)'}`,
+  ], parsed.maxBytes)
+  if (!out) { process.stdout.write(report); return }
+  try {
+    // Exclusive creation fails closed for files and links. Resolve the parent
+    // first so a directory link cannot redirect an export into .fde/.
+    const parent = fs.realpathSync(path.dirname(out))
+    const target = path.join(parent, path.basename(out))
+    const root = fs.realpathSync(eng)
+    if (parent.split(path.sep).includes('.fde') || target === root || target.startsWith(root + path.sep)) throw new Error('export outside .fde/; engagement records are not export destinations')
+    fs.writeFileSync(target, report, { flag: 'wx', mode: 0o600 })
+    console.log(`${label.toLowerCase()} → ${out}`)
+  } catch (e) { console.error(`could not export packet: ${e.message}`); process.exit(1) }
 }
 
 function cmdRecall(args) {
@@ -2552,7 +2717,33 @@ function silentCommitIssues(eng) {
 // Deterministic fieldbook hygiene - shared by doctor + session TRIAGE.
 // Silent when clean OR brand-new (no dated work yet). Never auto-rewrites.
 // High-value moments: week-start (via triage), ship/close, after real work accrues.
-function collectDoctorIssues(eng) {
+function successContractIssues(success) {
+  const issues = []
+  const text = stripTemplateNoise(String(success || ''))
+  const checks = []
+  let active = -1
+  for (const line of text.split('\n')) {
+    const header = line.match(/^(?:\*\*)?(?:Done when|Acceptance check)(?:\s*\([^\n)]*\))?:(?:\*\*)?[^\S\n]*(.*)$/i)
+    if (header) { checks.push(header[1].trim()); active = checks.length - 1; continue }
+    if (/^#{1,6}\s|^\*\*[^*]+:/.test(line)) { active = -1; continue }
+    if (active !== -1 && line.trim()) checks[active] += ` ${line.trim()}`
+  }
+  const observable = checks.some(check => {
+    const stimulus = /\b(?:test|drill|replay|runs?|request|sample|given|when|simulate|inject|compare|restore|verified|observed|measured)\b/i.test(check)
+    const result = /\b(?:returns?|rejects?|matches?|equals?|arrives?|alerts?|restores?|passes?|fails?|contains?|produces?|shows?|remains?|receives?)\b/i.test(check)
+    const target = /(?:\b(?:within|under|at most|at least|exactly|zero|no missing|no duplicate|all|every|none|true|false|pass|fail|http)\b|[<>=])/i.test(check)
+    return stimulus && result && target && !/\b(?:tbd|to be defined|improve|better|satisfactory|as expected|works well)\b/i.test(check)
+  })
+  if (!observable) issues.push('success.md needs a binary acceptance check: state a test/input and an observable pass/fail result under **Done when:** or **Acceptance check:**; numbers alone are not a check')
+  const signerLine = ((text.match(/^\*\*Stakeholder who signs off:\*\*[^\S\n]*(.*)$/m) || [])[1] || '').replace(/\[source:[^\]]+\]/gi, '').trim()
+  // A named primary signer may be followed by responsibilities or another
+  // signer's role. Preserve the full record; validate only the leading name.
+  const signer = (signerLine.match(/^((?:[A-Z]\.|[A-Z][\w'-]+)(?:\s+(?:[A-Z]\.|[A-Z][\w'-]+)){0,2})(?=\s*(?:[.,;:]|\(|$))/) || [])[1] || ''
+  if (!looksLikePersonName(signer) || /\b(?:pending|unknown|tbd|nobody|none|unassigned|unconfirmed)\b/i.test(signer)) issues.push('success.md needs a named customer-side signer under **Stakeholder who signs off:**; a team, role, or pending name is not authority')
+  return issues
+}
+
+function collectDoctorIssues(eng, { readiness = false } = {}) {
   const issues = []
   const s = computeSignals(eng)
   // stripTemplateNoise: a dated example inside a template comment is not work.
@@ -2577,7 +2768,7 @@ function collectDoctorIssues(eng) {
       issues.push(`${f} is not a regular file - reads come back empty and every write fails; remove it and re-run any fde write`)
     }
   }
-  if (fresh) return issues
+  if (fresh && !readiness) return issues
 
   if (s.phase === '?' || s.phase === 'unset') {
     if (hasDatedWork) {
@@ -2609,7 +2800,11 @@ function collectDoctorIssues(eng) {
       issues.push(`${file} has ${unclosed} unclosed <private> - everything after it is sealed, including notes added later`)
     }
   }
+  const { hasSource } = require('./lib/provenance')
+  const unsourced = readClean(eng, 'decisions.md').split('\n').filter(line => /^[-*]\s*\[\d{4}-\d{2}-\d{2}\]/.test(line.trim()) && !hasSource(line))
+  if (unsourced.length) issues.push(`${unsourced.length} dated decision(s) remain CLAIM: source missing - add the actual meeting, transcript, email, or artifact reference; a log date is not evidence`)
   const success = readClean(eng, 'success.md')
+  if (readiness || /^(plan|ship|outcome|close)$/.test(s.phase)) issues.push(...successContractIssues(success))
   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 })) {
@@ -2802,7 +2997,7 @@ function hasValueBucket(eng) {
 }
 
 // Shared classification keeps CLI, dashboard, and vault acceptance consistent.
-const { PENDING_CELL_RE, valueState } = require('./lib/value-ledger')
+const { PENDING_CELL_RE, valueState, evidenceSource } = require('./lib/value-ledger')
 
 function parseValueLedger(eng) {
   // Last section with actual rows, not merely the last non-empty one: a template
@@ -2832,7 +3027,7 @@ function parseValueLedger(eng) {
     const evidence = cell(row, idx.evidence)
     const acceptanceStatus = idx.acceptanceStatus === -1 ? undefined : cell(row, idx.acceptanceStatus)
     const state = valueState({ measured, accepted, acceptanceStatus, evidence })
-    rows.push({ slice, promised, measured, accepted, evidence, evidenceMissing: !evidence || PENDING_CELL_RE.test(evidence), state })
+    rows.push({ slice, promised, measured, accepted, evidence, evidenceMissing: !evidenceSource(evidence), state })
   }
   return { rows, columnMissing: idx.accepted === -1 }
 }
@@ -2936,8 +3131,26 @@ function hygieneTriageLines(eng) {
   ]
 }
 
+function deliverySummaryFor(eng) {
+  const signals = computeSignals(eng)
+  const next = stripTemplateNoise(sectionBody(readClean(eng, 'context.md'), 'Next action', { lastNonEmpty: true })).trim()
+  const signer = ((readClean(eng, 'success.md').match(/^\*\*Stakeholder who signs off:\*\*[^\S\n]*(.*)$/m) || [])[1] || '').trim()
+  return deliverySummary({ signals, next, hasNext: !!next,
+    hasSigner: !!require('./lib/value-ledger').acceptanceName(signer),
+    highRisks: extractRisks(eng).filter(r => r.severity === 'high').length,
+    valueRows: parseValueLedger(eng).rows,
+    quiet: signals.ageDays !== Infinity && signals.ageDays >= 3,
+  })
+}
+
+function firstActionLine(eng) {
+  const action = deliverySummaryFor(eng).firstAction
+  return `  do first: ${previewLine(action.text, 140)} (${action.source}: ${previewLine(action.reason, 140)})`
+}
+
 function printTriageBlock(eng) {
   console.log(resumeTriage(eng))
+  console.log(firstActionLine(eng))
   for (const line of hygieneTriageLines(eng)) console.log(line)
 }
 
@@ -2960,16 +3173,15 @@ function recordDigest(eng) {
     const target = ((success.match(/^\*\*Baseline[^\S\n]*→[^\S\n]*target:\*\*[^\S\n]*(.*)$/m) || [])[1] || '').trim()
     if (target) lines.push(`  promised: ${target.slice(0, 110)}`)
   }
-  const decisions = readClean(eng, 'decisions.md').split('\n')
-    .filter(l => /^-\s*\[\d{4}-\d{2}-\d{2}\]/.test(l.trim())).slice(-2)
-  for (const d of decisions) lines.push(`  decided: ${formatDecisionRecord(d)}`)
+  const decisions = datedDecisions(readClean(eng, 'decisions.md')).slice(-2)
+  for (const d of decisions) lines.push(`  decided: ${formatDecisionRecord(d.text)}; source: ${previewLine(sourceReference(d.text) || '(missing)', 100)}`)
   return ['RECORD (read-only - success, delivery, decisions)', ...lines]
 }
 
-function cmdDoctor() {
+function cmdDoctor(args = []) {
   const eng = resolveEngagement()
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
-  const issues = collectDoctorIssues(eng)
+  const issues = collectDoctorIssues(eng, { readiness: args.includes('--ready') })
   console.log(`FDE DOCTOR - ${engagementSlugFromPath(eng)}`)
   printTriageBlock(eng)
   if (!issues.length) {
@@ -3399,6 +3611,7 @@ function cmdDashboard(args) {
     e.log = extractLog(e.dir)
     e.stats = extractStats(e.dir)
     e.valueRows = parseValueLedger(e.dir).rows
+    e.hasSigner = !deliverySummaryFor(e.dir).gaps.some(g => g.kind === 'signer')
     e.highRisks = e.risks.filter(r => r.severity === 'high').length
     e.quiet = e.signals.ageDays !== Infinity && e.signals.ageDays >= 3
     e.slug = slugify(e.name)
@@ -3423,7 +3636,13 @@ function cmdDashboard(args) {
   const html = render.buildFieldbookHtml({ engagements, today, generatedAt: new Date().toISOString() })
 
   try {
+    const isRecordPath = p => p.split(path.sep).some(part => ['.fde', '.git'].includes(part.toLowerCase()))
+    if (isRecordPath(outPath)) throw new Error('save the dashboard outside .fde/ and .git/; these folders hold records, not reports')
+    let existingParent = path.dirname(outPath)
+    while (!fs.existsSync(existingParent)) existingParent = path.dirname(existingParent)
+    if (isRecordPath(fs.realpathSync(existingParent))) throw new Error('save the dashboard outside .fde/ and .git/; this path points into a record folder')
     fs.mkdirSync(path.dirname(outPath), { recursive: true })
+    if (isRecordPath(fs.realpathSync(path.dirname(outPath)))) throw new Error('save the dashboard outside .fde/ and .git/; this path points into a record folder')
     atomicWriteFile(outPath, html)
   } catch (e) {
     failFs(e, 'write fieldbook', outPath)
@@ -3623,13 +3842,15 @@ function cmdVault(args) {
 // here fabricates output: the fieldbook you see is what debrief/log actually
 // wrote, so the demo cannot drift from the product.
 const DEMO_SLUG = 'acme-payments'
-const DEMO_NOTES = `Kickoff call with Acme payments team - Priya (VP Eng, sponsor), Tom (staff eng)
+const DEMO_NOTES = `Fictional kickoff transcript - Acme payments, meeting 2026-09-10
 
-decision: settle on the existing Stripe connector instead of the in-house rewrite - Priya wants the Q3 audit clean first
-risk: nobody can name who owns the reconciliation job; it has failed silently twice since March
-delivery: read-only access to the payments repo and the last 90 days of audit logs
-contact: Priya is bought in but travelling for two weeks - Tom is the day-to-day decision maker
-next: get the reconciliation runbook from Tom before touching anything
+We need read-only access to the payments repo and the last 90 days of audit logs. [source: meeting 2026-09-10]
+We agreed to settle on the existing Stripe connector instead of the in-house rewrite - Priya wants the Q3 audit clean first. [source: meeting 2026-09-10]
+Proposed scope: repair reconciliation alerts; leave the connector rewrite out pending sponsor confirmation. [source: meeting 2026-09-10]
+Risk: nobody can name who owns the reconciliation job; it has failed silently twice since March. [source: meeting 2026-09-10]
+Priya Shah signs off on the acceptance test. [source: meeting 2026-09-10]
+Priya is travelling for two weeks - Tom is the day-to-day contact. [source: meeting 2026-09-10]
+Next action: get the reconciliation runbook from Tom before touching anything. [source: meeting 2026-09-10]
 
 <private>
 Priya hinted the previous vendor was let go mid-contract. Do not repeat this to the team.
@@ -3644,14 +3865,17 @@ const DEMO_LAND_ARTIFACTS = {
 
 **As stated:** clean up payment reconciliation before the Q3 audit.
 **What we heard instead:** nobody owns the reconciliation job, and it fails silently.
-**Out of scope (agreed):** the in-house connector rewrite.
+**Proposed out of scope:** the in-house connector rewrite; sponsor confirmation is still required.
 `,
   'success.md': `# Success
 
-- Reconciliation failures alert someone within 15 minutes, with a named owner.
-- The Q3 audit can trace any settlement discrepancy to a dated record.
+**Done when:** Replay a failed settlement in staging; its alert arrives at the on-call queue within 15 minutes.
+**Primary value bucket:** risk-mitigation
+**Baseline → target:** no reliable alert → an alert within 15 minutes of a simulated failure.
+**Explicitly out of scope:** connector rewrite (proposed; not customer-approved).
+**Stakeholder who signs off:** Priya Shah [source: meeting 2026-09-10]
 
-**Signed off by:** Priya (VP Eng) - 2026-08-07
+Acceptance is pending. The named signer identifies authority, not an approval.
 `,
 }
 
@@ -3705,11 +3929,13 @@ function cmdDemo(args) {
   fdeops demo - a fake client, real commands, nothing sent anywhere
 
   Sandbox:  ${root}
-  Fake client: Acme (payments platform). No data of yours is read or written.`)
+  Fake client: Acme (payments platform). This writes fictional notes, local Git history, and HTML inside the sandbox above.
+  It resets that sandbox on repeat runs; real client records stay untouched.
+  Allow under five minutes. Fictional proposal approval is automatic in this demo only.`)
 
   demoStep('1. Monday of week 1 - create the fieldbook for this client', ['resume', '--init', DEMO_SLUG], workspace, env)
   demoStep('2. You walk out of the kickoff with messy notes - hand them over', ['debrief', '--smart', notes], workspace, env)
-  demoStep('3. You confirm. Only now does anything enter the record', ['debrief', '--apply'], workspace, env)
+  demoStep('3. Demo automatically confirms the fictional record (not customer acceptance)', ['debrief', '--apply'], workspace, env)
   demoStep('4. Say where you are in the engagement', ['log', 'phase', 'land'], workspace, env)
   const engDir = path.join(root, DEMO_SLUG, '.fde')
   console.log(`\n${demoHead('5. During land, @fde drafts the brief and the definition of done with you')}`)
@@ -3730,11 +3956,12 @@ function cmdDemo(args) {
   // about uncommitted manual edits - correct behaviour, wrong lesson for a demo.
   const landHash = commitMemory(engDir, 'land: brief + success', { files: [...Object.keys(DEMO_LAND_ARTIFACTS), 'context.md'] })
   if (landHash) console.log(`  memory @${landHash}`)
-  demoStep('6. Two days later, the sponsor goes quiet', ['log', 'contact', 'Priya has not replied to two emails about the runbook', '--signal', 'amber'], workspace, env)
-  demoStep('7. Next morning, a fresh agent session with no memory of any of this', ['resume'], workspace, env)
-  demoStep('8. A meeting in ten minutes - what do you walk in knowing?', ['prep', 'sponsor check-in'], workspace, env)
-  demoStep('9. Six weeks later: "we never agreed to drop the rewrite"', ['receipts', 'rewrite'], workspace, env)
-  demoStep('10. The whole engagement on one page', ['dashboard'], workspace, env)
+  demoStep('6. Add a fictional measured result with evidence, still awaiting customer acceptance', ['log', 'delivery', 'Reconciliation alert | risk-mitigation | alert within 15 minutes | alert in 8 minutes | pending | PR#42 staging replay | revert alert rule'], workspace, env)
+  demoStep('7. Two days later, the sponsor goes quiet', ['log', 'contact', 'Priya has not replied to two emails about the runbook', '--signal', 'amber'], workspace, env)
+  demoStep('8. Next morning, a fresh agent session with no memory of any of this', ['resume'], workspace, env)
+  demoStep('9. A meeting in ten minutes - what do you walk in knowing?', ['prep', 'sponsor check-in'], workspace, env)
+  demoStep('10. Six weeks later: "we never agreed to drop the rewrite"', ['receipts', 'rewrite'], workspace, env)
+  demoStep('11. The whole engagement on one page', ['dashboard'], workspace, env)
   // cmdDashboard's default out path, computed rather than scraped from its output:
   // a HOME with a space in it truncates any whitespace-delimited parse.
   const html = path.join(root, 'fieldbook-current.html')
@@ -3743,8 +3970,10 @@ function cmdDemo(args) {
   ${demoHead('What just happened')}
 
   - Every line above came from the real CLI - no canned output.
-  - The kickoff notes became dated decisions, risks, deliveries and a stakeholder
-    signal, and you confirmed before any of it was written.
+  - The kickoff notes became proposed asks, scope, dated decisions, risks, and a
+    next action. This demo applied fictional notes automatically after showing REVIEW.
+  - PR#42 is fictional evidence for a measured result. The ledger still says claimed:
+    naming Priya as signer does not mean she accepted the result.
   - The <private> block in those notes never appears in resume, prep, receipts or
     the dashboard - it is sealed in context.md and redacted from anything an agent
     or a screen share can see.
@@ -3774,17 +4003,20 @@ function printUsage() {
   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; REVIEW first (decided/asked/open/next/signer); --apply after one confirm
+    --replace-proposal    explicitly discard a pending review when proposing different notes
   fde ingest stage …       stage raw pull into <engagement>/.inbox/ (not .fde/)
   fde ingest list          list staged inbox items
   fde ingest propose <id>  smart-propose a staged item → .debrief-propose (confirm before apply)
   fde ingest apply         same as: fde debrief --apply
   fde prep [label]         grounded walk-in brief from existing .fde/ only
-  fde doctor               lint engagement memory (stale signals, gaps). status/dashboard/resume print the same issues
+  fde doctor [--ready]     lint memory; --ready checks success before plan/build. Lint (stale signals, gaps). status/dashboard/resume print the same issues
   fde redact <term>        preview/remove lines containing a buried term (pass --apply to commit; subject never repeats the term)
   fde tidy [--apply]       propose consolidations; blesses hand-written dirty files when you apply
   fde owner [set email]    who keeps this engagement record
   fde recall <topic>       bounded, redacted source excerpts (--max-bytes 4096..65536)
-  fde receipts <term>      "what did we agree?" with dates
+  fde receipts <term>      source-backed records versus claims
+  fde defend              sponsor readout: accepted assertions, claims, sources, gaps
+  fde handoff [--out file] portable redacted packet; stdout by default, new file only
   fde status [--all]       value ledger, then trust (pass --all for full portfolio)
   fde dashboard [--all] [--open] [--out <path>]  bound fieldbook (pass --all for every client)
   fde vault                derived Obsidian vault of every engagement (--current for one, --redacted for a shared screen, --out <dir>)
@@ -3810,13 +4042,15 @@ switch (cmd) {
   case 'debrief': cmdDebrief(args); break
   case 'ingest': cmdIngest(args); break
   case 'prep': cmdPrep(args); break
-  case 'doctor': cmdDoctor(); break
+  case 'doctor': cmdDoctor(args); break
   case 'redact': cmdRedact(args); break
   // `garden` was the name through 3.11.x; it keeps working.
   case 'tidy':
   case 'garden': cmdGarden(args); break
   case 'owner': cmdOwner(args); break
   case 'receipts': cmdReceipts(args); break
+  case 'handoff': cmdHandoff(args); break
+  case 'defend': cmdHandoff(args, 'Sponsor readout'); break
   case 'capture': cmdCapture(); break
   case 'preserve': cmdPreserve(); break
   case 'status': cmdStatus(args); break