fdeops 3.27.0 → 3.28.0

package/bin/fde.js

@@ -487,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)
 }
@@ -503,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)
@@ -518,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) {
@@ -833,7 +840,7 @@ function valueLedgerRowCount(body) {
   return t.rows.filter(r => r.some(c => String(c || '').trim())).length
 }
 
-function appendValueLedgerRow(eng, cells) {
+function appendValueLedgerRow(eng, cells, { skipCommit = false } = {}) {
   ensureMemoryGit(eng)
   const p = path.join(eng, 'delivery.md')
   let row
@@ -880,7 +887,7 @@ function appendValueLedgerRow(eng, cells) {
     atomicWriteFile(p, md.endsWith('\n') ? md : md + '\n')
   })
   recordLastWrite(eng, 'delivery.md', row)
-  commitMemory(eng, 'log delivery', { files: ['delivery.md'] })
+  if (!skipCommit) commitMemory(eng, 'log delivery', { files: ['delivery.md'] })
 }
 
 function retireOpenRisks(eng, needle) {
@@ -976,7 +983,7 @@ const {
   countOpenRisks,
 } = createTrustApi({
   fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
-  stripTemplateNoise, stripLegendLines,
+  stripTemplateNoise, stripLegendLines, extractRisks,
 })
 
 // Stakeholders: columns are matched by header wording, not position - real
@@ -1092,14 +1099,14 @@ function extractStakeholders(eng) {
 
 // Risks: table rows AND dated CLI/debrief bullets. Empty template cells ignored.
 function extractRisks(eng) {
-  const md = readClean(eng, 'risks.md')
+  const md = stripTemplateNoise(readClean(eng, 'risks.md'))
   const body = md.split(/^#{1,6}\s+Retired\b/im)[0] || md
   const HIGH = /critical|blocker|exposure|breach|urgent|at risk|at stake|\brace\b|rollback|no test/i
   const out = []
   const seen = new Set()
   const push = (text) => {
     const t = String(text || '').trim()
-    if (!t || seen.has(t.toLowerCase())) return
+    if (!t || /^(?:\[[xX]\]\s|(?:closed|resolved|retired)\s*:)/i.test(t) || seen.has(t.toLowerCase())) return
     seen.add(t.toLowerCase())
     out.push({ text: t, severity: HIGH.test(t) ? 'high' : 'med' })
   }
@@ -1107,13 +1114,23 @@ function extractRisks(eng) {
   if (table) {
     const riskIdx = colIndex(table.headers, /^risk$/i)
     if (riskIdx !== -1) {
-      for (const cs of table.rows) push(cs[riskIdx])
+      const statusIdx = colIndex(table.headers, /^status$/i)
+      for (const cs of table.rows) {
+        if (statusIdx !== -1 && /^(closed|resolved|retired)$/i.test((cs[statusIdx] || '').trim())) continue
+        push(cs[riskIdx])
+      }
     }
   }
   for (const raw of body.split('\n')) {
     const t = raw.trim()
     const m = t.match(/^-\s*\[\d{4}-\d{2}-\d{2}\]\s*(?:\[@[^\]]+\]\s*)?(.*)$/)
     if (m) push(m[1])
+    else {
+      // Inherited Markdown may predate the dated CLI format. Keep its open
+      // bullets visible; absence of a date does not mean absence of a risk.
+      const bullet = t.match(/^[-*+]\s+(.*)$/)
+      if (bullet && !/^\[[xX]\]\s/.test(bullet[1])) push(bullet[1].replace(/^\[ \]\s*/, ''))
+    }
   }
   return out
 }
@@ -1534,7 +1551,8 @@ function cmdLog(args) {
     return
   }
   if (type === 'delivery' && text.includes('|')) {
-    const cells = text.split('|').map(s => s.trim())
+    let cells
+    try { cells = deliveryCells(text) } catch (error) { console.error(error.message); process.exitCode = 1; return }
     appendValueLedgerRow(eng, cells)
     const hash = memoryHead(eng)
     console.log(`logged → delivery.md (value ledger)${hash ? ` @${hash}` : ''}`)
@@ -1789,28 +1807,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')
   }
@@ -1823,15 +1837,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 {
@@ -1859,6 +1887,8 @@ 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, eng) {
+  const repeats = repeatedDebriefStatements(eng, text)
+  if (repeats.length) console.log(`REPLAY WARNING: ${repeats.length} source-backed statement(s) already recorded. Review newer facts and next action; applying again requires --allow-replay.\n`)
   const buckets = { decided: [], asked: [], scope: [], delivery: [], open: [], next: [], signer: [] }
   for (const raw of String(text || '').split('\n')) {
     const line = raw.trim().replace(/^[-*+]\s+/, '')
@@ -1898,12 +1928,13 @@ function printDebriefReview(text, eng) {
   let any = false
   for (const [label, items] of order) {
     if (!items.length) {
-      if (['stated asks', 'proposed scope', 'next action', 'named signer (authority, not approval)'].includes(label)) console.log(`  ${label}: not stated`)
+      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)')
   const recorded = eng ? parseValueLedger(eng).rows : []
@@ -1972,13 +2003,116 @@ function readSealedProposal(eng) {
   } catch (_) { return [] }
 }
 
-function routeDebriefInput(eng, input, { dry, force, sealed = [] }) {
+// 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 deliveryCells(text) {
+  const cells = text.split('|').map(s => s.trim())
+  if (cells.length !== 7) throw new Error('delivery needs exactly 7 fields: Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback. Use pending for unknowns; omit pipes for a narrative note.')
+  return cells
+}
+
+// Exact sourced statement replay only; a shared source may contain new facts.
+// Do not silently deduplicate: the engineer decides whether a repeated event is intended.
+function repeatedDebriefStatements(eng, input) {
+  const repeats = []
+  const records = new Map()
+  const normalize = value => value.replace(/\s*\|\s*/g, '|').replace(/\s+/g, ' ').trim()
+  for (const raw of splitPrivate(input, { sealDangling: true }).clean.split('\n')) {
+    const match = raw.trim().replace(/^[-*+]\s+/, '').match(/^(decision|risk|delivery|contact):\s*(.+)$/i)
+    if (!match || !/\[source:[^\]]+\]/i.test(match[2])) continue
+    const body = match[2].trim()
+    const file = LOG_FILES[match[1].toLowerCase()]
+    if (!records.has(file)) {
+      const statements = String(readClean(eng, file) || '').split('\n').map(line => {
+        if (/^\s*\|/.test(line)) return normalize(line.trim().replace(/^\|\s*\d{4}-\d{2}-\d{2}\s*\|/, '').replace(/\|\s*$/, ''))
+        return normalize(line.replace(/^\s*[-*+]\s+/, '').replace(/^(?:\[(?:\d{4}-\d{2}-\d{2}|@[^\]]+|signal:[^\]]+)\]\s*)+/, ''))
+      })
+      records.set(file, new Set(statements))
+    }
+    if (records.get(file).has(normalize(body))) repeats.push(body)
+  }
+  return repeats
+}
+
+function routeDebriefInput(eng, input, { dry, force, sealed = [], allowReplay = false }) {
+  if (!dry && !debriefTransactionActive) {
+    ensureMemoryGit(eng)
+    return withDebriefRecords(eng, () => {
+      const result = routeDebriefInput(eng, input, { dry, force, sealed, allowReplay })
+      // 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 repeats = repeatedDebriefStatements(eng, input)
+  if (repeats.length && !dry && !allowReplay) throw new Error('source-backed statement already recorded; review the existing record and newer next action. Explicitly confirm a repeat with --allow-replay, or remove the repeated statement from the proposal.')
   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 }
   const ctxLines = []
   let nextAction = ''
-  ensureMemoryGit(eng)
+  if (!dry) ensureMemoryGit(eng)
   // Sealed blocks are pulled out before routing, so a <private> block's interior
   // lines are never previewed and never routed into decisions/risks/stakeholders
   // unsealed. They land verbatim in context.md instead: the preview a human
@@ -2002,7 +2136,7 @@ function routeDebriefInput(eng, input, { dry, force, sealed = [] }) {
         const who = body.replace(/\s+signs?(?:\s+off)?\b.*$/i, '').trim() || body.trim()
         if (dry) {
           console.log(`→ success.md  **Stakeholder who signs off:** ${previewLine(who)}`)
-          console.log(`→ stakeholders.md  ${previewLine(datedEntry(eng, date, `${who} signs off`))}`)
+          console.log(`→ stakeholders.md  ${previewLine(`- [${date}] ${who} signs off`)}`)
         } else {
           setSigner(eng, who)
           appendLogEntry(eng, 'contact', datedEntry(eng, date, `${who} signs off`), { skipCommit: true })
@@ -2016,9 +2150,16 @@ function routeDebriefInput(eng, input, { dry, force, sealed = [] }) {
         counts.next++
         continue
       }
+      if (type === 'delivery' && body.includes('|')) {
+        const cells = deliveryCells(body)
+        if (dry) console.log(`→ delivery.md ## Value ledger  ${previewLine(body)}`)
+        else appendValueLedgerRow(eng, cells, { skipCommit: true })
+        counts.delivery++
+        continue
+      }
       const sigInline = (body.match(/\[signal:(red|amber|green)\]/i) || [])[1]
       if (sigInline) body = body.replace(/\[signal:(red|amber|green)\]/i, '').trim()
-      const entry = datedEntry(eng, date, body, type === 'contact' && sigInline ? sigInline.toLowerCase() : '')
+      const entry = dry ? `- [${date}]${type === 'contact' && sigInline ? ` [signal:${sigInline.toLowerCase()}]` : ''} ${body}` : datedEntry(eng, date, body, type === 'contact' && sigInline ? sigInline.toLowerCase() : '')
       if (dry) console.log(`→ ${LOG_FILES[type]}  ${previewLine(entry)}`)
       else appendLogEntry(eng, type, entry, { skipCommit: true })
       counts[type]++
@@ -2044,7 +2185,34 @@ 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 replayIdx = args.indexOf('--allow-replay')
+  const allowReplay = replayIdx !== -1
+  if (allowReplay) args.splice(replayIdx, 1)
+  if (args.includes('--review')) {
+    if (args.length !== 1 || allowReplay) throw new Error('use debrief --review alone to inspect the pending proposal')
+    const proposal = path.join(eng, DEBRIEF_PROPOSE)
+    const refused = refuseSymlinkWrite(proposal, { soft: true })
+    if (refused) throw new Error(refused)
+    if (!fs.existsSync(proposal)) throw new Error('nothing to review - run debrief --smart <notes> first')
+    const { clean: input } = splitPrivate(fs.readFileSync(proposal, 'utf8'), { sealDangling: true })
+    return boundedDebriefPreview(eng, () => {
+      printDebriefReview(input, eng)
+      routeDebriefInput(eng, input, { dry: true, force: false })
+    })
+  }
   const dryIdx = args.indexOf('--dry-run')
   const dry = dryIdx !== -1
   if (dry) args.splice(dryIdx, 1)
@@ -2058,53 +2226,61 @@ 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, 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')
-      console.log('(edit the propose file first if a line mis-routed)')
+      console.log('(edit the propose file if mis-routed; debrief --review shows the pending REVIEW)')
       return
     }
     input = clean
     sealed = blocks
   }
 
-  const { counts, ctxLines, privateBlocks } = routeDebriefInput(eng, input, { dry, force, sealed })
+  const route = () => routeDebriefInput(eng, input, { dry, force, sealed, allowReplay })
+  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 = {
@@ -2224,10 +2400,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, 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)')
@@ -2319,12 +2499,30 @@ function cmdReceipts(args) {
       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)
+      ;(recordFiles.includes(file) && source ? records : claims).push({ file, hit })
     })
   }
-  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'))
+  // Alternate the latest and earliest matching lines per file. Otherwise a
+  // long history can spend the entire packet on approvals before a withdrawal.
+  const select = hits => {
+    const groups = new Map()
+    for (const { file, hit } of hits) {
+      if (!groups.has(file)) groups.set(file, [])
+      groups.get(file).push(hit)
+    }
+    const selected = []
+    let latest = true
+    while (selected.length < 24 && [...groups.values()].some(group => group.length)) {
+      for (const group of groups.values()) {
+        if (group.length && selected.length < 24) selected.push(latest ? group.pop() : group.shift())
+      }
+      latest = !latest
+    }
+    return `Selected ${selected.length} of ${hits.length} matching lines; omitted matches require a narrower search.\n` + selected.join('\n')
+  }
+  const sections = ['RECEIPTS: a cited record is not proof of customer approval. File line numbers refer to the redacted view. Latest and earliest matching lines are sampled; file order is not authority. Check conflicting records.']
+  if (records.length) sections.push('ON RECORD (dated, source-backed):\n' + select(records))
+  if (claims.length) sections.push('CLAIMS & working notes (verify source and approval before citing):\n' + select(claims))
   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))
 }
@@ -2353,13 +2551,14 @@ function cmdHandoff(args, label = 'Handoff') {
   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)
+  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\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)'}`,
+    label === 'Handoff' ? `## Operational handoff - handoff.md\n${stripTemplateNoise(readClean(eng, 'handoff.md')) || '(missing; record recovery steps and the operating owner before rotation)'}` : '',
+    `## 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 + ']' + (r.acceptanceIssue ? '; ' + r.acceptanceIssue : '')).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)
@@ -2385,7 +2584,7 @@ function cmdRecall(args) {
   }
   const eng = resolveEngagement()
   if (!eng) { console.error('no engagement - bind a client before recall'); process.exit(2) }
-  const files = ['context.md', 'trust-profile.md', 'success.md', 'decisions.md', 'risks.md', 'delivery.md', 'stakeholders.md', 'brief.md', 'reality.md', 'assumptions.md', 'terrain.md']
+  const files = ['context.md', 'trust-profile.md', 'success.md', 'decisions.md', 'risks.md', 'delivery.md', 'stakeholders.md', 'brief.md', 'reality.md', 'assumptions.md', 'terrain.md', 'handoff.md']
   const result = context.recallSections(files.map(file => ({ file, text: readClean(eng, file) })), query)
   process.stdout.write(context.boundedSections([
     `RECALL - ${eng}\n${result.total ? `${result.sections.length} of ${result.total} matching lines; refine the query if evidence is omitted.` : 'No matching record. This is not proof that the event never happened.'}\nSources are local record assertions; verify dates, supersession and approval scope.`,
@@ -2615,12 +2814,20 @@ function successContractIssues(success) {
     if (active !== -1 && line.trim()) checks[active] += ` ${line.trim()}`
   }
   const observable = checks.some(check => {
+    // This is a lint check, not a semantic proof. Explicit fields let any
+    // domain describe its test without depending on a vocabulary of verbs.
+    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
+    const vague = /\b(?:tbd|unknown|to be defined|improve|better|satisfactory|as expected|works well)\b/i
+    if (vague.test(check)) return false
+    const explicit = check.match(/(?:^|\s)(?:-\s*)?Input:\s*(.+?)\s+(?:-\s*)?Pass when:\s*(.+)$/i)
+    if (explicit) return explicit[1].trim().length > 3 && target.test(explicit[2])
     const stimulus = /\b(?:test|drill|replay|runs?|request|sample|given|when|simulate|inject|compare|restore|verified|observed|measured)\b/i.test(check)
+      || /^\d+\s+[a-z]/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)
+      || /\b(?:zero|no duplicate|no missing)\s+[a-z]/i.test(check)
+    return stimulus && result && target.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')
+  if (!observable) issues.push('success.md needs a binary acceptance check: the wording was not recognized as a test/input and observable pass/fail result under **Done when:** or **Acceptance check:**. Use Input: and Pass when: for a domain-specific check; this lint does not prove readiness')
   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.
@@ -2883,7 +3090,7 @@ function hasValueBucket(eng) {
 }
 
 // Shared classification keeps CLI, dashboard, and vault acceptance consistent.
-const { PENDING_CELL_RE, valueState, evidenceSource } = require('./lib/value-ledger')
+const { PENDING_CELL_RE, valueState, evidenceSource, reconcileValueRows } = require('./lib/value-ledger')
 
 function parseValueLedger(eng) {
   // Last section with actual rows, not merely the last non-empty one: a template
@@ -2913,9 +3120,9 @@ 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: !evidenceSource(evidence), state })
+    rows.push({ slice, promised, measured, accepted, acceptanceStatus, evidence, evidenceMissing: !evidenceSource(evidence), state })
   }
-  return { rows, columnMissing: idx.accepted === -1 }
+  return { rows: reconcileValueRows(rows, readClean(eng, 'success.md')), columnMissing: idx.accepted === -1 }
 }
 
 function claimedValueRows(eng) {
@@ -2932,8 +3139,9 @@ function formatValueLedgerLine(r) {
   }
   const head = body ? `${name}: ${body}` : name
   if (r.state === 'accepted') return `${head} · accepted by ${r.accepted}`
-  if (r.state === 'claimed') return `${head} · claimed, not yet accepted`
-  return `${head} · not yet measured`
+  const issue = r.acceptanceIssue ? `; ${r.acceptanceIssue}` : ''
+  if (r.state === 'claimed') return `${head} · claimed, not yet accepted${issue}`
+  return `${head} · not yet measured${issue}`
 }
 
 function valueLedgerStatusLines(eng, opts = {}) {
@@ -3522,7 +3730,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)
@@ -3883,6 +4097,9 @@ 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
+    --review              inspect the pending REVIEW after editing, without replacing it
+    --allow-replay        explicitly apply already recorded sourced statements after review
+    --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)

package/bin/lib/render.js

@@ -374,7 +374,7 @@ function deliveryHtml(e) {
   return `<section class="fb-block fb-delivery" aria-label="Delivery evidence">
 <div class="fb-sec-row"><h2 class="fb-sec">Delivery evidence</h2><span class="fb-count">${rows.length} outcome${rows.length === 1 ? '' : 's'}</span></div>
 <p class="fb-evidence-note">Recorded in delivery.md. Acceptance reflects the saved record, not independent verification.</p>
