fdeops 5.1.2 → 5.1.4

package/README.md

@@ -12,19 +12,23 @@ Use it for a single integration, a small client project, or work within a larger
 
 [Get started](#quick-start) · [Choose a task](#task-skills) · [Keep a customer record](#keep-a-customer-record) · [Documentation](docs/README.md)
 
+<img width="1000" height="586" alt="fdeops-flow" src="https://github.com/user-attachments/assets/12bbec6a-d0b3-4d03-81aa-4b842731a044" />
+
 ## Quick start
 
-You need an AI coding agent that supports skills. The installation commands and FDEOps CLI require **Node.js 18+ and Git** on your machine.
+Use FDEOps with an AI coding agent that supports skills. Start with one task, or let `fde` coordinate a customer project.
 
 ### Work on a customer project
 
-Run this in your terminal and select your agent in the installer:
+Run this in the terminal where your coding agent runs, then select your agent in the installer:
 
 ```bash
 npx skills add suboss87/fdeops --skill fde
 ```
 
-Then start a conversation with your agent:
+This installation method uses Node.js (which includes `npx`) and Git. If either is missing, ask your agent to help with setup. The FDEOps CLI requires Node.js 18 or later. See [installation options](docs/install.md) for your agent.
+
+Then select `fde` in your agent and start a conversation. In agents that support `@fde`, use:
 
 ```text
 @fde this is client01. Their support team reads incoming requests,

package/bin/check.js

@@ -291,15 +291,6 @@ for (const phrase of badPhrases) {
     fail(`README must not contain hype phrase: ${phrase}`)
   }
 }
-// fdeops stands on its own. The README must never frame it as a derivative -
-// a fork, port, or rebuild of another project.
-const derivativeFraming = [
-  /\b(fork of|forked from|port of|rebuild of|reimplementation of|based on)\s+[A-Z]/,
-  /\b(inspired by|built on top of|powered by)\s+[A-Z][A-Za-z0-9-]+/,
-]
-for (const rx of derivativeFraming) {
-  if (rx.test(readme)) fail(`README must not frame fdeops as derivative: ${rx}`)
-}
 if (/docs\/internal|PMF_360/i.test(readme)) {
   fail('README must not link docs/internal or PMF_360')
 }

package/bin/fde.js

@@ -76,7 +76,15 @@ function maskedSections(sections, maxBytes = context.DEFAULT_BYTES, heading = ''
   return prefix + context.boundedSections(sections.map(text => masking.mask(text)), maxBytes - Buffer.byteLength(prefix))
 }
 const DEBRIEF_MAX_BYTES = 256 * 1024
-const CODE_EXT = ['.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.go', '.rb', '.cs', '.php']
+const CODE_EXT = ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.py', '.java', '.go', '.rb', '.cs', '.php']
+function isTestCodeFile(file, cwd) {
+  if (!CODE_EXT.includes(path.extname(file))) return false
+  const parts = path.relative(cwd, file).split(path.sep)
+  const name = path.basename(parts.pop(), path.extname(file))
+  return parts.some(part => /^(?:tests?|specs?|__tests__)$/i.test(part))
+    || /(?:^|[._-])(?:test|spec)(?:[._-]|$)/i.test(name)
+    || /(?:Tests?|Specs?)$/.test(name)
+}
 const CONF_EXT = CODE_EXT.concat(['.env', '.yaml', '.yml', '.json'])
 // Bare "inference" is banned here: TypeScript codebases are full of "type
 // inference" comments and the false positives poison the day-1 questions.
@@ -1252,7 +1260,11 @@ function cmdScan() {
   out.push('='.repeat(60))
 
   // stack + age
-  const files = walk(cwd, CONF_EXT.concat(['.md']), 5000)
+  const candidates = walk(cwd, CONF_EXT.concat(['.md']), 5001)
+  const files = candidates.slice(0, 5000)
+  out.push(`COVERAGE  ${files.length} supported files selected${candidates.length > 5000 ? ' - 5,000-file limit reached; scan is partial' : ''}`)
+  out.push('  Hidden/generated directories, files over 1 MiB and unsupported formats are not inspected.')
+  out.push('  Findings are capped per section. Absence of findings does not establish test coverage or production readiness.')
   const extCount = {}
   for (const f of files) { const e = path.extname(f); extCount[e] = (extCount[e] || 0) + 1 }
   const langs = Object.entries(extCount).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([e, n]) => `${e}:${n}`).join(' ')
@@ -1268,7 +1280,7 @@ function cmdScan() {
     const counts = {}
     churn.split('\n').filter(Boolean).forEach(f => { counts[f] = (counts[f] || 0) + 1 })
     const top = Object.entries(counts).sort((a, b) => b[1] - a[1]).slice(0, 8)
-    const testFiles = files.filter(f => /test|spec/i.test(f))
+    const testFiles = files.filter(f => isTestCodeFile(f, cwd))
     if (top.length === 0) out.push('  (no commits in the last 90 days)')
     for (const [f, n] of top) {
       const base = path.basename(f).replace(/\.[^.]+$/, '')
@@ -1317,7 +1329,7 @@ function cmdScan() {
   if (!reverts && readmeHits.length === 0) out.push('  none visible')
 
   // test landscape
-  const testCount = files.filter(f => /test|spec/i.test(f)).length
+  const testCount = codeFiles.filter(f => isTestCodeFile(f, cwd)).length
   out.push(`\nTEST LANDSCAPE  ${testCount} test file(s) across ${codeFiles.length} code files`)
 
   // day-1 questions - each one earned by a finding above, skipped when empty
@@ -1330,7 +1342,7 @@ function cmdScan() {
   if (tmp.length) asks.push("Which of these 'temporary' fixes are now load-bearing contracts?")
   asks.length
     ? asks.slice(0, 5).forEach((q, i) => out.push(`  ${i + 1}. ${q}`))
-    : out.push('  (clean scan - ask what the last engineer wished they had known)')
+    : out.push(codeFiles.length ? '  No additional questions from these heuristics; inspect the untested paths with the team.' : '  No supported code files inspected; identify the application files before relying on this scan.')
 
   out.push('\n' + '-'.repeat(60))
   out.push("Facts only - interpretation is the FDE's (or @fde's) job.")
@@ -1969,6 +1981,7 @@ function printDebriefReview(text, eng) {
     }
   }
   console.log('REVIEW (one screen - confirm once, then apply)\n')
+  console.log('PENDING UPDATE - not yet saved. Review these proposed changes:\n')
   const order = [
     ['decided', buckets.decided],
     ['stated asks', buckets.asked],
@@ -1994,10 +2007,14 @@ function printDebriefReview(text, eng) {
   const measured = recorded.some(row => row.state !== 'unmeasured')
   const evidenced = recorded.some(row => !row.evidenceMissing)
   const accepted = recorded.some(row => row.state === 'accepted')
-  console.log('  delivery picture (existing record; this proposal does not certify it):')
-  console.log(`    - measurement: ${measured ? 'recorded; check the value ledger' : 'missing - record the observed result'}`)
-  console.log(`    - evidence: ${evidenced ? 'recorded; review its source' : 'missing - cite the test, artifact, or source'}`)
-  console.log(`    - customer approval: ${accepted ? 'recorded for a prior outcome; not this proposal' : 'missing - request explicit acceptance after evidence review'}`)
+  console.log('\nSAVED RECORD - before this update; pending changes above are not included:')
+  if (!recorded.length) {
+    console.log('  No delivery results saved yet. Review the proposed delivery above before applying.')
+  } else {
+    console.log(`  - result: ${measured ? 'recorded; check its scope in the value ledger' : 'not yet recorded'}`)
+    console.log(`  - evidence: ${evidenced ? 'recorded; review its source' : 'not yet recorded'}`)
+    console.log(`  - customer approval: ${accepted ? 'recorded for a prior result; not this proposal' : 'not yet recorded'}`)
+  }
   console.log('  Saving this update confirms your record, not customer acceptance.\n')
 }
 
@@ -2610,7 +2627,11 @@ function cmdHandoff(args, label = 'Handoff') {
     out = path.resolve(parsed.args[1])
   }
   const eng = resolveEngagement()
-  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  if (!eng) {
+    const skill = label === 'Handoff' ? 'handoff' : 'readout'
+    console.error(`This command exports an existing customer record; none is selected.\nFor a standalone draft, ask your agent to use the ${skill} skill with supplied notes; no record is required.\nTo keep an ongoing customer record, run: fde resume --init <name>`)
+    process.exit(2)
+  }
   const success = stripTemplateNoise(readClean(eng, 'success.md'))
   const signer = ((success.match(/^\*\*Stakeholder who signs off:\*\*[^\S\n]*(.*)$/m) || [])[1] || '').trim()
   const ledger = parseValueLedger(eng).rows

package/bin/lib/delivery-gaps.js

@@ -17,7 +17,7 @@ function deliverySummary(e) {
   const unmeasured = rows.filter(r => r.state === 'unmeasured').length
   if (unmeasured) add('measurement', `${unmeasured} outcome${unmeasured === 1 ? '' : 's'} not yet measured`, 'Agree how to measure the outcome and collect the result', 'delivery.md')
   const claimed = rows.filter(r => r.state === 'claimed').length
-  if (claimed) add('acceptance', `${claimed} measured outcome${claimed === 1 ? '' : 's'} awaiting acceptance`, 'Ask the acceptance owner to review the measured outcome', 'delivery.md')
+  if (claimed) add('acceptance', `${claimed} reported result${claimed === 1 ? '' : 's'} awaiting acceptance`, 'Ask the acceptance owner to review the reported result and its evidence', 'delivery.md')
   if (signals.trust === 'amber') add('trust', 'Check in with the customer: trust is watch', 'Check the customer concern and agree the next step', 'stakeholders.md')
   if (signals.stale) add('stale-trust', 'Reconfirm the dated trust signal', 'Check whether the recorded customer signal still applies', 'stakeholders.md')
   if (!e.hasNext) add('next', 'Set the next action', 'Set one next action with an owner and completion check', 'context.md')

package/mcp/fdeops-ingest/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "5.1.2",
+  "version": "5.1.4",
   "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
   "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": "5.1.2",
+  "version": "5.1.4",
   "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
   "author": {
     "name": "Subash Natarajan",

package/skills/build/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "19f32ecae72b96ee19cb87658ddd998cce96ec2e3960255d13fcc2906c6d0b6b",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/build/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/build/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/debug/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "7862670d5c023f0195e0b3fa8b52a3b33796813e53aaad083ae82a9a469e0faa",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/debug/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/debug/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/evaluate/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "6a8f9490294e1a055c25984955d011db23ebb1eb2fb4f8634584d1455331425e",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/evaluate/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/evaluate/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/fde/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/fde/references/close.md

@@ -2,6 +2,8 @@
 
 **Context:** apply [task context and evidence](task-context.md) before using the named records below.
 
+For a standalone handoff draft, use the supplied notes and project evidence; no customer record is required. The `fde handoff` CLI exports an existing record. Use it only when a record is selected, not to create one merely for a draft.
+
 **Enter when:** the engagement is ending - the customer team must run this without the FDE.
 
 **Read first:** for standalone work, use the supplied permitted operating notes, evidence and ownership; no engagement binding or CLI command is required. For a bound engagement, use bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Never initialize records merely to draft a handoff. Build the picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for code paths needed by the successor.

package/skills/fde/references/plan.md

@@ -116,30 +116,19 @@ Write estimates to `decisions.md` under `## Sizing`. Include the assumptions - w
 
 ## Method - migration strategy (when the engagement is "move from X to Y")
 
-Migrations are the most common enterprise FDE engagement. The strategy precedes the plan:
+Choose the strategy from the existing contracts and permitted operating constraints before sequencing changes.
 
-**Step 1: Classify the migration type.**
+**Step 1: Classify what changes.** Rehost moves infrastructure; replatform changes platform dependencies; refactor changes implementation; replace introduces a different system; retire removes one. Identify affected data, callers, ownership and external effects. The label alone does not determine the risk.
 
-| Type | What it means | Risk profile |
-|------|---------------|-------------|
-| **Rehost** (lift-and-shift) | Same code, different infrastructure | Low code risk, high ops risk |
-| **Replatform** | Minor code changes to use new platform features | Medium risk, clear scope |
-| **Refactor** | Rewrite components to fit the new architecture | High risk, scope creep magnet |
-| **Replace** | Buy/build new, retire old | Highest risk, requires parallel running |
-| **Retire** | Turn off, nobody uses it | Politically hard, technically easy |
+**Step 2: Order by compatibility.** Map who calls or reads what, which versions coexist, and which prerequisite each change needs. There is no universal leaf-first order. Add compatible schema/API capabilities and reader support before switching dependent writers or callers. Remove an old contract only after its consumers and retention obligations permit it, within approved scope.
 
-**Step 2: Map the dependency graph.** What calls what. What breaks if this moves first. The migration order is the reverse of the dependency chain - leaf nodes first, core last.
+**Step 3: Choose cutover and data handling.** Compare a direct switch, staged replacement or parallel comparison against downtime, consistency, capacity and side-effect constraints. Parallel execution must not duplicate customer actions. For a live backfill, define resumable batches, how concurrent writes are preserved, and reconciliation of actual values and tenant ownership; row counts alone do not prove correctness. Use the existing platform's supported mechanisms and test their failure cases.
 
-**Step 3: Define the cutover strategy.**
-- **Big bang** - everything moves at once. Fast but catastrophic on failure. Only for small systems.
-- **Strangler fig** - new traffic to new system, old traffic drains. Safe but slow. Preferred for anything load-bearing.
-- **Parallel run** - both systems run, outputs compared. Expensive but safest for data-critical systems.
+**Step 4: Specify recovery before cutover.** Use the recovery required for release: rollback, restore, compensation or roll-forward must match the effects that persist and the agreed recovery limits. Do not route to an old binary that cannot read new writes. Identify the irreversible boundary, required authority, operator and stop conditions; exercise the chosen recovery in a permitted representative environment before release. Missing recovery evidence blocks cutover, not useful planning or reversible preparation.
 
-**Step 4: Write the rollback before the migration starts.** "If we move service X and it fails, we route back to old within [time]." No rollback = no migration.
+**Step 5: Define phase acceptance.** Check supported old/new version combinations, no lost updates, tenant isolation and relevant service-level targets. Record baseline, environment, thresholds, evidence and operating owner rather than imposing generic percentages.
 
-**Step 5: Define success metrics per phase.** Not "migration complete" - that's a project plan. "Error rate same or lower, latency within 10%, zero data loss, team can operate without FDE." Measurable, per service.
-
-Write migration strategy to `decisions.md` under `## Migration`. Each service gets a row: type, order, cutover method, rollback, success metric.
+In a bound engagement, propose the migration plan in `decisions.md` under `## Migration`. Each step records compatibility prerequisites, cutover/data handling, recovery and acceptance evidence. Standalone work returns the same plan directly.
 
 ## When the plan changes mid-engagement
 
@@ -164,4 +153,4 @@ First visible slice goes to Marco, not Priya: he is the one whose morning change
 - No kill list, no finished plan.
 - No **Kill if** on a Now PR, that PR is hope.
 - Estimates are ranges, not promises. Name the assumptions and the observation that voids them.
-- Migrations: leaf nodes first, core last. Rollback before cutover.
+- Migrations: compatibility determines order; verified recovery precedes cutover.

package/skills/fde/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/handoff/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "9f08605914670f2c0bd09631d3d40c079e7f63174d1a2607e60ea6eca5d54d93",
-    "references/close.md": "7403c49ceef1c3d5347efbef9c45af3bd0f5927d595b2df3d4e35eadfd154344",
+    "references/close.md": "b3dbc1ecef12ee1c9d298e32a21d87ce61c9f6c88039d7a8b19970c6e3f21254",
     "references/encode-pattern.md": "3be7bf9d0f69af31659423c54d6023a4af1556e2ce200fb025bf64d0757de4d8",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27"
   }

