fdeops 3.30.0 → 4.0.0

package/README.md

@@ -40,6 +40,16 @@ One chat. Name the client:
 
 That creates `~/fde-engagements/client01/.fde/` on your laptop. Paste kickoff notes in the same thread. `@fde` picks what to check. You still decide. After a meeting you review what changed, new asks, open questions, and next actions. Correct the proposal, then confirm the update.
 
+### Make it fit your work
+
+Setup asks three short questions: how you work, what would help first, and what to mask before sharing context with your agent. Review your choices before saving; change them anytime.
+
+```bash
+npx fdeops@latest setup
+```
+
+[See the choices and custom masking options](docs/USAGE.md#make-fdeops-fit-your-day).
+
 Open the engagement fieldbook:
 
 ```bash
@@ -56,8 +66,6 @@ Read-only HTML of the record - promised, measured, accepted, and evidence. Regen
 /plugin install fdeops@fdeops
 ```
 
-Make it fit your day: `fde setup` asks three choices for your daily overview, context size, and report masking. [First-use setup](docs/USAGE.md#make-fdeops-fit-your-day).
-
 The plugin adds session hooks and the slash commands below. Skill-only installation does not add hooks. See the [installation guide](docs/install.md) for setup details.
 
 </details>

package/bin/fde.js

@@ -98,9 +98,9 @@ function gitIsAncestor(eng, olderHash, newerHash) {
   } catch (_) { return false }
 }
 
-function gitLogHash(eng, args) {
+function gitLogHash(eng, args, format = '%H') {
   try {
-    return execFileSync('git', ['log', '-1', '--format=%H', ...args], {
+    return execFileSync('git', ['log', '-1', `--format=${format}`, ...args], {
       cwd: eng, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15000,
     }).trim()
   } catch (_) { return '' }
@@ -821,7 +821,7 @@ function phaseLabel(phase) {
 // colon) collapses to '' here, which callers treat as "nothing to show".
 function firstLine(md, maxLen) {
   for (const raw of md.split('\n')) {
-    const l = raw.trim()
+    const l = maskDisplay(raw).trim()
     if (!l || /^#{1,6}\s/.test(l)) continue
     const clean = maskDisplay(l.replace(/^\*\*[^*]+:\*\*\s*/, '').replace(/\*\*/g, '').replace(/^["']|["']$/g, '').trim())
     if (!clean) continue
@@ -1041,7 +1041,7 @@ function parseSignalHistoryEntries(eng) {
 }
 
 function displayNameFromSignalText(text) {
-  if (preferences.privacy === 'reports' && masking.mask(text) !== text) return 'Contact (identifier masked)'
+  if ((preferences.privacy === 'reports' || !['dashboard', 'vault'].includes(process.argv[2])) && masking.mask(text) !== text) return 'Contact (identifier masked)'
   const person = personFromSignalText(text)
   if (person) return person
   const t = String(text).trim()
@@ -1166,7 +1166,7 @@ function extractRisks(eng) {
 // sides look like real numbers/percentages, deduped by value pair, capped at
 // 4; nothing reliable found -> the widget stays empty, never an invented number.
 function extractStats(eng) {
-  const text = readClean(eng, 'delivery.md') + '\n' + readClean(eng, 'decisions.md')
+  const text = maskDisplay(readClean(eng, 'delivery.md') + '\n' + readClean(eng, 'decisions.md'))
   const patterns = [
     /(\d+(?:\.\d+)?%)[^\n%]{0,40}?(?:→|->)[^\n%]{0,20}?(\d+(?:\.\d+)?%)/g, // "X% ... -> Y%"
     /(\d+(?:\.\d+)?%)\s+to\s+(\d+(?:\.\d+)?%)/gi,                               // "X% to Y%"
@@ -1458,6 +1458,7 @@ function cmdResume(args) {
   const risks = readClean(eng, 'risks.md')
   process.stdout.write(maskedSections([
     policy ? `CLIENT POLICY - trust-profile.md\n${policy}` : '',
+    preferences.work ? `WORKING PREFERENCES: ${preferences.work}. Starting help: ${preferences.start}.\n${setup.nextStep(preferences)}\nThis is a starting preference, not a client fact; current instructions and engagement state take precedence.` : '',
     `${intro}\n\nENGAGEMENT: ${eng}`,
     success ? `CURRENT GOALS & ACCEPTANCE - success.md\n${success}` : '',
     risks ? `OPEN RISKS - risks.md\n${extractRisks(eng).map(r => r.text).join('\n') || '(none recorded)'}` : '',
@@ -1575,7 +1576,7 @@ function cmdLog(args) {
   if (hit && force) console.error(`warning: logging possible ${hit} (--force)`)
   if (retire) {
     const n = retireOpenRisks(eng, text)
-    if (!n) { console.error(`no open risk matched ${JSON.stringify(text)}`); process.exit(1) }
+    if (!n) { console.error(`no open risk matched ${JSON.stringify(masking.mask(text))}`); process.exit(1) }
     const hash = commitMemory(eng, 'retire risk', { files: ['risks.md'] })
     console.log(`retired ${n} risk(s) → risks.md${hash ? ` @${hash}` : ''}`)
     return
@@ -1916,6 +1917,19 @@ function stripApprovedStamp(text) {
   return String(text || '').replace(/\s*\[approved:\s*[^\]]+\]/i, '').trim()
 }
 
+function proposedSigner(body) {
+  // Unknown or tentative ownership is a note, never a fabricated sign-off.
+  const sources = body.match(/\[source:[^\]]*\]/gi) || []
+  const prose = body.replace(/\[source:[^\]]*\]/gi, '').trim()
+  if (/\?|\b(?:maybe|might|whether|could|should|would|if|unless)\b/i.test(prose)) return ''
+  // Check uncertainty before removing a suffix, then validate the actual
+  // identity so "customer sponsor signs off" cannot become a named person.
+  if (!require('./lib/value-ledger').acceptanceName(prose)) return ''
+  const identity = prose.replace(/\s+signs?(?:\s+off)?\b.*$/i, '').trim()
+  if (!require('./lib/value-ledger').acceptanceName(identity)) return ''
+  return [identity, ...sources].join(' ')
+}
+
 // One screen a human can confirm in two minutes. The file-by-file routing
 // still prints after this - agents edit prefixes; people read this.
 function printDebriefReview(text, eng) {
@@ -1933,7 +1947,7 @@ function printDebriefReview(text, eng) {
     if (type === 'decision') {
       const who = approvedStamp(body)
       const core = previewLine(stripApprovedStamp(body), 90)
-      buckets.decided.push(who ? `${core}  (approved ${who})` : `${core}  (unconfirmed)`)
+      buckets.decided.push(!hasSource(body) ? `${core}  (CLAIM - source missing; unconfirmed)` : who ? `${core}  (approved ${who}; source recorded)` : `${core}  (unconfirmed; source recorded)`)
     } else if (type === 'ask') {
       buckets.asked.push(previewLine(body, 100))
     } else if (type === 'scope') {
@@ -1945,7 +1959,8 @@ function printDebriefReview(text, eng) {
     } else if (type === 'next') {
       buckets.next.push(previewLine(body, 100))
     } else if (type === 'signer') {
-      buckets.signer.push(previewLine(body, 80))
+      if (proposedSigner(body)) buckets.signer.push(previewLine(body, 80))
+      else buckets.open.push(`signer authority missing or uncertain: ${previewLine(body, 80)}`)
     }
   }
   console.log('REVIEW (one screen - confirm once, then apply)\n')
@@ -2005,7 +2020,7 @@ function changeReviewIssues(eng) {
   const del = latestDeliveryEntry(readClean(eng, 'delivery.md'))
   const dec = latestDatedDecision(readClean(eng, 'decisions.md'))
   const delHash = del.line
-    ? sh(`git log -1 --format=%H -S${JSON.stringify(del.line)} -- delivery.md`, eng)
+    ? gitLogHash(eng, ['-S', del.line, '--', 'delivery.md'])
     : ''
   if (del.date && dec.date && dec.date > del.date && delHash) {
     issues.push(
@@ -2168,7 +2183,8 @@ function routeDebriefInput(eng, input, { dry, force, sealed = [], allowReplay =
         continue
       }
       if (type === 'signer') {
-        const who = body.replace(/\s+signs?(?:\s+off)?\b.*$/i, '').trim() || body.trim()
+        const who = proposedSigner(body)
+        if (!who) { ctxLines.push(line); continue }
         if (dry) {
           console.log(`→ success.md  **Stakeholder who signs off:** ${previewLine(who)}`)
           console.log(`→ stakeholders.md  ${previewLine(`- [${date}] ${who} signs off`)}`)
@@ -2261,6 +2277,7 @@ function runDebrief(args, eng) {
   const applyIdx = args.indexOf('--apply')
   const apply = applyIdx !== -1
   if (apply) args.splice(applyIdx, 1)
+  if (smart && apply) throw new Error('run --smart first, review the proposal, then confirm with --apply in a separate command')
   let force = false
   const forceIdx = args.indexOf('--force')
   if (forceIdx !== -1) { force = true; args.splice(forceIdx, 1) }
@@ -2819,7 +2836,7 @@ function silentCommitIssues(eng) {
     // Pickaxe on the entry text, not the file: a later status edit to
     // delivery.md must not become the cutoff and hide commits before it.
     const raw = entry.line
-      ? sh(`git log -1 --format=%cI -S${JSON.stringify(entry.line)} -- delivery.md`, eng)
+      ? gitLogHash(eng, ['-S', entry.line, '--', 'delivery.md'], '%cI')
       : ''
     // git --since is inclusive at second grain; a commit in the same second as
     // the receipt is the receipt's own work, not a silent one.
@@ -3355,10 +3372,10 @@ function cmdRedact(args) {
     })
   }
   if (!hits.length) {
-    console.log(`redact: no lines contain ${JSON.stringify(term)}`)
+    console.log(`redact: no lines contain ${JSON.stringify(masking.mask(term))}`)
     return
   }
-  console.log(`REDACT - ${hits.length} matching line(s) for ${JSON.stringify(term)}`)
+  console.log(`REDACT - ${hits.length} matching line(s) for ${JSON.stringify(masking.mask(term))}`)
   hits.slice(0, 20).forEach(h => {
     const preview = h.line.length > 100 ? masking.mask(h.line).slice(0, 97) + '…' : h.line
     console.log(`  ${h.file}:${h.lineNo}  ${preview}`)
@@ -3758,13 +3775,13 @@ function cmdDashboard(args) {
     ].map(([f, title]) => [title, readClean(e.dir, f)])
     .filter(([, md]) => render.hasRealContent(md))
     .map(([title, md]) => ({ title, html: render.mdBlockHtml(maskDisplay(md), parseMdTable) }))
-    e.searchBlob = render.escapeHtml([
+    e.searchBlob = render.escapeHtml(maskDisplay([
       e.name, e.next, e.lastSession, e.reality, e.brief,
       ...e.log.map(g => g.text), ...e.risks.map(r => r.text),
       ...e.stakeholders.map(p => `${p.name} ${p.role} ${p.note}`),
       ...e.moreSections.map(s => s.title),
       ...e.valueRows.map(r => `${r.slice} ${r.promised} ${r.measured} ${r.accepted} ${r.evidence}`),
-    ].join(' ').toLowerCase())
+    ].join(' ').toLowerCase()))
   })
 
   const html = render.buildFieldbookHtml({ engagements: maskReport(engagements), today, generatedAt: new Date().toISOString() })
@@ -4170,7 +4187,8 @@ let outputBudget
 if (['resume', 'recall', 'handoff', 'defend'].includes(cmd) && !rawArgs.some(a => ['--full', '--init', '--bind', '--out'].includes(a))) {
   try { outputBudget = context.budgetArgs(rawArgs, (setupStore.read() || setup.DEFAULTS).context === 'compact' ? 4096 : 16384).maxBytes } catch (_) {}
 }
-require('./lib/masking').protectOutput(masking, { maxBytes: outputBudget })
+require('./lib/masking').protectOutput(cmd === 'setup' && rawArgs.length === 1 && rawArgs[0] === '--show'
+  ? require('./lib/masking').createMasking(ENGAGEMENTS_ROOT, { custom: false }) : masking, { maxBytes: outputBudget })
 let args
 try {
   args = rawArgs.map(arg => masking.restore(arg))
@@ -4192,7 +4210,7 @@ switch (cmd) {
   case 'setup': finishAsync(setup.command(setupStore, args)); break
   case 'privacy':
     if (args.length) { console.error('usage: fde privacy'); process.exitCode = 2; break }
-    console.log(`FDEOps ${require('../package.json').version} - identifier masking enabled by default.\nCLI responses, smart proposals, handoff packets and ingest MCP results use local aliases.\nPatterns: common emails, international/US phones, SSN-shaped identifiers and supported credentials.\nNames and arbitrary sensitive prose are not detected; mark them <private>.\nRaw files, pasted chat and upstream MCP content bypass this protection. Local reports retain identifiers by default; fde setup can also mask newly generated report content.`)
+    console.log(`FDEOps ${require('../package.json').version} - identifier masking enabled by default.\nCLI responses, smart proposals, handoff packets and ingest MCP results use local aliases.\nPatterns: common emails, international/US phones, SSN-shaped identifiers and supported credentials.\nNames and arbitrary sensitive prose are not automatically detected; mark them <private> or supply local custom terms with fde setup.\nRaw files, pasted chat and upstream MCP content bypass this protection. Local reports retain identifiers by default; fde setup can also mask newly generated report content.`)
     break
   case 'demo': cmdDemo(args); break
   case 'scan': cmdScan(); break

package/bin/lib/context.js

@@ -37,6 +37,12 @@ function boundedSections(sections, maxBytes = DEFAULT_BYTES) {
     const available = maxBytes - Buffer.byteLength(out + footer) - 2
     const share = Math.max(0, Math.floor(available / (filled.length - i)))
     const text = filled[i]
+    // A truncation marker also consumes the budget. If the fair share cannot
+    // fit one, stop with one marker instead of overflowing for every section.
+    if (Buffer.byteLength(text) > share && share < Buffer.byteLength(OMITTED)) {
+      out += (out ? '\n\n' : '') + clipUtf8(text, Math.max(0, available - Buffer.byteLength(OMITTED))) + clipUtf8(OMITTED, Math.max(0, available))
+      break
+    }
     const next = Buffer.byteLength(text) <= share ? text : clipUtf8(text, Math.max(0, share - Buffer.byteLength(OMITTED))) + OMITTED
     out += (out ? '\n\n' : '') + next
   }

package/bin/lib/masking.js

@@ -6,7 +6,7 @@ const fs = require('node:fs')
 const path = require('node:path')
 const crypto = require('node:crypto')
 const { StringDecoder } = require('node:string_decoder')
-const ALIAS = /\[\[(email|phone|identifier|credential):[a-f0-9]{16}\]\]/g
+const ALIAS = /\[\[(email|phone|identifier|credential|term):[a-f0-9]{16}\]\]/g
 const PATTERNS = [
   ['credential', /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|$)/g],
   ['credential', /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g],
@@ -25,7 +25,27 @@ function replacements(text, replace) {
   for (const [kind, pattern] of PATTERNS) out = out.replace(pattern, value => replace(kind, value))
   return out
 }
-function createMasking(root) {
+function createMasking(root, { custom = true } = {}) {
+  const settings = require('./setup').createSetup(root)
+  function replaceAll(text, replace) {
+    let terms = []
+    if (custom) {
+      const profile = settings.read()
+      if (profile && profile.masking === 'custom') terms = profile.terms
+    }
+    const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const pattern = terms.length ? new RegExp(terms.slice().sort((a, b) => b.length - a.length).map(term =>
+      '(?<![\\p{L}\\p{N}_])' + escape(term) + '(?![\\p{L}\\p{N}_])').join('|'), 'giu') : null
+    // Existing aliases are protocol tokens, never input for further masking.
+    const pieces = String(text).split(/(\[\[(?:email|phone|identifier|credential|term):[a-f0-9]{16}\]\])/g)
+    return pieces.map((piece, i) => {
+      if (i % 2) return piece
+      const builtIn = replacements(piece, replace)
+      if (!pattern) return builtIn
+      return builtIn.split(/(\[\[(?:email|phone|identifier|credential|term):[a-f0-9]{16}\]\])/g)
+        .map((part, j) => j % 2 ? part : part.replace(pattern, value => replace('term', value))).join('')
+    }).join('')
+  }
   const directory = path.join(root, '.privacy'), file = path.join(directory, 'identifiers.json')
   function directoryReady(create) {
     if (create) fs.mkdirSync(root, { recursive: true })
@@ -43,7 +63,7 @@ function createMasking(root) {
       if (data.version !== 1 || !Array.isArray(data.entries) || data.entries.length > 50000) throw new Error(FAIL)
       const seen = new Set()
       for (const entry of data.entries) {
-        if (!entry || typeof entry.value !== 'string' || !/^\[\[(email|phone|identifier|credential):[a-f0-9]{16}\]\]$/.test(entry.alias) || seen.has(entry.alias)) throw new Error(FAIL)
+        if (!entry || typeof entry.value !== 'string' || !/^\[\[(email|phone|identifier|credential|term):[a-f0-9]{16}\]\]$/.test(entry.alias) || seen.has(entry.alias)) throw new Error(FAIL)
         seen.add(entry.alias)
       }
       return data
@@ -76,11 +96,11 @@ function createMasking(root) {
   function mask(text) {
     text = String(text)
     let detected = false
-    replacements(text, (_, value) => { detected = true; return value })
+    replaceAll(text, (_, value) => { detected = true; return value })
     if (!detected) return text
     return transact(true, entries => {
       const values = new Map(entries.map(e => [e.value, e.alias]))
-      return replacements(text, (kind, value) => {
+      return replaceAll(text, (kind, value) => {
         if (!values.has(value)) {
           const alias = `[[${kind}:${crypto.randomBytes(8).toString('hex')}]]`
           entries.push({ alias, value }); values.set(value, alias)
@@ -91,7 +111,7 @@ function createMasking(root) {
   }
   function restore(text) {
     text = String(text)
-    if (/\[\[(email|phone|identifier|credential):/.test(text.replace(ALIAS, ''))) throw new Error(FAIL)
+    if (/\[\[(email|phone|identifier|credential|term):/.test(text.replace(ALIAS, ''))) throw new Error(FAIL)
     if (!text.match(ALIAS)) return text
     return transact(false, entries => {
       const aliases = new Map(entries.map(e => [e.alias, e.value]))

package/bin/lib/memory.js

@@ -53,7 +53,7 @@ function createMemoryApi(deps) {
           execFileSync('git', ['add', '--', f], { cwd: eng, stdio: 'ignore', timeout: 10000 })
         }
       } else {
-        execFileSync('git', ['add', '-A', '--', '.', ':(exclude).privacy'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
+        execFileSync('git', ['add', '-A', '--', '.', ':(exclude).privacy', ':(exclude).preferences.json'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
       }
       const porcelain = execFileSync('git', ['status', '--porcelain'], {
         cwd: eng, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'],
@@ -73,7 +73,7 @@ function createMemoryApi(deps) {
         }
       }
       // Even a previously staged alias dictionary must never enter a CLI commit.
-      const privateStaged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: eng, encoding: 'utf8', timeout: 10000 }).split('\n').some(f => f.split('/').includes('.privacy'))
+      const privateStaged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: eng, encoding: 'utf8', timeout: 10000 }).split('\n').some(f => f.split('/').some(part => ['.privacy', '.preferences.json'].includes(part)))
       if (privateStaged) throw new Error('private alias state must not be staged in engagement history')
       const still = execFileSync('git', ['diff', '--cached', '--name-only'], {
         cwd: eng, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'],
@@ -134,7 +134,7 @@ function createMemoryApi(deps) {
       execFileSync('git', ['init'], { cwd: eng, stdio: 'ignore', timeout: 10000 })
       atomicWriteFile(
         path.join(eng, '.gitignore'),
-        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal', '.privacy/', ''].join('\n')
+        ['*.lock', '*.tmp', '.last-write', '.debrief-propose', '.debrief-private', '.debrief-seal', '.privacy/', '.preferences.json', ''].join('\n')
       )
       const owner = writeOwnerIfMissing(eng)
       configureMemoryGitIdentity(eng, owner)

package/bin/lib/setup.js

@@ -5,7 +5,7 @@ const crypto = require('node:crypto')
 const paths = require('./install-paths')
 
 const DEFAULTS = { view: 'current', context: 'standard', privacy: 'agent' }
-const QUESTIONS = [
+const SETTINGS = [
   { key: 'view', title: 'What should your daily overview show?', options: [
     ['current', 'The client I am working on'], ['portfolio', 'All my clients'],
   ] },
@@ -17,14 +17,60 @@ const QUESTIONS = [
     ['reports', 'Agent context and newly generated Fieldbook/vault reports'],
   ] },
 ]
-const LIMITS = 'Both options hide <private> content. Masking covers common identifier formats, not all personal data. Names and sensitive prose need private marking. Your AI host controls provider transmission; setup does not change it. Existing exports are not rewritten.'
+const QUESTIONS = [
+  { key: 'work', title: 'How do you work?', options: [
+    ['single', 'One client'], ['multiple', 'Several clients'], ['team', 'Leading a delivery team'],
+  ] },
+  { key: 'start', title: 'What would help you first?', options: [
+    ['new', 'Starting an engagement'], ['daily', 'Continuing daily work'], ['takeover', 'Taking over existing work'],
+  ] },
+  { key: 'masking', title: 'What should FDEOps hide before sharing context with your agent?', options: [
+    ['standard', 'Common identifiers and secrets'], ['custom', 'Those, plus names and terms I specify'],
+  ] },
+]
+const PROFILE_DEFAULTS = { work: 'single', start: 'daily', masking: 'standard', terms: [] }
+const LIMITS = 'Both choices hide marked private content. Masking reduces exposure; it does not guarantee anonymity or permission to share client data. Raw file tools, pasted chat and other tools can bypass it. AI-provider settings are unchanged.'
+function validateTerms(terms) {
+  if (!Array.isArray(terms) || terms.length > 100 || terms.some(t => typeof t !== 'string' || t.length < 2 || t.length > 128 || t !== t.trim() || /[\r\n\x00-\x1f]|\[\[|\]\]/.test(t))) {
+    throw new Error('Use up to 100 names or terms, one per line, each 2-128 characters; control characters and alias markers are not allowed.')
+  }
+  return [...new Set(terms)]
+}
 function validate(value) {
+  const keys = value && Object.keys(value)
+  const personal = value && Object.hasOwn(value, 'work')
   if (!value || typeof value !== 'object' || Array.isArray(value) ||
-      Object.keys(value).length !== 3 || QUESTIONS.some(q => !q.options.some(([v]) => value[q.key] === v))) {
+      keys.length !== (personal ? 7 : 3) ||
+      (personal ? SETTINGS.concat(QUESTIONS) : SETTINGS).some(q => !q.options.some(([v]) => value[q.key] === v))) {
     throw new Error('Invalid setup choices; run fde setup to see the supported options.')
   }
+  if (personal) {
+    validateTerms(value.terms)
+    if (value.masking === 'custom' && !value.terms.length) throw new Error('Custom masking needs at least one name or term.')
+  }
   return value
 }
+function readTerms(file) {
+  let fd
+  try {
+    paths.checkPath(file)
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+    const st = fs.fstatSync(fd)
+    if (!st.isFile() || st.nlink !== 1 || st.size > 65536) throw new Error('unsafe')
+    const terms = validateTerms(fs.readFileSync(fd, 'utf8').split(/\r?\n/).map(t => t.trim()).filter(Boolean))
+    if (!terms.length) throw new Error('empty')
+    return terms
+  } catch (_) { throw new Error('Cannot load custom terms. Use an ordinary local UTF-8 file with 1-100 terms, one per line, each 2-128 characters.') }
+  finally { if (fd !== undefined) fs.closeSync(fd) }
+}
+function nextStep(value) {
+  const start = {
+    new: 'Clarify the client problem, one measurable outcome, and who will accept it. Start with land.',
+    daily: 'Resume the current client and choose one action from the existing blockers. Start with triage.',
+    takeover: 'Check the existing evidence, open risks and previous commitments before changing anything. Start with audit.',
+  }
+  return (start[value.start] || '') + (value.work === 'team' ? ' Make responsibility and handoff clear; do not assume shared access or synchronization.' : '')
+}
 function createSetup(root) {
   const file = path.join(root, '.preferences.json')
   function read() {
@@ -33,7 +79,7 @@ function createSetup(root) {
       paths.checkPath(file)
       fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
       const st = fs.fstatSync(fd)
-      if (!st.isFile() || st.nlink !== 1 || st.size > 4096) throw new Error('unsafe')
+      if (!st.isFile() || st.nlink !== 1 || st.size > 65536 || (process.platform !== 'win32' && (st.mode & 0o077))) throw new Error('unsafe')
       return validate(JSON.parse(fs.readFileSync(fd, 'utf8')))
     } catch (e) {
       if (e.code === 'ENOENT') return null
@@ -53,57 +99,93 @@ function createSetup(root) {
   }
   return { read, save }
 }
-function describe(value) {
-  return QUESTIONS.map(q => `${q.title} ${q.options.find(([v]) => v === value[q.key])[1]}`).join('\n')
+function describe(value, questions = QUESTIONS) {
+  return questions.map(q => `${q.title} ${q.options.find(([v]) => v === value[q.key])[1]}`).join('\n')
+}
+function saveAnswers(store, choices, questions, termsFile) {
+  const saved = store.read(), current = saved || DEFAULTS
+  if (questions.some(q => !q.options.some(([v]) => choices[q.key] === v)) || Object.keys(choices).length !== questions.length) throw new Error('Supply one valid answer for each question.')
+  let result
+  if (questions === SETTINGS) result = { ...current, ...choices }
+  else {
+    if (termsFile && choices.masking !== 'custom') throw new Error('A terms file requires custom masking.')
+    const terms = termsFile ? readTerms(termsFile) : current.terms || []
+    result = { ...current, ...choices, terms, view: !saved || (saved.work && saved.work !== choices.work) ? (choices.work === 'multiple' ? 'portfolio' : 'current') : saved.view }
+  }
+  store.save(result)
+  return result
 }
 function command(store, args) {
   if (args.length === 1 && args[0] === '--show') {
-    const saved = store.read()
-    console.log(JSON.stringify({ configured: !!saved, ...(saved || DEFAULTS) }))
+    const saved = store.read(), { terms, ...safe } = saved || DEFAULTS
+    console.log(JSON.stringify({ configured: !!saved, ...safe, ...(terms ? { termCount: terms.length, nextStep: nextStep(saved) } : {}) }))
     return
   }
-  if (args.length) {
-    const choices = {}
-    if (!args.includes('--save') || args.filter(a => a === '--save').length !== 1) throw new Error('Use fde setup, or supply all three choices with --save.')
-    const rest = args.filter(a => a !== '--save')
+  if (args.length && !(args.length === 1 && args[0] === '--settings')) {
+    const choices = {}, rest = args.filter(a => a !== '--save')
+    let termsFile
+    if (args.filter(a => a === '--save').length !== 1) throw new Error('Use fde setup, or supply all three answers with --save.')
     for (let i = 0; i < rest.length; i += 2) {
       const key = rest[i].replace(/^--/, '')
-      if (!rest[i].startsWith('--') || !Object.hasOwn(DEFAULTS, key) || Object.hasOwn(choices, key)) throw new Error('Unknown or repeated setup option.')
+      if (key === 'terms-file' && !termsFile && rest[i + 1]) { termsFile = rest[i + 1]; continue }
+      if (!rest[i].startsWith('--') || !SETTINGS.concat(QUESTIONS).some(q => q.key === key) || Object.hasOwn(choices, key)) throw new Error('Unknown or repeated setup option.')
       choices[key] = rest[i + 1]
     }
-    validate(choices)
-    store.save(choices)
-    console.log('Setup saved for this engagements folder. Change it anytime with fde setup.\n' + describe(choices) + '\n' + LIMITS)
+    const questions = Object.hasOwn(choices, 'work') ? QUESTIONS : SETTINGS
+    if (termsFile && questions === SETTINGS) throw new Error('Use personal setup to change custom terms.')
+    const result = saveAnswers(store, choices, questions, termsFile)
+    console.log('Setup saved locally. Change it anytime with fde setup.\n' + describe(result, questions) + '\n' + nextStep(result) + '\n' + LIMITS)
     return
   }
-  if (process.stdin.isTTY && process.stdout.isTTY) return interactive(store)
-  console.log('FIRST-USE SETUP: ask these three questions together, then save the answers. No settings have been changed.')
-  for (const [i, q] of QUESTIONS.entries()) console.log(`${i + 1}. ${q.title}\n` + q.options.map(([value, label]) => `   ${value}: ${label}`).join('\n'))
-  console.log(LIMITS + '\nAfter the user answers: fde setup --view current|portfolio --context standard|compact --privacy agent|reports --save\nUse fde setup --show to inspect existing choices. Never infer client policy from these preferences.')
+  const questions = args[0] === '--settings' ? SETTINGS : QUESTIONS
+  if (process.stdin.isTTY && process.stdout.isTTY) return interactive(store, questions)
+  console.log('SETUP: ask these three questions together. No settings have been changed.')
+  for (const [i, q] of questions.entries()) console.log(`${i + 1}. ${q.title}\n` + q.options.map(([value, label]) => `   ${value}: ${label}`).join('\n'))
+  console.log(LIMITS)
+  console.log(questions === QUESTIONS
+    ? 'After answers: fde setup --work single|multiple|team --start new|daily|takeover --masking standard|custom [--terms-file LOCAL_FILE] --save\nFor custom masking, enter names locally with fde setup, or provide a local terms-file path; do not ask to paste sensitive names into chat. Existing terms are kept unless a replacement file is supplied.'
+    : 'Save settings: fde setup --view current|portfolio --context standard|compact --privacy agent|reports --save')
+  console.log('fde setup --show shows choices and term count only. fde setup --settings changes display and context options.')
 }
-async function interactive(store) {
-  // Only static prompts and validated enum labels bypass buffered CLI output.
+async function interactive(store, questions) {
   const emit = text => fs.writeSync(1, text)
+  const current = { ...PROFILE_DEFAULTS, ...(store.read() || DEFAULTS) }, choices = {}
   const rl = require('node:readline').createInterface({ input: process.stdin, terminal: false })
   const lines = rl[Symbol.asyncIterator]()
-  const current = store.read() || DEFAULTS, choices = {}
   try {
-    emit('Make FDEOps fit your day. Three choices; Enter keeps the current choice. Ctrl-C cancels.\n' + LIMITS + '\n')
-    for (const q of QUESTIONS) {
+    emit('Make FDEOps fit your work. Enter keeps the current choice. Ctrl-C cancels.\n' + LIMITS + '\n')
+    for (const q of questions) {
       const selected = q.options.findIndex(([v]) => v === current[q.key])
       while (true) {
         emit(q.title + '\n' + q.options.map(([, label], i) => `  ${i + 1}. ${label}${i === selected ? ' (current)' : ''}`).join('\n') + '\n> ')
         const next = await lines.next()
-        if (next.done) { emit('\nSetup cancelled; nothing saved.\n'); return }
-        const value = next.value.trim(), index = value === '' ? selected : /^[12]$/.test(value) ? Number(value) - 1 : -1
-        if (index >= 0) { choices[q.key] = q.options[index][0]; break }
-        emit('Choose 1 or 2, or press Enter.\n')
+        if (next.done) { emit('\nCancelled; nothing saved.\n'); return }
+        const value = next.value.trim(), index = value === '' ? selected : /^[123]$/.test(value) ? Number(value) - 1 : -1
+        if (index >= 0 && index < q.options.length) { choices[q.key] = q.options[index][0]; break }
+        emit('Choose a listed number, or press Enter.\n')
       }
     }
-    emit('\n' + describe(choices) + '\nSave these settings? [y/N] ')
+    let terms = current.terms
+    if (choices.masking === 'custom') {
+      emit(`Names or terms to hide, one per line; finish with an empty line. Enter alone keeps ${terms.length} saved terms. This input stays local.\n`)
+      const entered = []
+      while (true) {
+        const next = await lines.next()
+        if (next.done) { emit('\nCancelled; nothing saved.\n'); return }
+        if (!next.value.trim()) break
+        entered.push(next.value.trim())
+        validateTerms(entered)
+      }
+      terms = entered.length ? validateTerms(entered) : terms
+      if (!terms.length) throw new Error('Custom masking needs at least one term; nothing saved.')
+    }
+    const saved = store.read()
+    const result = questions === SETTINGS ? { ...(saved || DEFAULTS), ...choices }
+      : { ...(saved || DEFAULTS), ...choices, terms, view: !saved || (saved.work && saved.work !== choices.work) ? (choices.work === 'multiple' ? 'portfolio' : 'current') : saved.view }
+    emit('\n' + describe(result, questions) + (choices.masking === 'custom' ? `\n${terms.length} custom terms ready to save locally.` : '') + '\nSave these choices? [y/N] ')
     const next = await lines.next()
-    if (!next.done && /^y(es)?$/i.test(next.value.trim())) { store.save(choices); emit('\nSetup saved. Change it anytime with fde setup.\n') }
-    else emit('\nSetup cancelled; nothing saved.\n')
+    if (!next.done && /^y(es)?$/i.test(next.value.trim())) { store.save(result); emit('\nSetup saved. Change it anytime with fde setup.\n' + nextStep(result) + '\n') }
+    else emit('\nCancelled; nothing saved.\n')
   } finally { rl.close() }
 }
-module.exports = { createSetup, command, DEFAULTS }
+module.exports = { createSetup, command, DEFAULTS, nextStep }

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "3.30.0",
+  "version": "4.0.0",
   "private": true,
   "description": "Thin stdio MCP sink for FDEOps ingest (stage → propose → apply). Zero runtime dependencies.",
   "bin": {

package/mcp/fdeops-ingest/server.js

@@ -176,7 +176,13 @@ function cliPayload(out) {
 
 function toolResult(payload) {
   let text
-  try { text = masking.mask(typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2)) }
+  try {
+    const clean = value => typeof value === 'string' ? masking.mask(value)
+      : Array.isArray(value) ? value.map(clean)
+      : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clean(item)])) : value
+    const safe = clean(payload)
+    text = typeof safe === 'string' ? safe : JSON.stringify(safe, null, 2)
+  }
   catch (_) { return { isError: true, content: [{ type: 'text', text: 'privacy masking unavailable; no unmasked tool output returned' }] } }
   return { content: [{ type: 'text', text }] }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.30.0",
+  "version": "4.0.0",
   "description": "Client delivery tools for Forward Deployed Engineers. One @fde skill, local Markdown engagement records, and an offline dashboard for decisions, evidence, approvals, and next actions.",
   "bin": {
     "fdeops": "bin/install.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "3.30.0",
+  "version": "4.0.0",
   "description": "Forward deployed engineering skills for AI coding agents. One @fde skill for the client work around the code. You confirm; then it lands in .fde/ on your laptop.",
   "author": {
     "name": "Subash Natarajan",

package/skills/fde/SKILL.md

@@ -36,13 +36,13 @@ On someone else's site the work is not "write code, remember later." Every chang
 
 1. **Name it** in `decisions.md` (plan), or timebox the riskiest assumption and record what the POC proves.
 2. **Characterise their code** before you change it. Brownfield: their tests, their runner. Greenfield: the empty tree, first path they can click.
-3. **Prove it on their staging.** Staging they operate, a screen the signer in `success.md` can reject.
+3. **Verify, then prove delivery.** Use their checks and the agreed representative environment; at the delivery checkpoint the signer in `success.md` can replay and reject the acceptance check. See `ship` for evidence requirements.
 4. **If a model judges:** `evals.md` Verdict SHIP before that change is done (eval-pack).
-5. **Log delivery.** Outcome is promised → measured → accepted, not a green CI. Then go live with a rollback you have run (`ship`).
+5. **Log delivery.** Outcome is promised → measured → accepted, not a green CI. Then go live with a tested recovery path (`ship`).
 
-A throwaway file can skip the loop. Bound client work cannot.
+Scale the loop to the change. A routine, reversible fix within confirmed scope reuses the existing outcome, signer, acceptance criteria, and engineering plan; batch its verification into a concise delivery receipt. It does not need a new sponsor decision or staging ceremony per edit. New outcomes, changed acceptance or authority, and production release decisions still need the relevant confirmation and evidence. This does not bypass confirmation for judgment written into the engagement record.
 
-**Skip is loud.** Bound + a change that will ship + no this-turn line in `delivery.md` = not done. Say that. Do not call it shipped. A coding pack may write the function; `@fde` still owns done.
+**Status is explicit.** Record what is implemented, verified, deployed, and accepted separately. A routine fix may be implementation-complete before release or customer acceptance; state what remains and attach the current verification receipt. A coding pack may write the function; `@fde` owns the engagement evidence.
 
 ## Working with an engineering pack
 
@@ -58,7 +58,9 @@ Fallbacks: `node ~/.claude/fdeops/fde.js …`, then `npx --yes fdeops …`. Skil
 
 ## First-use preferences
 
-Run `fde setup --show` before client reads. If unavailable, update the CLI before offering setup; never pretend preferences were saved. If `configured` is false, finish binding the named client, then run `fde setup` and present its **three questions together**, with the two choices each. Use answers already given; do not invent preferences or ask again per client. Save their selections using the displayed `--save` command; their answers authorize this settings write only. If they skip, continue with existing defaults and leave setup unsaved. On later sessions use saved choices; change them only when requested. Setup configures report scope, initial context size and masking of newly generated reports. It does not install a model, approve client data for AI, or change provider settings. Client policy always takes precedence. Reports can still contain names or other unrecognized sensitive prose; never treat them as anonymized.
+Run `fde setup --show` before client reads. If unavailable, update the CLI before offering setup. If `configured` is false, bind the named client, then run `fde setup` and present its three questions together: how they work, what would help first, and what to mask. Save their explicit answers; never infer permission to share data. For custom masking, the optional fourth question asks them to enter terms **locally** with `fde setup`, or give a local terms-file path. Do not ask them to paste sensitive names into chat or open that file with model-facing file tools. Pass the path directly to `--terms-file`; inspect only the returned count, never `.preferences.json` or the alias dictionary. If they skip, keep existing defaults.
+
+Use `work` to tailor the help: single = focus on the bound client; multiple = portfolio overview with one bound client per write; team = clarify responsibility and handoff, without implying shared storage. `start` chooses the initial route when no more specific request or record determines it: new → land, daily → triage, takeover → audit. Current client evidence and the user's request always take precedence; never restart an existing engagement because of this preference. `masking` selects standard patterns or those plus custom terms. Older technical settings remain valid; offer personal setup when requested rather than resetting them. Do not ask again per client. `fde setup --settings` keeps display, context size and report masking editable. Choices do not configure models or approve client data use.
 
 ## Entry (every session)
 
@@ -207,8 +209,8 @@ Ready to build with no `terrain.md` / plan: discover or plan first. Takeover wit
 
 - Never ask the FDE to pick a phase. That's your job.
 - Same six stages at any scale. Overlays carry the industry. Greenfield and brownfield change the first move inside ship, not the map.
-- Ground loop on a bound client: name → characterise → prove on their staging → go live → log. A coding pack may write the function. `@fde` still owns done. When they disagree, their repo and the signer win.
-- Do not call a change done until the signer in `success.md` can reject it on staging they operate. No this-turn receipt in `delivery.md` is a failed test, not a note to write later.
+- Ground loop on a bound client: name → characterise → verify in the agreed environment → authorize release → log. A coding pack may write the function. `@fde` still owns done. When they disagree, their repo and the signer win.
+- Customer delivery needs a replayable acceptance check in the agreed environment; reuse existing criteria for routine fixes. Missing evidence means unproven, not an observed test failure. Never equate implementation-complete with deployed or customer-accepted.
 - Read `context.md` before speaking. One sharp question - never a barrage.
 - Never invent people, meetings, or numbers - `unknown - ask:` beats a polished lie.
 - Every phase ends with its artifact written. No artifact, no "done."
@@ -218,4 +220,4 @@ Ready to build with no `terrain.md` / plan: discover or plan first. Takeover wit
 
 ## Identifier masking
 
-Before reading engagement content in a session, run `fde privacy` to verify runtime support. If the command is unavailable, stop and update the CLI; a new skill alone does not upgrade an older executable. Use CLI context and previews for model input. They mask common email, phone, SSN-shaped, and credential patterns by default; aliases remain consistent within the local engagements root. Preserve complete alias tokens when drafting updates; the CLI resolves them locally. Never read the private `.privacy/` dictionary, sealed sidecars, raw sensitive notes, or local dashboard/vault files to recover an identity. Names, company names, addresses, and unrecognized formats are not automatically detected: keep sensitive prose in `<private>` blocks. Direct file tools, pasted chat, and upstream source MCPs bypass this boundary.
+Before reading engagement content in a session, run `fde privacy` to verify runtime support. If the command is unavailable, stop and update the CLI; a new skill alone does not upgrade an older executable. Use CLI context and previews for model input. They mask common email, phone, SSN-shaped, and credential patterns by default; aliases remain consistent within the local engagements root. Preserve complete alias tokens when drafting updates; the CLI resolves them locally. Never read the private `.privacy/` dictionary, sealed sidecars, raw sensitive notes, or local dashboard/vault files to recover an identity. Custom masking additionally hides the literal names or terms the user supplied locally, ignoring letter case and matching whole terms. It does not infer variants or discover names. Names, company names, addresses, and unrecognized formats are otherwise not automatically detected: keep sensitive prose in `<private>` blocks. Direct file tools, pasted chat, and upstream source MCPs bypass this boundary.

package/skills/fde/references/ai.md

@@ -20,19 +20,19 @@ Record in `trust-profile.md` under `## AI policy`.
 
 ## Model selection - choosing the right tool
 
-Never start with the most powerful model. Start with the cheapest that meets the quality bar.
+Compare plausible approaches against the task’s quality, latency, privacy, and operating constraints. Optimize total cost per successful outcome, including retries, review, failures, and maintenance; call price alone can select the more expensive system.
 
-**The evaluation ladder:**
-1. **Can rules solve it?** If yes, no model needed. Rules are debuggable, testable, and free.
-2. **Can a small/fast model solve it?** (GPT-4o-mini, Claude Haiku, local models) - try this first. Cheaper, faster, easier to self-host.
-3. **Does it need a frontier model?** (GPT-4o, Claude Sonnet/Opus, Gemini Pro) - only when the quality gap is measurable and justified.
-4. **Does it need fine-tuning?** Only when: you have 500+ high-quality examples, the base model fails consistently on your domain, and the cost of inference at scale justifies the training cost.
+**Candidate approaches (test the plausible ones, not a mandatory ladder):**
+1. **Can rules solve it?** If yes, no model needed. Include their implementation and maintenance cost.
+2. **Can a small/fast model solve it?** Include one when suitable for the task and hosting constraints; measure quality and total cost.
+3. **Would a more capable model improve the outcome?** It may reduce retries, supervision, or implementation complexity enough to justify its price. Verify current model availability and capabilities in official documentation.
+4. **Does it need fine-tuning?** Consider it when representative data and a held-out evaluation support a persistent domain gap. Compare against prompt/retrieval changes; justify dataset coverage and training, serving, and maintenance costs rather than assuming a fixed example count suffices.
 
 **Evaluation method (before choosing):**
-- Build a test set: 50-100 representative inputs with expected outputs.
-- Run every candidate model against the test set.
-- Score: accuracy, latency, cost per call, failure modes.
-- The cheapest model that scores above the quality threshold wins.
+- Build a representative test set with expected outcomes and critical failure cases. Size it to diversity, consequence, and uncertainty; a small pilot set cannot establish rare-failure safety.
+- Run a bounded shortlist against the same held-out cases; record model/version and settings.
+- Score: task success, critical failures, latency, total cost per successful outcome, and failure modes, including repeated runs when variability matters.
+- Select the approach that meets the agreed constraints with the best measured tradeoff. Record uncertainty and what would trigger re-evaluation.
 
 Write model selection rationale to `decisions.md`. Include: models tested, test set size, scores, cost comparison.
 
@@ -42,7 +42,7 @@ When any slice touches a model, embeddings, RAG, or an agent: create or update `
 
 **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).
+2. **Golden cases** - representative inputs with expected outputs and a pass rule. 5-20 can seed a pilot, not certify readiness; expand for risk and coverage. 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.
@@ -59,9 +59,9 @@ When the AI needs to answer questions about the client's data:
 3. **Generate** - chunks + query → LLM → answer with citations
 
 **Common failure modes:**
-- **Chunk size wrong.** Too small = lost context. Too large = noise drowns signal. Start at 500-1000 tokens with 100-token overlap.
+- **Chunk size wrong.** Too small = lost context. Too large = noise drowns signal. Choose boundaries from document structure and answer needs; tune size, overlap, and top-K against retrieval and answer-quality evals, latency, and context limits.
 - **No citation/grounding.** If the model can't point to where it found the answer, you can't verify it. Always require source attribution.
-- **Stale index.** Documents update, embeddings don't. Define the refresh cadence. Real-time for critical data, daily for reference docs.
+- **Stale index.** Documents update, embeddings don't. Define refresh and deletion handling from source update patterns and acceptable staleness; test them.
 - **Retrieval miss.** The right document exists but wasn't retrieved. Test with known-answer queries where the answer IS in the corpus - if retrieval misses these, the embedding model or chunking strategy needs work.
 
 ## Agent and agentic systems
@@ -71,23 +71,23 @@ When the AI takes actions (not just generates text):
 **Safety principles:**
 - **Least privilege.** An agent gets the minimum permissions needed. Never give an agent admin access "for convenience."
 - **Confirmation gates.** Any destructive or irreversible action requires human confirmation. Delete, send, transfer, publish = confirm before execute.
-- **Observability of reasoning.** Log the agent's chain of thought, tool calls, and decisions. When it does something wrong, you need to see why.
+- **Observable execution.** Record tool/action summaries, versions, timing, cost, outcomes, validation results, and concise decision rationale. Do not request or store hidden chain-of-thought. Minimize and redact logged inputs/outputs; apply the client’s access, retention, and data policies. Never log raw `<private>` content or secrets.
 - **Deterministic fallbacks.** When the agent fails or is uncertain, it falls back to a known-safe behavior (queue for human review, return a safe default, do nothing). "The agent got confused and did something unexpected" is never acceptable in production.
-- **Cost caps.** Agents in loops can burn through API budgets. Hard-cap per request, per user, per hour. Alert at 50% of cap.
+- **Cost caps.** Agents in loops can burn through API budgets. Set request and aggregate budgets with bounded retries and stopping conditions. Choose alert thresholds early enough for the owner to act.
 
 ## AI governance - responsible deployment
 
 **Before production:**
-- **Bias testing.** Run the model on demographic-varied inputs. If outputs differ by protected characteristic, it doesn't ship.
+- **Bias testing.** Run the model on demographic-varied inputs. Define relevant groups, harms, and acceptable disparity with the responsible owner; investigate material differences and block unresolved critical harm. Aggregate accuracy alone is insufficient.
 - **Explainability.** Can you explain to a non-technical stakeholder why the model made a specific decision? If not, it's a black box - some jurisdictions and industries prohibit this.
 - **Model card.** Document: what the model does, what data it was trained/tuned on, known limitations, failure modes, who owns it. One page. Required before production.
 - **Kill switch.** Every AI component must be disable-able without taking down the feature it powers. The fallback path (rule-based, human-routed, or gracefully degraded) must work when the AI is off.
 
 **In production:**
-- **Drift monitoring.** Compare production outputs weekly against the baseline quality. Models don't break - they slowly get worse as the world changes around them.
+- **Drift monitoring.** Compare production outputs against baseline quality on a cadence matched to traffic, drift risk, and impact. Quality can deteriorate gradually or fail abruptly after model, data, tool, or policy changes; monitor both patterns.
 - **Feedback collection.** Thumbs up/down, corrections, escalations. This is your retraining signal AND your quality metric.
 - **Cost monitoring.** Track: tokens consumed, calls made, cost per user, cost per feature. AI costs surprise everyone at scale.
-- **Incident response.** When the AI produces harmful/wrong output: disable (kill switch), investigate (logged reasoning), fix (prompt/model/data), restore. Define this BEFORE it happens.
+- **Incident response.** When the AI produces harmful/wrong output: disable (kill switch), investigate (sanitized execution traces and observed outcomes), fix (prompt/model/data), restore. Define this BEFORE it happens.
 
 ## Writes
 
@@ -96,10 +96,10 @@ When the AI takes actions (not just generates text):
 ## Principles
 
 - AI degrades silently. Monitor outputs, not just uptime.
-- Start with the cheapest model that meets the quality bar.
+- Choose by measured quality and total cost per successful outcome, within policy and latency constraints.
 - 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.
+- Debug from privacy-safe observable execution and concise rationale, never hidden chain-of-thought.
 - Drift is inevitable. Define the detection method before shipping.
 - Cost at scale ≠ cost at pilot. Model the 10× number before committing.
 - Bias testing is a pre-production gate, not a post-launch audit.

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

@@ -14,13 +14,13 @@ Intelligence without evidence is token-maxing with a nicer name. An FDE earns tr
 
 **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:
+**2. Build a golden set sized to risk and coverage.** A pilot may start with 5-20 cases; neither that range nor 50-100 proves broad-scale safety. Include representative segments, boundary cases, and known critical failures. Expand based on observed failure modes and uncertainty; hold out cases from tuning and repeat runs when variability matters. 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).
+**3. Score pass/fail, not vibes.** Define the quality threshold and critical failure rules before running the suite. Run it; record count pass / fail, segment coverage, and limitations. 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. Judgement that has a side effect (write, send, transfer, ticket, deploy, pay, page) is **NO-SHIP** without a named human on their side in the loop. Do not write "none - allowed under policy" to bless lights-out write-access. Staging may run a supervised loop with a kill switch, a cost cap, and a golden set from **their** failures. Production stays gated until they have a written policy, a named owner, and dated eval receipts on real traffic.
 

package/skills/fde/references/plan.md

@@ -4,7 +4,7 @@
 
 **Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if poc produced one. Not the full folder.
 
-**Before committing a plan or building:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint.
+**Before a new delivery plan or material scope change:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
 
 ## Validation gate (confirm understanding, clarify where it elevates)
 
@@ -34,7 +34,7 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 
 **3. One user action per change.** Each task delivers something visible and testable ("user submits form, sees it saved"), never a layer ("build the database layer"). See `ship`.
 
-**4. Size to 30-90 minutes, PR-sized.** Longer = two tasks. Each task implementable, testable, reviewable without a thousand-line diff.
+**4. Size to a coherent, verifiable outcome.** Split unrelated work and tasks too complex to review or recover safely. Use bounded review sections for large cohesive changes; elapsed time and line count are signals to examine, not universal limits.
 
 **5. AI components get explicit eval tasks.** "Output validated on 50 real production examples," "fallback tested under model unavailability," "inputs/outputs logging to <destination>" - these are pre-conditions of shipping, in the plan before build starts.
 

package/skills/fde/references/review.md

@@ -8,7 +8,7 @@ Engagement review ≠ product-company review: a codebase you don't own, systems
 
 ## Pre-flight: is this reviewable?
 
-Thousands of lines or dozens of unrelated files → **stop**, recommend the split in `decisions.md`, route to plan. Review loops fail on huge diffs. Ask: one agreed task, or did scope merge mid-build?
+Check whether the diff has one agreed intent and can be reviewed with the available evidence. Split unrelated work; for a large cohesive change, separate generated/mechanical output from behavioral changes and review in bounded sections. Size is a warning to investigate, not a universal stop threshold.
 
 ## Stage 1 - did we build what we agreed? (you do this work)
 
@@ -43,19 +43,19 @@ Five dimensions, line-specific ("line 47 fails under concurrent writes - no lock
 - **Correctness** - does what it says; edge cases; error paths traced.
 - **Blast radius** - what breaks at 2am; downstream systems; failure mode loud (errors surface) or silent (data corrupts over time)?
 - **Security** - input validation at boundaries; no secrets in logs; no new attack surface; `trust-profile.md` sensitivity classes respected.
-- **Rollback** - revertible in under 5 minutes, documented? "We'd need a data migration to roll back" is a blocker.
-- **AI policy & components** - human-review requirements honoured; model output treated as untrusted until validated; fallback exists; inputs/outputs logged; outputs bounded so a hallucination can't cascade; in regulated environments a human can explain why the AI decided X (compliance requirement, not preference).
+- **Recovery** - can the documented, tested rollback or recovery path meet the agreed recovery-time and data-loss limits? For irreversible changes, require explicit authority, compatibility checks, and a tested restore/compensation or roll-forward plan; a code revert alone is not proof.
+- **AI policy & components** - human-review requirements honoured; model output treated as untrusted until validated; fallback exists; privacy-safe execution evidence retained under the client’s data policy (no secrets, raw private data, or hidden chain-of-thought); outputs bounded so a hallucination can't cascade; check applicable explanation and human-review requirements with the client’s responsible owner; provide source evidence and concise rationale without claiming access to hidden reasoning.
 
-**Structural pass on AI-heavy or data-touching changes:** migrations reversible · destructive SQL guarded · PII/PCI/PHI paths match `trust-profile.md` · side effects (flags, webhooks, emails, jobs) fire only when intended · magic strings that break on rename · new behaviour has a test or an explicit reason it can't yet. One line problem, one line fix.
+**Structural pass on AI-heavy or data-touching changes:** migration compatibility and tested recovery · destructive SQL guarded · PII/PCI/PHI paths match `trust-profile.md` · side effects (flags, webhooks, emails, jobs) fire only when intended · magic strings that break on rename · new behaviour has a test or an explicit reason it can't yet. One line problem, one line fix.
 
 ## The review-fix loop (until clean)
 
 1. Read the full diff before commenting.
 2. Verdicts: **Stage 1: Pass / Blocked (reason)** · **Stage 2: Pass / Concerns (line-specific)**.
-3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why. Their comments are to check, not to obey. Restate each against the one-line intent and `trust-profile.md`. One item unclear → ask before changing any of them. If it breaks a signed constraint, a sacred system, or nothing calls it: one-sentence pushback, then wait.
+3. Fix only **real** findings tied to this change - no drive-by refactors. Reject false positives with one sentence why. Their comments are to check, not to obey. Restate each against the one-line intent and `trust-profile.md`. An unclear item waits for clarification; continue independent, understood fixes. If it breaks a signed constraint, a sacred system, or nothing calls it: one-sentence pushback, then wait.
 4. Add or update a test per bug found where possible.
 5. Re-run tests/typechecks - state what ran.
-6. Re-review. Repeat until Pass/Pass or a human must decide scope/product.
+6. Re-review. If two repair/review cycles do not converge, reassess the evidence and approach; continue independent fixes and escalate concrete scope/product decisions.
 
 ## Before the PR - thinking for the next reader
 
@@ -72,6 +72,6 @@ Code alone loses the "why." Before you call the change reviewable, run the **ses
 - Stage 1 before Stage 2. Wrong scope reviewed well is still wrong scope.
 - KEEP / JUSTIFY / SPLIT / DROP - every path gets a verdict; silent extras fail Stage 1.
 - Specific or silent - vague concerns waste everyone's time.
-- No rollback path = first finding.
+- No viable tested recovery path = a release blocker.
 - 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/rollback.md

@@ -13,7 +13,7 @@
 | Change type | Rollback method | Complication | Test |
 |-------------|----------------|--------------|------|
 | **Code deploy** | Revert the PR / redeploy previous version | Feature flags, cache invalidation | Deploy previous version to staging, verify function |
-| **Database migration** | Down migration script | Irreversible migrations (column drops, data transforms) | Run down migration on staging copy |
+| **Database migration** | Compatible rollback, restore, or roll-forward | Irreversible transforms, concurrent writes, old/new schema compatibility | Rehearse on representative staging data; verify integrity, elapsed time, and possible data loss |
 | **Config change** | Restore previous config | Propagation delay, dependent service restarts | Flip config, verify all services pick it up |
 | **Infrastructure** | Terraform/Pulumi rollback or manual | State drift, dependent resources | Plan the rollback, review the diff |
 | **Data backfill** | Restore from backup or reverse script | Mixed old/new data states | Run reverse on a 100-row sample |
@@ -96,7 +96,7 @@ One statement: "Rollback tested on staging. Time: <N minutes>. Result: <pass/fai
 ## Principles
 
 - A rollback plan that hasn't been tested is a wish.
-- Time the drill. If it takes 45 minutes on staging, it takes 90 in production at 2am.
+- Time the drill and account for differences in production scale and operating conditions; do not assume a fixed multiplier.
 - Identify the irreversible components and name the compensating action.
 - The drill report is evidence for the change ticket and the team's confidence.
 - A drill that fails is a success - you found the problem before production did.

package/skills/fde/references/ship.md

@@ -10,11 +10,11 @@ Do not ask them to pick a mode. Name where you are, then start at the matching s
 - On staging, the signer in `success.md` can reject it → **go-live**
 - Prod is the question → **go-live**. Do not start a second change.
 
-If going live, opening question: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
+If going live, check the evidence for the recovery path: has rollback, restore, compensation, or roll-forward been exercised under representative conditions? If only planned, validate it before release. Reuse applicable drill evidence when the mechanism and relevant conditions are unchanged; record why it applies.
 
 A bounded experiment that tests an assumption is `poc`. This skill turns a validated direction into a maintainable change on a repo they will own, then production. Inspect existing prototype code and retain suitable tested parts; replace unsafe shortcuts based on evidence. A successful demo alone does not satisfy the readiness gates below.
 
-**Before committing a plan or building:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint.
+**Before a new delivery plan or material scope change:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer and acceptance check; record verification without restarting approval. New judgment in the record still requires confirmation.
 
 ## Field (name it once, then the same loop)
 
@@ -22,18 +22,18 @@ A bounded experiment that tests an assumption is `poc`. This skill turns a valid
 |--|------------|------------|
 | What you touch | Code they already run | A new path or empty tree they will own |
 | First move | Characterise their tests, their runner, the workaround in `terrain.md` | First path a user can click. Not the whole product. |
-| Proof | Their staging, a screen they already use | Their staging, or the environment they will operate. Local demo is not delivery. |
-| Undo | Revert this change on its own | Same. If you cannot undo it, the design is coupled. |
+| Proof | Agreed representative environment and replayable acceptance check | Agreed representative environment and replayable acceptance check; record what remains untested before release |
+| Undo | Revert this change on its own | Name rollback or tested recovery; identify irreversible effects and required authority. |
 
 Skip POC only when the killer assumption already lives in the repo (typical brownfield). If the bet is unproven, `poc` first.
 
-**Done means:** the signer in `success.md` can reject this on staging they operate. A green check on your laptop is not delivery. Do not start the next change until this one is rejectable.
+**Customer delivery means:** the signer in `success.md` can replay and reject the agreed acceptance check in an environment they operate. A green check on your laptop proves only what ran there. Routine fixes can share a delivery checkpoint; distinguish implementation, verification, deployment, and acceptance.
 
 If `terrain.md` **Data estate** lists a **Blocker** this change depends on (source or pipe): stop. That is discover, not ship. Do not build a path they cannot feed.
 
 ## Method - one change they can see
 
-One change = one thing a user can do, with a test, that you can revert on its own. Not "all the APIs, then all the UI." Not a 2,000-line dump. A PR is how this often lands. It is not the job. The job is the change they can see.
+One change = one coherent outcome with observable verification and a bounded recovery path. Prefer vertical slices that can be reviewed and exercised independently. A PR is how this often lands. It is not the job. The job is the change they can see.
 
 ```
 BAD (layers):
@@ -49,7 +49,7 @@ GOOD (one user action each):
   4: Admin can void a payment (auth + logic + UI) - testable
 ```
 
-Each change is independently revertible.
+Prefer independently revertible changes. When data or external effects cannot be undone, name the dependency, containment, tested recovery, and authorized owner before release.
 
 **Before you start this change:**
 
@@ -58,7 +58,7 @@ Each change is independently revertible.
 - [ ] Rollback named: revert this change, or something more specific
 - [ ] No dependency on an unmerged change (if dependent, state it and land in order)
 - [ ] `Kill if` is written - the observation that stops this change
-- [ ] Before-receipt captured: the failing output, number, or screen as it is today, dated in `delivery.md`, before you change anything
+- [ ] Before-state evidence identified: the relevant failing output, number, or behavior, with its source and date. For a routine fix within confirmed scope, reference applicable existing evidence and batch the delivery receipt; capture new evidence when the relevant behavior or conditions changed. Never imply an old check was rerun.
 - [ ] Open PRs and uncommitted work in the area checked (`gh pr list`, `gh pr diff <n> --name-only`); overlap goes to `decisions.md` before you start
 
 Your coding pack writes the function. This skill owns done. When they disagree with this repo, the repo wins.
@@ -69,34 +69,25 @@ Your coding pack writes the function. This skill owns done. When they disagree w
 Read existing code in the area (search before creating)
   → Characterise what is already there (their tests, their runner; greenfield: the empty tree)
     → Implement the smallest path that works
-      → Prove it on their staging (below)
+      → Verify the change; demonstrate at the agreed delivery checkpoint (below)
         → Cleanup pass (dedupe, simplify - behaviour unchanged)
           → Self-review against acceptance criteria
             → Commit with a message the client's team can read
               → Update decisions.md + delivery.md
 ```
 
-**Prove it on their staging.** A green check on your laptop is not delivery.
+**Verify the change and prove customer delivery.** Match evidence to the reviewed revision, environment, and acceptance criteria.
 
-- Run **their** test command, on **their** CI, with **their** fixtures. Write the command and the result in `delivery.md` in this turn. You do not add a runner they will not keep. If you have not run their command in this turn, you cannot write that it passed. Last session's green, "should pass," and "looks correct" are not a receipt. Missing this-turn line = not proven. Same as a failing test.
-- If the signer in `success.md` cannot reject this on a screen they already use, it is not proven.
-- Staging they operate beats a local demo. If you have no staging: `unknown - ask:` who owns an environment, then stop pretending it shipped.
-- **Monday-shaped data.** Staging that is empty, synthetic, or last quarter is not next Tuesday. Before go-live, write what staging is missing (volume, PII, the batch that only runs in prod, the account that only exists in the warehouse) and what that means for the kill test. If the signer cannot reject it on a screen they already operate, with data that looks like next Tuesday, it is not proven.
+- Use **their** test commands, fixtures, and CI. Record the command, result, revision, environment, and run date in `delivery.md`. Reuse existing evidence only when the relevant code and conditions are unchanged, citing why it still applies; never claim it was rerun. Run affected checks for changed behavior and required release checks before deployment. Missing evidence means unproven, not an observed failure.
+- At the agreed delivery checkpoint, the signer in `success.md` must be able to replay and reject the acceptance check using an interface they operate (screen, API, report, or equivalent). Routine fixes can share that checkpoint; passing tests alone does not establish customer acceptance.
+- Prefer staging they operate. When unavailable, use an agreed, permitted representative test environment, record its owner and limitations, and resolve material release-evidence gaps before production. A local demonstration is not deployment.
+- **Representative data.** Use permitted sanitized or synthetic fixtures that exercise relevant volumes, edge cases, and operating paths. Before go-live, record gaps such as batch timing, distribution, or production-only dependencies and their impact on the acceptance and abort checks. Resolve material gaps or explicitly narrow the release; never load sensitive production data merely to make a demo realistic.
 - Model in the path: `eval-pack` until `evals.md` says SHIP. Do not skip because "it looked right in chat."
 - A model drafts. A named human on their side ships. No unsupervised loop on their production. If the brief demands lights-out write-access, that is `who-decides` / `hold-scope`, not ship.
 
 The proof is whatever this client already believes, plus one new receipt they can replay.
 
-**Size.** Each change targets:
-
-| Metric | Target | Why |
-|--------|--------|-----|
-| Lines changed | 100-300 | Reviewable in one sitting |
-| Time to implement | 30-90 minutes | Testable before context decays |
-| Files touched | 1-5 | Blast radius stays containable |
-| Tests added | ≥1 per new behaviour | Proves this change; guards against regression |
-
-Larger than 300 lines → split first. "It's all connected" means the design needs work, not a bigger dump.
+**Size by reviewability and risk.** Keep one coherent intent, bounded context, and observable acceptance checks. Split unrelated behavior or work whose recovery and review cannot be understood together. Diff size and elapsed time are warning signals, not hard gates: generated changes may be large and low risk; a one-line permission change may be critical. Use the repository’s checks and add meaningful coverage for changed behavior, rather than a test-count quota.
 
 **Show it.** Every 2-3 changes, something the customer can see: an endpoint they can hit, a UI they can click, a metric that moved, a risk that was retired. Technical progress invisible to stakeholders is trust decay. `delivery.md` gets updated after every visible change.
 
@@ -106,7 +97,7 @@ Larger than 300 lines → split first. "It's all connected" means the design nee
 - If it's NOT in `decisions.md`: log it as a scope receipt (see `hold-scope.md`), don't touch it.
 - Ugly code outside this change stays ugly. That is discipline, not laziness.
 
-After each change: tests pass (state the command and result), acceptance criteria met, blast radius as declared, `Kill if` still false. After every 2-3: what did they see, and what's their signal? Then, when the signer can reject it on their staging, go-live below.
+After each change: required checks pass with applicable evidence, acceptance criteria evaluated, blast radius as declared, `Kill if` still false. At the agreed delivery checkpoint: what did they see, and what is their signal? Before production, complete the go-live gates below.
 
 ---
 
@@ -141,7 +132,7 @@ Score each dimension green/amber/red. This is the gate, not a suggestion:
 | Dimension | Green | Amber | Red |
 |-----------|-------|-------|-----|
 | Tests | All pass on deploy branch | Flaky tests skipped with justification | Failures present or tests not run |
-| Rollback | Tested end-to-end (not planned - TESTED) | Documented but untested | No rollback path defined |
+| Recovery | Applicable tested rollback/restore/compensation/roll-forward meets agreed recovery and data-loss limits | Documented; drill evidence needs refresh | No viable recovery, failed drill, or irreversible effects lack explicit authority |
 | Sign-off | Stakeholder approval in `decisions.md` with date | Verbal approval, not logged | No approval sought |
 | 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 |
@@ -211,16 +202,16 @@ grep -rnE "(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][^'\"]{8,}" \
   --include="*.js" --include="*.ts" --include="*.py" --include="*.env" \
   --include="*.yaml" --include="*.json" . | grep -vE "example|template|test" | head
 ```
-- DB migrations reversible.
-- Rollback documented **and tested**.
+- DB migrations checked for compatibility, data loss, and old/new application coexistence. Prefer expand/contract for destructive changes. Irreversible steps require explicit authority and a tested restore, compensation, or roll-forward plan.
+- Recovery documented **and tested**, with acceptable recovery time and data loss.
 - Monitoring alerts configured, someone watching.
 - Team knows the deploy is happening.
-- Not a Friday unless genuine emergency with someone on call.
+- Deploy window has staffed observation and recovery coverage appropriate to the risk; respect the client’s change calendar and business-critical periods.
 - **Change approval (CAB) environments:** window open, ticket approved. In banking/healthcare/gov, deploying outside an approved window is a compliance finding even when the deploy succeeds. "We didn't know there was a CAB process" is not a defence - find out before the deploy date.
 
 ## Method - the deploy
 
-**Canary:** 1-5% of traffic, ≥10 minutes. Watch error rate, latency, and **the business metric this change affects**. Anything looks wrong → roll back immediately; investigate safely; redeploy when confident. Never investigate during the canary. Then stage up: 5% → 25% → 100%, each confirmed stable.
+**Rollout:** Choose canary, blue/green, staged cohorts, or the client’s proven release mechanism based on isolation, traffic, and failure cost. For a canary, set cohort size, exposure cap, observation duration, minimum sample, and advance/abort thresholds before starting; allow for delayed and batch effects. Watch errors, latency, and **the business metric this change affects**. Breached thresholds or critical harm → halt expansion and execute the tested recovery/containment plan; investigate after exposure is controlled. Advance only with sufficient evidence and a named operator.
 
 **Canary receipt** (write it, or the canary did not happen): what was watched, on whose dashboard, for how long, and that the next change did not start in the window. If prod is a CAB console, vendor button, or their pipeline, write the owner and the click path - the host agent does not get to pretend it shipped.
 
@@ -275,7 +266,7 @@ Never skip a step. The sponsor always wants to skip from pilot to standard - tha
 Adoption isn't a handoff-stage problem - it starts while you are still writing the change. Software that launches to silence is software that gets decommissioned.
 
 **During the change:**
-- **Feature flags from day one.** Every new capability behind a flag. Ship to 5% of users first. Watch behavior before opening to 100%.
+- **Controlled exposure.** Use a feature flag or equivalent isolation when it reduces rollout risk. Choose cohorts and expansion criteria from traffic and impact; name the flag owner and removal point.
 - **Feedback loops built in.** A thumbs-up/down, a "was this helpful?", a usage counter. Instrument adoption, don't assume it.
 - **Resistance signals.** Watch for: workaround creation (they built a spreadsheet instead of using the tool), drop-off after day 3 (onboarding fails), vocal detractors (one influential skeptic can kill adoption). Address these before launch, not after.
 
@@ -290,13 +281,13 @@ Adoption isn't a handoff-stage problem - it starts while you are still writing t
 
 **`decisions.md`** - each change: what was implemented, what was tested, what was deferred, `Kill if`.
 
-**`delivery.md`** - each visible change in business language; then the deployment record: what shipped, when, rollback procedure, pulse definition, **scale-readiness assessment, and adoption metrics**. Written for whoever inherits the system.
+**`delivery.md`** - each visible change in business language; then the deployment record: what shipped, when, recovery procedure, pulse definition, **scale-readiness assessment, and adoption metrics**. Written for whoever inherits the system.
 
 ## Checkpoint
 
-After each change: tests pass, acceptance criteria met, blast radius as declared, `Kill if` still false, proven on staging they operate.
+After each change: required checks pass, acceptance criteria evaluated, blast radius as declared, `Kill if` still false. Batch routine fixes at the agreed delivery checkpoint; record staging and customer acceptance separately.
 
-Before 100% live: canary clean, business metric verified, pulse written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**, **intent vs diff clean** (no unresolved SPLIT/DROP). Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
+Before full exposure: the chosen rollout’s advance criteria are met with sufficient observation and business-metric evidence, and the pulse is written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**, **intent vs diff clean** (no unresolved SPLIT/DROP). Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
 
 ## Worked example
 
@@ -315,10 +306,10 @@ Greenfield is the same loop with an empty tree: first path a user can click, on
 ## Principles
 
 - One user action per change. Layers are untestable until assembled.
-- On their staging, and you can undo it. Local green is not delivery.
+- Prove the agreed outcome in their environment and test recovery. Local green is not customer delivery.
 - The ugly code outside this change stays ugly. That's discipline, not laziness.
-- A deployment without a tested rollback is reckless.
-- Roll back on any canary anomaly; investigate safely.
+- A deployment needs tested recovery within agreed time and data-loss limits; irreversible effects require explicit authority.
+- Halt expansion on breached thresholds or critical harm; contain exposure with the tested recovery plan before investigating.
 - Verify the business metric, not just the technical one.
 - No value bucket, no green ship. No pulse, no done.
 - Diff larger than the stated intent without KEEP/JUSTIFY receipts = fix-first.