fdeops 3.7.1 → 3.7.3

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - working in the fdeops repository
 
-This repository **is** fdeops - the operating system 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 writes itself into `.fde/` files.
 
 ## If you are helping use fdeops in an engagement
 

package/README.md

@@ -27,6 +27,8 @@ Your AI agent's memory is scoped to a **repo**. Client work isn't: one engagemen
 
 fdeops adds the missing layer: memory scoped to the **client** - plain markdown at `~/fde-engagements/<client>/.fde/`, written as a side effect of doing the work. Local only, zero dependencies, no network, no telemetry.
 
+A notes app stores what you type. fdeops loads the right client into your AI agent's context automatically and turns meetings into dated receipts you can defend - the difference is what happens without you opening it.
+
 ## Without fdeops vs with fdeops
 
 | Moment | Without fdeops | With fdeops |
@@ -51,9 +53,11 @@ fdeops adds the missing layer: memory scoped to the **client** - plain markdown
 **2. Bind your client workspace** - run once, inside the workspace:
 
 ```bash
-fde resume --init garvey
+npx fdeops resume --init garvey
 ```
 
+(`npx` needs nothing pre-installed. Want the bare `fde` command the rest of this README uses? `npm i -g fdeops` - the plugin install alone does not put `fde` on your PATH.)
+
 fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde/` (plain markdown, private to your machine) and binds this workspace to it. The hooks read that binding - context auto-loads at session start, auto-captures at session end. That is the whole setup.
 
 **3. Work**
@@ -64,7 +68,7 @@ fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde
 
 `@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).
 
-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.
+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.
 
 <details>
 <summary><strong>Other install paths</strong> - Cursor, Codex, Copilot, Gemini CLI, local LLMs, air-gapped</summary>
@@ -80,6 +84,17 @@ Not ready to install? `npx fdeops scan` runs on any repo you can read - day-1 re
 
 ---
 
+## The week
+
+This is the actual habit, not the 35 skills:
+
+- **Monday morning** - open your agent, context loads, you're not re-explaining anything
+- **After a meeting** - `fde debrief` turns raw notes into dated decisions, risks, and signals
+- **Mid-scope-fight** - `fde receipts <term>` answers "when did we agree to that?"
+- **Friday** - `fde status` gives you the sponsor update from the week's actual record
+
+---
+
 ## How it works
 
 Two hooks and one router, on top of the fieldbook:
@@ -100,7 +115,7 @@ Two hooks and one router, on top of the fieldbook:
 
 Overlays for regulated domains (AI, fintech, healthcare, government) activate on signal. fdeops complements your agent's native repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *engagement* works. Full matrix: [docs/skills.md](docs/skills.md).
 
-Works with **Claude Code** - **Cursor** - **Copilot** - **Devin** - **Gemini CLI** - **Ollama** - **LM Studio** - any model that reads a markdown file.
+Works with **Claude Code** - **Cursor** - **Copilot** - **Gemini CLI** - **Ollama** - **LM Studio** - any model that reads a markdown file.
 
 ---
 
@@ -174,6 +189,7 @@ Details: [PRIVACY.md](PRIVACY.md) · [SECURITY.md](SECURITY.md)
 ## Principles
 
 - **The artifact is the memory** - producing work and recording it are one action
+- **Methods, not autonomy** - each skill tells you what to check; the judgment, the trust, and the consequences stay yours
 - **Trust before production** - earn the right to touch their systems
 - **Brief is a hypothesis** - discover before building the wrong thing
 - **Evidence on every claim** - these files get defended in front of skeptical clients

package/bin/fde.js

@@ -111,9 +111,17 @@ function resolveEngagement() {
       }
     } catch (_) {}
   }
