fdeops 3.9.16 → 3.9.18

package/README.md

@@ -7,7 +7,9 @@
 [![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)
 
-One `@fde` skill over a local client notebook (the **fieldbook** under `.fde/`) - one folder per client. The **system of record for embeds** - Forward Deployed Engineers and anyone living on a client site from first meeting to handoff. Feels like a second brain; behaves like a defensible record (dated, sourced, yours). Works the same for consultants, agency developers, solutions architects, and fractional CTOs.
+**Memory + methodology + skills, in one kit.** Skill packs teach your AI agent how to build. None of them remember who the client is, what was decided, or what's safe to ship. FDEOps adds the missing layer: a private fieldbook per engagement (`.fde/`), a field methodology (land → close), and one `@fde` skill that routes it all. 
+
+Built for Forward Deployed Engineers, and anyone embedded in client work: consultants, agency developers, solutions architects, fractional CTOs. Feels like a second brain; behaves like a defensible record (dated, sourced, yours).
 
 ```
   land      discover      plan      build      ship      close
@@ -195,4 +197,8 @@ cd fdeops && git pull && node bin/install.js
 
 Built and maintained by **[Subash Natarajan](https://www.linkedin.com/in/subashn/)**. Share your feedback via [Issues](https://github.com/suboss87/fdeops/issues) - see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-[FDE Methodology](FDE-METHODOLOGY.md) - [ATTRIBUTION.md](ATTRIBUTION.md) - [SECURITY.md](SECURITY.md) - [PRIVACY.md](PRIVACY.md) - [Repo layout](docs/REPO_LAYOUT.md) - [Skills matrix](docs/skills.md) - MIT
+Thanks to builders whose craft helped sharpen the thinking behind this kit, among them [Andrej Karpathy](https://karpathy.ai/)'s engineering guidelines and the [agentic engineering workflow](https://github.com/pawel-cell/micky-podcast-agentic-engineering) notes from David Ondrej / Michael Shimeles. FDEOps itself is handcrafted for field work; any resemblance is inspiration, not a fork.
+
+**What we won't build:** SaaS sync or Slack/Notion connectors inside the CLI, CRM as core, hardware capture, or generic code-craft skill packs (TDD/review already exist elsewhere - FDEOps owns the engagement, not the keyboard). The `fde` CLI stays local-only.
+
+[FDE Methodology](FDE-METHODOLOGY.md) - [SECURITY.md](SECURITY.md) - [PRIVACY.md](PRIVACY.md) - [Repo layout](docs/REPO_LAYOUT.md) - [Skills matrix](docs/skills.md) - MIT

package/bin/check.js

@@ -235,6 +235,19 @@ if (!skillBody.includes('fde prep')) {
 if (!skillBody.includes('debrief --smart')) {
   fail('SKILL.md must prefer fde debrief --smart for messy notes')
 }
+const debriefRef = read('skills/fde/references/debrief.md')
+if (!/gate \+ writer|not a brain/i.test(debriefRef) || !/rewrite.*prefix/i.test(debriefRef)) {
+  fail('debrief.md must state --smart is a gate (agent rewrites propose with prefixes)')
+} else ok('debrief --smart honesty contract')
+if (!/existing.*## Next action|never append a second/i.test(skillBody)) {
+  fail('SKILL.md must warn against appending a second ## Next action')
+} else ok('session-end Next action instruction')
+if (!/session digest/i.test(skillBody) || !/Key decisions & why/i.test(skillBody)) {
+  fail('SKILL.md memory contract must define session digest (TL;DR / decisions & why → .fde/)')
+} else ok('session digest in memory contract')
+if (!/transcript/i.test(skillBody) || !/judgment/i.test(skillBody)) {
+  fail('SKILL.md must reject transcript dumps in favor of judgment in .fde/')
+} else ok('session digest anti-transcript gate')
 if (!/\btriage\b/.test(hook)) {
   fail('session-start must still inject TRIAGE')
 }

package/bin/fde.js

@@ -443,16 +443,56 @@ const {
 } = createMemoryApi({ fs, path, gitBinOk, writeOwnerIfMissing, atomicWriteFile })
 
 // Pull the body under a "## Heading" up to the next "##" (or EOF).
-function sectionBody(md, heading) {
-  const lines = md.split('\n')
-  const start = lines.findIndex(l => new RegExp('^#{1,6}\\s+' + heading + '\\b', 'i').test(l.trim()))
-  if (start === -1) return ''
-  const body = []
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^#{1,6}\s/.test(lines[i].trim())) break
-    body.push(lines[i])
+// opts.lastNonEmpty: when duplicate headings exist (common skill trap: template
+// "## Next action" left empty, agent appends a second), prefer the last filled
+// body so triage/resume do not silently report "(none set)".
+function sectionBody(md, heading, opts) {
+  const preferLast = opts && opts.lastNonEmpty
+  const lines = String(md || '').split('\n')
+  const re = new RegExp('^#{1,6}\\s+' + heading + '\\b', 'i')
+  let first = ''
+  let lastFilled = ''
+  let seen = false
+  for (let i = 0; i < lines.length; i++) {
+    if (!re.test(lines[i].trim())) continue
+    const body = []
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^#{1,6}\s/.test(lines[j].trim())) break
+      body.push(lines[j])
+    }
+    const text = body.join('\n').trim()
+    if (!seen) { first = text; seen = true }
+    if (text) lastFilled = text
   }
-  return body.join('\n').trim()
+  if (!seen) return ''
+  return preferLast ? (lastFilled || first) : first
+}
+
+function countSections(md, heading) {
+  const re = new RegExp('^#{1,6}\\s+' + heading + '\\b', 'i')
+  let n = 0
+  for (const raw of String(md || '').split('\n')) {
+    if (re.test(raw.trim())) n++
+  }
+  return n
+}
+
+// Remove every "## Heading" section (heading line + body). Used to collapse
+// duplicate Next action blocks before writing a single canonical one.
+function stripAllSections(md, heading) {
+  const lines = String(md || '').split('\n')
+  const re = new RegExp('^#{1,6}\\s+' + heading + '\\b', 'i')
+  const out = []
+  for (let i = 0; i < lines.length; i++) {
+    if (re.test(lines[i].trim())) {
+      i++
+      while (i < lines.length && !/^#{1,6}\s/.test(lines[i].trim())) i++
+      i--
+      continue
+    }
+    out.push(lines[i])
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '\n')
 }
 
 // Append `entry` as the last line of a "## Heading" section, creating the
@@ -1106,11 +1146,12 @@ function setContextPhase(eng, phase) {
 
 
 // Meeting notes → structured memory. Deterministic routing, zero AI: lines that
-// start with decision:/risk:/delivery:/contact: (case-insensitive) go to their
-// LOG_FILES target as dated bullets; everything else lands in context.md as one
-// dated debrief block. contact: lines may carry an inline [signal:x] token
-// anywhere in the text - preserved verbatim so computeSignals can trust it.
-// --smart: heuristic propose from messy prose (confirm with --apply). No network.
+// start with decision:/risk:/delivery:/contact:/next: (case-insensitive) go to
+// their LOG_FILES target as dated bullets; everything else lands in context.md
+// as one dated debrief block. contact: lines may carry an inline [signal:x]
+// token anywhere in the text - preserved verbatim so computeSignals can trust it.
+// --smart: thin heuristic propose (existing prefixes + light keywords). Not a
+// brain — the agent rewrites .debrief-propose with prefixes; --apply commits.
 // --dry-run prints the routing without writing anything.
 function inferContactSignal(text) {
   const t = String(text)
@@ -1178,8 +1219,13 @@ function setNextAction(eng, text) {
   const p = path.join(eng, 'context.md')
   let md = readEng(eng, 'context.md')
   if (!md) md = '# Engagement context\n\n'
-  if (/^##\s+Next action\b/im.test(md)) {
-    md = md.replace(/(^##\s+Next action\b[^\n]*\n)([\s\S]*?)(?=^##\s|\s*$)/im, `$1\n${bullet}\n\n`)
+  // Collapse duplicate ## Next action headings (skill-append trap) into one.
+  md = stripAllSections(md, 'Next action')
+  if (/^##\s+Current state\b/im.test(md)) {
+    md = md.replace(
+      /(^##\s+Current state\b[^\n]*\n)([\s\S]*?)(?=^##\s|\s*$)/im,
+      (_, h, body) => `${h}${String(body).replace(/\n*$/, '\n')}\n## Next action\n\n${bullet}\n\n`
+    )
   } else {
     md = md.replace(/\n*$/, `\n\n## Next action\n\n${bullet}\n`)
   }
