fdeops 4.0.2 → 4.0.4

package/adapters/AGENTS.md

@@ -14,9 +14,9 @@ Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client
 
 ## Engagement memory
 
-Read and write engagement files under the workspace's bound engagement: run `fde resume` to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
+Read and write engagement files under the workspace's bound engagement: follow the skill’s entry rule to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
 
-On entry, run `fde resume` (fallback `node ~/.claude/fdeops/fde.js resume`) to load `context.md`. Use the CLI for deterministic work - `fde scan | log | receipts | status | dashboard` - instead of improvising shell.
+Follow **First-use preferences** and **Entry (every session)** in `skills/fde/SKILL.md` for setup, context reuse and refresh. Use the CLI for deterministic work - `fde scan | log | receipts | status | dashboard` - instead of improvising shell.
 
 ## Voice
 

package/adapters/GEMINI.md

@@ -14,9 +14,9 @@ Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client
 
 ## Engagement memory
 
-Read and write engagement files under the workspace's bound engagement: run `fde resume` to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
+Read and write engagement files under the workspace's bound engagement: follow the skill’s entry rule to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
 
-On entry, run `fde resume` (fallback `node ~/.claude/fdeops/fde.js resume`) to load `context.md`. Use the CLI for deterministic work - `fde scan | log | receipts | status | dashboard` - instead of improvising shell.
+Follow **First-use preferences** and **Entry (every session)** in `skills/fde/SKILL.md` for setup, context reuse and refresh. Use the CLI for deterministic work - `fde scan | log | receipts | status | dashboard` - instead of improvising shell.
 
 ## Voice
 

package/adapters/LOCAL-LLM.md

@@ -7,7 +7,7 @@ The FDEOps CLI and offline dashboard need Node.js and Git, not a model. AI-assis
 1. Download FDEOps, your agent host and your model while online. After that, the CLI operates offline. Model/provider configuration belongs to the host; FDEOps does not start or configure an inference server.
 2. From the client workspace, run `node /path/to/fdeops/bin/fde.js resume --init my-client` to create and bind a local record.
 3. Make `skills/fde/SKILL.md` and its references available to the host. Use the host's documented skill/file mechanism. Give it the FDEOps CLI path and permission to read the bound record and execute the requested commands.
-4. Start with `fde resume` and ask for the next action. Inspect the tool calls, cited records and any proposed writes before trusting the workflow.
+4. Follow **First-use preferences** and **Entry (every session)** in `skills/fde/SKILL.md`, then ask for the next action. Inspect the tool calls, cited records and any proposed writes before trusting the workflow.
 
 Use `fde recall <topic>` for relevant evidence. `resume` and `recall` default to a 16 KiB output ceiling; `--max-bytes 4096` requests a smaller allowance. This limits FDEOps output, not the host's entire context window. Keep unrelated transcripts and tools out of the active context. Private blocks must stay out of direct file reads as well as prompts.
 

package/adapters/copilot-instructions.md

@@ -14,9 +14,9 @@ Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client
 
 ## Engagement memory
 
-Read and write engagement files under the workspace's bound engagement: run `fde resume` to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
+Read and write engagement files under the workspace's bound engagement: follow the skill’s entry rule to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
 
-On entry, run `fde resume` (fallback `node ~/.claude/fdeops/fde.js resume`) to load `context.md`. Use the CLI for deterministic work - `fde scan | log | receipts | status | dashboard` - instead of improvising shell.
+Follow **First-use preferences** and **Entry (every session)** in `skills/fde/SKILL.md` for setup, context reuse and refresh. Use the CLI for deterministic work - `fde scan | log | receipts | status | dashboard` - instead of improvising shell.
 
 ## Voice
 

package/adapters/cursor.fde.mdc

@@ -19,9 +19,9 @@ Do **not** load `@fde` for a one-line typo in an unbound repo. On a bound client
 
 ## Engagement memory
 
-Read and write engagement files under the workspace's bound engagement: run `fde resume` to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
+Read and write engagement files under the workspace's bound engagement: follow the skill’s entry rule to resolve it (binding created once with `fde resume --init <name>`; default `~/fde-engagements/<name>/.fde/`). `FDEOPS_ENGAGEMENT` (expand `~`) overrides when set. Use `./.fde/` only when the engagement approves it and it is gitignored.
 