package/skills/handoff/references/close.md

@@ -2,6 +2,8 @@
 
 **Context:** apply [task context and evidence](task-context.md) before using the named records below.
 
+For a standalone handoff draft, use the supplied notes and project evidence; no customer record is required. The `fde handoff` CLI exports an existing record. Use it only when a record is selected, not to create one merely for a draft.
+
 **Enter when:** the engagement is ending - the customer team must run this without the FDE.
 
 **Read first:** for standalone work, use the supplied permitted operating notes, evidence and ownership; no engagement binding or CLI command is required. For a bound engagement, use bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Never initialize records merely to draft a handoff. Build the picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for code paths needed by the successor.

package/skills/integrate/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "ea74e65eff6b189e1e2fb00c3553192116ccc475785eb82bfaee49819610dfd4",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/integrate/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/integrate/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/plan/.fde-generated.json

@@ -4,7 +4,7 @@
   "files": {
     "SKILL.md": "7228088cfea2128c220475fb1b2a417e3aecfb70dbd96a8fcbbc6b652ab0e3a2",
     "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
-    "references/plan.md": "721b6cd2dc67129b73ff321a90a02e7588a53200209418a1067ce65836bdfdfe",
+    "references/plan.md": "4ccc74a3476da1c10bf8c05d249d573bcf73d13b8b6c88bd769635d816d0914b",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27"
   }
 }

