fdeops 3.9.5 → 3.9.8

package/bin/lib/trust.js

@@ -0,0 +1,188 @@
+'use strict'
+
+function createTrustApi(deps) {
+  const {
+    fs, path, readClean, readEng, parseMdTable, sectionBody, SIGNAL_LEDGER, memoryDirtyManual,
+  } = deps
+
+  // 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
+  // one. Older than 21 days → stale: shown with a "?" marker + age so a forgotten
+  // signal never silently drives triage. The keyword grep survives only as the
+  // zero-effort floor when NO token exists anywhere - prose like "escalated to CTO,
+  // resolved amicably" must not flip a client amber forever.
+  function stakeholdersMemoryHealth(eng) {
+    // Hostile handoff: binary / unparseable stakeholders must not read as healthy green.
+    let buf
+    try { buf = fs.readFileSync(path.join(eng, 'stakeholders.md')) } catch (_) {
+      return { ok: true, warn: '' }
+    }
+    if (buf.includes(0)) {
+      return { ok: false, warn: 'memory unreadable - verify (binary data in stakeholders.md)' }
+    }
+    const md = buf.toString('utf8')
+    const ledger = readEng(eng, SIGNAL_LEDGER)
+    if (/\[signal:(red|amber|green)\]/i.test(md + '\n' + ledger)) {
+      return { ok: true, warn: '' }
+    }
+    const trustLine = md.match(/\*\*Trust:\*\*\s*([A-Za-z?]+)/i)
+    if (trustLine && !/^(red|amber|green)$/i.test(trustLine[1])) {
+      return { ok: false, warn: 'memory unreadable - verify (invalid trust value)' }
+    }
+    const table = parseMdTable(md)
+    const meaningful = md.split('\n').filter(l => {
+      const t = l.trim()
+      return t && !t.startsWith('#') && !t.startsWith('<!--') && !/^\|?\s*:?-{3,}/.test(t)
+    }).length
+    // Content present but no table and no structured signal → do not invent "green"
+    if (meaningful >= 3 && !table) {
+      return { ok: false, warn: 'memory unreadable - verify (stakeholders.md unparseable)' }
+    }
+    return { ok: true, warn: '' }
+  }
+
+  // Subject key for a signal-history line - first real name word (same spirit as
+  // extractStakeholders). A green about Randy must not clear an amber about Denise.
+  // Strip author tags [@email-local] so attribution never becomes the subject key.
+  function signalSubjectKey(text) {
+    const cleaned = String(text).replace(/\[@[^\]]+\]/g, '').replace(/\([^)]*\)/g, '')
+    const words = cleaned.split(/\s+/).filter(w => w && !/^(dr|mr|mrs|ms)\.?$/i.test(w))
+    const frag = (words[0] || '').replace(/[^a-z0-9]/gi, '').toLowerCase()
+    return frag.length >= 3 ? frag : ('anon:' + cleaned.slice(0, 48).toLowerCase())
+  }
+
+  function parsePhase(ctx) {
+    // Template ships "**Phase:** land | discover | ..." - that is UNSET, not land.
+    const m = ctx.match(/\*\*Phase:\*\*\s*(.+)/i) || ctx.match(/^phase[:\s*]+(.+)$/im)
+    if (!m) return '?'
+    const raw = m[1].replace(/\*/g, '').trim()
+    if (!raw || /\|/.test(raw) || /^unset$/i.test(raw) || /^[\[(]/.test(raw)) return '?'
+    const one = raw.toLowerCase().match(/^(land|discover|plan|build|ship|close)\b/)
+    return one ? one[1] : '?'
+  }
+
+  function countOpenRisks(eng) {
+    const md = readClean(eng, 'risks.md')
+    const body = md.split(/^#{1,6}\s+Retired\b/im)[0] || md
+    let n = 0
+    for (const raw of body.split('\n')) {
+      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++
+    }
+    return n
+  }
+
+  function nextActionLine(ctx) {
+    const body = sectionBody(ctx, 'Next action')
+    for (const raw of body.split('\n')) {
+      const t = raw.trim().replace(/^[-*]\s+/, '')
+      if (t) return t.slice(0, 120)
+    }
+    return ''
+  }
+
+  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 = parsePhase(ctx)
+    // Latest signal PER stakeholder, then worst-of those actives.
+    // Global "latest wins" let a green from person B hide a sponsor crisis on A.
+    const byPerson = new Map()
+    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] || ''
+      const text = l.replace(/^\s*-\s*/, '')
+        .replace(/\[signal:(red|amber|green)\]/i, '')
+        .replace(/\[\d{4}-\d{2}-\d{2}\]/, '')
+        .replace(/\[@[^\]]+\]/g, '')
+        .trim()
+      const key = signalSubjectKey(text)
+      const prev = byPerson.get(key)
+      if (!prev || date >= prev.date) byPerson.set(key, { date, sig: sm[1].toLowerCase(), text })
+    }
+    const RANK = { red: 0, amber: 1, green: 2 }
+    let worst = null
+    for (const s of byPerson.values()) {
+      if (!worst || RANK[s.sig] < RANK[worst.sig] || (RANK[s.sig] === RANK[worst.sig] && s.date >= worst.date)) {
+        worst = s
+      }
+    }
+    const mem = stakeholdersMemoryHealth(eng)
+    let trust, signalAge = null, stale = false, trustReason = ''
+    if (!mem.ok && !worst) {
+      trust = 'amber'
+      trustReason = mem.warn
+    } else if (worst) {
+      trust = worst.sig === 'red' ? 'RED' : worst.sig
+      trustReason = (worst.text || '').slice(0, 80)
+      if (worst.date) {
+        signalAge = Math.max(0, Math.floor((Date.now() - Date.parse(worst.date)) / 86400000))
+        stale = signalAge > 21
+      }
+    } else {
+      const sLines = stake.split('\n').filter(l => !(/green/i.test(l) && /red|amber/i.test(l)))
+      trust = sLines.some(l => /\bred\b/i.test(l)) ? 'RED'
+        : sLines.some(l => /amber|gone quiet|routing around|escalat/i.test(l)) ? 'amber' : 'green'
+    }
+    const topRisk = (risks.split('\n').find(l => {
+      const t = l.trim()
+      return /^[-|]/.test(t) && t.length > 20 && !/^\|?[-\s|]+$/.test(t) &&
+        !/risk\s*\|\s*status|mitigation/i.test(t) && !t.startsWith('<!--')
+    }) || '').replace(/\|/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80)
+    // Prefer trust trigger / memory warn over a random risk line; always keep mem.warn available
+    const reason = (trustReason || mem.warn) ? (trustReason || mem.warn) : topRisk
+    const openRisks = countOpenRisks(eng)
+    const nextAction = nextActionLine(ctx)
+    let updated = 'never', ageDays = Infinity
+    try {
+      ageDays = Math.floor((Date.now() - fs.statSync(path.join(eng, 'context.md')).mtimeMs) / 86400000)
+      updated = ageDays === 0 ? 'today' : `${ageDays}d ago`
+    } catch (_) {}
+    const dirty = memoryDirtyManual(eng)
+    return {
+      phase, trust, signalAge, stale, topRisk, reason, memoryWarn: mem.warn,
+      dirtyFiles: dirty, openRisks, nextAction, updated, ageDays,
+    }
+  }
+
+  function resumeTriage(eng) {
+    const s = computeSignals(eng)
+    const label = s.trust + (s.stale ? '?' : '')
+    const phase = s.phase === '?' ? 'unset' : s.phase
+    const lines = [
+      `TRIAGE  [${label.padEnd(6)}]  phase:${phase}  updated:${s.updated}  open risks:${s.openRisks}`,
+    ]
+    if (s.reason) {
+      const age = s.signalAge != null ? ` (${s.signalAge}d old${s.stale ? ', STALE - reconfirm' : ''})` : ''
+      lines.push(`  trust: ${s.reason}${age}`)
+    }
+    // Always surface corruption / unreadable memory - even when trust still reads green
+    if (s.memoryWarn) lines.push(`  memory: ${s.memoryWarn}`)
+    if (s.dirtyFiles && s.dirtyFiles.length) {
+      lines.push(`  ⚠ memory dirty (uncommitted manual edits): ${s.dirtyFiles.slice(0, 5).join(', ')}${s.dirtyFiles.length > 5 ? '…' : ''}`)
+      lines.push('    review before relying on the ledger - fde writes will not auto-commit these')
+    }
+    if (s.nextAction) lines.push(`  next: ${s.nextAction}`)
+    else lines.push('  next: (none set - add under ## Next action in context.md)')
+    return lines.join('\n')
+  }
+
+  return {
+    stakeholdersMemoryHealth,
+    signalSubjectKey,
+    parsePhase,
+    countOpenRisks,
+    nextActionLine,
+    computeSignals,
+    resumeTriage,
+  }
+}
+
+module.exports = { createTrustApi }

