fdeops 3.7.8 → 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')
@@ -202,9 +255,13 @@ function appendUnderSection(md, heading, entry) {
 function appendLogEntry(eng, type, entry) {
   const p = path.join(eng, LOG_FILES[type])
   if (type === 'contact' && /\[signal:(red|amber|green)\]/i.test(entry)) {
-    fs.writeFileSync(p, appendUnderSection(readEng(eng, LOG_FILES[type]), 'Signal history', 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 {
-    fs.appendFileSync(p, `\n${entry}\n`)
+    lockedAppendFile(p, `\n${entry}\n`)
   }
 }
 
@@ -219,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] || ''
@@ -351,7 +410,8 @@ function extractStakeholders(eng) {
   // 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.
-  sectionBody(md, 'Signal history').split('\n').forEach(l => {
+  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)
@@ -470,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')
   })
 
@@ -592,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
@@ -667,7 +728,7 @@ 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)
   const entry = `- [${date}] ${signal ? `[signal:${signal}] ` : ''}${text}`
@@ -690,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]) {
@@ -739,7 +800,7 @@ function cmdDebrief(args) {
   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])
@@ -794,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)
@@ -812,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) {
@@ -1609,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)
@@ -1632,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.7.8",
+  "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

@@ -38,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:**