package/skills/plan/references/plan.md

@@ -116,30 +116,19 @@ Write estimates to `decisions.md` under `## Sizing`. Include the assumptions - w
 
 ## Method - migration strategy (when the engagement is "move from X to Y")
 
-Migrations are the most common enterprise FDE engagement. The strategy precedes the plan:
+Choose the strategy from the existing contracts and permitted operating constraints before sequencing changes.
 
-**Step 1: Classify the migration type.**
+**Step 1: Classify what changes.** Rehost moves infrastructure; replatform changes platform dependencies; refactor changes implementation; replace introduces a different system; retire removes one. Identify affected data, callers, ownership and external effects. The label alone does not determine the risk.
 
-| Type | What it means | Risk profile |
-|------|---------------|-------------|
-| **Rehost** (lift-and-shift) | Same code, different infrastructure | Low code risk, high ops risk |
-| **Replatform** | Minor code changes to use new platform features | Medium risk, clear scope |
-| **Refactor** | Rewrite components to fit the new architecture | High risk, scope creep magnet |
-| **Replace** | Buy/build new, retire old | Highest risk, requires parallel running |
-| **Retire** | Turn off, nobody uses it | Politically hard, technically easy |
+**Step 2: Order by compatibility.** Map who calls or reads what, which versions coexist, and which prerequisite each change needs. There is no universal leaf-first order. Add compatible schema/API capabilities and reader support before switching dependent writers or callers. Remove an old contract only after its consumers and retention obligations permit it, within approved scope.
 
