fdeops 5.1.3 → 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.3",
+  "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.3",
+  "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.3",
+  "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/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/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/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.