-**On every session entry (before other work):** run `fde triage` (fallback `node ~/.claude/fdeops/fde.js triage`, then `fde resume`). Lead with that TRIAGE block - trust, phase, open risks, next action, record owner/hash. Do not invent stakeholders or status.
+Follow **First-use preferences** and **Entry (every session)** in `skills/fde/SKILL.md` for setup, context reuse and refresh. The entry packet includes TRIAGE; use it for trust, phase, open risks and next action. Do not invent stakeholders or status.
 
 You run the CLI for deterministic work - `fde scan | log | debrief | prep | doctor | receipts | status | dashboard` - instead of improvising shell or handing commands to the human.
 

package/bin/fde.js

@@ -36,7 +36,7 @@ const { createMemoryApi } = require('./lib/memory')
 const { createTrustApi } = require('./lib/trust')
 const vault = require('./lib/vault')
 const context = require('./lib/context')
-const { sourceReference, hasSource, datedDecisions } = require('./lib/provenance')
+const { sourceReference, sourceReferences, hasSource, datedDecisions } = require('./lib/provenance')
 const { deliverySummary } = require('./lib/delivery-gaps')
 
 const HOME = os.homedir()
@@ -67,8 +67,13 @@ function maskReport(value) {
   if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskReport(item)]))
   return value
 }
-function maskedSections(sections, maxBytes) {
-  return context.boundedSections(sections.map(text => masking.mask(text)), maxBytes)
+function maskedSections(sections, maxBytes = context.DEFAULT_BYTES, heading = '') {
+  // Reserve identity before sharing the remaining budget between excerpts.
+  // Pathological path lengths remain explicitly clipped rather than exhausting policy space.
+  const maskedHeading = masking.mask(heading)
+  const prefix = heading ? (Buffer.byteLength(maskedHeading) <= 1024 ? maskedHeading
+    : context.clipMaskedUtf8(maskedHeading, 900) + '\n[Identity path truncated; use fde resume --bind to inspect.]') + '\n\n' : ''
+  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']
@@ -1459,12 +1464,12 @@ function cmdResume(args) {
   process.stdout.write(maskedSections([
     policy ? `CLIENT POLICY - trust-profile.md\n${policy}` : '',
     preferences.work ? `WORKING PREFERENCES: ${preferences.work}. Starting help: ${preferences.start}.\n${setup.nextStep(preferences)}\nThis is a starting preference, not a client fact; current instructions and engagement state take precedence.` : '',
-    `${intro}\n\nENGAGEMENT: ${eng}`,
+    intro,
     success ? `CURRENT GOALS & ACCEPTANCE - success.md\n${success}` : '',
     risks ? `OPEN RISKS - risks.md\n${extractRisks(eng).map(r => r.text).join('\n') || '(none recorded)'}` : '',
     `VALUE LEDGER - delivery.md\n${parseValueLedger(eng).rows.map(r => formatValueLedgerLine(r) + '; source: ' + (r.evidence || '(missing)')).join('\n') || '(none recorded)'}`,
     `WORKING CONTEXT - context.md\n${ctx ? resumeView(ctx) : '(no context.md yet)'}`,
-  ], maxBytes))
+  ], maxBytes, `ENGAGEMENT: ${eng}`))
 }
 
 // Token discipline: context.md grows every session (the session-stop hook
@@ -2083,7 +2088,10 @@ function withDebriefRecords(eng, apply, files = ['decisions.md', 'risks.md', 'de
         } catch (_) { failed.push(path.basename(target)) }
       }
       if (failed.length) throw new Error(`${error.message}; recovery could not restore ${failed.join(', ')}. Inspect these records and the pending proposal before retrying.`)
-      throw new Error(`${error.message}; no record changes kept. The proposal is retained; retry after resolving the cause.`)
+      const recovery = snapshots.get(path.join(eng, DEBRIEF_PROPOSE))
+        ? 'The proposal is retained; inspect it with fde debrief --review before retrying.'
+        : 'No pending proposal was retained; review your input before retrying.'
+      throw new Error(`${error.message}; no record changes kept. ${recovery}`)
     } finally { debriefTransactionActive = false }
   }
   return lockAt(0)
@@ -2156,7 +2164,7 @@ function routeDebriefInput(eng, input, { dry, force, sealed = [], allowReplay =
     })
   }
   const repeats = repeatedDebriefStatements(eng, input)
-  if (repeats.length && !dry && !allowReplay) throw new Error('source-backed statement already recorded; review the existing record and newer next action. Explicitly confirm a repeat with --allow-replay, or remove the repeated statement from the proposal.')
+  if (repeats.length && !dry && !allowReplay) throw new Error('source-backed statement already recorded; review the existing record and newer next action. Explicitly confirm a repeat with --allow-replay, or remove the repeated statement from your input or pending proposal.')
   const d = new Date()
   const date = d.toISOString().slice(0, 10)
   const counts = { decision: 0, risk: 0, delivery: 0, contact: 0, next: 0, signer: 0 }
