fdeops 3.9.20 → 3.10.0

package/README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**Memory + methodology + skills, in one kit.** Skill packs teach your AI agent how to build. None of them remember who the client is, what was decided, or what's safe to ship. FDEOps adds the missing layer: a private fieldbook per engagement (`.fde/`), a field methodology (land → close), and one `@fde` skill that routes it all. 
+**Memory + methodology + skills, in one kit.** Skill packs - BMAD, Spec-Kit, [mattpocock/skills](https://github.com/mattpocock/skills) - teach your AI agent how to *build*. None of them remember who the client is, what you promised them, or who agreed it was delivered. FDEOps adds the missing layer: a private fieldbook per engagement (`.fde/`), a field methodology (land → close), and one `@fde` skill that routes it all. 
 
 Built for Forward Deployed Engineers, and anyone embedded in client work: consultants, agency developers, solutions architects, fractional CTOs. Feels like a second brain; behaves like a defensible record (dated, sourced, yours).
 
@@ -40,19 +40,35 @@ Same client folder every time (`~/fde-engagements/<client>/.fde/`). Your AI codi
 
 ---
 
-## Quickstart
-
-**1. Install** (pick one)
+## See it in 60 seconds (no client, no install)
 
 ```bash
-npx skills add suboss87/fdeops          # Cursor, Codex, and skills-compatible agents
+npx fdeops demo
 ```
 
+Walks one fake engagement end to end with the **real** commands: messy kickoff notes → proposed updates → you confirm → cold session reload → meeting prep → dated receipts → the fieldbook page. Nothing of yours is read, nothing leaves the machine, and it lives in a throwaway `~/fde-engagements/.demo/` that never appears in your portfolio. Remove it with `npx fdeops demo --clean`.
+
+Or watch it first. One real session below - day 1 kickoff notes, the next morning's cold start, and "when did we agree to that?" six weeks later. Every line is the CLI's own output; only the typing pace is staged, and you can re-record it yourself with [`media/record-session.sh`](media/record-session.sh):
+
+<p align="center"><img alt="A real fdeops session: messy kickoff notes routed into dated memory after you confirm, then a cold session that already knows the client, a grounded sponsor-meeting brief, and dated receipts" src="media/session.gif" width="900" /></p>
+
+Note the two things a chat window cannot do: **nothing is written until you confirm the routing**, and the `<private>` block in those notes lands sealed on disk as `(private - redacted)` - it never appears in `resume`, `prep`, `receipts`, or the dashboard.
+
+---
+
+## Quickstart
+
+**1. Install.** Claude Code gets session hooks (context loads before you type); everywhere else the same fieldbook loads when you ask.
+
 ```text
 /plugin marketplace add suboss87/fdeops # Claude Code
 /plugin install fdeops@fdeops
 ```
 
+```bash
+npx skills add suboss87/fdeops          # Cursor, Codex, and skills-compatible agents
+```
+
 **2. Bind once** - inside the client workspace (setup only; not a daily habit):
 
 ```bash
@@ -73,13 +89,15 @@ npx fdeops resume                 # prints a short "where we are" for this clien
 
 `@fde` routes and updates the fieldbook - you confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
 
+**It's working if** `npx fdeops resume` prints this client's phase, trust signal, and next action - and tomorrow's session starts from that instead of a blank chat.
+
 <details>
 <summary><strong>Other install paths</strong> · scan · env</summary>
 
 - **Cursor / Codex / Copilot / Gemini CLI:** `npx fdeops adapters .` - [adapters/](adapters/README.md)
 - **Local LLMs (Ollama, LM Studio, llama.cpp):** load `skills/fde/SKILL.md` as the system prompt - [guide](adapters/LOCAL-LLM.md)
 - **Manual / air-gapped:** `git clone https://github.com/suboss87/fdeops.git && cd fdeops && node bin/install.js`
-- **Try without install:** `npx fdeops scan` - day-1 recon (heuristic leads, not findings)
+- **Try without install:** `npx fdeops demo` - the whole loop on a fake client · `npx fdeops scan` - day-1 recon of this repo (heuristic leads, not findings)
 - **Requires:** [Node.js](https://nodejs.org) >= 18 for the CLI and adapters
 - **Advanced:** `FDEOPS_ENGAGEMENT` overrides the workspace registry. Full matrix: [docs/install.md](docs/install.md)
 
@@ -126,6 +144,25 @@ Overlays for regulated domains (AI, fintech, healthcare, government) activate on
 
 ---
 
+## The field methods
+
+You never pick one - you describe the situation and `@fde` routes. They are listed here because the methodology is the product, and it should be readable before you install anything. **37 methods across 6 domains**, each one a method (the thinking, the artifact it drafts, the checkpoint with you), not advice:
+
+| Domain | Methods |
+|--------|---------|
+| **1. Embed & Trust** - first days, access, credibility | [land](skills/fde/references/land.md) · [audit](skills/fde/references/audit.md) · [stakeholder-radar](skills/fde/references/stakeholder-radar.md) · [trust-engineering](skills/fde/references/trust-engineering.md) · [scope-defense](skills/fde/references/scope-defense.md) |
+| **2. Discover & Diagnose** - find the real problem | [discover](skills/fde/references/discover.md) · [assumption-audit](skills/fde/references/assumption-audit.md) · [use-case-scoring](skills/fde/references/use-case-scoring.md) · [sketch](skills/fde/references/sketch.md) |
+| **3. Plan & Align** - sequence it, sell it | [plan](skills/fde/references/plan.md) · [business-case](skills/fde/references/business-case.md) · [options-analysis](skills/fde/references/options-analysis.md) · [initiative-triage](skills/fde/references/initiative-triage.md) |
+| **4. Build & Guard** - the work, and not breaking their business | [build](skills/fde/references/build.md) · [incremental-build](skills/fde/references/incremental-build.md) · [test-on-legacy](skills/fde/references/test-on-legacy.md) · [blast-radius](skills/fde/references/blast-radius.md) · [debug](skills/fde/references/debug.md) · [rescue](skills/fde/references/rescue.md) · [security-audit](skills/fde/references/security-audit.md) · [observability](skills/fde/references/observability.md) |
+| **5. Ship & Verify** - production, with a way back | [ship](skills/fde/references/ship.md) · [review](skills/fde/references/review.md) · [rollback-drill](skills/fde/references/rollback-drill.md) · [qa-live](skills/fde/references/qa-live.md) |
+| **6. Operate & Close** - the part that decides renewals | [status](skills/fde/references/status.md) · [demo-prep](skills/fde/references/demo-prep.md) · [debrief](skills/fde/references/debrief.md) · [exec-narrative](skills/fde/references/exec-narrative.md) · [dashboard](skills/fde/references/dashboard.md) · [multi-customer-ops](skills/fde/references/multi-customer-ops.md) · [close](skills/fde/references/close.md) · [handoff-engineering](skills/fde/references/handoff-engineering.md) · [pattern-extract](skills/fde/references/pattern-extract.md) · [red-team](skills/fde/references/red-team.md) · [ingest](skills/fde/references/ingest.md) · [ingest-connect](skills/fde/references/ingest-connect.md) |
+
+Plus five overlays that activate on signal rather than being chosen - [ai](skills/fde/references/ai.md) · [artifacts](skills/fde/references/artifacts.md) · [fintech](skills/fde/references/fintech.md) · [healthcare](skills/fde/references/healthcare.md) · [gov](skills/fde/references/gov.md) - which add the checks that domain demands to whatever method is already running.
+
+Every method, with the exact phrases that route to it: **[docs/skills-reference.md](docs/skills-reference.md)**.
+
+---
+
 ## Engagement memory (`.fde/`)
 
 The **fieldbook** is the system of record for the embed - one folder per client, plain markdown you can read, grep, and take with you:

package/adapters/LOCAL-LLM.md

@@ -62,7 +62,7 @@ The model reads SKILL.md, routes to the right skill, and produces artifacts in y
 
 ## Model size recommendations
 
-The methodology is detailed (35 skills, routing logic, evidence format, memory contract). Larger models handle it better:
+The methodology is detailed (37 methods, routing logic, evidence format, memory contract). Larger models handle it better:
 
 | Model class | Experience |
 |-------------|-----------|

package/adapters/README.md

@@ -31,4 +31,4 @@ Defaults to the current directory if no path is given. Existing files are never
 
 ## The principle
 
-The adapter only tells the tool **where the brain is and how to behave**. All the method - the 35 skills, the overlays, the memory contract - lives once in `skills/fde/SKILL.md`. Update the brain, every platform gets it. That's why fdeops feels native in whatever the FDE already uses, without five things to keep in sync.
+The adapter only tells the tool **where the brain is and how to behave**. All the method - the 37 methods, the overlays, the memory contract - lives once in `skills/fde/SKILL.md`. Update the brain, every platform gets it. That's why fdeops feels native in whatever the FDE already uses, without five things to keep in sync.

package/bin/check.js

@@ -76,6 +76,29 @@ for (const f of requiredReferences) {
 }
 ok('phase references')
 
+// A method reference teaches by showing one engagement, not by describing a shape:
+// every judgment-heavy reference carries a worked example that names the memory
+// file the work lands in. Prose-only guidance drifts into advice nobody can apply.
+const exampleReferences = [
+  'land.md', 'discover.md', 'plan.md', 'build.md', 'ship.md', 'close.md',
+  'status.md', 'stakeholder-radar.md', 'options-analysis.md', 'business-case.md',
+  'assumption-audit.md', 'scope-defense.md',
+]
+for (const f of exampleReferences) {
+  const p = path.join(root, 'skills', 'fde', 'references', f)
+  if (!fs.existsSync(p)) { fail(`missing method reference skills/fde/references/${f}`); continue }
+  const body = fs.readFileSync(p, 'utf8')
+  const section = (body.match(/\n## Worked example\n([\s\S]*?)(?=\n## |$)/) || [])[1]
+  if (!section) {
+    fail(`references/${f} missing ## Worked example`)
+  } else if (section.trim().length < 400) {
+    fail(`references/${f} worked example is too thin to teach anything`)
+  } else if (!/`[a-z-]+\.md`/.test(section)) {
+    fail(`references/${f} worked example never names the memory file the work lands in`)
+  }
+}
+ok(`worked examples (${exampleReferences.length} references)`)
+
 const router = read('skills/fde/SKILL.md')
 if (!router.includes('memory contract')) fail('SKILL.md must define the memory contract')
 // every references/<name>.md the router mentions must exist
@@ -88,6 +111,94 @@ for (const refFile of mentioned) {
 }
 ok(`router dispatch (${mentioned.length} reference targets verified) + memory contract`)
 
+// Public claims must match the router. The docs advertise a method count and a
+// per-domain list; both drifted from SKILL.md once (ingest / ingest-connect
+// routed but undocumented), and a number nobody can verify is worse than none.
+{
+  // Every routing row must parse. A row this misses is a method that could go
+  // undocumented for free, so an unparsed row is a hard failure, not a silent skip.
+  const routed = new Set()
+  const routing = (router.split('## Routing - 6 domains')[1] || '').split('**Overlays')[0]
+  const methodCell = line => (line.split('|')[2] || '').trim().replace(/\s*\([^)]*\)\s*$/, '')
+  for (const line of routing.split('\n')) {
+    if (!/^\|/.test(line)) continue
+    // A row that names a method but no reference would route that method while
+    // nothing requires anyone to document it - shape checks can only police rows
+    // they recognise, so name a method here and you must name its reference.
+    if (!/references\/[a-z0-9-]+\.md/.test(line)) {
+      const orphan = methodCell(line)
+      // a method name, not a `-` placeholder (CLI-only rows) or a `---` separator
+      if (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(orphan)) {
+        fail(`SKILL.md routes '${orphan}' without naming a reference: ${line.trim().slice(0, 80)}`)
+      }
+      continue
+    }
+    // Candidate rows are selected on the reference name in ANY form, then the
+    // shape is enforced - a row this cannot read must fail, never be skipped,
+    // or a method could go undocumented by being written unusually.
+    if (!/`references\/[a-z0-9-]+\.md`/.test(line)) {
+      fail(`SKILL.md routing row must name its reference as \`references/<name>.md\`: ${line.trim().slice(0, 80)}`)
+      continue
+    }
+    // | You hear | <method> | <cell mentioning references/*.md> |
+    const method = methodCell(line)
+    if (!/^[a-z0-9-]+$/.test(method)) {
+      fail(`check.js cannot read the method name in a SKILL.md routing row: ${line.trim().slice(0, 80)}`)
+      continue
+    }
+    routed.add(method)
+  }
+  if (!routed.size) fail('check.js could not parse the SKILL.md routing table')
+
+  // docs/skills-reference.md is the canonical per-method list: one row per
+  // method inside the six domain tables, ending at the Overlays section.
+  const reference = read('docs/skills-reference.md')
+  const documented = new Set()
+  let documentedRows = 0
+  for (const line of reference.split('### Overlays')[0].split('\n')) {
+    const m = line.match(/^\|\s*\[([a-z0-9-]+)\]\(\.\.\/skills\/fde\/references\/([a-z0-9-]+\.md)\)/)
+    if (!m) continue
+    documentedRows++
+    documented.add(m[1])
+    // A link nobody followed is the same unverifiable claim this gate exists for:
+    // the target must exist, and it must be the method the text names.
+    if (m[2] !== `${m[1]}.md`) {
+      fail(`docs/skills-reference.md links [${m[1]}] at references/${m[2]}`)
+    } else if (!fs.existsSync(path.join(root, 'skills', 'fde', 'references', m[2]))) {
+      fail(`docs/skills-reference.md links references/${m[2]}, which does not exist`)
+    }
+  }
+  if (documented.size !== documentedRows) {
+    fail(`docs/skills-reference.md lists ${documentedRows} method rows for ${documented.size} methods - a duplicate row inflates the count`)
+  }
+  const undocumented = [...routed].filter(name => !documented.has(name))
+  if (undocumented.length) {
+    fail(`SKILL.md routes skill(s) missing from docs/skills-reference.md: ${undocumented.join(', ')}`)
+  }
+  // and the other direction: a documented method nothing routes to is a method
+  // the agent can never reach, advertised anyway.
+  const unrouted = [...documented].filter(name => !routed.has(name))
+  if (unrouted.length) {
+    fail(`docs/skills-reference.md documents method(s) SKILL.md never routes to: ${unrouted.join(', ')}`)
+  }
+  for (const rel of ['docs/skills.md', 'docs/skills-reference.md']) {
+    const body = read(rel)
+    // `-` is a word boundary, so \bingest\b matches inside `ingest-connect`:
+    // a method could disappear from the docs behind a hyphenated sibling.
+    const absent = [...documented].filter(name => !new RegExp(`(?<![\\w-])${name}(?![\\w-])`).test(body))
+    if (absent.length) fail(`${rel} does not list method(s): ${absent.join(', ')}`)
+    // every count claim, not just the first: an earlier sentence must not shadow
+    // a stale headline (or the reverse).
+    const claims = [...body.matchAll(/(\d+)\s+methods/g)].map(m => Number(m[1]))
+    if (!claims.length) fail(`${rel} must state how many methods it documents`)
+    const wrong = [...new Set(claims.filter(n => n !== documented.size))]
+    if (wrong.length) {
+      fail(`${rel} claims ${wrong.join('/')} methods; ${documented.size} are documented`)
+    }
+  }
+  ok(`public method count is verifiable (${documented.size} documented, ${routed.size} routed)`)
+}
+
 const install = read('bin/install.js')
 if (install.includes('scaffoldFdeInProject(process.cwd())')) {
   fail('install.js must not auto-scaffold .fde in customer cwd')
@@ -104,8 +215,34 @@ if (read('package.json').includes('postinstall')) {
 }
 
 const readme = read('README.md')
-if (readme.includes('demo.gif')) fail('README must not embed demo.gif (removed for clarity)')
-else ok('README no demo gif')
+// The README shows one recording: media/session.gif, a real CLI session.
+// media/demo.gif is a hand-typed mock kept for history - it must never be embedded,
+// or the front door shows output no command actually produced.
+if (readme.includes('demo.gif')) fail('README must not embed media/demo.gif (staged mock, not real CLI output)')
+else ok('README no staged demo gif')
+
+if (!readme.includes('media/session.gif')) {
+  fail('README must embed media/session.gif (the recorded session is the front door)')
+} else if (!readme.includes('media/record-session.sh')) {
+  fail('README must link media/record-session.sh next to the recording, so it can be re-recorded')
+} else {
+  const gifPath = path.join(root, 'media', 'session.gif')
+  const rec = path.join(root, 'media', 'record-session.sh')
+  if (!fs.existsSync(gifPath) || fs.statSync(gifPath).size < 50000) fail('media/session.gif missing or too small')
+  else if (!fs.existsSync(rec)) fail('media/record-session.sh missing - the recording must be reproducible')
+  else if (!fs.existsSync(path.join(root, 'media', 'session.cast'))) fail('media/session.cast missing - keep the source recording next to the gif')
+  else ok('README recorded session (gif + reproducible recorder + cast)')
+}
+
+// Every repo-relative README link and image must resolve, or the front door 404s.
+const brokenLinks = []
+for (const m of readme.matchAll(/(?:\]\(|src=")([^)"#\s]+)(?:\)|")/g)) {
+  const target = m[1]
+  if (/^(https?:|mailto:|#|\/)/.test(target)) continue
+  if (!fs.existsSync(path.join(root, target))) brokenLinks.push(target)
+}
+if (brokenLinks.length) fail(`README links to missing paths: ${brokenLinks.join(', ')}`)
+else ok('README links all resolve')
 
 for (const section of [
   'How it works',
@@ -180,7 +317,15 @@ if (!fs.existsSync(path.join(root, 'docs', 'schema.md'))) fail('docs/schema.md m
 else ok('docs/schema.md')
 
 if (!fs.existsSync(path.join(root, 'SECURITY.md'))) fail('SECURITY.md missing')
-else ok('SECURITY.md')
+else {
+  // A reporting section that only offers GitHub Security Advisories is a dead end
+  // whenever private reporting is off for the repo (that page 403s), which is how
+  // issue #9 sat unreported. Require a channel that does not depend on a repo setting.
+  const sec = read('SECURITY.md')
+  if (!/[\w.+-]+@[\w-]+\.[\w.]+/.test(sec)) {
+    fail('SECURITY.md must give a reporting channel that works when GitHub private reporting is off (an email address)')
+  } else ok('SECURITY.md (reachable reporting channel)')
+}
 
 const exampleFiles = ['reality.md', 'decisions.md', 'delivery.md', 'stakeholders.md', 'assumptions.md']
 for (const f of exampleFiles) {
@@ -361,6 +506,68 @@ if (!fs.existsSync(path.join(root, 'mcp', 'fdeops-ingest', 'server.js'))) {
   ok('ingest MCP + connect recipes + skill reference')
 }
 
+// Agent Plugins 1.0.0 conformance (agent-plugins.org/specification).
+// plugin.json has a closed schema: an illegal field is fatal to the whole plugin,
+// and an mcp.json whose $schema version differs from plugin.json silently disables MCP.
+const AP_VERSION = '1.0.0'
+const AP_PLUGIN_SCHEMA = `https://agent-plugins.org/schemas/${AP_VERSION}/plugin.schema.json`
+const AP_MCP_SCHEMA = `https://agent-plugins.org/schemas/${AP_VERSION}/mcp.schema.json`
+const AP_MANIFEST_FIELDS = [
+  '$schema', 'name', 'version', 'description', 'author',
+  'homepage', 'repository', 'license', 'keywords', 'extensions',
+]
+
+const apManifest = JSON.parse(read('plugin.json'))
+const apUnknown = Object.keys(apManifest).filter(k => !AP_MANIFEST_FIELDS.includes(k))
+if (apManifest.$schema !== AP_PLUGIN_SCHEMA) {
+  fail(`plugin.json $schema must be ${AP_PLUGIN_SCHEMA}`)
+} else if (apUnknown.length) {
+  fail(`plugin.json has non-portable field(s) ${apUnknown.join(', ')} - client-specific data belongs under extensions`)
+} else if (!/^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(apManifest.name)) {
+  fail(`plugin.json name "${apManifest.name}" violates Agent Plugins name constraints`)
+} else if (apManifest.version !== pkg.version) {
+  fail(`version mismatch package.json ${pkg.version} vs plugin.json ${apManifest.version}`)
+} else ok('agent plugins manifest')
+
+const apMcp = JSON.parse(read('mcp.json'))
+const apServers = apMcp.mcpServers || {}
+if (apMcp.$schema !== AP_MCP_SCHEMA) {
+  fail(`mcp.json $schema must be ${AP_MCP_SCHEMA} (a version mismatch with plugin.json disables MCP)`)
+} else if (Object.keys(apMcp).some(k => k !== '$schema' && k !== 'mcpServers')) {
+  fail('mcp.json permits only $schema and mcpServers')
+} else {
+  for (const [name, srv] of Object.entries(apServers)) {
+    if (srv.type !== 'stdio') fail(`mcp.json ${name}: fdeops ships stdio servers only (local-only core)`)
+    else if (!srv.command || (/[\s/]/.test(srv.command) && !srv.command.startsWith('./'))) {
+      fail(`mcp.json ${name}: command must be one executable token or a ./-relative path`)
+    } else if ((srv.args || []).some(a => path.isAbsolute(a))) {
+      fail(`mcp.json ${name}: args must use \${PLUGIN_ROOT}, never an absolute path`)
+    } else if (Object.keys(srv.env || {}).some(k => k === 'PLUGIN_ROOT' || k === 'PLUGIN_DATA')) {
+      fail(`mcp.json ${name}: env must not set PLUGIN_ROOT/PLUGIN_DATA (client-supplied)`)
+    }
+  }
+  const ingest = apServers['fdeops-ingest']
+  const rootArg = ingest && (ingest.args || []).find(a => String(a).startsWith('${PLUGIN_ROOT}/'))
+  const target = rootArg ? String(rootArg).replace('${PLUGIN_ROOT}/', '') : ''
+  if (!ingest) fail('mcp.json must declare the fdeops-ingest stdio server')
+  else if (!rootArg) fail('mcp.json fdeops-ingest: args must include a ${PLUGIN_ROOT}-relative server path')
+  else if (!fs.existsSync(path.join(root, target))) fail(`mcp.json fdeops-ingest points at missing ${target}`)
+  else ok('agent plugins mcp config')
+}
+
+// A manifest that ships only in git and not in the npm tarball is the worst kind of drift.
+for (const manifest of ['plugin.json', 'mcp.json']) {
+  if (!(pkg.files || []).includes(manifest)) fail(`package.json files must include ${manifest}`)
+  else ok(`${manifest} published to npm`)
+}
+
+for (const entry of fs.readdirSync(path.join(root, 'skills'))) {
+  const dir = path.join(root, 'skills', entry)
+  if (!fs.statSync(dir).isDirectory()) continue
+  if (!fs.existsSync(path.join(dir, 'SKILL.md'))) fail(`skills/${entry}/ has no SKILL.md - clients skip it`)
+  else ok(`skill ${entry} discoverable`)
+}
+
 if (!fs.existsSync(path.join(root, '.github', 'ISSUE_TEMPLATE', 'bug_report.yml'))) {
   fail('GitHub issue template missing')
 } else ok('issue templates')