fdeops 3.9.14 → 3.9.16

package/bin/fde.js

@@ -107,9 +107,13 @@ function resolveEngagement(opts = {}) {
   // 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
+  const accept = (p) => acceptEngagementPath(p, { 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
+  if (env) {
+    const ok = accept(env)
+    if (ok) return ok
+  }
   // 2) workspace registry binding (written by resume --init). Match the cwd OR
   // any ancestor of it - FDEs run commands from src/, packages/api/, etc., not
   // just the repo root where they bound. Nearest (deepest) registered ancestor
@@ -122,8 +126,8 @@ function resolveEngagement(opts = {}) {
     .filter(r => cwd === r.workspace || cwd.startsWith(r.workspace + path.sep))
     .sort((a, b) => b.workspace.length - a.workspace.length)[0]
   if (reg) {
-    const p = path.join(ENGAGEMENTS_ROOT, reg.slug, '.fde')
-    if (fs.existsSync(p)) return p
+    const ok = accept(path.join(ENGAGEMENTS_ROOT, reg.slug, '.fde'))
+    if (ok) return ok
   }
   // 3) global pointer file (back-compat: try old FDEOS-CLAUDE.md too)
   for (const ptrName of ['FDEOPS-CLAUDE.md', 'FDEOS-CLAUDE.md']) {
@@ -131,8 +135,8 @@ function resolveEngagement(opts = {}) {
       const ptr = fs.readFileSync(path.join(HOME, '.claude', ptrName), 'utf8')
       const m = ptr.match(/^(?:FDEOPS|FDEOS)_ENGAGEMENT=(.+)$/m)
       if (m) {
-        const p = m[1].trim().replace(/^~/, HOME)
-        if (fs.existsSync(p)) return p
+        const ok = accept(m[1].trim().replace(/^~/, HOME))
+        if (ok) return ok
       }
     } catch (_) {}
   }
@@ -150,14 +154,37 @@ function resolveEngagement(opts = {}) {
       )
       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
+    const ok = accept(guess)
+    if (ok) {
+      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 ok
+    }
   }
   // 5) in-repo .fde (engagement-approved only)
-  if (fs.existsSync(path.join(cwd, '.fde'))) return path.join(cwd, '.fde')
+  const inRepo = accept(path.join(cwd, '.fde'))
+  if (inRepo) return inRepo
   return null
 }
 
+// Engagement memory must be a directory. A file named .fde used to yield a
+// healthy-looking green TRIAGE then raw ENOTDIR on write - refuse loudly.
+function acceptEngagementPath(p, opts = {}) {
+  if (!p || !fs.existsSync(p)) return null
+  try {
+    const st = fs.statSync(p)
+    if (st.isDirectory()) return p
+    const msg =
+      `engagement path is not a directory (memory missing/broken): ${p}\n` +
+      '  repair: remove that file, then re-run: fde resume --init <name>'
+    console.error(msg)
+    if (opts.forWrite) process.exit(1)
+    return null
+  } catch (e) {
+    if (opts.forWrite) failFs(e, 'open', p)
+    return null
+  }
+}
+
 function templatesDir() {
   for (const c of [path.join(__dirname, '..', 'templates', '.fde'), path.join(__dirname, 'templates', '.fde')]) {
     if (fs.existsSync(c)) return c
@@ -172,11 +199,19 @@ function readEng(eng, f) {
 }
 
 // Redact private notes and template hints from every model-facing read.
+// Also strip terminal control chars so poisoned memory cannot smuggle ANSI
+// into triage/prep/status (C0/C1 except tab/LF/CR).
+function stripControlChars(s) {
+  return String(s || '').replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
+}
+
 function stripPrivate(md) {
-  return md
-    .replace(/<private>[\s\S]*?<\/private>/gi, '(private - redacted)')
-    .replace(/<private>[\s\S]*$/i, '(private - redacted)')
-    .replace(/<!--[\s\S]*?-->/g, '')
+  return stripControlChars(
+    String(md || '')
+      .replace(/<private>[\s\S]*?<\/private>/gi, '(private - redacted)')
+      .replace(/<private>[\s\S]*$/i, '(private - redacted)')
+      .replace(/<!--[\s\S]*?-->/g, '')
+  )
 }
 
 // Read + redact in one step - the default way dashboard code should ever touch
@@ -239,6 +274,9 @@ function formatFsError(err, action, target) {
   const code = err && err.code
   const where = path.basename(String(target || '')) || String(target || 'path')
   if (code === 'ENOSPC') return `cannot ${action} ${where} - disk full`
+  if (code === 'ENOTDIR') {
+    return `cannot ${action} ${where} - engagement path is not a directory (memory missing/broken); remove the file and re-run fde resume --init`
+  }
   if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS') {
     return `cannot ${action} ${where} - permission denied (read-only or locked down)`
   }
@@ -392,7 +430,7 @@ function datedEntry(eng, date, text, signal) {
   const bits = [`- [${date}]`]
   if (who) bits.push(`[${who}]`)
   if (signal) bits.push(`[signal:${signal}]`)
-  bits.push(text)
+  bits.push(stripControlChars(text))
   return bits.join(' ')
 }
 
@@ -1136,7 +1174,7 @@ function smartProposeText(input) {
 
 function setNextAction(eng, text) {
   ensureMemoryGit(eng)
-  const bullet = `- ${String(text).replace(/^[-*]\s+/, '').trim()}`
+  const bullet = `- ${stripControlChars(String(text).replace(/^[-*]\s+/, '').trim())}`
   const p = path.join(eng, 'context.md')
   let md = readEng(eng, 'context.md')
   if (!md) md = '# Engagement context\n\n'
@@ -1148,6 +1186,24 @@ function setNextAction(eng, text) {
   withFileLock(p, () => { atomicWriteFile(p, md.endsWith('\n') ? md : md + '\n') })
 }
 
+function looksLikeBinaryNoise(text) {
+  const s = String(text || '')
+  if (!s) return false
+  if (s.includes('\0')) return true
+  const sample = s.slice(0, 8192)
+  let ctrl = 0
+  let replacement = 0
+  for (let i = 0; i < sample.length; i++) {
+    const c = sample.charCodeAt(i)
+    if (c === 0xfffd) replacement++
+    if (c === 9 || c === 10 || c === 13) continue
+    if (c < 32 || (c >= 0x7f && c <= 0x9f)) ctrl++
+  }
+  if (!sample.length) return false
+  // Mostly-control or high U+FFFD density = urandom / binary mistyped as text.
+  return (ctrl / sample.length) > 0.05 || (replacement / sample.length) > 0.1
+}
+
 function readDebriefInput(args) {
   let input = ''
   if (args[0]) {
@@ -1160,19 +1216,25 @@ function readDebriefInput(args) {
     }
     let buf
     try { buf = fs.readFileSync(notesPath) } catch (_) { console.error(`cannot read ${args[0]}`); process.exit(1) }
-    if (buf.includes(0)) {
-      console.error(`debrief refused: ${args[0]} looks binary (null bytes). Paste text notes only.`)
+    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)
     }
     input = buf.toString('utf8')
   } else {
-    try { input = fs.readFileSync(0, 'utf8') } catch (_) {}
-    if (Buffer.byteLength(input, 'utf8') > DEBRIEF_MAX_BYTES) {
+    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)
     }
+    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)
+    }
+    input = buf.toString('utf8')
   }
-  return input
+  return stripControlChars(input)
 }
 
 function previewLine(text, max = 240) {
@@ -1250,7 +1312,7 @@ function cmdDebrief(args) {
 
   let input = ''
   if (apply && !smart && !args[0]) {
-    try { input = fs.readFileSync(path.join(eng, DEBRIEF_PROPOSE), 'utf8') } catch (_) {
+    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)
     }

package/package.json

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

@@ -49,7 +49,7 @@ These stop confident fiction. They are not optional soft tips.
 | Invent a stakeholder, meeting, or quote to make the narrative rich | **Stop.** Write `unknown - ask: <question>`. One fake name poisons every real citation. |
 | Route to a phase because it "feels senior" while the signal is muddy | **Stop.** Playback + one natural question, or name the ambiguity ("discover or rescue — leaning X because…"). |
 | Fill `success.md` / `terrain.md` with plausible defaults when the brief is thin | **Stop.** Run **brief interrogation** in land/discover (one Q + GUESS + confidence) until you can write without guessing, or leave gaps explicit. |
-| Ship / go-live / irreversible change with "probably fine" | **Stop.** Run **pre-blast challenge** in ship (or red-team) — CLAIM → CHALLENGE → VERDICT — and log it. |
+| Ship / go-live / irreversible change with "probably fine" | **Stop.** Run **intent vs diff** (KEEP/JUSTIFY/SPLIT/DROP) then **pre-blast challenge** in ship (or red-team) — CLAIM → CHALLENGE → VERDICT — and log both. |
 | Grill the FDE with a checklist when they're mid-flow | **Stop.** Playback rule wins. Probe only when a missing fact changes the next move. |
 
 When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FDE explicitly asked for speed, answer already in `.fde/`.
@@ -243,6 +243,7 @@ Getting to production without surprises.
 |----------|-------|-----------|
 | Ready to deploy, going live, pre-flight check | ship | `references/ship.md` |
 | Review this change, is it safe, does it match what we agreed | review | `references/review.md` |
+| Diff grew / scope creep in the PR / "did we only build what we said" / KEEP JUSTIFY SPLIT DROP | review (+ ship if going live) | `references/review.md` Stage 1 · `references/ship.md` Intent vs diff |
 | "We can always revert" - need to actually test the escape route | rollback-drill | `references/rollback-drill.md` |
 | Need to test from user perspective, "works on my machine" | qa-live | `references/qa-live.md` |
 

package/skills/fde/references/build.md

@@ -58,7 +58,7 @@ The spec becomes the test list - every line is something to verify after build.
    - `[DEFERRED]` intentionally left for a later task (state which one)
    Surface the results to the FDE. If any scenario fails, fix it before cleanup. This is not optional - the spec is the contract.
 9. **Cleanup pass after it works.** Dedupe repeated mechanics into the smallest service module; behavior unchanged; re-run the same tests. If you wrote 200 lines and 50 would do, rewrite before review.
-10. **Review gate (before merge):** two stages, in order - (a) **scope**: does the diff match the approved spec and `decisions.md`, nothing more? (b) **safety**: blast radius honest, tests meaningful, rollback real, secrets absent. Fix real findings, re-verify, repeat until clean or blocked on a human decision.
+10. **Review gate (before merge):** two stages, in order - (a) **intent vs diff**: every path KEEP / JUSTIFY / SPLIT / DROP against the stated slice in `decisions.md` (see `review.md` Stage 1); (b) **safety**: blast radius honest, tests meaningful, rollback real, secrets absent. Fix real findings, re-verify, repeat until clean or blocked on a human decision.
 11. **Log and deliver.** Update the artifacts (below). Visible progress beats invisible perfection - every 2–3 tasks something shown to a stakeholder.
 
 **Touching existing code - classify before changing:**

package/skills/fde/references/review.md

@@ -12,13 +12,29 @@ Thousands of lines or dozens of unrelated files → **stop**, recommend the spli
 
 ## Stage 1 - did we build what we agreed? (you do this work)
 
-Check the diff against `decisions.md` - what was *explicitly decided*, not what seems right:
-- Matches agreed scope?
+Check the diff against the **one-line intent** in `decisions.md` / acceptance criteria — what was *explicitly decided*, not what seems right:
+
+```bash
+git diff <base>...HEAD --stat
+```
+
+For each touched path (or logical hunk), assign one verdict:
+
+| Verdict | Meaning |
+|---------|---------|
+| **KEEP** | Required for the stated intent |
+| **JUSTIFY** | Adjacent but must ship now — write one sentence why, or SPLIT |
+| **SPLIT** | Real work for another PR / Next / kill list — do not merge with this slice |
+| **DROP** | Noise / drive-by — revert before Pass |
+
+Also check:
 - Any sacred system from `trust-profile.md` touched?
 - Any sensitive data newly in scope?
 - Rollback path defined before build still honoured?
 
-**Stage 1 fails → stop.** Quality review on out-of-scope code is wasted work. Record the specific mismatch in `decisions.md`.
+**Stage 1 fails → stop** if any SPLIT/DROP remains, or JUSTIFY lacks a written sentence. Quality review on out-of-scope code is wasted work. Record the mismatch (and the KEEP/JUSTIFY/SPLIT/DROP tally) in `decisions.md`.
+
+Stakeholder "also can you…" mid-build is `scope-defense` — different axis. This stage is **code vs claim**.
 
 ## Stage 2 - is it safe to live with?
 
@@ -48,6 +64,7 @@ Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock
 ## Principles
 
 - Stage 1 before Stage 2. Wrong scope reviewed well is still wrong scope.
+- KEEP / JUSTIFY / SPLIT / DROP — every path gets a verdict; silent extras fail Stage 1.
 - Specific or silent - vague concerns waste everyone's time.
 - No rollback path = first finding.
 - A clean review proves this diff is safe as agreed - not that the feature was right.

package/skills/fde/references/ship.md

@@ -63,6 +63,28 @@ Score each dimension green/amber/red. This is the gate, not a suggestion:
 
 Write the readiness score (including value + receipts) to `delivery.md` before deploying. The score is the evidence if anything goes wrong.
 
+## Intent vs diff (before pre-blast)
+
+Ship the change you intended — not the drift that snuck in. Run this on the deploy branch against the **one-line intent** from `decisions.md` / `success.md` (the slice you said you were building).
+
+```bash
+git diff <base>...HEAD --stat
+git diff <base>...HEAD
+```
+
+Score every touched path (or logical hunk):
+
+| Path / change | Verdict | Rule |
+|---------------|---------|------|
+| | **KEEP** | Directly required for the stated intent |
+| | **JUSTIFY** | Adjacent but load-bearing — one sentence why it must ship *now*, or split |
+| | **SPLIT** | Real work, wrong PR — park in `decisions.md` kill/Next; do not deploy with this slice |
+| | **DROP** | Noise (format-only, drive-by rename, unrelated tidy) — revert before ship |
+
+**Any SPLIT or DROP still in the tree = fix-first.** JUSTIFY without a written sentence = treat as SPLIT. Log a one-line receipt in `delivery.md`: `intent vs diff: KEEP n · JUSTIFY n · SPLIT n · DROP n — <intent>`.
+
+This is **code drift**, not stakeholder "also can you…" (that is `scope-defense`). Same family as review Stage 1 — ship refuses green when the diff outgrew the claim.
+
 ## Pre-blast challenge (before the deploy button)
 
 For any non-trivial go-live (shared infra, regulated data, irreversible migration, or first prod touch), run this once before canary — not as theater, as a stop-the-line check:
@@ -162,7 +184,7 @@ Adoption isn't a handoff-stage problem - it starts during build. Software that l
 
 ## Checkpoint
 
-Before 100%: canary clean, business metric verified, pulse written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**. Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
+Before 100%: canary clean, business metric verified, pulse written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**, **intent vs diff clean** (no unresolved SPLIT/DROP). Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
 
 ## Principles
 
@@ -170,6 +192,7 @@ Before 100%: canary clean, business metric verified, pulse written into `deliver
 - Roll back on any canary anomaly; investigate safely.
 - Verify the business metric, not just the technical one.
 - No value bucket, no green ship. No pulse, no done.
+- Diff larger than the stated intent without KEEP/JUSTIFY receipts = fix-first.
 - AI path without eval receipt = fix-first; non-AI ships leave eval as n/a.
 - Scale readiness is organizational, not just technical. Check all 8 dimensions.
 - Adoption is measured from day one, not hoped for at launch.