fdeops 3.7.7 → 3.8.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - working in the fdeops repository
 
-This repository **is** fdeops - the second brain for Forward Deployed Engineers. One `@fde` skill routes an entire client engagement across six domains, the `fde` CLI does the deterministic work, and per-customer memory writes itself into `.fde/` files.
+This repository **is** fdeops - the second brain for Forward Deployed Engineers. One `@fde` skill routes an entire client engagement across six domains, the `fde` CLI does the deterministic work, and per-customer memory lands in `.fde/` files as a side effect of the work (you still confirm judgment).
 
 ## If you are helping use fdeops in an engagement
 

package/README.md

@@ -37,7 +37,7 @@ A notes app stores what you type. fdeops loads the right client into your AI age
 | **After a meeting** | Notes rot in a scratch file | `fde debrief` routes decisions, risks, deliveries, and contacts into the record, dated |
 | **Scope dispute** | "Small" additions absorbed silently; no record when the sponsor asks | `fde receipts <term>` answers "when did we agree to that?" with dates |
 | **Quiet stakeholder** | Noticed three weeks too late | `fde log contact --signal amber` the day it happens; `fde status` surfaces it |
-| **Multiple clients** | Details blur across engagements | One folder per client, never cross-contaminated |
+| **Multiple clients** | Details blur across engagements | One folder per client; bind the workspace so writes cannot land on a name-alike checkout |
 
 ---
 
@@ -66,7 +66,7 @@ fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde
 @fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
 ```
 
-`@fde` is the one skill fdeops installs. Describe what's happening; it routes to the right field method and the memory writes itself. Full workflow: [docs/USAGE.md](docs/USAGE.md).
+`@fde` is the one skill fdeops installs. Describe what's happening; it routes to the right field method and writes matching `.fde/` artifacts — you still confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
 
 Not ready to install? `npx fdeops scan` runs on any repo you can read - day-1 recon (pure `git` + file reads, no config, no account) that maps hotspots, test gaps, and reverted attempts, and ends with the ASK ON DAY 1 questions the brief never mentions. The scan is heuristic by design - treat its output as leads to verify on day one, not findings.
 

package/bin/fde.js

@@ -93,7 +93,11 @@ function readRegistry() {
   } catch (_) { return [] }
 }
 
-function resolveEngagement() {
+function resolveEngagement(opts = {}) {
+  // opts.forWrite: memory mutations (log/debrief/capture) require an intentional
+  // bind - env, registry, pointer, or in-repo .fde. Basename matching is
+  // read-only convenience; writing on a folder-name guess contaminates clients.
+  const forWrite = !!opts.forWrite
   // 1) explicit env (back-compat: accept old FDEOS_ENGAGEMENT too)
   const env = (process.env.FDEOPS_ENGAGEMENT || process.env.FDEOS_ENGAGEMENT || '').replace(/^~/, HOME).trim()
   if (env && fs.existsSync(env)) return env
@@ -123,15 +127,21 @@ function resolveEngagement() {
       }
     } catch (_) {}
   }
-  // 4) workspace dir name matches an engagement slug. This is a convenience,
-  // NOT a binding - an unbound directory that merely happens to be named like a
-  // client (a fork, a demo, a second client with the same codename) would
-  // otherwise attach to that client's memory silently and get written into.
-  // Never silent: warn on stderr so cross-client contamination can't happen
-  // unnoticed, and tell the user how to make the binding explicit.
-  const guess = path.join(ENGAGEMENTS_ROOT, slugify(path.basename(cwd)), '.fde')
+  // 4) workspace dir name matches an engagement slug. Read-only convenience.
+  // NEVER a write target - an unbound checkout named like a client must not
+  // append into that client's memory.
+  const slugGuess = slugify(path.basename(cwd))
+  const guess = path.join(ENGAGEMENTS_ROOT, slugGuess, '.fde')
   if (fs.existsSync(guess)) {
-    process.stderr.write(`⚠ resolved engagement by directory name ("${slugify(path.basename(cwd))}"), not a saved binding. If this is the right client, run \`fde resume --init ${slugify(path.basename(cwd))}\` here to bind it; if not, you are about to read/write the WRONG client's memory.\n`)
+    if (forWrite) {
+      process.stderr.write(
+        `no binding for this workspace - folder name matched "${slugGuess}" but writes require an explicit bind.\n` +
+        `run: fde resume --init ${slugGuess}\n` +
+        ` or: export FDEOPS_ENGAGEMENT=${guess}\n`
+      )
+      return null
+    }
+    process.stderr.write(`⚠ resolved engagement by directory name ("${slugGuess}"), not a saved binding (read-only). If this is the right client, run \`fde resume --init ${slugGuess}\` here to bind it before logging or debriefing.\n`)
     return guess
   }
   // 5) in-repo .fde (engagement-approved only)
