fdeops 3.9.16 → 3.9.17

package/README.md

@@ -7,7 +7,7 @@
 [![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 +195,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
+  }
+  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 body.join('\n').trim()
+  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(
@@ -2090,7 +2141,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 +2209,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.17",
   "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,7 +82,7 @@ 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 |
@@ -79,7 +91,7 @@ When NOT to interrogate or challenge: unambiguous one-liners, mechanical ops, FD
 | "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`.
+**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/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.