-${rows.length ? `<div class="fb-table-scroll" role="region" aria-label="Promised, measured and accepted outcomes" tabindex="0"><table class="fb-table fb-value-table"><thead><tr><th scope="col">Outcome</th><th scope="col">Promised</th><th scope="col">Measured</th><th scope="col">Acceptance</th><th scope="col">Evidence</th></tr></thead><tbody>${rows.map(r => `<tr><th scope="row">${inlineMd(r.slice || 'Outcome')}<span class="fb-value-state t-${r.state === 'accepted' ? 'green' : 'amber'}">${labels[r.state]}</span></th><td>${cell(r.promised, 'Not recorded')}</td><td>${cell(r.measured, 'Not yet measured')}</td><td>${cell(r.accepted, 'Not recorded')}</td><td>${cell(r.evidence, 'Not recorded')}</td></tr>`).join('')}</tbody></table></div>` : `<div class="fb-empty-evidence"><strong>No delivery evidence yet</strong><p>Ask your agent to define one useful increment: the expected result, how to measure it, and who will accept it.</p></div>`}
+${rows.length ? `<div class="fb-table-scroll" role="region" aria-label="Promised, measured and accepted outcomes" tabindex="0"><table class="fb-table fb-value-table"><thead><tr><th scope="col">Outcome</th><th scope="col">Promised</th><th scope="col">Measured</th><th scope="col">Acceptance</th><th scope="col">Evidence</th></tr></thead><tbody>${rows.map(r => `<tr><th scope="row">${inlineMd(r.slice || 'Outcome')}<span class="fb-value-state t-${r.state === 'accepted' ? 'green' : 'amber'}">${labels[r.state]}</span>${r.acceptanceIssue ? `<span class="fb-muted">${inlineMd(r.acceptanceIssue)}</span>` : ''}</th><td>${cell(r.promised, 'Not recorded')}</td><td>${cell(r.measured, 'Not yet measured')}</td><td>${cell(r.accepted, 'Not recorded')}</td><td>${cell(r.evidence, 'Not recorded')}</td></tr>`).join('')}</tbody></table></div>` : `<div class="fb-empty-evidence"><strong>No delivery evidence yet</strong><p>Ask your agent to define one useful increment: the expected result, how to measure it, and who will accept it.</p></div>`}
 </section>`
 }
 
@@ -573,7 +573,7 @@ ${railItems}
 </aside>
 <main id="fb-main" tabindex="-1" class="fb-main fb-scroll">
 <div class="fb-main-inner">
-<div class="fb-snapshot"><strong>Read-only snapshot</strong> &middot; Snapshot generated <time datetime="${escapeHtml(generatedAt)}">${escapeHtml(generatedAt ? generatedAt.replace('T', ' ').replace(/\.\d+Z$/, ' UTC') : today)}</time>. Re-run <code>fde dashboard</code> after updating your records. Reloading this page alone does not refresh the record.</div>
+<div class="fb-snapshot"><strong>Read-only snapshot</strong> &middot; Snapshot generated <time datetime="${escapeHtml(generatedAt)}">${escapeHtml(generatedAt ? generatedAt.replace('T', ' ').replace(/\.\d+Z$/, ' UTC') : today)}</time>. After updating your records, run the dashboard command that created this file again, keeping the same <code>--all</code> and <code>--out</code> options if used. Then reload. Reloading this page alone does not refresh the record.</div>
 ${todayView}
 ${clientViews}
 <p id="fb-status" class="fb-copy-status" role="status" aria-live="polite"></p>