package/hooks/session-start

@@ -136,7 +136,7 @@ bounded_context() {
 CONTENT=""
 
 # Lean pointer only - never cat SKILL.md. Methods load on @fde / skill trigger.
-CONTENT="${CONTENT}fdeops: engagement fieldbook active. For field methods, invoke @fde (loads skills/fde/SKILL.md + one references/*.md). Plumbing is zero-token CLI: fde triage | resume | debrief | prep | receipts | status.\n\n"
+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

package/package.json

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

@@ -1,17 +1,26 @@
 ---
 name: fde
-description: Second brain for Forward Deployed Engineers. One @fde router over field methods plus a local CLI for scan, memory, and receipts. Tell it your situation — it routes, does the work, and writes the engagement fieldbook.
+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.
 ---
 
 # @fde
 
 ## Audience (read this first)
 
-- **FDE** = the **human** who types `@fde` in the chat.
+- **FDE** = the **human** who types `@fde` (or plain language) in the chat.
 - **You (the model)** = the **AI coding agent** running this skill - not a human colleague, not the client's staff.
 
 When this skill says "ask the FDE," it means the human. When it says "write to `.fde/`," you (the AI) write the files.
 
+## Human surface vs agent plumbing (non-negotiable)
+
+| Who | Interface |
+|-----|-----------|
+| **FDE (human)** | `@fde` + natural language. Examples: "debrief these notes", "prep me for tomorrow's sponsor meeting", "when did we agree to drop that?", "draft the sponsor update". |
+| **You (agent)** | Run the local `fde` CLI for deterministic memory work. Never tell the FDE to type `fde …` (except if setup is missing - then **you** run `fde resume --init <name>` after one clarifying question). |
+
+If you catch yourself saying "run `fde debrief --smart notes.txt`" to the human - **stop**. Run it yourself (or write a temp notes file and run it), then show the human the result in plain language for confirm/reject.
+
 ## Purpose
 
 The single entry point for an entire client engagement. Field methods cover the FDE lifecycle (land through close, plus daily verbs and overlays). The human FDE describes what is happening - new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship. You read the engagement memory, route to the right method, **do the work**, and leave the memory updated so the next session starts where this one ended.
@@ -36,6 +45,7 @@ These stop confident fiction. They are not optional soft tips.
 
 | Temptation | Gate |
 |------------|------|
+| Tell the FDE to run `fde debrief` / `fde prep` / `fde receipts` themselves | **Stop.** You run the CLI; they confirm results in plain language. |
 | 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. |
@@ -54,21 +64,22 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 
 **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:**
+**You run the `fde` CLI for deterministic work - never improvise shell, never hand the command to the FDE:**
 
-| Mechanics | Command |
-|-----------|---------|
-| Load/create engagement memory | `fde resume` (bounded) / `fde resume --full` / `fde resume --init <name>` |
-| Day-1 repo recon (facts + ASK ON DAY 1) | `fde scan` - then YOU interpret against the brief |
-| Structured memory appends | `fde log decision\|risk\|delivery\|contact "<text>"` - on `contact`, add `--signal green\|amber\|red` to write a `[signal:…]` token |
-| Meeting notes → memory | `fde debrief <file>` (or stdin) - `decision:`/`risk:`/`delivery:`/`contact:` prefixed lines route to their `.fde` file with dates; the rest lands as a dated block in `context.md` |
-| "What did we agree?" with dates | `fde receipts <term>` |
-| Portfolio across customers | `fde status` - trust from the latest dated `[signal:…]` token (stale after 21 days; keyword heuristic only as fallback); verify before acting |
-| Visual portfolio (one local page) | `fde dashboard` - renders `.fde/` → `fieldbook.html`, deterministic, 0 tokens |
+| When the FDE says (approx.) | You run |
+|-----------------------------|---------|
+| (session entry / where are we) | `fde resume` or use injected TRIAGE; `fde resume --init <name>` only if unbound |
+| Day-1 look at the repo | `fde scan` - then you interpret against the brief |
+| "Debrief these notes" / pastes meeting notes | Prefer `fde debrief --smart <notes>` → show propose → on confirm `fde debrief --apply`. Fallback: structure `decision:`/`risk:`/`delivery:`/`contact:` lines yourself, show FDE, then `fde debrief` |
+| "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) |
+| Want the HTML fieldbook | `fde dashboard` |
 
-**The debrief verb.** When the FDE shares meeting notes or a transcript, or says "debrief": structure the notes into lines prefixed `decision:` / `risk:` / `delivery:` / `contact:` (append `[signal:green|amber|red]` to a `contact:` line when the notes carry trust information), leave everything else unprefixed, **show the structured version to the FDE for confirmation**, then pipe it to `fde debrief`. Routing and dating are deterministic and cost zero tokens - your judgment is the structuring. Signal-reading guidance: `references/debrief.md`.
+**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`.
 
-CLI missing → use the manual fallback commands inside each reference.
+CLI missing → use the manual fallbacks inside each reference (still you write files; still never ask the FDE to run setup).
 
 **Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Session-start hooks inject **TRIAGE + bounded `context.md` + a one-line pointer** - never this full skill body (that loads only when `@fde` triggers). Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
 
@@ -241,6 +252,7 @@ Running the engagement and ending it well.
 | Weekly update due, "need to send the sponsor something" | status | `references/status.md` |
 | Demo coming up, show-and-tell, exec walkthrough | demo-prep | `references/demo-prep.md` |
 | Just out of a meeting, raw notes, "they said…", "debrief" | debrief | the debrief verb (above) + `references/debrief.md` |
+| Prep me for a meeting / walk-in brief / "what should I know before I talk to…" | - | run `fde prep "<label>"`, present in plain language |
 | Sponsor's boss needs a summary, board update, justify continued investment | exec-narrative | `references/exec-narrative.md` |
 | Status across all my customers | dashboard | `references/dashboard.md` |
 | Juggling 2+ customers, losing track, context-switching | multi-customer-ops | `references/multi-customer-ops.md` |

package/skills/fde/references/debrief.md

@@ -1,36 +1,51 @@
 # debrief - capture the meeting before it evaporates
 
-**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". The highest-frequency moment in FDE life (3–5×/day). Capture within the hour - memory decays fast.
+**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". Highest-frequency moment in FDE life. Capture within the hour.
 
-**Read first:** `context.md`, `stakeholders.md` (to update signals against what's known).
+**Read first:** `context.md`, `stakeholders.md` (signals against what's known).
+
+**Who runs the CLI:** you (the agent). Never tell the FDE to type `fde debrief …`.
 
 ## Method (you do this work)
 
-Take the raw dump exactly as given. Extract into five buckets - **only what was actually said**; rule 4 applies with full force here (no invented names, no embellished quotes):
+### Preferred path - smart debrief (messy notes)
+
+1. Save the FDE's notes to a temp `.md` file in the workspace (or pipe stdin).
+2. Run `fde debrief --smart <notes.md>` (or `npx fdeops debrief --smart …`).
+3. Show the **proposed** routing in plain language (what would become decisions, risks, contacts, etc.).
+4. On FDE confirm → run `fde debrief --apply`.
+5. On reject → stop; ask what to change; do not apply.
+
+No invented names or quotes. If the propose looks wrong, fix with judgment then re-propose or use the fallback path.
+
+### Fallback - you structure, then route
+
+If `--smart` is unavailable or the notes are already cleanly prefixed:
 
-1. **Decisions** - what was agreed, by whom, in their words where possible.
-2. **Action items** - owner + due date. Unowned actions get `owner: unknown - ask`.
-3. **Stakeholder signals** - tone shifts, hesitations, who went quiet, who pushed back, verbatim quotes that matter. Map each to green/amber/red movement *with the evidence*.
-4. **Risks** - new ones surfaced, old ones confirmed or retired.
-5. **Open questions** - what the FDE must chase before the next session.
+1. Extract into buckets - **only what was actually said**:
+   - **Decisions** - agreed, by whom, in their words where possible
+   - **Action items** - owner + due; unowned → `owner: unknown - ask`
+   - **Stakeholder signals** - tone shifts with evidence → green/amber/red
+   - **Risks** - new / confirmed / retired
+   - **Open questions** - what to chase next
+2. Format lines as `decision:` / `risk:` / `delivery:` / `contact:` (contacts may end with `[signal:green|amber|red]`).
+3. Show that structured version to the FDE for confirmation.
+4. Pipe to `fde debrief` (or write a file and run it).
 
-Ambiguity in the dump → ask **one** clarifying question, then write. Never stall the capture on completeness.
+One clarifying question max if the dump is ambiguous - then write. Never stall capture on completeness.
 
-## Artifact (this IS the memory - write immediately)
+## Artifact
 
-- Decisions → `decisions.md` via `fde log decision "<text> (meeting: <who>, <date>)"` or direct append, dated and attributed.
-- Signal changes → `stakeholders.md`: update the signal column with evidence + date. A quote moves a signal; a vibe does not.
-- Risks → `risks.md`, dated.
-- Action items + open questions → `context.md` under "Next actions".
-- Sacred/sensitive things mentioned (data, systems, politics) → `trust-profile.md` if new.
+- Smart apply / debrief CLI writes the dated routes into the right `.fde/` files.
+- If you must write directly: decisions → `decisions.md`; signals → `stakeholders.md` Signal history; risks → `risks.md`; next actions → `context.md`. Prefer the CLI.
 
 ## Checkpoint
 
-Read back the 2–3 most consequential captures in one breath - "Logged: descope agreed with Dana; ops lead went amber (quote attached); CISO ticket now blocking" - so the FDE can correct on the spot. Then stop. No summary theatre.
+Read back the 2-3 most consequential captures in one breath - so the FDE can correct on the spot. Then stop. No summary theatre.
 
 ## Principles
 
-- Capture within the hour or lose the nuance forever.
-- The verbatim quote outranks the paraphrase. The hesitation outranks the quote.
-- Signals move on evidence, never on inference.
-- A meeting that produced no decisions and no actions - say so; that's a finding about the meeting.
+- Capture within the hour or lose the nuance.
+- Verbatim quote outranks paraphrase; hesitation outranks quote.
+- Signals move on evidence, never on vibe alone.
+- A meeting with no decisions and no actions - say so; that is a finding.