@@ -1593,8 +1639,13 @@ function collectDoctorIssues(eng) {
   }
   const success = readClean(eng, 'success.md')
   if (!firstLine(success, 80)) issues.push('success.md has no stated done-definition - fill before plan/build')
-  if (!sectionBody(readClean(eng, 'context.md'), 'Next action')) {
+  const ctxMd = readClean(eng, 'context.md')
+  if (!sectionBody(ctxMd, 'Next action', { lastNonEmpty: true })) {
     issues.push('no ## Next action in context.md - Monday morning has nothing to drive')
+  } else if (countSections(ctxMd, 'Next action') > 1) {
+    issues.push(
+      'duplicate ## Next action headings in context.md - fill the first (template) section and remove extras; triage reads the last non-empty'
+    )
   }
   if ((s.phase === 'close' || s.phase === 'ship') && s.openRisks > 0) {
     issues.push(
@@ -1620,9 +1671,92 @@ function collectDoctorIssues(eng) {
       `${dupes.length} duplicate open-risk cluster(s) (e.g. "${sample}${sample.length >= 60 ? '…' : ''}") - consolidate or retire echoes in risks.md`
     )
   }
+  // Failure-path (exception-led operating map): required once past discover.
+  // Land seeds; discover fills; plan+ without a real break→owner row is wallpaper.
+  if (/^(plan|build|ship|close)$/.test(s.phase) && !hasOperatingMapContent(eng)) {
+    issues.push(
+      `phase is ${s.phase} with empty operating map - fill terrain.md ## Operating map (exception-led): break → who notices → workaround → evidence`
+    )
+  }
+  const aliases = findAmbiguousStakeholders(eng)
+  if (aliases.length) {
+    const sample = aliases[0].forms.slice(0, 3).join(' / ')
+    issues.push(
+      `${aliases.length} stakeholder identity cluster(s) (e.g. "${sample}") - same person under different names? consolidate in stakeholders.md`
+    )
+  }
   return issues
 }
 
+// True when ## Operating map has at least one real exception row (not the empty template).
+function hasOperatingMapContent(eng) {
+  const terrain = stripTemplateNoise(readClean(eng, 'terrain.md'))
+  const body = sectionBody(terrain, 'Operating map')
+  if (!body.trim()) return false
+  const table = parseMdTable(body)
+  if (table) {
+    const exIdx = colIndex(table.headers, /exception|break/i)
+    const idx = exIdx !== -1 ? exIdx : 0
+    for (const row of table.rows) {
+      const cell = (row[idx] || '').trim()
+      if (cell && !/^unknown/i.test(cell)) return true
+    }
+  }
+  for (const raw of body.split('\n')) {
+    const t = raw.trim().replace(/^[-*]\s+/, '')
+    if (!t || t.startsWith('#') || t.startsWith('|') || /^\*\*/.test(t)) continue
+    if (t.length >= 8 && !/^unknown/i.test(t)) return true
+  }
+  return false
+}
+
+// Near-duplicate stakeholder forms sharing a first-name key (Denise vs Denise Chen).
+function findAmbiguousStakeholders(eng) {
+  const forms = []
+  const md = readClean(eng, 'stakeholders.md')
+  const table = parseMdTable(md)
+  if (table) {
+    const nameIdx = colIndex(table.headers, /name|who/i)
+    if (nameIdx !== -1) {
+      for (const row of table.rows) {
+        const name = (row[nameIdx] || '').trim()
+        if (!name || name.length < 2) continue
+        forms.push(name)
+      }
+    }
+  }
+  for (const h of parseSignalHistoryEntries(eng)) {
+    const name = displayNameFromSignalText(h.text)
+    if (name && name.length >= 2 && !/^anon:/i.test(name)) forms.push(name)
+  }
+  const byKey = new Map()
+  for (const name of forms) {
+    const key = signalSubjectKey(name)
+    if (!key || key.startsWith('anon:')) continue
+    const norm = name.replace(/\s+/g, ' ').trim().toLowerCase()
+    if (!byKey.has(key)) byKey.set(key, new Set())
+    byKey.get(key).add(norm)
+  }
+  const clusters = []
+  for (const [key, set] of byKey) {
+    if (set.size < 2) continue
+    // Prefer clusters where forms aren't just identical casing - already lowercased.
+    // Require at least one multi-token form vs a shorter form (Denise / Denise Chen).
+    const list = [...set]
+    const hasLong = list.some(f => f.split(/\s+/).length >= 2)
+    const hasShort = list.some(f => f.split(/\s+/).length === 1)
+    if (hasLong && hasShort) {
+      clusters.push({ key, forms: list })
+      continue
+    }
+    // Or two multi-token forms that share first token but differ later (Denise Chen / Denise C.)
+    if (list.length >= 2 && list.every(f => f.split(/\s+/).length >= 2)) {
+      clusters.push({ key, forms: list })
+    }
+  }
+  return clusters
+}
+
 // Strip template comments / italic *(hints)* so doctor does not treat stubs as filled.
 function stripTemplateNoise(md) {
   return String(md || '')
@@ -2090,7 +2224,7 @@ function cmdDashboard(args) {
   // one-liners, sector/overlay, days elapsed, and the four structured widgets.
   engagements.forEach(e => {
     const ctx = readClean(e.dir, 'context.md')
-    e.next = (sectionBody(ctx, 'Next action').split('\n').find(l => l.trim()) || '').trim()
+    e.next = (sectionBody(ctx, 'Next action', { lastNonEmpty: true }).split('\n').find(l => l.trim()) || '').trim()
     e.hasNext = !!e.next
     e.lastSession = firstLine(sectionBody(ctx, 'Current state'), 240)
     // 220, not 140 - now that brief/reality each get their own full-width
@@ -2158,7 +2292,7 @@ function printUsage() {
   fde log phase <phase>    set engagement phase (land|discover|plan|build|ship|close)
   fde log --undo           remove the last CLI log/debrief entry from memory
   fde debrief [file]       meeting notes → memory (prefixed lines; --dry-run; --force)
-  fde debrief --smart      propose routing from messy notes → review → fde debrief --apply
+  fde debrief --smart      heuristic propose (prefix + light keywords); agent routes, CLI gates → --apply
   fde prep [label]         grounded walk-in brief from existing .fde/ only
   fde doctor               lint engagement memory (stale signals, gaps)
   fde redact <term>        preview/remove lines containing a buried term (pass --apply to commit)

package/bin/lib/trust.js

@@ -85,7 +85,9 @@ function createTrustApi(deps) {
   }
 
   function nextActionLine(ctx) {
-    const body = sectionBody(ctx, 'Next action')
+    // lastNonEmpty: template ships an empty ## Next action; agents often append a
+    // second heading with the real bullet — first-match would report "(none set)".
+    const body = sectionBody(ctx, 'Next action', { lastNonEmpty: true })
     for (const raw of body.split('\n')) {
       const t = raw.trim().replace(/^[-*]\s+/, '')
       if (t) return t.slice(0, 120)

package/package.json

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

@@ -35,7 +35,18 @@ This is what makes fdeops a second brain instead of a chat window.
 2. **Deliverable = memory.** The output of every phase IS a `.fde/` file. You never ask the FDE to "update their notes" - producing the work and writing the memory are one action. The phase reference tells you which file.
 3. **Evidence rule.** Every claim in an artifact carries its source: `(validated with: ops lead, Day 5)`, `(churn: 47 commits/90d)`, `(stated, unverified)`. The FDE defends these files in front of skeptical clients - traceable beats plausible.
 4. **No invented facts - ever.** People, names, quotes, meetings, and numbers exist only if the FDE said them or the repo shows them. Never invent a stakeholder, a conversation, or a source to make the narrative richer - one fabricated name poisons every real citation around it. A missing fact is written as `unknown - ask: <the question>`, nothing else.
-5. **On exit:** before the session ends, append three lines to `context.md`: where we are, what changed today, the next step. The `session-stop` hook backstops this deterministically (hooks resolve the engagement through the workspace registry - no env var needed), but you write the meaningful version.
+5. **On exit (session digest):** before the session ends — and again before opening a PR — capture the *thinking*, not the chat. Propose this digest in plain language; on FDE confirm, write into existing `.fde/` files (never a transcript dump, never a product-repo history folder):
+
+   | Digest beat | Lands in |
+   |-------------|----------|
+   | **TL;DR** (1–2 sentences: what moved) | `context.md` current state / short dated note |
+   | **Key decisions & why** (only real ones) | `decisions.md` dated lines — skip if none |
+   | **Pivot / aha** (course correction that mattered) | one line in `context.md`, or `decisions.md` if it changed the plan |
+   | **Scope + verification** (files/slice + how you checked) | `delivery.md` when code or a PR is in play; else skip |
+   | **Gotchas for the next reader** | `context.md` (teammate / Monday-you) |
+   | **Next action** | existing `## Next action` — **replace** the bullet; never append a second heading |
+
+   The `session-stop` hook backstops a thin snapshot; **you** write the meaningful digest. Raw agent transcripts stay on the machine — judgment is what ships in the fieldbook.
 6. **One customer, one folder.** Never merge two engagements into one `.fde/`. Confirm which engagement applies when multiple exist.
 7. **Never delete a code-read section when rewriting an artifact.** `stakeholders.md`'s `## Signal history` holds dated `[signal:...]` tokens that `fde status`/`fde receipts`/the dashboard read verbatim; `risks.md`'s `## Retired` is read the same way. Rewriting either file as an artifact (land, audit, stakeholder-radar) is fine - dropping one of these sections is not. Carry existing entries forward untouched.
 
@@ -51,6 +62,7 @@ These stop confident fiction. They are not optional soft tips.
 | 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 **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. |
+| Sync chat transcripts / agent brain folders into the product git repo for "team share" | **Stop.** Run **session digest** into `.fde/` (judgment only). Transcripts stay local. |
 
 When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FDE explicitly asked for speed, answer already in `.fde/`.
 
@@ -70,16 +82,16 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 |-----------------------------|---------|
 | (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` |
+| "Debrief these notes" / pastes meeting notes | Prefer `fde debrief --smart <notes>` → **you** (the agent) rewrite `.debrief-propose` with `decision:`/`risk:`/`delivery:`/`contact:`/`next:` prefixes where needed → show FDE → on confirm `fde debrief --apply`. `--smart` is a prefix/keyword gate, not a brain. Fallback: structure prefixed 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`. 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. |
+| "Clean up the fieldbook" / hygiene / memory feels messy | `fde doctor` - walk issues in plain language; propose fixes; never auto-rewrite without confirm. Includes structural gaps: empty operating map (plan+), stakeholder name forks (Denise vs Denise Chen), duplicates, ship/close risks. 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`.
+**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). `--smart` writes a propose file via deterministic heuristics (existing prefixes + light keywords); authentic rambling notes often land mostly in context until **you** rewrite lines with type prefixes. 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 fallbacks inside each reference (still you write files; still never ask the FDE to run setup).
 
@@ -244,6 +256,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 |
+| Wrap the session / share the thinking / catch teammates up / before I open the PR | (memory contract — session digest) | SKILL.md **On exit** — write TL;DR + decisions/why into `.fde/`; no transcript sync |
 | "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) **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.
+10. **Review gate (before merge):** three beats, in order - (a) **session digest**: TL;DR + decisions/why + scope/verification into `.fde/` so the PR carries thinking, not just code (memory contract On exit; see `review.md`); (b) **intent vs diff**: every path KEEP / JUSTIFY / SPLIT / DROP against the stated slice in `decisions.md` (see `review.md` Stage 1); (c) **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/debrief.md

@@ -6,21 +6,34 @@
 
 **Who runs the CLI:** you (the agent). Never tell the FDE to type `fde debrief …`.
 
+## Honest contract (read once)
+
+- The `fde` CLI is **local, deterministic, no AI**. `--smart` is a **gate + writer**, not a brain.
+- It keeps lines that already have `decision:` / `risk:` / `delivery:` / `contact:` / `next:` prefixes, plus a thin keyword pass (e.g. "we agreed", person+verb lines, "open question").
+- Real messy notes without prefixes often route **0 useful lines** — everything else lands as a context dump. That is expected. **You are the router:** rewrite `.debrief-propose` with type prefixes, then `--apply`.
+- `.debrief-propose` is raw lines only (no routing annotations). "Edit if mis-routed" means **rewrite the line with the right prefix**, not leave a comment in the file.
+
 ## Method (you do this work)
 
 ### 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.
+3. Open `.debrief-propose`. If lines lack type prefixes, **rewrite them** before showing the FDE, e.g.:
+   - `decision: agreed chargebacks stay phase 2 — Priya`
+   - `risk: legal may reopen scope if we slip the SOW date`
+   - `contact: Priya pushed hard on Friday deck [signal:amber]`
+   - `next: send one-pager before Thursday 9am`
+   - unprefixed lines stay context color only
+4. Show the **proposed** routing in plain language (what would become decisions, risks, contacts, next).
+5. On FDE confirm → run `fde debrief --apply`.
+6. On reject → stop; ask what to change; do not apply.
+
+No invented names or quotes. If the propose looks wrong, fix prefixes with judgment then re-apply or use the fallback path.
 
 ### Fallback - you structure, then route
 
-If `--smart` is unavailable or the notes are already cleanly prefixed:
+If `--smart` is unavailable or you already have clean prefixes:
 
 1. Extract into buckets - **only what was actually said**:
    - **Decisions** - agreed, by whom, in their words where possible
@@ -28,7 +41,7 @@ If `--smart` is unavailable or the notes are already cleanly prefixed:
    - **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]`).
+2. Format lines as `decision:` / `risk:` / `delivery:` / `contact:` / `next:` (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).
 
@@ -37,7 +50,8 @@ One clarifying question max if the dump is ambiguous - then write. Never stall c
 ## Artifact
 
 - 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.
+- `next:` updates the existing `## Next action` in `context.md` (collapses duplicates). Do not append a second `## Next action` heading by hand.
+- If you must write directly: decisions → `decisions.md`; signals → `stakeholders.md` Signal history; risks → `risks.md`; next actions → fill under the template `## Next action` in `context.md`. Prefer the CLI.
 
 ## Checkpoint
 

package/skills/fde/references/discover.md

@@ -92,7 +92,7 @@ The real spec is what people **do** when the system fails - not what the slide d
 - **The hesitation.** When someone says "well, there's also this other thing we do…" - stop them, ask them to finish. The main story is what they're comfortable explaining; the hesitation is the real problem.
 - **"Which part of the codebase do you least want to touch?"** The answer is unanimous and it's the load-bearing wall. Check it against your churn scan - when the human answer and the churn data agree, that's your first map landmark.
 - **Shadow AI.** Someone pasting data into ChatGPT to cope = a real unmet need + an uncontrolled data risk. Note both.
-- **Exception-led operating map.** For each real break (not the slide-deck process): what fails, who notices first, what they do today, and which artifact is trusted in that moment. Prefer exceptions over happy-path swimlanes — the workaround is the operating system. Write rows under `terrain.md` → `## Operating map (exception-led)`. If the section is missing on an older engagement, add it; never regenerate the rest of terrain. When AI is in play, also fill `## Intelligence placement` (deterministic vs LLM judgement vs human approve).
+- **Exception-led operating map.** For each real break (not the slide-deck process): what fails, who notices first, what they do today, and which artifact is trusted in that moment. Prefer exceptions over happy-path swimlanes — the workaround is the operating system. Write rows under `terrain.md` → `## Operating map (exception-led)`. If the section is missing on an older engagement, add it; never regenerate the rest of terrain. When AI is in play, also fill `## Intelligence placement` (deterministic vs LLM judgement vs human approve). **`fde doctor` requires at least one filled exception row before plan/build/ship/close** — empty map after discover is a hygiene fail, not optional polish.
 
 ## Method - part 3: workshop facilitation
 

package/skills/fde/references/review.md

@@ -57,9 +57,15 @@ Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock
 5. Re-run tests/typechecks - state what ran.
 6. Re-review. Repeat until Pass/Pass or a human must decide scope/product.
 
+## Before the PR - thinking for the next reader
+
+Code alone loses the "why." Before you call the change reviewable, run the **session digest** from the memory contract (SKILL.md On exit): TL;DR, key decisions & rationale, scope + how you verified, gotchas. Confirm with the FDE, then write into `.fde/` — `decisions.md` / `delivery.md` / `context.md`. Reviewers (or Monday-you) should answer "why this approach?" from the fieldbook, not from a chat transcript. Do **not** dump agent logs into the product repo.
+
 ## Artifact
 
-**`decisions.md`** - each cycle logged: what was reviewed, flagged, fixed, verified. Stage 1 failures recorded with the specific mismatch.
+**`decisions.md`** - each cycle logged: what was reviewed, flagged, fixed, verified. Stage 1 failures recorded with the specific mismatch. Digest decisions (with *why*) land here too when the slice ships.
+
+**`delivery.md`** - scope + verification from the digest when a PR is opening; intent-vs-diff receipt stays the ship gate.
 
 ## Principles
 
@@ -68,3 +74,4 @@ Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock
 - 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.
+- Judgment in `.fde/` beats transcript in git.

package/skills/fde/references/stakeholder-radar.md

@@ -28,6 +28,8 @@ The org chart tells you who reports to whom. The stakeholder radar tells you who
 
 **3. The 48-hour rule.** A stakeholder who goes amber has roughly 48 hours before they go red. A stakeholder who goes red is already escalating above you. Respond same-day to amber signals - not with more delivery, with a conversation.
 
+**3b. One name per person.** If the table says "Denise Chen" and Signal history says "Denise" or "D. Chen", trust keys fork and prep lies. Consolidate to one spelling. `fde doctor` flags these identity clusters — treat that as a fix, not a nit.
+
 **4. Detect the invisible escalation.** Three markers:
 - Questions shift from "what are you building" to "when will it be done" - someone above is asking.
 - A meeting gets shortened or cancelled - they're meeting without you.

package/templates/.fde/stakeholders.md

@@ -1,6 +1,7 @@
 # Stakeholders
 
-<!-- Champions, blockers, veto power. Trust signals: quiet = escalate. -->
+<!-- Champions, blockers, veto power. Trust signals: quiet = escalate.
+     One row per real person - if Denise / Denise Chen / D. Chen appear, consolidate. -->
 
 | Name | Role | Stance | Notes |
 |------|------|--------|-------|
@@ -14,5 +15,6 @@
 <!-- `fde log contact --signal <color>` and `fde debrief` write dated tokens here.
      fde status/receipts read the LATEST dated [signal:...] token in this section
      to drive the trust column - do not delete this heading, and if you rewrite
-     this file as an artifact, keep this section's entries intact. -->
+     this file as an artifact, keep this section's entries intact.
+     Prefer the same Name spelling as the table so trust keys don't fork. -->
 

package/templates/.fde/terrain.md

@@ -8,7 +8,8 @@
 
 ## Operating map (exception-led)
 
-<!-- How work actually runs when the happy path fails. Fill in discover; leave blank until heard/seen. -->
+<!-- How work actually runs when the happy path fails. Fill in discover; leave blank until heard/seen.
+     fde doctor requires ≥1 real exception row before plan/build/ship/close. -->
 
 | Exception / break | Who notices first | What they do today (workaround) | System of record then | Blast if wrong | Evidence |
 |-------------------|-------------------|---------------------------------|-----------------------|----------------|----------|