@@ -156,6 +166,49 @@ function readEng(eng, f) {
 // a markdown file, so a forgotten stripPrivate() call can't leak a <private> block.
 function readClean(eng, f) { return stripPrivate(readEng(eng, f)) }
 
+// CLI-owned append-only mirror of [signal:x] lines. Survives an agent rewrite
+// that drops stakeholders.md "## Signal history" - skill discipline still
+// matters, but CLI-logged trust tokens must not vanish with the markdown.
+const SIGNAL_LEDGER = '.signal-ledger'
+
+// 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) {
+  const lockPath = targetPath + '.lock'
+  const deadline = Date.now() + 5000
+  while (true) {
+    let fd
+    try {
+      fd = fs.openSync(lockPath, 'wx')
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      if (Date.now() > deadline) {
+        console.error(`could not lock ${path.basename(targetPath)} - another writer is active; retry`)
+        process.exit(1)
+      }
+      const waitUntil = Date.now() + 20
+      while (Date.now() < waitUntil) { /* spin */ }
+      continue
+    }
+    try {
+      return fn()
+    } finally {
+      try { fs.closeSync(fd) } catch (_) {}
+      try { fs.unlinkSync(lockPath) } catch (_) {}
+    }
+  }
+}
+
+function atomicWriteFile(p, content) {
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`
+  fs.writeFileSync(tmp, content)
+  fs.renameSync(tmp, p)
+}
+
+function lockedAppendFile(p, text) {
+  withFileLock(p, () => { fs.appendFileSync(p, text) })
+}
+
 // Pull the body under a "## Heading" up to the next "##" (or EOF).
 function sectionBody(md, heading) {
   const lines = md.split('\n')
@@ -169,6 +222,49 @@ function sectionBody(md, heading) {
   return body.join('\n').trim()
 }
 
+// Append `entry` as the last line of a "## Heading" section, creating the
+// section at end-of-file if it doesn't exist yet. Plain fs.appendFileSync
+// would land the entry after ANY later section the agent added (e.g. a
+// "## Notes" heading appended after "## Signal history"), silently moving a
+// signal token outside the section the reader scans - this keeps it inside
+// regardless of what follows.
+function appendUnderSection(md, heading, entry) {
+  const lines = md.split('\n')
+  const start = lines.findIndex(l => new RegExp('^#{1,6}\\s+' + heading + '\\b', 'i').test(l.trim()))
+  if (start === -1) {
+    const sep = md.length && !md.endsWith('\n') ? '\n' : ''
+    return `${md}${sep}\n## ${heading}\n\n${entry}\n`
+  }
+  let end = lines.length
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,6}\s/.test(lines[i].trim())) { end = i; break }
+  }
+  const before = lines.slice(0, end)
+  const after = lines.slice(end)
+  while (before.length > start + 1 && before[before.length - 1].trim() === '') before.pop()
+  before.push(entry)
+  if (after.length) before.push('')
+  return before.concat(after).join('\n')
+}
+
+// Shared by cmdLog and cmdDebrief so the two writers can't drift (the earlier
+// bug: fde log's format and fde debrief's format both existed, only one of
+// them matched what extractStakeholders actually read). A contact entry
+// carrying a [signal:x] token - however it got there - lands inside
+// "## Signal history"; everything else is a plain end-of-file append.
+function appendLogEntry(eng, type, entry) {
+  const p = path.join(eng, LOG_FILES[type])
+  if (type === 'contact' && /\[signal:(red|amber|green)\]/i.test(entry)) {
+    withFileLock(p, () => {
+      atomicWriteFile(p, appendUnderSection(readEng(eng, LOG_FILES[type]), 'Signal history', entry))
+    })
+    // Durable CLI ledger - not rewritten by agent artifact passes.
+    lockedAppendFile(path.join(eng, SIGNAL_LEDGER), `${entry}\n`)
+  } else {
+    lockedAppendFile(p, `\n${entry}\n`)
+  }
+}
+
 // phase / trust / top risk / freshness - identical heuristic for status + dashboard.
 // Trust resolution: structured [signal:red|amber|green] tokens in stakeholders.md
 // (written by `fde log contact --signal` and `fde debrief`) win - the latest dated