-  // 4) workspace dir name matches an engagement slug
+  // 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')
-  if (fs.existsSync(guess)) return guess
+  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`)
+    return guess
+  }
   // 5) in-repo .fde (engagement-approved only)
   if (fs.existsSync(path.join(cwd, '.fde'))) return path.join(cwd, '.fde')
   return null
@@ -157,7 +165,9 @@ function sectionBody(md, heading) {
 // zero-effort floor when NO token exists anywhere - prose like "escalated to CTO,
 // resolved amicably" must not flip a client amber forever.
 function computeSignals(eng) {
-  const ctx = readEng(eng, 'context.md'); const stake = readEng(eng, 'stakeholders.md'); const risks = readEng(eng, 'risks.md')
+  // 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')
   const phase = (ctx.match(/phase[:* ]+\**([a-z-]+)/i) || [])[1] || '?'
   let latest = null
   for (const l of stake.split('\n')) {
@@ -463,7 +473,7 @@ function cmdScan() {
   const sec = grepFiles(confFiles, /(api[_-]?key|secret|password|token)\s*[:=]\s*['"][^'"]{8,}/i, 10)
     .filter(h => !/example|template|test|sample|placeholder/i.test(h.file + h.text))
   sec.length
-    ? sec.forEach(h => out.push(`  ${h.file}:${h.line}  ${h.text.replace(/(['"])([^'"]{4})[^'"]+(['"])/, '$1$2…REDACTED$3')}`))
+    ? sec.forEach(h => out.push(`  ${h.file}:${h.line}  ${h.text.replace(/(['"])[^'"]+(['"])/, '$1REDACTED$2')}`))
     : out.push('  none found')
   out.push('  (grep-grade check - run gitleaks or trufflehog for real secret coverage)')
 
@@ -547,10 +557,11 @@ function cmdResume(args) {
     process.exit(2)
   }
   console.log(`ENGAGEMENT: ${eng}\n`)
-  try {
-    const ctx = fs.readFileSync(path.join(eng, 'context.md'), 'utf8')
-    console.log(args.includes('--full') ? ctx : resumeView(ctx))
-  } catch (_) { console.log('(context.md empty - new engagement)') }
+  // readClean, not fs.readFileSync: this output is what an agent loads as
+  // context, so it goes through the same <private> redaction as the dashboard.
+  const ctx = readClean(eng, 'context.md')
+  if (!ctx) { console.log('(context.md empty - new engagement)') }
+  else { console.log(args.includes('--full') ? ctx : resumeView(ctx)) }
 }
 
 // Token discipline: context.md grows every session (the session-stop hook
@@ -660,7 +671,10 @@ function cmdReceipts(args) {
   for (const f of ['decisions.md', 'delivery.md', 'risks.md', 'stakeholders.md', 'context.md', 'success.md', 'brief.md', 'reality.md']) {
     const p = path.join(eng, f)
     if (!fs.existsSync(p)) continue
-    fs.readFileSync(p, 'utf8').split('\n').forEach((l, i) => {
+    // readClean, not raw read: receipts must not grep sealed <private> notes back
+    // out. Redaction can shift line numbers past a multi-line block; the file:line
+    // is advisory, and not leaking a sealed secret is worth an approximate number.
+    readClean(eng, f).split('\n').forEach((l, i) => {
       if (rx.test(l)) { console.log(`${f}:${i + 1}  ${l.trim().slice(0, 160)}`); found++ }
     })
   }
@@ -724,9 +738,14 @@ function escapeHtml(s) {
 // Closed pairs are redacted; an unclosed <private> redacts to end-of-text so a
 // forgotten closing tag can never leak the rest of the file.
 function stripPrivate(md) {
+  // Redact <private> before <!-- --> so a private block that itself contains a
+  // comment can't survive. Closed pairs first; then any unclosed <private> to
+  // end-of-text so a forgotten close tag never leaks the rest of the file.
+  // Case-insensitive (<PRIVATE> too). This is the ONE redactor every read path
+  // that can reach the model or a shared artifact must go through - see readClean.
   return md
-    .replace(/<private>[\s\S]*?<\/private>/gi, '(private - redacted from dashboard)')
-    .replace(/<private>[\s\S]*$/i, '(private - redacted from dashboard)')
+    .replace(/<private>[\s\S]*?<\/private>/gi, '(private - redacted)')
+    .replace(/<private>[\s\S]*$/i, '(private - redacted)')
     .replace(/<!--[\s\S]*?-->/g, '')
 }
 

package/hooks/pre-compact

@@ -56,19 +56,40 @@ MARKER="[fdeops context preserved"
 [ -f "$CONTEXT_FILE" ] || exit 0
 
 # Avoid unbounded growth: skip if we already preserved today.
-if grep -q "$MARKER" "$CONTEXT_FILE" 2>/dev/null; then
-  LAST=$(grep "$MARKER" "$CONTEXT_FILE" | tail -1)
+if grep -Fq "$MARKER" "$CONTEXT_FILE" 2>/dev/null; then
+  LAST=$(grep -F "$MARKER" "$CONTEXT_FILE" | tail -1)
   if echo "$LAST" | grep -q "$(date -u +%Y-%m-%d)"; then
     exit 0
   fi
 fi
 
+# Redact <private> before extracting lines - this content is appended to
+# context.md, which session-start loads into the model. A closed private block
+# collapses to one placeholder line, so its inner text can't be tail'd or
+# grepped out tag-stripped. Case-insensitive, mirrors the JS /gi redactor.
+strip_private() {
+  awk '
+    BEGIN { inblock = 0 }
+    {
+      line = $0
+      lc = tolower(line)
+      if (inblock) { if (index(lc, "</private>") > 0) { inblock = 0 } next }
+      if (index(lc, "<private>") > 0) {
+        print "(private - redacted)"
+        if (index(lc, "</private>") == 0) { inblock = 1 }
+        next
+      }
+      print line
+    }
+  ' "$1"
+}
+
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 LAST_DECISIONS=""
 OPEN_RISKS=""
 
-[ -f "$DECISIONS_FILE" ] && LAST_DECISIONS=$(tail -20 "$DECISIONS_FILE" 2>/dev/null)
-[ -f "$RISKS_FILE" ] && OPEN_RISKS=$(grep -iE "open|active|unresolved" "$RISKS_FILE" 2>/dev/null | head -8)
+[ -f "$DECISIONS_FILE" ] && LAST_DECISIONS=$(strip_private "$DECISIONS_FILE" 2>/dev/null | tail -20)
+[ -f "$RISKS_FILE" ] && OPEN_RISKS=$(strip_private "$RISKS_FILE" 2>/dev/null | grep -iE "open|active|unresolved" | head -8)
 
 cat >> "$CONTEXT_FILE" 2>/dev/null << EOF
 

package/hooks/session-start

@@ -79,6 +79,35 @@ if [ "$IS_FDE_PROJECT" -eq 0 ]; then
   exit 0
 fi
 
+# Mirrors stripPrivate() in bin/fde.js: this is what an agent loads as
+# context, so <private>...</private> blocks (sacred data, never-AI content)
+# must never reach here unredacted, same guarantee as the dashboard renderer.
+# <private> blocks are written one per line in the templates (own line, own
+# closing tag), so a line-based state machine matches the real usage; an
+# unclosed <private> redacts to end-of-file, same as the JS regex fallback.
+strip_private() {
+  # Detection is case-insensitive (matches the JS /gi redactor) - <PRIVATE>,
+  # <Private>, <private> all redact. Detect on a lowercased copy of the line;
+  # never print the original when a tag is present.
+  awk '
+    BEGIN { inblock = 0 }
+    {
+      line = $0
+      lc = tolower(line)
+      if (inblock) {
+        if (index(lc, "</private>") > 0) { inblock = 0 }
+        next
+      }
+      if (index(lc, "<private>") > 0) {
+        print "(private - redacted)"
+        if (index(lc, "</private>") == 0) { inblock = 1 }
+        next
+      }
+      print line
+    }
+  ' "$1"
+}
+
 # Token discipline: context.md grows every session (session-stop appends a
 # snapshot). Inject a bounded view - curated head + most recent activity -
 # instead of the whole log. Mirrors resumeView() in bin/fde.js; keep in sync.
@@ -106,7 +135,10 @@ if [ -n "$BOOTSTRAP" ]; then
 fi
 
 if [ -n "$CONTEXT_FILE" ] && [ -f "$CONTEXT_FILE" ]; then
-  CONTENT="$CONTENT---\nEngagement context ($CONTEXT_FILE):\n$(bounded_context "$CONTEXT_FILE")\n"
+  REDACTED_CONTEXT=$(mktemp)
+  strip_private "$CONTEXT_FILE" > "$REDACTED_CONTEXT"
+  CONTENT="$CONTENT---\nEngagement context ($CONTEXT_FILE):\n$(bounded_context "$REDACTED_CONTEXT")\n"
+  rm -f "$REDACTED_CONTEXT"
 fi
 
 printf '%b' "$CONTENT"

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "fdeops",
-  "version": "3.7.1",
+  "version": "3.7.3",
   "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",
     "fde": "bin/fde.js"
   },
   "scripts": {
-    "check": "node bin/check.js",
-    "prepublishOnly": "node bin/check.js"
+    "check": "node bin/check.js && npm test",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node bin/check.js && npm test"
   },
   "files": [
     "bin/",

package/skills/fde/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fde
-description: The operating system for Forward Deployed Engineers. 35 skills across 6 domains - from first meeting to final handoff. Tell it your situation, it routes to the right skill, does the work, and the engagement memory writes itself.
+description: The second brain for Forward Deployed Engineers. 35 skills across 6 domains - from first meeting to final handoff. Tell it your situation, it routes to the right skill, does the work, and the engagement memory writes itself.
 ---
 
 # @fde