fdeops 3.9.8 → 3.9.10

package/README.md

@@ -2,7 +2,7 @@
 
 **Your AI coding agent forgets your client every morning. fdeops remembers.**
 
-[![npm version](https://img.shields.io/npm/v/fdeops)](https://www.npmjs.com/package/fdeops)
+[![npm version](https://img.shields.io/npm/v/fdeops.svg)](https://www.npmjs.com/package/fdeops)
 [![CI](https://github.com/suboss87/fdeops/actions/workflows/validate.yml/badge.svg)](https://github.com/suboss87/fdeops/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
@@ -92,7 +92,17 @@ npx fdeops resume                 # prints a short "where we are" for this clien
 
 fdeops complements repo memory: CLAUDE.md holds how the *code* works; the fieldbook holds how the *client engagement* works.
 
-Works with **Claude Code** · **Cursor** · **Copilot** · **Gemini CLI** · **Ollama** · **LM Studio** - any model that reads markdown.
+### Switch coding agents anytime
+
+The fieldbook lives on disk at `~/fde-engagements/<client>/.fde/` - not inside Claude, Cursor, or any other tool. Change AI coding agents and the **same client record** is still there.
+
+On the new tool:
+
+1. Install `@fde` for that tool (plugin, `npx skills add suboss87/fdeops`, or `npx fdeops adapters .` - see [adapters/](adapters/README.md))
+2. Open a workspace already bound with `npx fdeops resume --init <client>` (or bind once if this checkout is new)
+3. Talk with `@fde` or run `npx fdeops resume`
+
+Same fieldbook. **Claude Code** gets the fullest ride (session start/stop hooks). Elsewhere the memory and CLI are the same; context usually loads when you ask `@fde` / `resume`, not automatically. Details: [docs/install.md](docs/install.md).
 
 <details>
 <summary><strong>Phase verbs</strong> (land → close)</summary>

package/adapters/README.md

@@ -2,6 +2,8 @@
 
 **One brain, thin adapters.** fdeops has a single source of truth - the `@fde` skill at `skills/fde/SKILL.md` and the `fde` CLI. Each AI coding tool discovers it through a small pointer file in the place that tool already looks. No forked logic, no five copies to maintain - every adapter says the same thing: *route via `@fde`, read/write `.fde/` memory, talk like a peer, never touch what isn't yours.*
 
+**Switching tools:** the fieldbook does not live in the agent. It lives at `~/fde-engagements/<client>/.fde/`. Point a new tool at a bound workspace, drop adapters (or install the skill/plugin for that tool), and the same client record opens. Auto session hooks are Claude Code–first; elsewhere load via `@fde` / `fde resume`. See [README § Switch coding agents](../README.md#switch-coding-agents-anytime).
+
 ## What goes where
 
 | Tool | File in your engagement workspace | Source template |

package/bin/fde.js

@@ -541,6 +541,7 @@ const {
   nextActionLine,
   computeSignals,
   resumeTriage,
+  countOpenRisks,
 } = createTrustApi({
   fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
 })
@@ -921,8 +922,8 @@ function cmdResume(args) {
     console.log(`NO ENGAGEMENT for this workspace.\nexisting: ${list}\ncreate + bind one:  fde resume --init <client-name>`)
     process.exit(2)
   }
-  // Monday-morning command: triage first (trust / phase / risks / next), then memory.
-  console.log(resumeTriage(eng))
+  // Monday-morning: triage + proactive hygiene (silent when clean), then memory.
+  printTriageBlock(eng)
   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.
@@ -1046,7 +1047,18 @@ function setContextPhase(eng, phase) {
     md = md.replace(/\*\*Last updated:\*\*\s*.*/i, `**Last updated:** ${today}`)
   }
   withFileLock(p, () => { atomicWriteFile(p, md.endsWith('\n') ? md : md + '\n') })
-  return commitMemory(eng, `phase ${phase}`, { files: ['context.md'] })
+  const hash = commitMemory(eng, `phase ${phase}`, { files: ['context.md'] })
+  // Proactive warn at the moment it matters - don't wait for Monday hygiene.
+  if (phase === 'ship' || phase === 'close') {
+    const open = countOpenRisks(eng)
+    if (open > 0) {
+      process.stderr.write(
+        `⚠ phase → ${phase} with ${open} open risk(s) still live - retire, hand off, or keep them intentional\n` +
+        '  say "@fde clean up the fieldbook" to walk the list (or: fde doctor)\n'
+      )
+    }
+  }
+  return hash
 }
 
 
@@ -1341,7 +1353,8 @@ function cmdTriage() {
     console.error('no engagement - run: fde resume --init <name>')
     process.exit(2)
   }
-  console.log(resumeTriage(eng))
+  // Session-start hooks call this - hygiene is proactive here (silent when clean).
+  printTriageBlock(eng)
   const owner = readOwner(eng) || writeOwnerIfMissing(eng)
   const head = memoryHead(eng)
   if (owner || head) {
@@ -1417,18 +1430,29 @@ function findDuplicateOpenRisks(eng) {
   return [...byKey.values()].filter(g => g.length >= 2)
 }
 
-function cmdDoctor() {
-  const eng = resolveEngagement()
-  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+// Deterministic fieldbook hygiene - shared by doctor + session TRIAGE.
+// Silent when clean OR brand-new (no dated work yet). Never auto-rewrites.
+// High-value moments: week-start (via triage), ship/close, after real work accrues.
+function collectDoctorIssues(eng) {
   const issues = []
   const s = computeSignals(eng)
-  if (s.phase === '?') {
-    const hasWork = /\[\d{4}-\d{2}-\d{2}\]/.test(readEng(eng, 'decisions.md') + readEng(eng, 'delivery.md'))
-    if (hasWork) issues.push('phase is unset but dated work exists - run: fde log phase <land|discover|plan|build|ship|close>')
-    else issues.push('phase is unset - set when you know where you are: fde log phase land')
+  const datedBlob = [
+    readEng(eng, 'decisions.md'), readEng(eng, 'delivery.md'),
+    readEng(eng, 'risks.md'), readEng(eng, 'stakeholders.md'),
+  ].join('\n')
+  const hasDatedWork = /\[\d{4}-\d{2}-\d{2}\]/.test(datedBlob)
+  // Day-1 empty templates are not hygiene failures - nagging there trains people to ignore doctor.
+  const fresh = !hasDatedWork && (s.phase === '?' || s.phase === 'unset') && !s.openRisks
+
+  if (s.memoryWarn) issues.push(s.memoryWarn)
+  if (fresh) return issues
+
+  if (s.phase === '?' || s.phase === 'unset') {
+    if (hasDatedWork) {
+      issues.push('phase is unset but dated work exists - run: fde log phase <land|discover|plan|build|ship|close>')
+    }
   }
   if (s.stale) issues.push(`trust signal is STALE (${s.signalAge}d) - reconfirm with fde log contact ... --signal`)
-  if (s.memoryWarn) issues.push(s.memoryWarn)
   if (!readOwner(eng)) issues.push('no .owner - run any write or: fde owner set you@firm.com')
   if (!fs.existsSync(path.join(eng, '.git'))) issues.push('memory not git-versioned - next write will init, or re-run resume --init')
   const success = readClean(eng, 'success.md')
@@ -1448,8 +1472,31 @@ function cmdDoctor() {
       `${dupes.length} duplicate open-risk cluster(s) (e.g. "${sample}${sample.length >= 60 ? '…' : ''}") - consolidate or retire echoes in risks.md`
     )
   }
-  console.log(`FDE DOCTOR - ${engagementSlugFromPath(eng)}`)
+  return issues
+}
+
+// Lean line for session-start TRIAGE - count + top issue + NL cue. Omitted when clean.
+function hygieneTriageLines(eng) {
+  const issues = collectDoctorIssues(eng)
+  if (!issues.length) return []
+  const top = issues[0].replace(/\s+/g, ' ').trim().slice(0, 72)
+  return [
+    `  hygiene: ${issues.length} issue(s) — ${top}${issues[0].length > 72 ? '…' : ''}`,
+    '    → say "@fde clean up the fieldbook" when ready (agent runs fde doctor; nothing auto-rewrites)',
+  ]
+}
+
+function printTriageBlock(eng) {
   console.log(resumeTriage(eng))
+  for (const line of hygieneTriageLines(eng)) console.log(line)
+}
+
+function cmdDoctor() {
+  const eng = resolveEngagement()
+  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  const issues = collectDoctorIssues(eng)
+  console.log(`FDE DOCTOR - ${engagementSlugFromPath(eng)}`)
+  printTriageBlock(eng)
   if (!issues.length) {
     console.log('\nOK - no structural issues (judgment still yours)')
     process.exit(0)

package/bin/lib/trust.js

@@ -70,7 +70,16 @@ function createTrustApi(deps) {
       const t = raw.trim()
       if (!t || t.startsWith('<!--') || /^#{1,6}\s/.test(t)) continue
       if (/risk\s*\|\s*status|mitigation/i.test(t) || /^\|?[\s|:-]+$/.test(t)) continue
-      if (/^[-*]/.test(t) || (/^\|/.test(t) && t.length > 12)) n++
+      // Bullet risk with substance (skip empty "- " stubs).
+      if (/^[-*]/.test(t)) {
+        if (t.replace(/^[-*]\s+/, '').trim()) n++
+        continue
+      }
+      // Table row: first cell must have risk text (day-1 "| | open | |" placeholders don't count).
+      if (/^\|/.test(t) && t.length > 12) {
+        const riskCell = t.split('|').map(c => c.trim())[1] || ''
+        if (riskCell) n++
+      }
     }
     return n
   }

package/hooks/session-start

@@ -138,8 +138,9 @@ CONTENT=""
 # Lean pointer only - never cat SKILL.md. Methods load on @fde / skill trigger.
 CONTENT="${CONTENT}fdeops: engagement fieldbook active. Human speaks plain language with @fde - you (the agent) run the local fde CLI for memory plumbing; never ask the human to type fde commands. Load skills/fde/SKILL.md when @fde triggers.\n\n"
 
-# Same TRIAGE block as `fde resume` / `fde triage` - Monday morning must not
-# depend on the model remembering to run a CLI command. Prefer the installed
+# Same TRIAGE block as `fde resume` / `fde triage` (includes proactive hygiene
+# when the fieldbook has doctor issues; silent when clean). Monday morning must
+# not depend on the model remembering to run a CLI command. Prefer the installed
 # fde binary; fall back to the plugin/repo copy of bin/fde.js.
 resolve_fde() {
   if command -v fde >/dev/null 2>&1; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.9.8",
+  "version": "3.9.10",
   "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",
@@ -9,6 +9,7 @@
   "scripts": {
     "check": "node bin/check.js && npm test",
     "test": "node --test test/*.test.js",
+    "test:skill-routing": "node evals/skill-routing/check.js && node evals/skill-routing/live-smoke.js",
     "prepublishOnly": "node bin/check.js && npm test"
   },
   "files": [

package/skills/fde/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fde
-description: Second brain for Forward Deployed Engineers. The human describes the situation in plain language with @fde - you route, run the local fde CLI for memory plumbing, and write the fieldbook. Never ask the human to type fde commands.
+description: Engagement fieldbook for Forward Deployed Engineers. Use when the human says @fde or asks about client memory, debrief, prep, receipts, trust, hygiene, or sponsor status — route and run the local fde CLI; never ask them to type fde commands. Do not use for ordinary code edits, unit tests, refactors, or git commits.
 ---
 
 # @fde
@@ -74,8 +74,10 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 | "Prep me for the meeting with …" / walk-in brief | `fde prep "<short label>"` - present the brief in plain language; do not invent facts missing from `.fde/` |
 | "When did we agree…?" / scope dispute | `fde receipts <term>` - answer with dates; no hit = gap, not proof |
 | "Draft the sponsor update" / how are we doing | `fde status` then follow `references/status.md` for the narrative |
-| "Log that they went quiet" / trust signal | `fde log contact "…" --signal amber\|green\|red` (after FDE confirms the read) |
+| "Log that they went quiet" / trust signal | `fde log contact "…" --signal amber\|green\|red`. If they already named the color ("log that as amber"), that is the confirm — write it. If they only described the situation, playback the color once, then write. |
 | Want the HTML fieldbook | `fde dashboard` |
+| "Clean up the fieldbook" / hygiene / memory feels messy | `fde doctor` - walk issues in plain language; propose fixes; never auto-rewrite without confirm. Contradictions need judgment (brief vs reality) - doctor is structural; you handle meaning. |
+| "Scrub this secret / redact that token" (buried line, not just last write) | `fde redact <term>` preview, then `fde redact <term> --apply` after confirm. Undo is last-write only; redact is for buried lines. Remind them to rotate the real credential. |
 
 **The debrief verb.** Highest-frequency loop. When the FDE shares notes or says "debrief": **you** run the smart path (write notes to a temp file if needed). Show the proposed routing in plain language. Only `--apply` (or pipe prefixed lines) after they confirm. Never ask them to run the CLI. Detail: `references/debrief.md`.
 
@@ -85,23 +87,24 @@ CLI missing → use the manual fallbacks inside each reference (still you write
 
 ## Proactive intelligence (run on every session start)
 
-After loading `context.md` via `fde resume`, run a quick integrity scan and open with a brief state playback - like a senior colleague who reviewed the file before the meeting started.
+Session-start already injects **TRIAGE** (deterministic, zero model tokens). When the fieldbook is dirty, TRIAGE includes a `hygiene:` line - that is the proactive doctor. Silent when clean.
+
+After you see TRIAGE + bounded `context.md`, open with a brief state playback - like a senior colleague who reviewed the file before the meeting started.
 
 **Always open with a 2-3 line state summary:**
 
 > "Last session you shipped the payment retry slice. Plan is 3/5 tasks done. Denise saw the demo Tuesday - signal is green. One thing worth noting: [finding, or 'nothing flagged - where do you want to pick up?']"
 
-**What to scan (in order, surface only what matters):**
+**What to surface (in order, at most ONE finding):**
 
-1. **Artifact staleness.** Any file the current work depends on that's 10+ days stale? Especially stakeholders.md (signals decay fast) and risks.md (unactioned risks compound).
-2. **Plan-success alignment.** Tasks in decisions.md that don't trace to any outcome in success.md - they may have absorbed in as scope creep.
-3. **Open risks overdue.** Critical or high risk open 7+ days with no mitigation.
-4. **Contradictions between files.** Reality.md vs. brief.md. Delivery.md vs. success.md.
+1. **If TRIAGE has `hygiene:`** - that is the finding. Offer: "Fieldbook has N hygiene issues - want me to walk them?" On yes: run `fde doctor`, explain in plain language, propose fixes; never auto-rewrite.
+2. Else optionally note: artifact staleness, open risks overdue, or brief↔reality tension - only if it changes today's move.
+3. If nothing flagged: one line, ask where to pick up.
 
 **Rules:**
-- Surface at most ONE finding alongside the state summary. Don't barrage.
-- If nothing's flagged, say so in one line and ask where they want to pick up.
-- Frame as observation: "I'm noticing stakeholders.md is 12 days old" - not accusation.
+- Don't re-run a second invented audit when hygiene already spoke.
+- Don't barrage. Don't accuse. Don't rewrite memory without confirm.
+- Full contradiction cleanup ("audit the sources before trusting the index") is an `@fde` conversation - doctor is the structural gate; you supply judgment.
 - If the concern is minor and won't change the next 3 moves - skip it.
 
 This is what makes fdeops a peer, not a notebook. The peer reviewed the file before you sat down.