-**Step 2: Map the dependency graph.** What calls what. What breaks if this moves first. The migration order is the reverse of the dependency chain - leaf nodes first, core last.
+**Step 3: Choose cutover and data handling.** Compare a direct switch, staged replacement or parallel comparison against downtime, consistency, capacity and side-effect constraints. Parallel execution must not duplicate customer actions. For a live backfill, define resumable batches, how concurrent writes are preserved, and reconciliation of actual values and tenant ownership; row counts alone do not prove correctness. Use the existing platform's supported mechanisms and test their failure cases.
 
-**Step 3: Define the cutover strategy.**
-- **Big bang** - everything moves at once. Fast but catastrophic on failure. Only for small systems.
-- **Strangler fig** - new traffic to new system, old traffic drains. Safe but slow. Preferred for anything load-bearing.
-- **Parallel run** - both systems run, outputs compared. Expensive but safest for data-critical systems.
+**Step 4: Specify recovery before cutover.** Use the recovery required for release: rollback, restore, compensation or roll-forward must match the effects that persist and the agreed recovery limits. Do not route to an old binary that cannot read new writes. Identify the irreversible boundary, required authority, operator and stop conditions; exercise the chosen recovery in a permitted representative environment before release. Missing recovery evidence blocks cutover, not useful planning or reversible preparation.
 
