fdeops 3.9.12 → 3.9.14

package/bin/check.js

@@ -63,6 +63,7 @@ const requiredReferences = [
   'debug.md', 'rescue.md', 'ship.md', 'sketch.md', 'close.md', 'dashboard.md',
   'debrief.md', 'status.md', 'demo-prep.md',
   'healthcare.md', 'fintech.md', 'gov.md',
+  'ai.md', 'eval-pack.md',
 ]
 for (const f of requiredReferences) {
   const p = path.join(root, 'skills', 'fde', 'references', f)

package/bin/fde.js

@@ -401,6 +401,7 @@ const {
   memoryDirtyManual,
   commitMemory,
   memoryHead,
+  memoryGitHealthy,
 } = createMemoryApi({ fs, path, gitBinOk, writeOwnerIfMissing, atomicWriteFile })
 
 // Pull the body under a "## Heading" up to the next "##" (or EOF).
@@ -843,8 +844,11 @@ function cmdResume(args) {
     const fdeDir = path.join(engRoot, '.fde')
     const existed = fs.existsSync(fdeDir)
 
+    // Optional stubs (AI eval pack, …) stay in templates/ for copy-on-use — not day-1 scaffold.
+    const SKIP_INIT_TEMPLATES = new Set(['evals.md'])
     const fillTemplates = (destFde) => {
       for (const f of fs.readdirSync(tpl)) {
+        if (SKIP_INIT_TEMPLATES.has(f)) continue
         const src = path.join(tpl, f); const dst = path.join(destFde, f)
         if (fs.statSync(src).isDirectory()) fs.mkdirSync(dst, { recursive: true })
         else if (!fs.existsSync(dst)) fs.copyFileSync(src, dst)
@@ -1092,6 +1096,10 @@ function smartProposeText(input) {
     let bare = line
       .replace(/^[-*+]\s+/, '')
       .replace(/^\*\*(decision|risk|delivery|contact|next):?\*\*:?\s*/i, '$1: ')
+    if (/^decided:\s+/i.test(bare)) {
+      out.push(`decision: ${bare.replace(/^decided:\s+/i, '')}`)
+      continue
+    }
     if (/^(decision|risk|delivery|contact|next):\s*/i.test(bare)) {
       let routed = bare.replace(/^(decision|risk|delivery|contact|next):\s*/i, (m, t) => `${t.toLowerCase()}: `)
       if (/^contact:/i.test(routed) && !/\[signal:(red|amber|green)\]/i.test(routed)) {
@@ -1107,7 +1115,7 @@ function smartProposeText(input) {
       out.push(`next: ${next}`)
       continue
     }
-    if (/\b(we (decided|agreed)|decision:|descope|agreed to|agreement was|freeze scope)\b/i.test(bare)) {
+    if (/\b(we (decided|agreed)|decided:|decision:|descope|agreed to|agreement was|freeze scope|freeze prompts)\b/i.test(bare)) {
       out.push(`decision: ${bare}`)
     } else if (/\b(open question|who signs|unclear who|unresolved)\b/i.test(bare)) {
       out.push(`risk: ${bare}`)
@@ -1167,6 +1175,12 @@ function readDebriefInput(args) {
   return input
 }
 
+function previewLine(text, max = 240) {
+  const t = String(text || '').replace(/\s+/g, ' ').trim()
+  if (t.length <= max) return t
+  return `${t.slice(0, max)}… (${t.length} chars)`
+}
+
 function routeDebriefInput(eng, input, { dry, force }) {
   const d = new Date()
   const date = d.toISOString().slice(0, 10)
@@ -1188,7 +1202,7 @@ function routeDebriefInput(eng, input, { dry, force }) {
         continue
       }
       if (type === 'next') {
-        if (dry) console.log(`→ context.md ## Next action  - ${body}`)
+        if (dry) console.log(`→ context.md ## Next action  - ${previewLine(body)}`)
         else nextAction = body
         counts.next++
         continue
@@ -1196,7 +1210,7 @@ function routeDebriefInput(eng, input, { dry, force }) {
       const sigInline = (body.match(/\[signal:(red|amber|green)\]/i) || [])[1]
       if (sigInline) body = body.replace(/\[signal:(red|amber|green)\]/i, '').trim()
       const entry = datedEntry(eng, date, body, type === 'contact' && sigInline ? sigInline.toLowerCase() : '')
-      if (dry) console.log(`→ ${LOG_FILES[type]}  ${entry}`)
+      if (dry) console.log(`→ ${LOG_FILES[type]}  ${previewLine(entry)}`)
       else appendLogEntry(eng, type, entry, { skipCommit: true })
       counts[type]++
     } else {
@@ -1210,7 +1224,7 @@ function routeDebriefInput(eng, input, { dry, force }) {
   if (nextAction && !dry) setNextAction(eng, nextAction)
   if (ctxLines.length) {
     const stamp = `${date} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
-    if (dry) ctxLines.forEach(l => console.log(`→ context.md  - ${l}`))
+    if (dry) ctxLines.forEach(l => console.log(`→ context.md  - ${previewLine(l)}`))
     else lockedAppendFile(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${ctxLines.map(l => `- ${l}`).join('\n')}\n`)
   }
   return { counts, ctxLines, date, nextAction }
@@ -1305,9 +1319,22 @@ function cmdReceipts(args) {
   }
   const agreed = collect(AGREEMENTS)
   const claimed = collect(CLAIMS)
+  const dirty = memoryDirtyManual(eng)
+  const dirtySet = new Set(dirty)
+  const dirtyAgreedHits = [...new Set(
+    agreed.map(h => (h.match(/^\s*([^:]+):/) || [])[1]).filter(f => f && dirtySet.has(f))
+  )]
   if (agreed.length) {
     console.log('ON RECORD (dated - defensible):')
-    agreed.forEach(h => console.log(h))
+    agreed.forEach(h => {
+      const file = (h.match(/^\s*([^:]+):/) || [])[1]
+      console.log(h + (file && dirtySet.has(file) ? '  ⚠ dirty file' : ''))
+    })
+    if (dirtyAgreedHits.length) {
+      console.log(
+        `⚠ memory dirty (uncommitted manual edits: ${dirtyAgreedHits.join(', ')}) - dated lines above may not match the tamper-evident ledger until reviewed`
+      )
+    }
   }
   if (claimed.length) {
     if (agreed.length) console.log('')
@@ -1490,7 +1517,18 @@ function collectDoctorIssues(eng) {
   }
   if (s.stale) issues.push(`trust signal is STALE (${s.signalAge}d) - reconfirm with fde log contact ... --signal`)
   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 gitHealth = memoryGitHealthy(eng)
+  if (!gitHealth.ok) {
+    if (gitHealth.reason === 'broken') {
+      issues.push(
+        'memory git is BROKEN (UNVERSIONED) - receipts are not tamper-evident; repair: mv .fde/.git .fde/.git.broken && re-run any fde write (or resume --init) to re-init the ledger'
+      )
+    } else if (gitHealth.reason === 'no-git-bin') {
+      issues.push('git binary missing - engagement memory cannot be versioned (receipts stay dated, not tamper-evident)')
+    } else {
+      issues.push('memory not git-versioned - next write will init, or re-run resume --init')
+    }
+  }
   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')) {
@@ -1501,6 +1539,18 @@ function collectDoctorIssues(eng) {
       `phase is ${s.phase} with ${s.openRisks} open risk(s) - retire, hand off, or move still-live ones before calling the embed done`
     )
   }
+  if (s.phase === 'close' || s.phase === 'ship') {
+    if (!hasValueBucket(eng)) {
+      issues.push(
+        `phase is ${s.phase} with no value bucket (cost-save | risk-mitigation | revenue-uplift) in success.md or delivery value ledger`
+      )
+    }
+    if (engagementTouchesAI(eng) && !hasEvalReceipt(eng)) {
+      issues.push(
+        `phase is ${s.phase} with AI in scope but no eval receipt (evals.md Verdict or delivery Eval / Ship receipts) — required before green ship/close`
+      )
+    }
+  }
   const dupes = findDuplicateOpenRisks(eng)
   if (dupes.length) {
     const sample = (dupes[0][0] || '').replace(/\s+/g, ' ').trim().slice(0, 60)
@@ -1511,6 +1561,71 @@ function collectDoctorIssues(eng) {
   return issues
 }
 
+// Strip template comments / italic *(hints)* so doctor does not treat stubs as filled.
+function stripTemplateNoise(md) {
+  return String(md || '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/\*\([^)]*\)\*/g, '')
+}
+
+const VALUE_BUCKET_RE = /(cost[- ]?save|risk[- ]?mitigat|revenue[- ]?uplift)/i
+
+function hasValueBucket(eng) {
+  const success = stripTemplateNoise(readClean(eng, 'success.md'))
+  const bucketLine = success.match(/\*\*Primary value bucket:\*\*\s*(.+)/i)
+  if (bucketLine && VALUE_BUCKET_RE.test(bucketLine[1].trim())) return true
+  if (!/\*\*Primary value bucket:\*\*/i.test(success) && VALUE_BUCKET_RE.test(success)) return true
+
+  const ledger = stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger') || '')
+  const table = parseMdTable(ledger)
+  if (table) {
+    const bIdx = colIndex(table.headers, /bucket/i)
+    if (bIdx !== -1) {
+      for (const row of table.rows) {
+        const cell = String(row[bIdx] || '').trim()
+        if (cell && VALUE_BUCKET_RE.test(cell)) return true
+      }
+    } else if (VALUE_BUCKET_RE.test(ledger)) {
+      return true
+    }
+  } else if (VALUE_BUCKET_RE.test(ledger)) {
+    return true
+  }
+  return false
+}
+
+// AI in scope for ship/close hygiene — delivery/decisions/trust evidence only.
+// Do not scan terrain.md: its template headers mention LLM and would false-positive every ship.
+function engagementTouchesAI(eng) {
+  const trust = readClean(eng, 'trust-profile.md')
+  const aiSec = stripTemplateNoise(sectionBody(trust, 'AI policy') || '')
+  if (aiSec.trim().length > 20) return true
+  const blob = stripTemplateNoise([
+    readClean(eng, 'delivery.md'),
+    readClean(eng, 'decisions.md'),
+  ].join('\n'))
+  return /\b(llm|rag|embedding|inference|model card|agentic|openai|anthropic|vector database|vector db)\b/i.test(blob)
+}
+
+function hasEvalReceipt(eng) {
+  const evalsPath = path.join(eng, 'evals.md')
+  if (fs.existsSync(evalsPath)) {
+    const e = stripTemplateNoise(readClean(eng, 'evals.md'))
+    // Empty G1 stub + "Pass / fail" heading is not a receipt — need a real verdict/run/result.
+    if (/\*\*Verdict:\*\*\s*SHIP\b/i.test(e) || /(?:^|\n)\s*-\s*\*\*Verdict:\*\*\s*SHIP\b/i.test(e)) return true
+    if (/\bLast run:\s*\d{4}-\d{2}-\d{2}/i.test(e)) return true
+    if (/\|\s*G\d+\s*\|[^|\n]+\|[^|\n]+\|[^|\n]+\|[^|\n]+\|\s*pass\s*\|/i.test(e)) return true
+  }
+  const del = stripTemplateNoise(readClean(eng, 'delivery.md'))
+  if (/#{1,6}\s+Eval\b/i.test(del) && /\b(pass|SHIP|\d+\/\d+)\b/i.test(sectionBody(del, 'Eval') || del)) return true
+  if (/\beval (pack|receipt)[:\s].*\b(pass|SHIP)\b/i.test(del)) return true
+  const receipts = sectionBody(del, 'Ship receipts') || ''
+  if (/\bevals\.md\b/i.test(receipts) && /\b(pass|SHIP)\b/i.test(receipts) && !/\*\([^)]*evals\.md[^)]*\)\*/i.test(receipts)) {
+    return true
+  }
+  return false
+}
+
 // Lean line for session-start TRIAGE - count + top issue + NL cue. Omitted when clean.
 function hygieneTriageLines(eng) {
   const issues = collectDoctorIssues(eng)
@@ -1651,10 +1766,24 @@ function cmdGarden(args) {
   const apply = args.includes('--apply')
   const eng = resolveEngagement({ forWrite: apply })
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  const gitHealth = memoryGitHealthy(eng)
   // Gardener contract (from Rowboat note_curation): no new facts, no deleted substance,
-  // reversible via git, confirm before apply. Mechanical only - no LLM rewrite.
-  console.log('GARDEN (contract: no new facts · no deleted substance · reversible via memory git)')
+  // reversible via git when healthy, confirm before apply. Mechanical only - no LLM rewrite.
+  if (gitHealth.ok) {
+    console.log('GARDEN (contract: no new facts · no deleted substance · reversible via memory git)')
+  } else if (gitHealth.reason === 'broken') {
+    console.log('GARDEN (contract: no new facts · no deleted substance · ⚠ memory git BROKEN — NOT reversible until ledger is repaired)')
+  } else {
+    console.log('GARDEN (contract: no new facts · no deleted substance · ⚠ memory not git-versioned — NOT reversible)')
+  }
   console.log(resumeTriage(eng))
+  if (!gitHealth.ok) {
+    console.log(
+      gitHealth.reason === 'broken'
+        ? '\n⚠ ledger is UNVERSIONED (corrupt .git). Repair before trusting garden apply: mv .fde/.git .fde/.git.broken && run any fde write to re-init.'
+        : '\n⚠ no memory git — garden apply cannot create a reversible commit until the ledger exists.'
+    )
+  }
   const proposals = []
   const s = computeSignals(eng)
   if (s.stale) {
@@ -1664,6 +1793,16 @@ function cmdGarden(args) {
       text: `Reconfirm stale ${s.trust} signal (${s.signalAge}d): fde log contact "…" --signal`,
     })
   }
+  const dupes = findDuplicateOpenRisks(eng)
+  if (dupes.length) {
+    const sample = (dupes[0][0] || '').replace(/\s+/g, ' ').trim().slice(0, 50)
+    proposals.push({
+      id: 'dedupe-risks',
+      kind: 'apply',
+      text: `Consolidate ${dupes.length} duplicate open-risk cluster(s) (e.g. "${sample}${sample.length >= 50 ? '…' : ''}") — keep first, retire echoes`,
+      clusters: dupes,
+    })
+  }
   const ctx = readEng(eng, 'context.md')
   const sessionBlocks = []
   const lines = ctx.split('\n')
@@ -1689,12 +1828,26 @@ function cmdGarden(args) {
   proposals.forEach((p, i) => console.log(`  ${i + 1}. [${p.kind}] ${p.text}`))
   if (!apply) {
     console.log('\nApply mechanical items only:  fde garden --apply')
-    console.log('Manual items stay yours. Every apply commits to memory git.')
+    console.log('Manual items stay yours. Every apply commits to memory git when the ledger is healthy.')
     return
   }
+  if (!gitHealth.ok && gitHealth.reason === 'broken') {
+    console.error('refusing garden --apply while memory git is broken - repair the ledger first')
+    process.exit(1)
+  }
   ensureMemoryGit(eng)
   let applied = 0
+  const touched = new Set()
   for (const p of proposals) {
+    if (p.id === 'dedupe-risks') {
+      const n = applyRiskDedupe(eng, p.clusters)
+      if (n > 0) {
+        applied++
+        touched.add('risks.md')
+        console.log(`applied: retired ${n} duplicate open-risk echo(s) → ## Retired`)
+      }
+      continue
+    }
     if (p.id !== 'archive-sessions') continue
     const cutDates = new Set(p.sessionBlocks.map(b => b.date))
     const keep = []
@@ -1728,13 +1881,61 @@ function cmdGarden(args) {
       atomicWriteFile(path.join(eng, 'context.md'), keep.join('\n').replace(/\n*$/, '\n'))
     })
     applied++
+    touched.add('context.md')
+    touched.add('context-archive.md')
     console.log(`applied: archived ${p.sessionBlocks.length} old session-end blocks → context-archive.md`)
   }
-  const hash = commitMemory(eng, 'garden', { files: ['context.md', 'context-archive.md'] })
+  const hash = commitMemory(eng, 'garden', { files: [...touched] })
   if (!applied) console.log('no mechanical proposals applied (manual items remain)')
   else console.log(`garden done${hash ? ` @${hash}` : ''}`)
 }
 
+// Keep the first open-risk bullet per fingerprint; move later echoes under ## Retired.
+function applyRiskDedupe(eng, clusters) {
+  const p = path.join(eng, 'risks.md')
+  let md = readEng(eng, 'risks.md')
+  if (!md) return 0
+  const echoTexts = new Set()
+  for (const group of clusters) {
+    for (let i = 1; i < group.length; i++) echoTexts.add(group[i])
+  }
+  if (!echoTexts.size) return 0
+  const retiredLines = []
+  const kept = []
+  let inRetired = false
+  let moved = 0
+  for (const raw of md.split('\n')) {
+    const t = raw.trim()
+    if (/^#{1,6}\s+Retired\b/i.test(t)) {
+      inRetired = true
+      kept.push(raw)
+      continue
+    }
+    if (!inRetired) {
+      const m = t.match(/^-\s*\[\d{4}-\d{2}-\d{2}\]\s*(?:\[@[^\]]+\]\s*)?(.*)$/)
+      if (m && echoTexts.has(m[1].trim())) {
+        retiredLines.push(raw)
+        moved++
+        continue
+      }
+    }
+    kept.push(raw)
+  }
+  if (!moved) return 0
+  let out = kept.join('\n')
+  if (!/^#{1,6}\s+Retired\b/im.test(out)) {
+    out = out.replace(/\n*$/, '\n\n## Retired\n')
+  }
+  const stamp = new Date().toISOString().slice(0, 10)
+  const block = retiredLines.map(l => {
+    const body = l.trim().replace(/^-\s*/, '')
+    return `- [${stamp}] (garden dedupe) ${body}`
+  }).join('\n')
+  out = appendUnderSection(out, 'Retired', block)
+  withFileLock(p, () => { atomicWriteFile(p, out.endsWith('\n') ? out : out + '\n') })
+  return moved
+}
+
 function engagementSlugFromPath(eng) {
   return path.basename(path.dirname(eng))
 }

package/bin/lib/memory.js

@@ -151,12 +151,32 @@ function createMemoryApi(deps) {
     } catch (_) { return '' }
   }
 
+  // True only when .git exists AND can resolve HEAD. A corrupt ledger (broken
+  // HEAD / missing objects) still has a .git directory — existsSync alone lied.
+  function memoryGitHealthy(eng) {
+    if (!eng) return { ok: false, reason: 'missing' }
+    if (!fs.existsSync(path.join(eng, '.git'))) return { ok: false, reason: 'missing' }
+    if (!gitBinOk()) return { ok: false, reason: 'no-git-bin' }
+    try {
+      execFileSync('git', ['rev-parse', '--verify', 'HEAD'], {
+        cwd: eng, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+      })
+      execFileSync('git', ['status', '--porcelain'], {
+        cwd: eng, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'],
+      })
+      return { ok: true, reason: '' }
+    } catch (_) {
+      return { ok: false, reason: 'broken' }
+    }
+  }
+
   return {
     MEMORY_EPHEMERAL,
     memoryPorcelainPaths,
     memoryDirtyManual,
     commitMemory,
     memoryHead,
+    memoryGitHealthy,
     ensureMemoryGit,
   }
 }

package/package.json

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

@@ -270,6 +270,7 @@ Running the engagement and ending it well.
 | Signal | Overlay |
 |--------|---------|
 | AI, ML, LLM, model, embeddings, RAG, agents, fine-tuning, inference, drift | `references/ai.md` |
+| Golden set, eval suite, eval pack, pass/fail before AI ship, HITL gate for model | `references/eval-pack.md` (+ `ai.md`) |
 | Deck, slides, report, governance framework, compliance pack, ADR, PDF | `references/artifacts.md` |
 | Patient data, PHI, HIPAA, EHR, clinical | `references/healthcare.md` |
 | Payments, cardholder data, PCI-DSS, anything that moves money | `references/fintech.md` |

package/skills/fde/references/ai.md

@@ -36,6 +36,19 @@ Never start with the most powerful model. Start with the cheapest that meets the
 
 Write model selection rationale to `decisions.md`. Include: models tested, test set size, scores, cost comparison.
 
+## Engagement eval pack (before AI ships)
+
+When any slice touches a model, embeddings, RAG, or an agent: create or update `.fde/evals.md` **before** ship. Full method: `references/eval-pack.md`. This is the engagement-local test set — not unit tests.
+
+**Minimum pack (do not grow until the minimum exists):**
+1. **Component + quality bar** — one sentence each; kill switch / fallback named.
+2. **Golden cases** — 5–20 representative inputs with expected outputs and a pass rule. Prefer real production-shaped data (sanitized).
+3. **Failure modes** — at least the silent ones: hallucination/ungrounded, retrieval miss (if RAG), drift, cost runaway.
+4. **Pass/fail** — dated run; Verdict **SHIP** or **NO-SHIP**; critical fails must be 0.
+5. **HITL gate** — which decisions need human review before action (align with `trust-profile.md`). Empty when policy requires review → NO-SHIP.
+
+**When to write:** plan seeds the pack; sketch/build grows goldens; ship requires Verdict SHIP and a receipt in `delivery.md` → `## Ship receipts`. Non-AI work skips this file entirely.
+
 ## RAG architecture (retrieval-augmented generation)
 
 When the AI needs to answer questions about the client's data:
@@ -78,12 +91,13 @@ When the AI takes actions (not just generates text):
 
 ## Writes
 
-`trust-profile.md` - AI policy, data classification, model hosting, human-in-the-loop requirements. `decisions.md` - model selection rationale, architecture choices. `risks.md` - bias findings, drift observations, cost projections. `delivery.md` - AI component inventory with kill switches documented.
+`trust-profile.md` - AI policy, data classification, model hosting, human-in-the-loop requirements. `evals.md` - golden cases, failure modes, SHIP/NO-SHIP, HITL. `decisions.md` - model selection rationale, architecture choices. `risks.md` - bias findings, drift observations, cost projections. `delivery.md` - AI component inventory with kill switches + eval receipt on ship.
 
 ## Principles
 
 - AI degrades silently. Monitor outputs, not just uptime.
 - Start with the cheapest model that meets the quality bar.
+- No golden set, no AI ship (`evals.md` Verdict SHIP).
 - Every AI component needs a kill switch and a fallback path.
 - Log reasoning, not just results. Debug AI from its decisions.
 - Drift is inevitable. Define the detection method before shipping.

package/skills/fde/references/build.md

@@ -127,7 +127,7 @@ The FDE's job is to make themselves replaceable. Not at handoff - every day. A c
 
 - **`decisions.md`** - each significant choice: what, alternatives considered, why this one. For non-trivial architecture decisions, present three options to the FDE (safe / pragmatic / aggressive) with costs and a recommendation - three options is a real decision; one option is a request for trust. Integration contracts go here too.
 - **`risks.md`** - new risks discovered while building.
-- **`delivery.md`** - append a **value ledger** row for every ship: Date | Slice | Promised | Measured | Evidence | Rollback. "Measured" may be `pending` until the pulse exists - never skip the promised column. Narrative under Shipped is optional color; the ledger is the record status and close read.
+- **`delivery.md`** - append a **value ledger** row for every ship: Date | Slice | Bucket | Promised | Measured | Evidence | Rollback. Bucket is `cost-save` / `risk-mitigation` / `revenue-uplift`. "Measured" may be `pending` until the pulse exists - never skip the promised column. Narrative under Shipped is optional color; the ledger is the record status and close read.
 
 ## Checkpoint
 

package/skills/fde/references/close.md

@@ -17,6 +17,12 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 - Which risk almost became real?
 - AI components: did they behave in production? What failure modes did the prototype hide? Is the team equipped to maintain them?
 
+**1b. Value + receipts close gate (refuse green close if any fail):**
+- Primary value bucket in `success.md` matches what the sponsor funded; at least one ledger row has **Measured** (not forever-`pending`) with evidence for that bucket — or the retrospective explicitly records “not measured; sponsor accepted pending.”
+- Audit receipt exists for the final shipped path (exceptions/operating map walked; cite file).
+- Eval receipt: **n/a if no AI**, else final golden/eval result + HITL owner recorded; kill switch / fallback named in `handoff.md`.
+- One line in the retrospective: which bucket moved, by how much, vs baseline.
+
 **2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. **If you do it twice, encode it.**
 
 **3. The handoff.** Operational knowledge for the person woken at 2am, not technical documentation: the 3 things that will break and the fix for each · who holds the tribal knowledge · what each alert means · deploy and rollback in plain language. AI components additionally: model version, what normal output looks like (so drift is recognisable), fallback behaviour, who owns retraining, **how to disable the AI path without taking down the feature** - without this the team turns it off at the first misbehaviour and it stays off.
@@ -33,11 +39,12 @@ The engagement doesn't end at ship. It ends when the customer can maintain what
 
 ## Checkpoint
 
-Direct assessment to the FDE: did the engagement achieve `success.md` · 2–3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Honest - a gap named now is cheaper than a callback in six weeks.
+Direct assessment to the FDE: did the engagement achieve `success.md` · 2–3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Also: value bucket + audit receipt green; eval **n/a or green**. Pending Measured without sponsor acceptance = gap, not green close. Honest - a gap named now is cheaper than a callback in six weeks.
 
 ## Principles
 
 - Done = the customer operates without you.
+- No named value bucket moved (or sponsor-accepted pending) = not a green close.
 - The retrospective is an investment in the next engagement, not a post-mortem.
 - Encode what repeated. The same lesson learned twice is a process failure.
 - Write the handoff for 2am.

package/skills/fde/references/discover.md

@@ -92,6 +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).
 
 ## Method - part 3: workshop facilitation
 
@@ -165,6 +166,11 @@ Score every candidate use case before anything gets prototyped:
 **Data flow:** <entry → transform → store → exit>
 **Test landscape:** <covered / gaps / lies>
 **Unknowns:** <named explicitly - an honest gap beats a confident guess>
+
+## Operating map (exception-led)
+| Exception / break | Who notices first | What they do today | System of record then | Blast | Evidence |
+|-------------------|-------------------|--------------------|----------------------|-------|----------|
+| <break> | <role> | <workaround> | <sheet/DB/person> | CRITICAL / LOAD-BEARING / CONVENIENCE | <who/day> |
 ```
 
 Every line carries its evidence. `(churn: 47/90d)` `(ops lead, Day 5)` `(stated, unverified)`.
@@ -173,11 +179,12 @@ Every line carries its evidence. `(churn: 47/90d)` `(ops lead, Day 5)` `(stated,
 
 ## Checkpoint (before any build)
 
-Present to the FDE, four things, one paragraph each - no padding:
+Present to the FDE, five things, one paragraph each - no padding:
 1. The real problem, with the two strongest pieces of evidence.
 2. The top 3 risk areas of the codebase, one line of why each.
 3. What must not be touched without characterisation tests.
-4. The recommendation: confirm brief / descope / rescope - and the decision it puts in front of the sponsor.
+4. The exception-led operating map: the two breaks that matter most, who owns the workaround, and where shadow systems live.
+5. The recommendation: confirm brief / descope / rescope - and the decision it puts in front of the sponsor.
 
 If discovery revealed the problem is 3× the brief: the FDE tells the customer **before** telling themselves it's manageable. Lead with evidence, offer three paths (descope / rescope / pause-and-plan), confirm any reset in writing - update `success.md` and `brief.md` before continuing.
 

package/skills/fde/references/eval-pack.md

@@ -0,0 +1,43 @@
+# eval-pack - prove the system before it acts
+
+**Enter when:** the work touches AI/LLM/agents/RAG, or ship/close is blocked because there is no evidence the non-deterministic path is safe. Activate alongside `ai.md`, `sketch`, `build`, or `ship` — not instead of them.
+
+**Read first:** `trust-profile.md` (AI policy + HITL), `terrain.md` (operating map), `delivery.md`. Create or extend `evals.md`.
+
+Non-AI engagements skip this pack entirely.
+
+## Why this exists
+
+Intelligence without evidence is token-maxing with a nicer name. An FDE earns trust by showing: golden cases, failure modes, and a human gate before action.
+
+## Method (you do this work)
+
+**1. Scope the judgement surface.** One sentence: which step uses model judgement, and what must never be autonomous.
+
+**2. Build a golden set (minimum 5–20 for a slice; prefer 50–100 before broad scale).** For each case:
+- input (sanitized — no `<private>` raw values)
+- expected outcome or expert-approved acceptance note
+- pass rule (exact / contains / short rubric)
+- source: real historical example / expert label / staged fixture
+
+**3. Score pass/fail, not vibes.** Run the suite. Record count pass / fail. Failures get a failure-mode tag (missing data, wrong record, format drift, hallucination, retrieval miss, unsafe action, other).
+
+**4. Human-in-the-loop gate.** Name which outcomes require human approve before side effects. If none, write why that is allowed under `trust-profile.md` AI policy — do not invent permission.
+
+**5. Ship rule.** Until `evals.md` shows Verdict **SHIP** with a dated run (critical fails = 0) and HITL filled when policy requires it, AI-touching ship stays **fix-first**. Log a one-line eval receipt in `delivery.md` → `## Ship receipts`.
+
+## Artifact — `evals.md`
+
+Create on first AI-touching slice (not at `resume --init`). Use the stub in `templates/.fde/evals.md`. Every claim needs a source. Missing evidence → leave the cell `unknown - ask:`, never invent scores.
+
+## Checkpoint
+
+Present to the FDE: suite size, pass rate, top failure mode, HITL gate, Verdict SHIP/NO-SHIP. If they want to ship without a run: say no, and offer the smallest suite that would unblock.
+
+## Principles
+
+- No golden set, no AI ship.
+- Pass/fail beats “looks good.”
+- Failure modes are the product — the happy path is table stakes.
+- HITL is a gate, not a slide.
+- Non-AI work does not need this file.

package/skills/fde/references/land.md

@@ -65,6 +65,7 @@ Let silence sit. If their fear doesn't match the written brief, the brief is wro
 - **The previous attempt** - "we tried something similar last year" is the most important sentence in the first meeting. Who was involved? Still there and protective, or gone because of it?
 - **The passed-over internal team** - they know exactly what's wrong, and they resent the FDE's presence. Find them before the first standup, ask what they tried, use their language in every meeting. Make them look right and they protect you; ignore them and they wait for the mistake.
 - **The sacred thing** - "Is there anything in this environment I should treat as untouchable?" The hesitation before the answer is the answer.
+- **Exception path (operating map seed)** - "When the happy path breaks this week, what do people actually do — who do they call, what spreadsheet opens, what do they skip?" Capture the break → workaround → who owns it. Do not build a full map on day 1; seed rows later in `terrain.md` → `## Operating map (exception-led)` during discover. Unknowns stay `unknown - ask:`.
 - **AI posture and policy** - tools already in use (sanctioned or shadow), and: "Does your organisation have a policy on AI-generated code? Are there decisions where you would not be comfortable with AI involvement?"
 - **Boundaries in multi-vendor rooms** - who owns what surface, who signs off before a change crosses it.
 
@@ -76,7 +77,7 @@ Before the end of day 1, ship one visible thing: a small bug fix, a cleanup the
 
 **`brief.md`** - what they said, who sent the FDE, the timeline, **and the gap list**.
 
-**`success.md`** - what done looks like, how it's measured, who actually signs off, what is explicitly out of scope. Agreed with the customer, not assumed.
+**`success.md`** - what done looks like, **primary value bucket** (`cost-save` | `risk-mitigation` | `revenue-uplift`), baseline → target, who actually signs off, what is explicitly out of scope. Agreed with the customer, not assumed.
 
 **`stakeholders.md`**:
 ```markdown
@@ -100,7 +101,7 @@ One falsifiable hypothesis about the real problem also goes at the bottom of `br
 
 ## Checkpoint
 
-One page back to the FDE: success + sign-off owner, out-of-scope boundary, sacred data, stakeholder map with veto power, AI posture, the hypothesis, and the top CRITICAL assumptions still OPEN. If it doesn't fit one page, the engagement isn't understood yet.
+One page back to the FDE: success + value bucket + sign-off owner, out-of-scope boundary, sacred data, stakeholder map with veto power, AI posture, the hypothesis, the top CRITICAL assumptions still OPEN, and any exception-path seeds heard (break → workaround → owner) for discover to map into `terrain.md`. If it doesn't fit one page, the engagement isn't understood yet.
 
 If remote: trust-building takes ~40% longer - push for a short video call before anything asynchronous.
 

package/skills/fde/references/ship.md

@@ -2,7 +2,7 @@
 
 **Enter when:** a slice is built, reviewed, and ready to deploy.
 
-**Read first:** `context.md`, `delivery.md`. Load `trust-profile.md` if the deploy touches regulated data or needs an approval chain.
+**Read first:** `context.md`, `delivery.md`, `success.md`. Load `trust-profile.md` if the deploy touches regulated data or needs an approval chain. Load `evals.md` when the deploy touches AI/ML/LLM/RAG/agents.
 
 Opening question, calm tech lead voice: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
 
@@ -42,10 +42,26 @@ Score each dimension green/amber/red. This is the gate, not a suggestion:
 | Runbook | Exists and someone other than you has read it | Exists but unreviewed | Missing |
 | Monitoring | Alerts configured, owner named, dashboard live | Alerts configured, no named owner | No monitoring |
 
+### Value + receipts gate (score with the table above)
+
+| Dimension | Green | Amber | Red |
+|-----------|-------|-------|-----|
+| **Value bucket** | `success.md` names primary bucket (`cost-save` \| `risk-mitigation` \| `revenue-uplift`) and a baseline→target metric; this slice’s value-ledger row has **Bucket** + **Promised** | Bucket named; **Measured** still `pending` with a pulse date | No bucket, or Promised empty / ticket-theater only |
+| **Audit receipt** | Dated line in `delivery.md` (`## Ship receipts` or ledger Evidence) proving exceptions/operating path were walked — cite `terrain.md` / `reality.md` / `audit.md` | Path described, not verified this ship | No audit receipt for this slice |
+| **Eval receipt** | **n/a** (no AI on this slice) **or** `evals.md` Verdict SHIP with dated golden run + HITL gate named | Eval pack exists; known fails open with owner + date | AI in scope and no eval receipt |
+| **AI eval pack** | `.fde/evals.md` Verdict SHIP; goldens run this change; critical fails 0; HITL filled if policy requires | Pack exists; run stale vs change log | AI-touching deploy and pack missing / NO-SHIP / HITL required but empty |
+
 **Any RED = stop. Do not deploy. Fix the red dimension first.**
 **2+ AMBER = sponsor conversation before deploying.** Present the ambers and get explicit "proceed" or "fix first."
 
-Write the readiness score to `delivery.md` before deploying. The score is the evidence if anything goes wrong.
+**AI-touching deploys (model, embeddings, RAG, agent, or inference path):**
+1. Read `.fde/evals.md`. If missing → **RED. Do not deploy.** Create the pack (`eval-pack` / `ai` overlay) and re-score.
+2. If Verdict is not **SHIP**, or Last run is older than the latest change-log row → **RED.**
+3. If `trust-profile.md` requires human-in-the-loop and the HITL gate has no reviewer → **RED.**
+4. Log in `delivery.md` → `## Ship receipts` before deploy: audit cite + eval receipt.
+5. Non-AI deploys: Eval = **n/a** — do not invent an empty pack.
+
+Write the readiness score (including value + receipts) to `delivery.md` before deploying. The score is the evidence if anything goes wrong.
 
 ## Pre-blast challenge (before the deploy button)
 
@@ -146,13 +162,14 @@ Adoption isn't a handoff-stage problem - it starts during build. Software that l
 
 ## Checkpoint
 
-Before 100%: canary clean, business metric verified, pulse written into `delivery.md`. Any item unconfirmed → the deploy waits. For enterprise-scale: scale-readiness gate passed before broad rollout.
+Before 100%: canary clean, business metric verified, pulse written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**. Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
 
 ## Principles
 
 - A deployment without a tested rollback is reckless.
 - Roll back on any canary anomaly; investigate safely.
 - Verify the business metric, not just the technical one.
-- No pulse, no done.
+- No value bucket, no green ship. No pulse, no done.
+- AI path without eval receipt = fix-first; non-AI ships leave eval as n/a.
 - Scale readiness is organizational, not just technical. Check all 8 dimensions.
 - Adoption is measured from day one, not hoped for at launch.

package/templates/.fde/delivery.md

@@ -4,9 +4,17 @@
 
 ## Value ledger
 
-| Date | Slice | Promised | Measured | Evidence | Rollback |
-|------|-------|----------|----------|----------|----------|
-| | | *(what we said it would change)* | *(what actually changed, or pending)* | *(who/when/metric)* | |
+| Date | Slice | Bucket | Promised | Measured | Evidence | Rollback |
+|------|-------|--------|----------|----------|----------|----------|
+| | | *(cost-save / risk-mitigation / revenue-uplift)* | *(what we said it would change)* | *(what actually changed, or pending)* | *(who/when/metric)* | |
+
+## Ship receipts
+
+<!-- Fill before green ship. Eval = n/a unless AI touches the slice. -->
+
+| Date | Slice | Audit receipt | Eval receipt |
+|------|-------|---------------|--------------|
+| | | *(dated cite: exceptions/operating path verified — terrain/reality/audit)* | *(n/a \| evals.md pass + HITL owner)* |
 
 ## Shipped
 

package/templates/.fde/evals.md

@@ -0,0 +1,42 @@
+# Engagement eval pack
+
+<!-- AI-touching work only. Fill before ship. Empty pack = do not deploy AI path. Non-AI engagements: leave unused or delete. -->
+
+## Component
+- **Name / slice:**
+- **Model / stack:** <!-- rules | small model | frontier | RAG | agent -->
+- **Quality bar:**
+- **Kill switch / fallback:**
+- **Owner:**
+
+## Golden cases
+
+| ID | Input (sanitized) | Expected | Pass rule | Last run | Result |
+|----|-------------------|----------|-----------|----------|--------|
+| G1 | | | | | |
+
+## Failure modes
+
+| Mode | How it shows up | Detection | Mitigation |
+|------|-----------------|-----------|------------|
+| | | | |
+
+## Pass / fail (this ship)
+- **Golden:** _/_ pass (threshold: _)
+- **Critical fails (must be 0):**
+- **Verdict:** <!-- SHIP | NO-SHIP -->
+- **Evidence:** <!-- who/when -->
+
+## Human-in-the-loop gate
+
+| Decision / action | Autonomous OK? | Reviewer role | Escalation |
+|-------------------|----------------|---------------|------------|
+| | | | |
+
+**HITL rule for this ship:**
+
+## Change log
+
+| Date | What changed | Pack re-run? | Notes |
+|------|--------------|--------------|-------|
+| | | | |

package/templates/.fde/success.md

@@ -3,5 +3,7 @@
 <!-- Agreed definition of done. Out-of-scope is as important as in-scope. -->
 
 **Done when:**
+**Primary value bucket:** <!-- cost-save | risk-mitigation | revenue-uplift (pick one) -->
+**Baseline → target:** <!-- metric, number, by when -->
 **Explicitly out of scope:**
 **Stakeholder who signs off:**

package/templates/.fde/terrain.md

@@ -5,3 +5,21 @@
 **Stack:**
 **Hotspots (handle with care):**
 **Test gaps:**
+
+## Operating map (exception-led)
+
+<!-- How work actually runs when the happy path fails. Fill in discover; leave blank until heard/seen. -->
+
+| Exception / break | Who notices first | What they do today (workaround) | System of record then | Blast if wrong | Evidence |
+|-------------------|-------------------|---------------------------------|-----------------------|----------------|----------|
+| | | | | | |
+
+**Shadow systems / silent workarounds:**
+**Sacred / untouchable in ops:**
+**Previous attempt residue:**
+
+## Intelligence placement (when AI is in play)
+
+| Step | Deterministic | Model judgement | Human approve |
+|------|---------------|-----------------|---------------|
+| | | | |