@@ -180,9 +276,11 @@ function computeSignals(eng) {
   // readClean, not readEng: status/dashboard echo topRisk and stakeholder lines
   // to the terminal and the rendered HTML - a <private> risk must never surface.
   const ctx = readClean(eng, 'context.md'); const stake = readClean(eng, 'stakeholders.md'); const risks = readClean(eng, 'risks.md')
+  // Prefer structured tokens from stakeholders + CLI ledger (ledger survives wipes)
+  const signalText = stake + '\n' + readClean(eng, SIGNAL_LEDGER)
   const phase = (ctx.match(/phase[:* ]+\**([a-z-]+)/i) || [])[1] || '?'
   let latest = null
-  for (const l of stake.split('\n')) {
+  for (const l of signalText.split('\n')) {
     const sm = l.match(/\[signal:(red|amber|green)\]/i)
     if (!sm) continue
     const date = (l.match(/\[(\d{4}-\d{2}-\d{2})\]/) || [])[1] || ''
@@ -305,9 +403,21 @@ function extractStakeholders(eng) {
   const notesIdx = colIndex(headers, /notes?/i)
 
   const history = []
-  sectionBody(md, 'Signal history').split('\n').forEach(l => {
-    const m = l.trim().match(/^-\s*\[(\d{4}-\d{2}-\d{2})\]\s*\[signal:(red|amber|green)\]\s*(.+)$/i)
-    if (m) history.push({ date: m[1], signal: m[2].toLowerCase(), text: m[3] })
+  // Format-agnostic on token position: `fde log contact --signal` writes
+  // "[date] [signal:x] text" (token right after the date), but `fde debrief`
+  // appends the token at the END of whatever the agent wrote per the skill's
+  // own contact: convention - "[date] text [signal:x]". Both are subject-first
+  // once the token is stripped, so match the token anywhere on the line rather
+  // than requiring it immediately after the date; a debrief-written signal was
+  // silently invisible to per-stakeholder matching before this.
+  const histText = sectionBody(md, 'Signal history') + '\n' + readEng(eng, SIGNAL_LEDGER)
+  histText.split('\n').forEach(l => {
+    const dm = l.trim().match(/^-\s*\[(\d{4}-\d{2}-\d{2})\]\s*(.*)$/i)
+    if (!dm) return
+    const sm = dm[2].match(/\[signal:(red|amber|green)\]/i)
+    if (!sm) return
+    const text = dm[2].replace(/\[signal:(red|amber|green)\]/i, '').trim()
+    history.push({ date: dm[1], signal: sm[1].toLowerCase(), text })
   })
 
   return rows.map(cs => {
@@ -420,7 +530,8 @@ function extractLog(eng) {
   sectionBody(readClean(eng, 'risks.md'), 'Retired').split('\n').forEach(l => {
     const m = l.trim().match(FLAT); if (m) push(m[1], m[2], 'receipt')
   })
-  sectionBody(readClean(eng, 'stakeholders.md'), 'Signal history').split('\n').forEach(l => {
+  const signalLog = sectionBody(readClean(eng, 'stakeholders.md'), 'Signal history') + '\n' + readClean(eng, SIGNAL_LEDGER)
+  signalLog.split('\n').forEach(l => {
     const m = l.trim().match(FLAT); if (m) push(m[1], m[2], 'note')
   })
 
@@ -542,7 +653,7 @@ function cmdResume(args) {
     const prev = readRegistry().find(r => r.workspace === cwd)
     const kept = readRegistry().filter(r => r.workspace !== cwd).map(r => `${r.workspace} ${r.slug}`)
     kept.push(`${cwd} ${slug}`)
-    fs.writeFileSync(REGISTRY, kept.join('\n') + '\n')
+    withFileLock(REGISTRY, () => { atomicWriteFile(REGISTRY, kept.join('\n') + '\n') })
     console.log(`ENGAGEMENT READY: ${fdeDir}\nbound to workspace: ${cwd}`)
     if (prev && prev.slug !== slug) console.log(`rebound: this workspace previously wrote to "${prev.slug}" - that memory is untouched; sessions here now write to "${slug}"`)
     // NDA surface: engagement notes must not silently leave the machine via file sync
@@ -617,10 +728,11 @@ function cmdLog(args) {
   const type = args[0]; const text = args.slice(1).join(' ')
   if (!LOG_FILES[type] || !text) { console.error('usage: fde log <decision|risk|delivery|contact> <text> [--signal red|amber|green]'); process.exit(1) }
   if (signal && type !== 'contact') { console.error('--signal only applies to: fde log contact'); process.exit(1) }
-  const eng = resolveEngagement()
+  const eng = resolveEngagement({ forWrite: true })
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
   const date = new Date().toISOString().slice(0, 10)
-  fs.appendFileSync(path.join(eng, LOG_FILES[type]), `\n- [${date}] ${signal ? `[signal:${signal}] ` : ''}${text}\n`)
+  const entry = `- [${date}] ${signal ? `[signal:${signal}] ` : ''}${text}`
+  appendLogEntry(eng, type, entry)
   console.log(`logged → ${LOG_FILES[type]}${signal ? ` (signal:${signal})` : ''}`)
 }
 
@@ -639,7 +751,7 @@ function cmdDebrief(args) {
   const dryIdx = args.indexOf('--dry-run')
   const dry = dryIdx !== -1
   if (dry) args.splice(dryIdx, 1)
-  const eng = resolveEngagement()
+  const eng = resolveEngagement({ forWrite: true })
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
   let input = ''
   if (args[0]) {
@@ -676,15 +788,19 @@ function cmdDebrief(args) {
     const m = bare.match(/^(decision|risk|delivery|contact):\s*(.+)$/i)
     if (m) {
       const type = m[1].toLowerCase()
-      if (dry) console.log(`→ ${LOG_FILES[type]}  - [${date}] ${m[2]}`)
-      else fs.appendFileSync(path.join(eng, LOG_FILES[type]), `\n- [${date}] ${m[2]}\n`)
+      const entry = `- [${date}] ${m[2]}`
+      if (dry) console.log(`→ ${LOG_FILES[type]}  ${entry}`)
+      // appendLogEntry, not a blind append: a contact: line may carry an
+      // inline [signal:x] token (the skill's own convention) and must land
+      // inside "## Signal history" the same way `fde log --signal` does.
+      else appendLogEntry(eng, type, entry)
       counts[type]++
     } else ctxLines.push(line)
   }
   if (ctxLines.length) {
     const stamp = `${date} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
     if (dry) ctxLines.forEach(l => console.log(`→ context.md  - ${l}`))
-    else fs.appendFileSync(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${ctxLines.map(l => `- ${l}`).join('\n')}\n`)
+    else lockedAppendFile(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${ctxLines.map(l => `- ${l}`).join('\n')}\n`)
   }
   const plural = { decision: 'decisions', risk: 'risks', delivery: 'deliveries', contact: 'contacts' }
   const parts = Object.keys(counts).filter(t => counts[t])
@@ -739,7 +855,7 @@ function cmdReceipts(args) {
 }
 
 function cmdCapture() {
-  const eng = resolveEngagement()
+  const eng = resolveEngagement({ forWrite: true })
   if (!eng) process.exit(0) // silent: capture must never break a session
   const branch = sh('git branch --show-current')
   const lastCommit = sh("git log -1 --format='%h %s'").slice(0, 100)
@@ -757,7 +873,7 @@ function cmdCapture() {
   if (branch) block += `- workspace: \`${branch}\` @ ${lastCommit || 'no commits yet'}\n`
   if (changed) block += `- uncommitted: ${changed}\n`
   if (updated) block += `- engagement files updated: ${updated}\n`
-  try { fs.appendFileSync(path.join(eng, 'context.md'), block) } catch (_) {}
+  try { lockedAppendFile(path.join(eng, 'context.md'), block) } catch (_) {}
 }
 
 function engagementSlugFromPath(eng) {
@@ -1554,18 +1670,8 @@ ${clientViews}
   }
 }
 
-const [cmd, ...args] = process.argv.slice(2)
-switch (cmd) {
-  case 'scan': cmdScan(); break
-  case 'resume': cmdResume(args); break
-  case 'log': cmdLog(args); break
-  case 'debrief': cmdDebrief(args); break
-  case 'receipts': cmdReceipts(args); break
-  case 'capture': cmdCapture(); break
-  case 'status': cmdStatus(args); break
-  case 'dashboard': cmdDashboard(args); break
-  default:
-    console.log(`fde - deterministic core of fdeops
+function printUsage() {
+  console.log(`fde - deterministic core of fdeops
   fde scan                 day-1 recon of this repo (facts, no AI)
   fde resume               load this workspace's engagement memory (bounded)
   fde resume --full        load the complete context.md (no bound)
@@ -1577,5 +1683,27 @@ switch (cmd) {
   fde capture              session-end memory snapshot (hooks use this)
   fde status [--all]       current engagement status (pass --all for full portfolio)
   fde dashboard [--all]    current engagement fieldbook (pass --all for every client)
-  env FDEOPS_ENGAGEMENTS_ROOT  override ~/fde-engagements (init/status/dashboard/registry)`)
+  env FDEOPS_ENGAGEMENTS_ROOT  override ~/fde-engagements (init/status/dashboard/registry)
+  writes require a workspace bind (or FDEOPS_ENGAGEMENT) - folder-name match is read-only`)
+}
+
+const [cmd, ...args] = process.argv.slice(2)
+switch (cmd) {
+  case 'scan': cmdScan(); break
+  case 'resume': cmdResume(args); break
+  case 'log': cmdLog(args); break
+  case 'debrief': cmdDebrief(args); break
+  case 'receipts': cmdReceipts(args); break
+  case 'capture': cmdCapture(); break
+  case 'status': cmdStatus(args); break
+  case 'dashboard': cmdDashboard(args); break
+  case 'help':
+  case '-h':
+  case '--help':
+    printUsage()
+    break
+  default:
+    printUsage()
+    // Missing or unknown command must fail - exit 0 made typos look like success in scripts/hooks.
+    process.exit(1)
 }

package/bin/install.js

@@ -142,6 +142,16 @@ function cmdAdapters(targetDir) {
   console.log(`  fdeops cross-platform adapters → ${dest}`)
   console.log('  One brain (skills/fde/SKILL.md). These are thin pointers per tool.')
   console.log('')
+  // The pointers below all point at ~/.claude/skills/fde/SKILL.md. Only the
+  // default install (bare `npx fdeops` / `node bin/install.js`) used to place
+  // that file - `adapters` alone wrote pointers to a brain that didn't exist
+  // yet, a dangling reference for anyone following the documented Cursor/Codex
+  // path. installSkills() is idempotent (safe to call every run).
+  if (!fs.existsSync(path.join(GLOBAL_SKILLS_DIR, 'fde', 'SKILL.md'))) {
+    installSkills()
+    console.log('  Skills → ~/.claude/skills/  (installed - the pointers below need this)')
+    console.log('')
+  }
   for (const a of ADAPTER_TARGETS) {
     if (!fs.existsSync(a.src)) { console.log(`  skip   ${a.label} (template missing)`); continue }
     placePointer(path.join(dest, a.dest), fs.readFileSync(a.src, 'utf8'), a.label, a.appendable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.7.7",
+  "version": "3.8.0",
   "description": "Field kit for engineers embedded in client work - a real CLI (recon, memory, portfolio), one @fde skill with field judgment on top, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
   "bin": {
     "fdeops": "bin/install.js",

package/skills/fde/SKILL.md

@@ -28,6 +28,7 @@ This is what makes fdeops a second brain instead of a chat window.
 4. **No invented facts - ever.** People, names, quotes, meetings, and numbers exist only if the FDE said them or the repo shows them. Never invent a stakeholder, a conversation, or a source to make the narrative richer - one fabricated name poisons every real citation around it. A missing fact is written as `unknown - ask: <the question>`, nothing else.
 5. **On exit:** before the session ends, append three lines to `context.md`: where we are, what changed today, the next step. The `session-stop` hook backstops this deterministically (hooks resolve the engagement through the workspace registry - no env var needed), but you write the meaningful version.
 6. **One customer, one folder.** Never merge two engagements into one `.fde/`. Confirm which engagement applies when multiple exist.
+7. **Never delete a code-read section when rewriting an artifact.** `stakeholders.md`'s `## Signal history` holds dated `[signal:...]` tokens that `fde status`/`fde receipts`/the dashboard read verbatim; `risks.md`'s `## Retired` is read the same way. Rewriting either file as an artifact (land, audit, stakeholder-radar) is fine - dropping one of these sections is not. Carry existing entries forward untouched.
 
 ## Data boundary (confirm before touching their code)
 
@@ -37,7 +38,7 @@ This is what makes fdeops a second brain instead of a chat window.
 - Data tagged `<private>` in `trust-profile.md` (sacred data, PHI, cardholder, classified) **never enters your context or any subagent prompt** - work around it, never with it.
 - Locked-down engagement (no AI on their code)? Use the CLI + the fieldbook only. The memory layer is the FDE's own notes, not customer code.
 
-**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match → `./.fde`. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
+**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes require a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
 
 **The `fde` CLI does the deterministic work - use it instead of improvising shell:**
 

package/skills/fde/references/land.md

@@ -69,6 +69,7 @@ Before the end of day 1, ship one visible thing: a small bug fix, a cleanup the
 |-----|------|--------|-------|
 | <name> | sponsor / champion / resistor / veto / passed-over | green/amber/red | <evidence, day> |
 ```
+If `stakeholders.md` already has a `## Signal history` section (it does from the template), **never delete or overwrite it** when you rewrite this file - it holds the dated `[signal:...]` tokens `fde log contact --signal` and `fde debrief` write, and `fde status`/`fde receipts`/the dashboard read only from that section. Edit the table above it freely; keep the section below intact.
 
 **`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: never loaded for status reads, never into subagent prompts.
 

package/templates/.fde/stakeholders.md

@@ -8,3 +8,11 @@
 
 **Trust signal:** green | amber | red  
 **Last trust check:**
+
+## Signal history
+
+<!-- `fde log contact --signal <color>` and `fde debrief` write dated tokens here.
+     fde status/receipts read the LATEST dated [signal:...] token in this section
+     to drive the trust column - do not delete this heading, and if you rewrite
+     this file as an artifact, keep this section's entries intact. -->
+