@@ -2547,15 +2555,20 @@ function cmdReceipts(args) {
   const records = [], claims = []
   for (const file of [...recordFiles, ...workingFiles]) {
     const document = readClean(eng, file)
+    const scaffold = new Set((templatesDir() ? readClean(templatesDir(), file) : '').split('\n').map(line => line.trim()))
     const decisionSources = new Map()
     if (file === 'decisions.md') for (const entry of datedDecisions(document)) {
-      const source = sourceReference(entry.text)
-      for (let line = entry.line; line < entry.line + entry.text.split('\n').length; line++) decisionSources.set(line, source)
+      for (let line = entry.line; line < entry.line + entry.text.split('\n').length; line++) decisionSources.set(line, entry.text)
     }
     document.split('\n').forEach((line, i) => {
       if (!line.toLowerCase().includes(term.toLowerCase())) return
-      const source = decisionSources.get(i + 1) || sourceReference(line)
-      const hit = `  ${file}:${i + 1}  ${masking.mask(line.trim()).slice(0, 160)}${source ? ` [source: ${masking.mask(source).slice(0, 160)}]` : ' [source missing]'}${dirty.has(file) ? '  dirty file - review manual edits' : ''}`
+      const sourceText = decisionSources.get(i + 1) || line
+      const source = sourceReference(sourceText)
+      if (!source && scaffold.has(line.trim())) return
+      const sources = sourceReferences(sourceText)
+      const attribution = masking.mask(sources.join('; '))
+      const displayed = Buffer.byteLength(attribution) <= 320 ? attribution : context.clipMaskedUtf8(attribution, 240) + '… [sources truncated; use fde recall]'
+      const hit = `  ${file}:${i + 1}  ${context.clipMaskedUtf8(masking.mask(line.trim()), 160)}${source ? ` [${sources.length > 1 ? 'sources' : 'source'}: ${displayed}]` : ' [source missing]'}${dirty.has(file) ? '  dirty file - review manual edits' : ''}`
       ;(recordFiles.includes(file) && source ? records : claims).push({ file, hit })
     })
   }

package/bin/lib/context.js

@@ -14,6 +14,13 @@ function clipUtf8(text, bytes) {
   while (end > 0 && (buf[end] & 0xc0) === 0x80) end--
   return buf.subarray(0, end).toString('utf8')
 }
+// Masking aliases must stay whole so they remain recognizable and reversible.
+function clipMaskedUtf8(text, bytes) {
+  const clipped = clipUtf8(text, bytes)
+  if (clipped === text) return text
+  const open = clipped.lastIndexOf('[[')
+  return open > clipped.lastIndexOf(']]') ? clipped.slice(0, open) : clipped
+}
 function budgetArgs(args, defaultBytes = DEFAULT_BYTES) {
   const rest = [...args]
   let maxBytes = defaultBytes
@@ -91,4 +98,4 @@ function recallSections(documents, query, maxHits = 12, outputText = text => tex
     sections: selected.map(h => `${h.file}:${h.line}-${h.end} (lines in redacted view)\n${h.text}`),
   }
 }
-module.exports = { DEFAULT_BYTES, clipUtf8, budgetArgs, boundedSections, recallSections }
+module.exports = { DEFAULT_BYTES, clipUtf8, clipMaskedUtf8, budgetArgs, boundedSections, recallSections }

package/bin/lib/provenance.js

@@ -40,3 +40,13 @@ function datedDecisions(value) {
   return entries.sort((a, b) => a.date.localeCompare(b.date) || a.line - b.line)
 }
 module.exports.datedDecisions = datedDecisions
+
+// Display every explicit attribution without selecting a primary source.
+// Keep classification through sourceReference unchanged.
+function sourceReferences(value) {
+  const explicit = String(value || '').match(/\[source:[^\]\n]+\]/gi) || []
+  if (explicit.length) return [...new Set(explicit.map(sourceReference).filter(Boolean))]
+  const fallback = sourceReference(value)
+  return fallback ? [fallback] : []
+}
+module.exports.sourceReferences = sourceReferences

package/mcp/fdeops-ingest/package.json

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

package/package.json

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

package/plugin.json

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

package/skills/fde/SKILL.md

@@ -23,7 +23,7 @@ A one-line typo or compile error in a file that will not ship. On a bound client
 
 | What's happening | Sentence to say | You run | Then read |
 |---------|-----------------|---------|-----------|
