fdeops 3.22.0 → 3.22.2

package/bin/fde.js

@@ -45,6 +45,9 @@ const REGISTRY = path.join(ENGAGEMENTS_ROOT, '.registry')
 const DEBRIEF_MAX_BYTES = 256 * 1024
 const CODE_EXT = ['.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.go', '.rb', '.cs', '.php']
 const CONF_EXT = CODE_EXT.concat(['.env', '.yaml', '.yml', '.json'])
+// Bare "inference" is banned here: TypeScript codebases are full of "type
+// inference" comments and the false positives poison the day-1 questions.
+const AI_CODE_RE = /openai|anthropic|\bllm\b|gpt-|claude|embedding|vector store|model inference|inference (?:api|endpoint|server|engine)/i
 // one routing table for structured appends - cmdLog and cmdDebrief share it
 const LOG_FILES = { decision: 'decisions.md', risk: 'risks.md', delivery: 'delivery.md', contact: 'stakeholders.md' }
 
@@ -633,13 +636,10 @@ const {
 // opts.lastNonEmpty: when duplicate headings exist (common skill trap: template
 // "## Next action" left empty, agent appends a second), prefer the last filled
 // body so triage/resume do not silently report "(none set)".
-function sectionBody(md, heading, opts) {
-  const preferLast = opts && opts.lastNonEmpty
+function sectionBodies(md, heading) {
   const lines = String(md || '').split('\n')
   const re = new RegExp('^#{1,6}\\s+' + heading + '\\b', 'i')
-  let first = ''
-  let lastFilled = ''
-  let seen = false
+  const out = []
   for (let i = 0; i < lines.length; i++) {
     if (!re.test(lines[i].trim())) continue
     const body = []
@@ -647,12 +647,16 @@ function sectionBody(md, heading, opts) {
       if (/^#{1,6}\s/.test(lines[j].trim())) break
       body.push(lines[j])
     }
-    const text = body.join('\n').trim()
-    if (!seen) { first = text; seen = true }
-    if (text) lastFilled = text
+    out.push(body.join('\n').trim())
   }
-  if (!seen) return ''
-  return preferLast ? (lastFilled || first) : first
+  return out
+}
+
+function sectionBody(md, heading, opts) {
+  const bodies = sectionBodies(md, heading)
+  if (!bodies.length) return ''
+  if (!(opts && opts.lastNonEmpty)) return bodies[0]
+  return [...bodies].reverse().find(Boolean) || bodies[0]
 }
 
 function countSections(md, heading) {
@@ -793,6 +797,19 @@ function parseReality(md, maxLen) {
   return { line: '', missing: '' }
 }
 
+// Same columns as templates/.fde/delivery.md - a row without them above it is
+// read as the header line, so the value it carries disappears.
+const VALUE_LEDGER_HEADER = '| Date | Slice | Bucket | Promised | Measured | Accepted by | Evidence | Rollback |'
+const VALUE_LEDGER_RULE = '|------|-------|--------|----------|----------|-------------|----------|----------|'
+
+// A header and a legend are text, not value: a template copy of the ledger has
+// zero rows, and must not shadow filled work above it (or receive a row).
+function valueLedgerRowCount(body) {
+  const t = parseMdTable(stripTemplateNoise(String(body || '')))
+  if (!t) return 0
+  return t.rows.filter(r => r.some(c => String(c || '').trim())).length
+}
+
 function appendValueLedgerRow(eng, cells) {
   ensureMemoryGit(eng)
   const p = path.join(eng, 'delivery.md')
@@ -802,17 +819,37 @@ function appendValueLedgerRow(eng, cells) {
   const cols = []
   for (let i = 0; i < 7; i++) cols.push((cells[i] || '').replace(/\|/g, '\\|').trim() || ' ')
   const row = `| ${date} | ${cols.join(' | ')} |`
+  // Write into the same section the readers take: the last filled ## Value ledger.
+  // A row appended to the empty template heading above a filled one is a row no
+  // gate can see.
   const lines = md.split('\n')
-  let inLedger = false
-  let lastTableLine = -1
+  const sections = []
+  let cur = null
   for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Value ledger\b/i.test(lines[i])) { inLedger = true; continue }
-    if (inLedger && /^##\s+/.test(lines[i])) break
-    if (inLedger && /^\|/.test(lines[i].trim())) lastTableLine = i
-  }
-  if (lastTableLine === -1) md = appendUnderSection(md, 'Value ledger', row)
-  else {
-    lines.splice(lastTableLine + 1, 0, row)
+    if (/^##\s+Value ledger\b/i.test(lines[i])) {
+      cur = { heading: i, lastTable: -1, filled: false, body: [] }
+      sections.push(cur)
+      continue
+    }
+    if (!cur) continue
+    if (/^##\s+/.test(lines[i])) { cur = null; continue }
+    cur.body.push(lines[i])
+    if (lines[i].trim()) cur.filled = true
+    if (/^\|/.test(lines[i].trim())) cur.lastTable = i
+  }
+  // Same choice parseValueLedger makes: the last section carrying rows, else the
+  // last with a body. A row written anywhere else is a row no gate can see.
+  const withRows = [...sections].reverse().find(s => valueLedgerRowCount(s.body.join('\n')))
+  const target = withRows || [...sections].reverse().find(s => s.filled) || sections[sections.length - 1]
+  if (!target) {
+    md = appendUnderSection(md, 'Value ledger', `${VALUE_LEDGER_HEADER}\n${VALUE_LEDGER_RULE}\n${row}`)
+  } else if (target.lastTable !== -1) {
+    lines.splice(target.lastTable + 1, 0, row)
+    md = lines.join('\n')
+  } else {
+    // No table under the chosen heading: a lone row would be read as the header
+    // line and the value would vanish. Lay the canonical table first.
+    lines.splice(target.heading + 1, 0, '', VALUE_LEDGER_HEADER, VALUE_LEDGER_RULE, row)
     md = lines.join('\n')
   }
   withFileLock(p, () => { atomicWriteFile(p, md.endsWith('\n') ? md : md + '\n') })
@@ -910,6 +947,7 @@ const {
   countOpenRisks,
 } = createTrustApi({
   fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
+  stripTemplateNoise, stripLegendLines,
 })
 
 // Stakeholders: columns are matched by header wording, not position - real
@@ -1168,8 +1206,14 @@ function cmdScan() {
   // NOTE: bare "inference" is banned from this regex - TypeScript codebases are
   // full of "type inference" comments and the false positives poison the day-1
   // questions. Model inference only, in explicit forms.
-  const ai = grepFiles(codeFiles, /openai|anthropic|\bllm\b|gpt-|claude|embedding|vector store|model inference|inference (?:api|endpoint|server|engine)/i, 10)
+  const ai = grepFiles(codeFiles, AI_CODE_RE, 10)
   ai.length ? ai.forEach(h => out.push(`  ${h.file}:${h.line}  ${h.text}`)) : out.push('  none found')
+  // The eval gate reads the record, not the repo. A finding here that never
+  // reaches .fde/ leaves ship/close green with no eval - so say the next move.
+  if (ai.length) {
+    out.push('  → the ship gate reads the record, not this scan. Put it there:')
+    out.push(`    fde log decision "AI in scope: ${path.basename(ai[0].file)} calls a model - eval receipt required before ship"`)
+  }
 
   // secrets (redacted)
   out.push('\nPOSSIBLE HARDCODED SECRETS (values redacted):')
@@ -1323,8 +1367,11 @@ 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)
   }
-  // Monday-morning: triage + proactive hygiene (silent when clean), then memory.
+  // Monday-morning: triage + proactive hygiene (silent when clean), the record
+  // (sponsor / promise / decisions), then the session log.
   printTriageBlock(eng)
+  const digest = recordDigest(eng)
+  if (digest.length) console.log('\n' + digest.join('\n'))
   console.log(`\nENGAGEMENT: ${eng}\n`)
   // readClean, not fs.readFileSync: this output is what an agent loads as
   // context, so it goes through the same <private> redaction as the dashboard.
@@ -1449,6 +1496,14 @@ function cmdLog(args) {
   appendLogEntry(eng, type, entry)
   const hash = memoryHead(eng)
   console.log(`logged → ${LOG_FILES[type]}${signal ? ` (signal:${signal})` : ''}${hash ? ` @${hash}` : ''}`)
+  // A dated bullet is a note; the ship gate reads the ledger. Say what this did
+  // NOT do, once, so promised→measured→accepted does not quietly stay unassembled.
+  if (type === 'delivery' && !parseValueLedger(eng).rows.length) {
+    console.log('  note: no value ledger row yet - "accepted by" is what a sponsor argues with. Add the row in delivery.md ## Value ledger (promised | measured | accepted by).')
+  }
+  if (type === 'contact' && !signal) {
+    console.log('  note: no --signal, so trust is unchanged - prep and status show people who carry a signal.')
+  }
 }
 
 function setContextPhase(eng, phase) {
@@ -1555,20 +1610,38 @@ function smartProposeText(input) {
   return out.join('\n') + (out.length ? '\n' : '')
 }
 
-// "Priya signs off" is the most expensive sentence in a kickoff and used to land
-// in context.md as a note. signer: fills the success.md line the whole kit
-// keys on, and logs the person as a contact so prep/status can see them.
-const SIGNER_RX = /^(?<who>[A-Z][\w.'-]+(?:\s+[A-Z][\w.'-]+){0,3}(?:\s*\([^)]{1,40}\))?)\s+(?:signs?(?:\s+off)?|approves|has (?:the )?final say|can say yes|owns the decision|is the (?:sponsor|signer|decision[- ]maker))\b/
+// Kickoff English, not only "signer: Priya". "Helena signs off", "Anand Mehta
+// has final say", "Finance controller (Helena) signs off" all have to fill
+// success.md - that is the line Monday's RECORD reads.
+const SIGNER_VERB = '(?:signs?(?:\\s+off)?|approves|has (?:the )?final say|can say yes|owns the decision|is the (?:sponsor|signer|decision[- ]maker))'
+const SIGNER_NAME = '([A-Z][\\w.\'-]+(?:\\s+[A-Z][\\w.\'-]+){0,3})'
+const NOT_A_PERSON = /^(The|This|That|It|We|They|She|He|Staging|Budget|Prod|Production|Nobody|Someone|Everyone|Finance|Legal|Security|Platform|Engineering)\b/
+const ROLE_TOKEN = /\b(VP|SVP|EVP|CTO|CFO|COO|CEO|CISO|Eng|Engineer|Director|Lead|Head|Manager|Controller|Ops|Legal|Finance|Sponsor)\b/i
+
+function looksLikePersonName(s) {
+  const t = String(s || '').trim()
+  if (!t || NOT_A_PERSON.test(t) || ROLE_TOKEN.test(t)) return false
+  return /^[A-Z][\w.'-]+(?:\s+[A-Z][\w.'-]+){0,2}$/.test(t)
+}
 
 function signerFromLine(text) {
-  const t = String(text || '').trim()
-  const m = t.match(SIGNER_RX)
-  if (!m) return ''
-  const who = m.groups.who.trim()
-  // "Staging exists" / "The API is slow" also match "Capital Word + verb"; a
-  // sentence-initial common noun is not a person.
-  if (/^(The|This|That|It|We|They|Staging|Budget|Prod|Production|Nobody|Someone|Everyone)\b/.test(who)) return ''
-  return who
+  const t = String(text || '').replace(/^[-*+]\s+/, '').trim()
+  if (!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) {
+    const before = titled[1].trim()
+    const inside = titled[2].trim()
+    if (looksLikePersonName(before) && ROLE_TOKEN.test(inside)) return before
+    if (looksLikePersonName(inside)) return inside
+    if (looksLikePersonName(before)) return before
+  }
+  const paren = t.match(new RegExp('\\(' + SIGNER_NAME + '\\)\\s+' + SIGNER_VERB + '\\b'))
+  if (paren && looksLikePersonName(paren[1])) return paren[1].trim()
+  const named = t.match(new RegExp('\\b' + SIGNER_NAME + '\\s+' + SIGNER_VERB + '\\b'))
+  if (!named) return ''
+  const who = named[1].trim()
+  return looksLikePersonName(who) ? who : ''
 }
 
 function setSigner(eng, who) {
@@ -1577,7 +1650,10 @@ function setSigner(eng, who) {
   let md = readEng(eng, 'success.md')
   if (!md) md = '# Success definition\n\n'
   const norm = (s) => String(s).replace(/\s+/g, ' ').trim().toLowerCase()
-  const line = /^\*\*Stakeholder who signs off:\*\*\s*(.*)$/m
+  // [^\S\n], not \s: \s crosses newlines, so an empty field captured the next
+  // line - and setSigner then read a filled field and filed the name as "also
+  // named" under whatever heading followed.
+  const line = /^\*\*Stakeholder who signs off:\*\*[^\S\n]*(.*)$/m
   const m = md.match(line)
   if (m && !m[1].trim()) {
     md = md.replace(line, `**Stakeholder who signs off:** ${who}`)
@@ -2076,7 +2152,7 @@ function cmdReceipts(args) {
     agreed.map(h => (h.match(/^\s*([^:]+):/) || [])[1]).filter(f => f && dirtySet.has(f))
   )]
   if (agreed.length) {
-    console.log('ON RECORD (dated - defensible):')
+    console.log('ON RECORD (dated):')
     agreed.forEach(h => {
       const file = (h.match(/^\s*([^:]+):/) || [])[1]
       console.log(h + (file && dirtySet.has(file) ? '  ⚠ dirty file' : ''))
@@ -2167,8 +2243,10 @@ function cmdTriage() {
     console.error('no engagement - run: fde resume --init <name>')
     process.exit(2)
   }
-  // Session-start hooks call this - hygiene is proactive here (silent when clean).
+  // Session-start hooks call this - hygiene is proactive here (silent when clean),
+  // and the record digest travels with it so a fresh session knows who signs.
   printTriageBlock(eng)
+  for (const line of recordDigest(eng)) console.log(line)
   const owner = readOwner(eng) || writeOwnerIfMissing(eng)
   const head = memoryHead(eng)
   if (owner || head) {
@@ -2397,6 +2475,13 @@ function collectDoctorIssues(eng) {
       issues.push(
         `phase is ${s.phase} with AI in scope but no eval receipt (evals.md Verdict or delivery Eval / Ship receipts) - required before green ship/close`
       )
+    } else if (!engagementTouchesAI(eng)) {
+      const hit = workspaceAIHit(eng)
+      if (hit) {
+        issues.push(
+          `the bound workspace calls a model (${hit.file}) but nothing in the record says AI is in scope - the eval gate is off; record it: fde log decision "AI in scope: …"`
+        )
+      }
     }
     issues.push(...silentCommitIssues(eng))
   }
@@ -2414,6 +2499,14 @@ function collectDoctorIssues(eng) {
       `phase is ${s.phase} with empty operating map - fill terrain.md ## Operating map (exception-led): break → who notices → workaround → evidence`
     )
   }
+  // A second copy of a heading the gates read: they take the last filled one, so
+  // the record is ambiguous rather than lost. Say so once, here.
+  // Full heading names only: "Value" would also match "## Value ledger".
+  for (const [file, heading] of [['terrain.md', 'Operating map'], ['delivery.md', 'Value ledger']]) {
+    if (countSections(readClean(eng, file), heading) > 1) {
+      issues.push(`duplicate ## ${heading} headings in ${file} - merge into one section; the gates read the last filled one`)
+    }
+  }
   const aliases = findAmbiguousStakeholders(eng)
   if (aliases.length) {
     const sample = aliases[0].forms.slice(0, 3).join(' / ')
@@ -2427,9 +2520,11 @@ function collectDoctorIssues(eng) {
 }
 
 // True when ## Operating map has at least one real exception row (not the empty template).
+// lastNonEmpty: an agent that appends a filled section leaves the empty template
+// heading above it. Reading the first match called that work invisible.
 function hasOperatingMapContent(eng) {
   const terrain = stripTemplateNoise(readClean(eng, 'terrain.md'))
-  const body = sectionBody(terrain, 'Operating map')
+  const body = sectionBody(terrain, 'Operating map', { lastNonEmpty: true })
   if (!body.trim()) return false
   const table = parseMdTable(body)
   if (table) {
@@ -2519,7 +2614,7 @@ function hasValueBucket(eng) {
   if (bucketLine && VALUE_BUCKET_RE.test(bucketLine[1].trim())) return true
   if (!/\*\*Primary value bucket:\*\*/i.test(success) && VALUE_BUCKET_RE.test(success)) return true
 
-  const ledger = stripLegendLines(stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger') || ''))
+  const ledger = stripLegendLines(stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger', { lastNonEmpty: true }) || ''))
   const table = parseMdTable(ledger)
   if (table) {
     const bIdx = colIndex(table.headers, /bucket/i)
@@ -2543,11 +2638,16 @@ function hasValueBucket(eng) {
 // "pending review", "TBD.", "n/a (blocked)" and "..." are all the same thing an
 // FDE means by an empty cell - nagging about them teaches people to ignore doctor.
 const PENDING_CELL_RE =
-  /^(?:pending|tbd|to ?be ?(?:measured|confirmed|determined)|n\s*\/\s*a|na|none|unknown|not measured|\?+|\.{2,}|…|-+|-+|-+)(?:[^\w].*)?$/i
+  /^(?:pending|tbd|to ?be ?(?:measured|confirmed|determined)|n\s*\/\s*a|na|none|unknown|not(?:\s+yet)?\s+measured|unmeasured|awaiting|\?+|\.{2,}|…|-+)(?:[^\w].*)?$/i
 
 function parseValueLedger(eng) {
-  const ledger = stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger') || '')
-  const table = parseMdTable(ledger)
+  // Last section with actual rows, not merely the last non-empty one: a template
+  // copy appended below filled work is a header and a legend - text, but no
+  // value - and it would otherwise shadow a real accepted row above it.
+  const bodies = sectionBodies(readClean(eng, 'delivery.md'), 'Value ledger')
+    .map(b => stripTemplateNoise(b || ''))
+  const withRows = [...bodies].reverse().find(b => valueLedgerRowCount(b))
+  const table = parseMdTable(withRows || [...bodies].reverse().find(Boolean) || '')
   if (!table) return { rows: [], columnMissing: false }
   const idx = {
     slice: colIndex(table.headers, /slice/i),
@@ -2600,17 +2700,46 @@ function valueLedgerStatusLines(eng, opts = {}) {
   return lines
 }
 
-// AI in scope for ship/close hygiene - delivery/decisions/trust evidence only.
+// AI in scope for ship/close hygiene - the FDE's own words, wherever they wrote them.
 // Do not scan terrain.md: its template headers mention LLM and would false-positive every ship.
 function engagementTouchesAI(eng) {
   const trust = readClean(eng, 'trust-profile.md')
-  const aiSec = stripTemplateNoise(sectionBody(trust, 'AI policy') || '')
+  const aiSec = stripTemplateNoise(sectionBody(trust, 'AI policy', { lastNonEmpty: true }) || '')
   if (aiSec.trim().length > 20) return true
+  // Not **AI code policy:** - that field is about the FDE's own agent writing
+  // code ("permitted with human review"), which every engagement now has. AI in
+  // the shipped product is a different claim, and only the record's own words
+  // below can make it.
+  // brief/success/risks included: an engagement is often declared AI in the brief
+  // or in a risk ("nobody can say what the accuracy was") and never again.
   const blob = stripTemplateNoise([
     readClean(eng, 'delivery.md'),
     readClean(eng, 'decisions.md'),
+    readClean(eng, 'brief.md'),
+    readClean(eng, 'success.md'),
+    readClean(eng, 'risks.md'),
+    readClean(eng, 'assumptions.md'),
   ].join('\n'))
-  return /\b(llm|rag|embedding|inference|model card|agentic|openai|anthropic|vector database|vector db)\b/i.test(blob)
+  // No bare "prompt": "prompt response" / "prompt payment" is ordinary delivery
+  // English and would fail every non-AI ship on a missing eval receipt.
+  return /\bAI in scope\b|\b(llm|rag|embedding|model card|model output|model drift|agentic|openai|anthropic|vector database|vector db|fine-tun\w*|hallucinat\w*)\b|\bmodel inference\b|\binference (?:api|endpoint|server|engine)\b|\b(?:system|model|user)\s+prompts?\b|\bprompt (?:engineering|injection|template)/i.test(blob)
+}
+
+// The repo says AI even when the record does not. Read-only, capped, local: the
+// point is to refuse to run a silent green ship over an unevaluated model.
+function workspaceAIHit(eng) {
+  const slug = path.basename(path.dirname(eng))
+  const ws = readRegistry().filter(r => r.slug === slug).map(r => r.workspace)
+  for (const dir of ws.slice(0, 3)) {
+    let files
+    try {
+      if (!fs.existsSync(dir)) continue
+      files = walk(dir, CODE_EXT, 1500)
+    } catch (_) { continue }
+    const hit = grepFiles(files, AI_CODE_RE, 1)[0]
+    if (hit) return { workspace: dir, file: hit.file }
+  }
+  return null
 }
 
 function hasEvalReceipt(eng) {
@@ -2623,9 +2752,9 @@ function hasEvalReceipt(eng) {
     if (/\|\s*G\d+\s*\|[^|\n]+\|[^|\n]+\|[^|\n]+\|[^|\n]+\|\s*pass\s*\|/i.test(e)) return true
   }
   const del = stripLegendLines(stripTemplateNoise(readClean(eng, 'delivery.md')))
-  if (/#{1,6}\s+Eval\b/i.test(del) && /\b(pass|SHIP|\d+\/\d+)\b/i.test(sectionBody(del, 'Eval') || del)) return true
+  if (/#{1,6}\s+Eval\b/i.test(del) && /\b(pass|SHIP|\d+\/\d+)\b/i.test(sectionBody(del, 'Eval', { lastNonEmpty: true }) || del)) return true
   if (/\beval (pack|receipt)[:\s].*\b(pass|SHIP)\b/i.test(del)) return true
-  const receipts = sectionBody(del, 'Ship receipts') || ''
+  const receipts = sectionBody(del, 'Ship receipts', { lastNonEmpty: true }) || ''
   if (/\bevals\.md\b/i.test(receipts) && /\b(pass|SHIP)\b/i.test(receipts) && !/\*\([^)]*evals\.md[^)]*\)\*/i.test(receipts)) {
     return true
   }
@@ -2648,6 +2777,31 @@ function printTriageBlock(eng) {
   for (const line of hygieneTriageLines(eng)) console.log(line)
 }
 
+// What a session must not have to ask for: who signs, what was promised, what was
+// decided. Read-only, and from the same places the writers use - the signer is
+// success.md **Stakeholder who signs off** (what `signer:` fills), never a role
+// guess out of stakeholders.md, where contacts live. Bounded on purpose (<= 6
+// lines): this is injected into every session.
+function recordDigest(eng) {
+  const success = stripTemplateNoise(readClean(eng, 'success.md'))
+  const signer = ((success.match(/^\*\*Stakeholder who signs off:\*\*[^\S\n]*(.*)$/m) || [])[1] || '').trim()
+  // "(none)" rather than a missing line: on session start, nobody named to sign
+  // off is the fact worth seeing, not an absence to scroll past.
+  const lines = [`  signer: ${signer.slice(0, 110) || '(none)'}`]
+  const { rows } = parseValueLedger(eng)
+  const promisedRow = [...rows].reverse().find(r => r.promised)
+  if (promisedRow) {
+    lines.push(`  promised: ${formatValueLedgerLine(promisedRow).slice(0, 110)}`)
+  } else {
+    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: ${d.trim().replace(/^-\s*/, '').slice(0, 110)}`)
+  return ['RECORD (read-only - success, delivery, decisions)', ...lines]
+}
+
 function cmdDoctor() {
   const eng = resolveEngagement()
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
@@ -2985,12 +3139,14 @@ function cmdStatus(args) {
     rows.push({ name: engagementSlugFromPath(eng), phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: note, memoryWarn: s.memoryWarn, dirtyFiles: s.dirtyFiles, valueLines: valueLedgerStatusLines(eng) })
   }
   if (!rows.length) { console.log('no engagements yet'); return }
-  const order = { RED: 0, amber: 1, green: 2 }
+  // `new` sorts last: nothing to act on yet, unlike a green somebody confirmed.
+  const order = { RED: 0, amber: 1, green: 2, new: 3 }
   rows.sort((a, b) => order[a.trust] - order[b.trust])
   console.log((all ? 'FDE PORTFOLIO' : 'FDE STATUS') + ' - value first, then trust\n')
   for (const r of rows) {
     for (const line of r.valueLines) console.log(line)
     // "amber?" = structured signal went stale (>21d) - reconfirm before trusting it
+    // "new" = nobody has been asked yet; green is reserved for asked-and-fine.
     const label = r.trust + (r.stale ? '?' : '')
     const sig = r.signalAge != null ? `signal ${r.signalAge}d old${r.stale ? ' (STALE - reconfirm)' : ''}  ` : ''
     console.log(`  [${label.padEnd(6)}] ${r.name.padEnd(24)} phase:${(r.phase === '?' ? 'unset' : r.phase).padEnd(10)} updated:${r.updated.padEnd(8)} ${sig}${r.reason}`)
@@ -3045,7 +3201,7 @@ function cmdDashboard(args) {
     }
     engagements = gatherEngagements({ only: eng })
   }
-  const counts = { green: 0, amber: 0, RED: 0 }
+  const counts = { green: 0, amber: 0, RED: 0, new: 0 }
   engagements.forEach(e => { counts[e.signals.trust]++ })
   const today = render.formatToday(new Date())
 
@@ -3100,7 +3256,7 @@ function cmdDashboard(args) {
     failFs(e, 'write fieldbook', outPath)
   }
   console.log(`fieldbook → ${outPath}`)
-  console.log(`${engagements.length} engagement(s) rendered · ${counts.RED} red / ${counts.amber} amber / ${counts.green} green · 0 tokens (pure render)`)
+  console.log(`${engagements.length} engagement(s) rendered · ${counts.RED} red / ${counts.amber} amber / ${counts.green} green / ${counts.new} new · 0 tokens (pure render)`)
   if (!all) {
     const current = resolveEngagement()
     if (current) for (const line of hygieneTriageLines(current)) console.log(line)
@@ -3131,7 +3287,7 @@ function cliVersion() {
 }
 
 function valueLedgerRows(eng) {
-  const ledger = stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger') || '')
+  const ledger = stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger', { lastNonEmpty: true }) || '')
   const table = parseMdTable(ledger)
   if (!table) return []
   const sIdx = colIndex(table.headers, /slice/i)
@@ -3480,6 +3636,10 @@ function printUsage() {
 }
 
 const [cmd, ...args] = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h') || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  printUsage()
+  process.exit(0)
+}
 switch (cmd) {
   case 'demo': cmdDemo(args); break
   case 'scan': cmdScan(); break

package/bin/install.js

@@ -292,8 +292,8 @@ function cmdAdapters(targetDir, opts = {}) {
 
 function cmdInit(engagementName) {
   if (!engagementName) {
-    console.error('  Usage: node bin/install.js init <engagement-name>')
-    console.error('  Example: node bin/install.js init retailbank-payments')
+    console.error('  Usage: fdeops init <engagement-name>')
+    console.error('  Example: fdeops init retailbank-payments')
     process.exit(1)
   }
   const slug = slugify(engagementName)
@@ -318,9 +318,15 @@ function cmdInit(engagementName) {
   else if (merged > 0) console.log(`  (${merged} missing template file(s) added)`)
   console.log('')
   console.log('  Next:')
-  console.log('  1. Open your workspace for this engagement')
-  console.log(`  2. Point your AI coding agent at: FDEOPS_ENGAGEMENT=${fdeDir}`)
-  console.log('  3. In the AI chat (not email), type: @fde and describe what is happening')
+  console.log('  1. cd into the workspace you will work in for this client')
+  console.log(`  2. Bind it once - no env var to remember afterwards:  fde resume --init ${slug}`)
+  console.log('  3. In the AI chat, say what happened. The agent runs the CLI.')
+  console.log('')
+  // Creating the memory does not bind a workspace: the registry maps a workspace
+  // path to a slug, and this command runs wherever the human happened to be.
+  // Saying so here is the difference between a bound engagement and a silent
+  // "NO ENGAGEMENT" in every later session.
+  console.log(`  (until it is bound, commands need: export FDEOPS_ENGAGEMENT=${fdeDir})`)
   console.log('')
 }
 
@@ -334,14 +340,14 @@ function cmdInstall(opts = {}) {
   console.log('  CLI → ~/.claude/fdeops/fde.js  (try: node ~/.claude/fdeops/fde.js scan)')
   console.log('')
   console.log('  Create an engagement (stays off customer infrastructure):')
-  console.log('    node bin/install.js init <engagement-name>')
+  console.log('    fdeops init <engagement-name>')
   console.log('')
   console.log('  Example:')
-  console.log('    node bin/install.js init garvey-payments')
-  console.log('  (npm 3.0.0+: npx fdeops@latest init <engagement-name>)')
+  console.log('    fdeops init garvey-payments')
+  console.log('  (from a clone, without installing: node bin/install.js init <engagement-name>)')
   console.log('')
   console.log('  Use another AI tool (Cursor, Codex, Gemini CLI, Copilot)? Wire it up:')
-  console.log('    node bin/install.js adapters <engagement-workspace>')
+  console.log('    fdeops adapters <engagement-workspace>')
   console.log('')
   console.log('  Then open your workspace and use @fde')
   console.log('  Docs: docs/install.md')

package/bin/lib/render.js

@@ -97,7 +97,8 @@ function formatLogDate(iso) {
   const m = String(iso).match(/^(\d{4})-(\d{2})-(\d{2})$/)
   return m ? `${MONTHS[parseInt(m[2], 10) - 1]} ${parseInt(m[3], 10)}` : iso
 }
-function trustWord(t) { return t === 'green' ? 'steady' : t === 'amber' ? 'watch' : 'at risk' }
+// `new` is its own word: nobody has been asked yet, which is neither steady nor at risk.
+function trustWord(t) { return t === 'green' ? 'steady' : t === 'amber' ? 'watch' : t === 'new' ? 'new' : 'at risk' }
 function dotClassFor(trust) { return trust === 'RED' ? 'red' : trust }
 
 // Two-pane fieldbook: left rail (search + today + per-client nav), right main
@@ -222,10 +223,11 @@ strong{font-weight:600}
 .dot.green{background:var(--green)}
 .dot.amber{background:var(--amber);border-radius:2px}
 .dot.red{background:transparent;border:1.5px solid var(--red)}
+.dot.new{background:transparent;border:1.5px solid var(--ink-faint)}
 .dot-sm{width:7px;height:7px}
 .dot-md{width:8px;height:8px}
 .dot-lg{width:9px;height:9px}
-.t-green{color:var(--green)}.t-amber{color:var(--amber)}.t-red{color:var(--red)}.t-accent{color:var(--accent)}.t-faint{color:var(--ink-faint)}.t-soft{color:var(--ink-soft)}
+.t-green{color:var(--green)}.t-amber{color:var(--amber)}.t-red{color:var(--red)}.t-accent{color:var(--accent)}.t-faint{color:var(--ink-faint)}.t-new{color:var(--ink-faint)}.t-soft{color:var(--ink-soft)}
 .fb-hints{margin-top:26px;display:flex;gap:14px;flex-wrap:wrap;font-family:'Geist Mono',monospace;font-size:10.5px;color:var(--ink-faint);border-top:1px solid var(--line);padding-top:12px}
 .fb-hints-spacer{margin-left:auto}
 .fb-palette-backdrop{position:fixed;inset:0;background:rgba(0,0,0,.45);z-index:60;display:none;align-items:flex-start;justify-content:center;padding-top:12vh}
@@ -586,9 +588,9 @@ function paletteItemsHtml(ordered) {
 
 function buildFieldbookHtml({ engagements, today }) {
   // rail + Today queue share one order: trust-first (red, amber, green)
-  const tierRank = { RED: 0, amber: 1, green: 2 }
+  const tierRank = { RED: 0, amber: 1, green: 2, new: 3 }
   const ordered = engagements.slice().sort((a, b) => tierRank[a.signals.trust] - tierRank[b.signals.trust])
-  const attentionCount = engagements.filter(e => e.signals.trust !== 'green').length
+  const attentionCount = engagements.filter(e => e.signals.trust !== 'green' && e.signals.trust !== 'new').length
   const highRiskTotal = engagements.reduce((n, e) => n + e.highRisks, 0)
 
   const railItems = ordered.map(railItemHtml).join('\n')

package/bin/lib/trust.js

@@ -3,6 +3,7 @@
 function createTrustApi(deps) {
   const {
     fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
+    stripTemplateNoise, stripLegendLines,
   } = deps
 
   // phase / trust / top risk / freshness - identical heuristic for status + dashboard.
@@ -183,9 +184,14 @@ function createTrustApi(deps) {
         stale = signalAge > 21
       }
     } else {
-      const sLines = stake.split('\n').filter(l => !(/green/i.test(l) && /red|amber/i.test(l)))
+      // No structured signal anywhere. Prose still gets to raise an alarm - a
+      // written "gone quiet" is worth an amber - but it never earns a green:
+      // green must mean somebody was asked and said they were fine, and a day-1
+      // template calling someone a "champion" is not that. That reads `new`.
+      const sLines = stripLegendLines(stripTemplateNoise(stake)).split('\n')
+        .filter(l => !(/green/i.test(l) && /red|amber/i.test(l)))
       trust = sLines.some(l => /\bred\b/i.test(l)) ? 'RED'
-        : sLines.some(l => /amber|gone quiet|routing around|escalat/i.test(l)) ? 'amber' : 'green'
+        : sLines.some(l => /amber|gone quiet|routing around|escalat/i.test(l)) ? 'amber' : 'new'
     }
     const topRisk = (risks.split('\n').find(l => {
       const t = l.trim()

package/mcp/fdeops-ingest/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.22.0",
+  "version": "3.22.2",
   "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code: who can say yes, what went live, whether they signed off. Dated markdown on your laptop. You confirm each write.",
   "bin": {
     "fdeops": "bin/install.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "3.22.0",
+  "version": "3.22.2",
   "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code. You confirm; then it lands in .fde/ on your laptop.",
   "author": {
     "name": "Subash Natarajan",