-**Step 4: Write the rollback before the migration starts.** "If we move service X and it fails, we route back to old within [time]." No rollback = no migration.
+**Step 5: Define phase acceptance.** Check supported old/new version combinations, no lost updates, tenant isolation and relevant service-level targets. Record baseline, environment, thresholds, evidence and operating owner rather than imposing generic percentages.
 
-**Step 5: Define success metrics per phase.** Not "migration complete" - that's a project plan. "Error rate same or lower, latency within 10%, zero data loss, team can operate without FDE." Measurable, per service.
-
-Write migration strategy to `decisions.md` under `## Migration`. Each service gets a row: type, order, cutover method, rollback, success metric.
+In a bound engagement, propose the migration plan in `decisions.md` under `## Migration`. Each step records compatibility prerequisites, cutover/data handling, recovery and acceptance evidence. Standalone work returns the same plan directly.
 
 ## When the plan changes mid-engagement
 
@@ -164,4 +153,4 @@ First visible slice goes to Marco, not Priya: he is the one whose morning change
 - No kill list, no finished plan.
 - No **Kill if** on a Now PR, that PR is hope.
 - Estimates are ranges, not promises. Name the assumptions and the observation that voids them.
-- Migrations: leaf nodes first, core last. Rollback before cutover.
+- Migrations: compatibility determines order; verified recovery precedes cutover.