-| **The brief is wrong** | "If this works, who in their company would have to agree that it worked?" | `fde resume` then discover | `references/discover.md` |
+| **The brief is wrong** | "If this works, who in their company would have to agree that it worked?" | Current entry packet (see Entry below), then discover | `references/discover.md` |
 | **They went quiet** | "Is this a process gap, or a trust problem?" | `fde log contact "…" --signal amber\|red\|green` | `references/rescue.md` |
 | **When did we agree?** | Don't argue from memory. Search the record. | `fde receipts <term>` | - |
 | **What's the outcome?** | A number nobody signed is claimed, not delivered. | `fde status` | `references/readout.md` |
@@ -64,7 +64,7 @@ Use `work` to tailor the help: single = focus on the bound client; multiple = po
 
 ## Entry (every session)
 
-1. `fde resume` (16 KiB by default, 4 KiB with compact setup; a byte ceiling, not a model token count). Read client constraints first, then signer, goals, risks, delivery ledger and current context. This command is the inspectable packet the session hook loads; never substitute a recursive read of `.fde/` or raw transcripts. If truncated or a decision needs evidence, run `fde recall <specific topic>`; narrow the query rather than loading the whole history. `--max-bytes 4096` reduces the allowance for smaller models. `--full` only when the complete log is explicitly needed.
+1. After the first-use setup check above, use one current `fde resume` packet (16 KiB by default, 4 KiB with compact setup; a byte ceiling, not a model token count). At each new user turn or task, run `fde resume` unless a fresh session-hook packet was supplied for that entry. Within this entry, reuse that hook packet or a packet from a CLI call made during the current turn/task only if its `ENGAGEMENT:` identity is visible, matches the current client binding, and freshness is certain. Never reuse a packet carried over from an earlier user turn or task: external edits may have changed the record. If the packet is absent, its identity or freshness is uncertain, the binding or engagement state changed since it was loaded (including your own writes or setup/masking changes), or the user asks for a refresh or “where are we,” run `fde resume` before using the context. Do not repeat an immediate entry call solely because the skill, an adapter, or a slash command was loaded. Read client constraints first, then signer, goals, risks, delivery ledger and current context; never substitute a recursive read of `.fde/` or raw transcripts. If truncated or a decision needs evidence, run `fde recall <specific topic>`; narrow the query rather than loading the whole history. `--max-bytes 4096` reduces the allowance for smaller models. `--full` only when the complete log is explicitly needed.
 2. **NO ENGAGEMENT:** ask "What should we call this client?" then **you** init. Pasted notes → debrief after bind.
 3. Playback 2-3 lines. `hygiene:` → offer `fde doctor`; **never auto-rewrite**.
 4. Route. Read **one** `references/*.md`. Confirm, then write.
@@ -90,7 +90,7 @@ Writes need a bind (`FDEOPS_ENGAGEMENT` or registry). Never install fdeops on in
 
 ## The memory contract
 
-1. **On entry:** `fde resume` only. Pull other `.fde/` files when the skill needs them.
+1. **On entry:** follow **Entry (every session)** above for the current packet and refresh rules. Retrieve additional evidence through targeted `fde recall` when needed.
 2. **Deliverable = memory.** The work *is* the `.fde/` file. The reference names which one.
 3. **Evidence.** Without a supplied source, a decision or measurement remains CLAIM. Use `[source: meeting YYYY-MM-DD]`, a PR/URL, transcript ID, or artifact path. The automatic log date is not attribution. ON RECORD means a source was supplied, not that it was authenticated or the customer approved. Never invent a source, signer, or acceptance.
 4. **No invented facts.** People, quotes, meetings, numbers: they said it or the repo shows it. Else `unknown - ask: <question>`.
@@ -211,7 +211,7 @@ Ready to build with no `terrain.md` / plan: discover or plan first. Takeover wit
 - Same six stages at any scale. Overlays carry the industry. Greenfield and brownfield change the first move inside ship, not the map.
 - Ground loop on a bound client: name → characterise → verify in the agreed environment → authorize release → log. A coding pack may write the function. `@fde` still owns done. When they disagree, their repo and the signer win.
 - Customer delivery needs a replayable acceptance check in the agreed environment; reuse existing criteria for routine fixes. Missing evidence means unproven, not an observed test failure. Never equate implementation-complete with deployed or customer-accepted.
-- Read `context.md` before speaking. One sharp question - never a barrage.
+- Read the current entry packet before speaking; follow **Entry (every session)** above. One sharp question - never a barrage.
 - Never invent people, meetings, or numbers - `unknown - ask:` beats a polished lie.
 - Every phase ends with its artifact written. No artifact, no "done."
 - Evidence on every claim. The FDE will be challenged on these files.