package/skills/poc/.fde-generated.json

@@ -4,13 +4,13 @@
   "files": {
     "SKILL.md": "bceae7ba11c006b3d1e93e330a80cc58eeef55d863cc374653eef8fd124c3056",
     "references/audit.md": "ed32ea78cbccb100742dd838e8cf4cd4b6f33ad44b3de7424fc624670d571dbc",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/discover.md": "f65aa11a539b4dbbed70cfaa94ec2a35595aa9a2d0282790510b933ac9c721ce",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
-    "references/plan.md": "721b6cd2dc67129b73ff321a90a02e7588a53200209418a1067ce65836bdfdfe",
+    "references/plan.md": "4ccc74a3476da1c10bf8c05d249d573bcf73d13b8b6c88bd769635d816d0914b",
     "references/poc.md": "818dc90c2d401819735233ab9d69df171675d75abf8644c403dab7dd1dcf9199",
     "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
@@ -18,6 +18,6 @@
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
     "references/test-assumptions.md": "bf60d8bb4c0701fcffb196d78f7f6c8b1c472fc877fb2caf41058fbf8e2415a1",
     "references/three-options.md": "168fab9fb8ac8de85b0d1fa58e1db17deaa244cdef8c99623a04a0a6c70fe52c",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/poc/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/poc/references/plan.md

@@ -116,30 +116,19 @@ Write estimates to `decisions.md` under `## Sizing`. Include the assumptions - w
 
 ## Method - migration strategy (when the engagement is "move from X to Y")
 
-Migrations are the most common enterprise FDE engagement. The strategy precedes the plan:
+Choose the strategy from the existing contracts and permitted operating constraints before sequencing changes.
 
-**Step 1: Classify the migration type.**
+**Step 1: Classify what changes.** Rehost moves infrastructure; replatform changes platform dependencies; refactor changes implementation; replace introduces a different system; retire removes one. Identify affected data, callers, ownership and external effects. The label alone does not determine the risk.
 
-| Type | What it means | Risk profile |
-|------|---------------|-------------|
-| **Rehost** (lift-and-shift) | Same code, different infrastructure | Low code risk, high ops risk |
-| **Replatform** | Minor code changes to use new platform features | Medium risk, clear scope |
-| **Refactor** | Rewrite components to fit the new architecture | High risk, scope creep magnet |
-| **Replace** | Buy/build new, retire old | Highest risk, requires parallel running |
-| **Retire** | Turn off, nobody uses it | Politically hard, technically easy |
+**Step 2: Order by compatibility.** Map who calls or reads what, which versions coexist, and which prerequisite each change needs. There is no universal leaf-first order. Add compatible schema/API capabilities and reader support before switching dependent writers or callers. Remove an old contract only after its consumers and retention obligations permit it, within approved scope.
 
-**Step 2: Map the dependency graph.** What calls what. What breaks if this moves first. The migration order is the reverse of the dependency chain - leaf nodes first, core last.
+**Step 3: Choose cutover and data handling.** Compare a direct switch, staged replacement or parallel comparison against downtime, consistency, capacity and side-effect constraints. Parallel execution must not duplicate customer actions. For a live backfill, define resumable batches, how concurrent writes are preserved, and reconciliation of actual values and tenant ownership; row counts alone do not prove correctness. Use the existing platform's supported mechanisms and test their failure cases.
 
-**Step 3: Define the cutover strategy.**
-- **Big bang** - everything moves at once. Fast but catastrophic on failure. Only for small systems.
-- **Strangler fig** - new traffic to new system, old traffic drains. Safe but slow. Preferred for anything load-bearing.
-- **Parallel run** - both systems run, outputs compared. Expensive but safest for data-critical systems.
+**Step 4: Specify recovery before cutover.** Use the recovery required for release: rollback, restore, compensation or roll-forward must match the effects that persist and the agreed recovery limits. Do not route to an old binary that cannot read new writes. Identify the irreversible boundary, required authority, operator and stop conditions; exercise the chosen recovery in a permitted representative environment before release. Missing recovery evidence blocks cutover, not useful planning or reversible preparation.
 
-**Step 4: Write the rollback before the migration starts.** "If we move service X and it fails, we route back to old within [time]." No rollback = no migration.
+**Step 5: Define phase acceptance.** Check supported old/new version combinations, no lost updates, tenant isolation and relevant service-level targets. Record baseline, environment, thresholds, evidence and operating owner rather than imposing generic percentages.
 
-**Step 5: Define success metrics per phase.** Not "migration complete" - that's a project plan. "Error rate same or lower, latency within 10%, zero data loss, team can operate without FDE." Measurable, per service.
-
-Write migration strategy to `decisions.md` under `## Migration`. Each service gets a row: type, order, cutover method, rollback, success metric.
+In a bound engagement, propose the migration plan in `decisions.md` under `## Migration`. Each step records compatibility prerequisites, cutover/data handling, recovery and acceptance evidence. Standalone work returns the same plan directly.
 
 ## When the plan changes mid-engagement
 
@@ -164,4 +153,4 @@ First visible slice goes to Marco, not Priya: he is the one whose morning change
 - No kill list, no finished plan.
 - No **Kill if** on a Now PR, that PR is hope.
 - Estimates are ranges, not promises. Name the assumptions and the observation that voids them.
-- Migrations: leaf nodes first, core last. Rollback before cutover.
+- Migrations: compatibility determines order; verified recovery precedes cutover.

package/skills/poc/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/qa/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "65b965474e847f240138c1ada0ee7d982affc421a24a0a7a37970021f8269a03",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/qa/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/qa/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/review/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "7c8310fbceb8768b6997c758bf041bf97be66a3e8cc1de5df2aa84e2771a374b",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/review/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/review/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields:

package/skills/runbook/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "5488cddb607cb05face73ad1a838dd87babb00716544793f36997ca15dcb1560",
-    "references/close.md": "7403c49ceef1c3d5347efbef9c45af3bd0f5927d595b2df3d4e35eadfd154344",
+    "references/close.md": "b3dbc1ecef12ee1c9d298e32a21d87ce61c9f6c88039d7a8b19970c6e3f21254",
     "references/encode-pattern.md": "3be7bf9d0f69af31659423c54d6023a4af1556e2ce200fb025bf64d0757de4d8",
     "references/runbook.md": "1233aa1943da8db6d3c7624b7a54b3a1afc340b97e16f95d70b42cdbf521b63c",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27"

package/skills/runbook/references/close.md

@@ -2,6 +2,8 @@
 
 **Context:** apply [task context and evidence](task-context.md) before using the named records below.
 
+For a standalone handoff draft, use the supplied notes and project evidence; no customer record is required. The `fde handoff` CLI exports an existing record. Use it only when a record is selected, not to create one merely for a draft.
+
 **Enter when:** the engagement is ending - the customer team must run this without the FDE.
 
 **Read first:** for standalone work, use the supplied permitted operating notes, evidence and ownership; no engagement binding or CLI command is required. For a bound engagement, use bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Never initialize records merely to draft a handoff. Build the picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for code paths needed by the successor.

package/skills/ship/.fde-generated.json

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "3ed6862aac292e971af7c0a7f5a68968b89b056be60f3cdc883f51534984c1fc",
-    "references/build.md": "b2027776d4d66f9bc88731d2b7d0c23b33679da21dbc6bb591c75035e2478d62",
+    "references/build.md": "3f8b5e52eb874ee4e99db5e0b70d1ccca1134f667a39279d6b4e55629832ae75",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
@@ -11,6 +11,6 @@
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
     "references/task-context.md": "28684273e9d6edf1d05fb02c96caf4223e19b73e7ae840bdec2ff0bf06e3bc27",
-    "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
+    "references/verification.md": "62bb4fb40d9b71c6481c57a4564bcc98c4014a8be5d4aedfe1eb3f7f90d5e1f7"
   }
 }

package/skills/ship/references/build.md

@@ -9,9 +9,9 @@ Use the permitted context and authority in [task context](task-context.md). This
 1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
-4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.
+4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
 5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
 
 ## Deliverable and acceptance
 

package/skills/ship/references/verification.md

@@ -13,6 +13,8 @@ Use [task context](task-context.md). This method returns evidence directly or wr
 5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
 6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
 
+For performance claims, identify the measured bottleneck and compare before/after runs under comparable workload, environment and cache conditions. Repeat enough to distinguish a change from noise, retain correctness checks, and report unmatched conditions or uncertainty rather than claiming an unsupported improvement. Use the project's existing profiling and benchmark tools.
+
 ## Receipt
 
 Use one compact entry per check or a table with these fields: