fdeops 3.26.0 → 3.27.0

package/bin/lib/provenance.js

@@ -0,0 +1,42 @@
+'use strict'
+
+// Source syntax records an inspectable attribution, never authenticates it.
+// The entry's automatic log date is deliberately not a source.
+const PLACEHOLDER = /^(?:none|unknown|tbd|pending|n\/?a|source|evidence|not provided|missing|\?+|-+)$/i
+function sourceReference(value) {
+  const text = String(value || '')
+  const explicit = text.match(/\[source:\s*([^\]\n]+)\]/i)
+  if (explicit) {
+    const source = explicit[1].trim()
+    return source && !PLACEHOLDER.test(source) ? source : ''
+  }
+  const url = text.match(/https?:\/\/[^\s<>\])|]+/i)
+  if (url) return url[0]
+  const id = text.match(/\b(?:PR\s*#\s*\d+|commit\s+[a-f0-9]{7,40}|(?:transcript|meeting|email|run)\s*(?:id\s*)?:\s*[\w][\w./#-]*)/i)
+  if (id && !PLACEHOLDER.test(id[0].split(':').pop().trim())) return id[0]
+  const dated = text.match(/\b(?:meeting|call|email|transcript)\b[^\n|]{0,60}\b\d{4}-\d{2}-\d{2}\b/i)
+  if (dated) return dated[0]
+  const file = text.match(/(?:^|[\s(])((?:[\w.-]+\/)*[\w.-]+\.(?:md|txt|csv|json|pdf|png|html|log))(?:$|[\s)#])/i)
+  return file ? file[1] : ''
+}
+module.exports = { sourceReference, hasSource: value => Boolean(sourceReference(value)) }
+
+// Both CLI bullets and the documented long-form decision format are records.
+// Keep the source with its decision body; a heading alone is not the evidence.
+function datedDecisions(value) {
+  const lines = String(value || '').split('\n')
+  const entries = []
+  for (let i = 0; i < lines.length; i++) {
+    const bullet = lines[i].match(/^\s*[-*]\s*\[(\d{4}-\d{2}-\d{2})\]\s*(.+)/)
+    const heading = lines[i].match(/^(#{2,3})\s+\[?(\d{4}-\d{2}-\d{2})(?:\]|\s+-)?\s+(.+)/)
+    if (bullet) entries.push({ date: bullet[1], text: lines[i].trim(), line: i + 1 })
+    else if (heading) {
+      let end = i + 1
+      while (end < lines.length && !/^#{1,3}\s/.test(lines[end]) && !/^\s*[-*]\s*\[\d{4}-\d{2}-\d{2}\]/.test(lines[end])) end++
+      entries.push({ date: heading[2], text: lines.slice(i, end).join('\n').trim(), line: i + 1 })
+      i = end - 1
+    }
+  }
+  return entries.sort((a, b) => a.date.localeCompare(b.date) || a.line - b.line)
+}
+module.exports.datedDecisions = datedDecisions

package/bin/lib/render.js

@@ -1,5 +1,7 @@
 "use strict"
 
+const { deliverySummary } = require('./delivery-gaps')
+
 // Pure, local HTML renderer for the FDE fieldbook. Data extraction stays in fde.js.
 
 function escapeHtml(s) {
@@ -199,6 +201,7 @@ strong{font-weight:600}
 .fb-queue-row:nth-child(even),.fb-flag-row:nth-child(even){background:var(--panel)}
 .fb-queue-slug{font-family:'Geist Mono',monospace;font-size:12px;color:var(--ink-faint);flex:0 0 130px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .fb-queue-action{font-size:14px;line-height:1.45;color:var(--ink);flex:1 1 auto}
+.fb-queue-reason{display:block;font-size:12px;color:var(--ink-faint);margin-top:5px;line-height:1.5}
 .fb-queue-touched{font-family:'Geist Mono',monospace;font-size:10.5px;color:var(--ink-faint);flex:0 0 auto}
 .fb-flag-slug{font-family:'Geist Mono',monospace;font-size:12px;color:var(--ink-faint);flex:0 0 130px}
 .fb-flag-text{font-family:'Geist Mono',monospace;font-size:12.5px}
@@ -308,13 +311,12 @@ function railItemHtml(e) {
 
 function queueRowHtml(e) {
   const dotClass = dotClassFor(e.signals.trust)
-  const noAction = !e.hasNext
-  const actionText = noAction ? 'Set the next action with your agent' : e.next
+  const action = e.firstAction
   const touchedClass = e.quiet ? 't-amber' : 't-faint'
   return `<button type="button" class="fb-row fb-queue-row" data-client="eng-${e.slug}" data-nav="eng-${e.slug}">
 <span class="dot dot-md ${dotClass}"></span>
 <span class="fb-queue-slug">${inlineMd(e.name)}</span>
-<span class="fb-queue-action${noAction ? ' t-amber' : ''}">${inlineMd(actionText)}</span>
+<span class="fb-queue-action">${inlineMd(action.text)}<span class="fb-queue-reason${action.tone ? ' t-' + action.tone : ''}">${escapeHtml(action.reason)} &middot; ${escapeHtml(action.source)}</span></span>
 <span class="fb-queue-touched ${touchedClass}">${escapeHtml(e.signals.updated)}</span>
 </button>`
 }
@@ -340,7 +342,8 @@ function todayViewHtml({ today, total, attentionCount, highRiskTotal, todayQueue
 <div class="fb-meta-line">${escapeHtml(today)} &middot; ${total} engagement${total === 1 ? '' : 's'} &middot; ${attentionCount} need you &middot; ${highRiskTotal} high risk${highRiskTotal === 1 ? '' : 's'} open</div>
 <p id="fb-results-empty" class="fb-empty-search" hidden>No clients match these filters. <button type="button" class="fb-btn" data-reset-filters>Clear filters</button></p>
 <div class="fb-block" data-filter-section>
-<div class="fb-sec">Next actions</div>
+<div class="fb-sec">Recommended first actions</div>
+<p class="fb-evidence-note">One starting point per client, based on the saved record. Confirm the gap before acting; these suggestions do not change recorded next actions.</p>
 ${todayQueue}
 </div>
 ${flagsHtml ? `<div class="fb-block" data-filter-section>
@@ -350,26 +353,6 @@ ${flagsHtml}
 </div>`
 }
 
-function attentionFor(e) {
-  const items = []
-  const add = (text, tone = 'amber') => items.push({ text, tone })
-  if (e.signals.memoryWarn) add('Record needs repair: ' + e.signals.memoryWarn, 'red')
-  if (e.highRisks) add(`${e.highRisks} high risk${e.highRisks === 1 ? '' : 's'} open`, 'red')
-  if (e.signals.trust === 'RED' || e.signals.trust === 'amber') add('Check in with the customer: trust is ' + trustWord(e.signals.trust), e.signals.trust === 'RED' ? 'red' : 'amber')
-  if (e.signals.trust === 'new') add('No dated trust signal yet - ask someone')
-  if (!e.hasNext) add('Set the next action')
-  const rows = e.valueRows || []
-  const missingEvidence = rows.filter(r => r.evidenceMissing).length
-  if (missingEvidence) add(`${missingEvidence} outcome${missingEvidence === 1 ? '' : 's'} missing evidence`)
-  const claimed = rows.filter(r => r.state === 'claimed').length
-  const unmeasured = rows.filter(r => r.state === 'unmeasured').length
-  if (claimed) add(`${claimed} measured outcome${claimed === 1 ? '' : 's'} awaiting acceptance`)
-  if (unmeasured) add(`${unmeasured} outcome${unmeasured === 1 ? '' : 's'} not yet measured`)
-  if (e.signals.stale) add('Reconfirm the dated trust signal')
-  if (e.quiet) add('Record last updated ' + e.signals.updated)
-  return items
-}
-
 function agentActionsHtml(e) {
   const prefix = `@fde Confirm the workspace is bound to ${JSON.stringify(e.name)} before using its records. `
   const actions = [
@@ -385,7 +368,7 @@ function agentActionsHtml(e) {
 
 function deliveryHtml(e) {
   const rows = e.valueRows || []
-  const labels = { unmeasured: 'Not yet measured', claimed: 'Awaiting acceptance', accepted: 'Acceptance recorded' }
+  const labels = { unmeasured: 'Not yet measured', claimed: 'CLAIM · Awaiting acceptance', accepted: 'Acceptance recorded' }
   const pending = value => !value || /^(?:pending|tbd|unknown|n\/a|none|awaiting)(?:\b|$)/i.test(value)
   const cell = (value, fallback) => pending(value) ? `<span class="t-faint">${escapeHtml(value || fallback)}</span>` : inlineMd(value)
   return `<section class="fb-block fb-delivery" aria-label="Delivery evidence">
@@ -452,7 +435,7 @@ ${e.realityMissing ? `<p class="fb-why fb-why-missing"><span class="fb-accent-la
   const vitalsBlock = `<div class="fb-vitals">
 ${vitalsRows.map(([label, val, tone]) => `<div class="fb-vital-row"><span class="fb-vital-label">${escapeHtml(label)}</span><span class="fb-vital-val${tone ? ' t-' + tone : ''}">${escapeHtml(val)}</span></div>`).join('\n')}
 ${teamStatus ? `<div class="fb-vital-row"><span class="fb-vital-label">team status</span><span class="fb-vital-val">${teamStatus}</span></div>` : ''}
-${e.stats.length ? `<div class="fb-vital-div"></div>${e.stats.map(s => `<div class="fb-vital-row"><span class="fb-vital-label">${inlineMd(s.label)}</span><span class="fb-vital-val">${inlineMd(s.from)} <span class="fb-arrow">&rarr;</span> <span class="fb-stat-to">${inlineMd(s.to)}</span></span></div>`).join('\n')}` : ''}
+${e.stats.length ? `<div class="fb-vital-div"></div><p class="fb-footnote">Metric excerpts are CLAIMS; verify source and acceptance.</p>${e.stats.map(s => `<div class="fb-vital-row"><span class="fb-vital-label">${inlineMd(s.label)}</span><span class="fb-vital-val">${inlineMd(s.from)} <span class="fb-arrow">&rarr;</span> <span class="fb-stat-to">${inlineMd(s.to)}</span></span></div>`).join('\n')}` : ''}
 </div>`
 
   const peopleBlock = e.stakeholders.length ? `<div class="fb-block">
@@ -534,10 +517,13 @@ function paletteItemsHtml(ordered) {
 }
 
 function buildFieldbookHtml({ engagements, today, generatedAt = '' }) {
-  engagements = engagements.map(e => ({ ...e, attention: attentionFor(e) }))
-  // rail + Today queue share one order: trust-first (red, amber, green)
+  engagements = engagements.map(e => {
+    const { gaps, firstAction } = deliverySummary(e)
+    return { ...e, attention: gaps, firstAction }
+  })
+  // Rail and Today queue share an order: urgent record gaps first, then trust.
   const tierRank = { RED: 0, amber: 1, green: 2, new: 3 }
-  const ordered = engagements.slice().sort((a, b) => Number(b.attention.length > 0) - Number(a.attention.length > 0) || tierRank[a.signals.trust] - tierRank[b.signals.trust])
+  const ordered = engagements.slice().sort((a, b) => Number(b.firstAction.tone === 'red') - Number(a.firstAction.tone === 'red') || Number(b.attention.length > 0) - Number(a.attention.length > 0) || tierRank[a.signals.trust] - tierRank[b.signals.trust])
   const attentionCount = engagements.filter(e => e.attention.length > 0).length
   const highRiskTotal = engagements.reduce((n, e) => n + e.highRisks, 0)
 
@@ -557,7 +543,7 @@ function buildFieldbookHtml({ engagements, today, generatedAt = '' }) {
 
   return `<!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
-<script>try{var t=localStorage.getItem("fde-fieldbook-theme");if(t==="dark"||(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches))document.documentElement.setAttribute("data-fde-theme","dark");}catch(e){}</script>
+<script>document.documentElement.setAttribute("data-fde-theme","dark");try{if(localStorage.getItem("fde-fieldbook-theme")==="light")document.documentElement.setAttribute("data-fde-theme","light");}catch(e){}</script>
 <title>FDE Fieldbook</title><style>${dashStyles()}</style></head><body>
 <a class="fb-skip" href="#fb-main">Skip to content</a>
 <div class="fb-app">

package/bin/lib/value-ledger.js

@@ -1,4 +1,5 @@
 'use strict'
+const { hasSource } = require('./provenance')
 
 // Empty measurements and unsigned outcomes are different facts. Keep their
 // interpretation shared by status, reports, and exported vaults.
@@ -19,9 +20,14 @@ function acceptanceName(value) {
   return name
 }
 
+function evidenceSource(evidence) {
+  const text = String(evidence || '').trim()
+  return hasSource(text) && !PENDING_CELL_RE.test(text) && !/\b(?:no evidence|never (?:run|tested|measured)|not (?:run|tested|measured|verified)|unverified|invalid|retracted)\b/i.test(text)
+}
+
 function valueState({ measured, accepted, acceptanceStatus, evidence }) {
   if (!measured || PENDING_CELL_RE.test(measured)) return 'unmeasured'
-  if (!acceptanceName(accepted)) return 'claimed'
+  if (!acceptanceName(accepted) || !evidenceSource(evidence)) return 'claimed'
   // Explicit status is authoritative when the column exists. Unknown values
   // fail closed. Existing name-only ledgers remain readable during migration.
   if (acceptanceStatus !== undefined) {
@@ -31,4 +37,4 @@ function valueState({ measured, accepted, acceptanceStatus, evidence }) {
   return 'accepted'
 }
 
-module.exports = { PENDING_CELL_RE, acceptanceName, valueState }
+module.exports = { PENDING_CELL_RE, acceptanceName, evidenceSource, valueState }

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "3.26.0",
+  "version": "3.27.0",
   "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": "3.26.0",
+  "version": "3.27.0",
   "description": "Client delivery tools for Forward Deployed Engineers. One @fde skill, local Markdown engagement records, and an offline dashboard for decisions, evidence, approvals, and next actions.",
   "bin": {
     "fdeops": "bin/install.js",

package/plugin.json

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

package/skills/fde/SKILL.md

@@ -28,13 +28,13 @@ A one-line typo or compile error in a file that will not ship. On a bound client
 | **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` |
 
-After a meeting: `fde debrief --smart` → one REVIEW screen (decided / asked / open / next / signer) → in chat, a four-row card (omit empty; Previously / Not yet agreed) → **Save this update?** (engineer accepted the record, not customer approval of every ask) → `--apply`. Walk-in: `fde prep`. Friday: `fde status`.
+After a meeting: `fde debrief --smart` → one REVIEW screen (decisions / asks / scope / delivery gaps / next / signer) → in chat, a four-row card (omit empty; Previously / Not yet agreed) → **Save this update?** (engineer accepted the record, not customer approval of every ask) → `--apply`. Walk-in: `fde prep`. Friday: `fde status`.
 
 ## Ground loop
 
 On someone else's site the work is not "write code, remember later." Every change on a bound client stays on `@fde`:
 
-1. **Name it** in `decisions.md` (plan) or kill it in a day (poc).
+1. **Name it** in `decisions.md` (plan), or timebox the riskiest assumption and record what the POC proves.
 2. **Characterise their code** before you change it. Brownfield: their tests, their runner. Greenfield: the empty tree, first path they can click.
 3. **Prove it on their staging.** Staging they operate, a screen the signer in `success.md` can reject.
 4. **If a model judges:** `evals.md` Verdict SHIP before that change is done (eval-pack).
@@ -58,7 +58,7 @@ Fallbacks: `node ~/.claude/fdeops/fde.js …`, then `npx --yes fdeops …`. Skil
 
 ## Entry (every session)
 
-1. `fde resume` (16 KiB output ceiling, not a model token count). Read the goals, risks and current context. 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. `fde resume` (16 KiB output 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.
 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.
@@ -72,7 +72,8 @@ Writes need a bind (`FDEOPS_ENGAGEMENT` or registry). Never install fdeops on in
 | debrief / pasted notes | `fde debrief --smart` → REVIEW → four-row chat card → Save this update? → `--apply`. `--smart` is a gate, not a brain. `references/debrief.md` |
 | prep me for … | `fde prep "<label>"` |
 | when did we agree | `fde receipts <term>` |
-| sponsor update / the outcome | `fde status` |
+| sponsor update / defend the number | `fde defend` |
+| successor / rotation / portable handoff | `fde handoff` (stdout; `--out new-file.md` only after export requested) |
 | they went quiet | `fde log contact "…" --signal amber\|green\|red` |
 | fieldbook page | `fde dashboard` (`--all` portfolio, `--open` to open the file) |
 | clean up the fieldbook | `fde doctor` - never auto-rewrite |
@@ -85,7 +86,7 @@ Writes need a bind (`FDEOPS_ENGAGEMENT` or registry). Never install fdeops on in
 
 1. **On entry:** `fde resume` only. Pull other `.fde/` files when the skill needs them.
 2. **Deliverable = memory.** The work *is* the `.fde/` file. The reference names which one.
-3. **Evidence.** Every claim has a source. Traceable beats plausible.
+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>`.
 5. **Session digest** (end of session and before a PR) - thinking, not the chat. Confirm, then write. Never a transcript dump.
 

package/skills/fde/references/plan.md

@@ -4,6 +4,8 @@
 
 **Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if poc produced one. Not the full folder.
 
+**Before committing a plan or building:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint.
+
 ## Validation gate (confirm understanding, clarify where it elevates)
 
 Before planning, state what you're working from in 2-3 lines:

package/skills/fde/references/poc.md

@@ -14,10 +14,10 @@ A green check on synthetic data is not a validated solution. The person who can
 
 **1. Pick by score when several use cases compete.** Use the scoring model from `discover.md` - (Value × Data readiness) / Complexity. If discover or score-use-cases already produced a ranking, reuse it; never invent a third ranking.
 
-**2. Build the minimum that tests the assumption.** No error handling, no polish. Same-day demo if possible. Rough is honest. The POC is done when the person who can say no has seen it and reacted, not when the code looks finished.
+**2. Build the minimum that tests the assumption.** Timebox the experiment with the FDE; aim for a same-day result when access and evidence permit it. Skip cosmetic polish, but keep the input validation, access controls, and failure handling needed to protect the test environment and data. Label shortcuts and simulated inputs. The POC is done when the person who can say no has seen the evidence and reacted, not when the code looks finished.
 
 **3. AI directions - test these before anything else:**
-- Data: available, clean, sufficient volume? Synthetic-data prototypes say nothing about production behaviour.
+- Data: available, clean, sufficient volume? Synthetic data can test mechanics, but does not establish production quality or real-world coverage.
 - Environment: are external model calls even allowed here?
 - Latency: acceptable against real user expectations, not ideal conditions?
 - Is AI the right tool at all - or is this a data-quality or process problem wearing an AI costume?
@@ -26,6 +26,14 @@ A green check on synthetic data is not a validated solution. The person who can
 
 **5. Translate to business language** once validated: problem solved, cost of inaction, success in numbers, 2-3 trade-offs. Three sentences max for the stakeholder - can't say it in three, don't understand it yet.
 
+## If proceeding to production
+
+Carry the hypothesis, test evidence, customer reaction, and remaining unknowns into the existing `plan` and `ship` workflow. A working demo does not establish production readiness or customer acceptance.
+
+Inspect the prototype before deciding what to reuse. Keep components whose behavior and boundaries are suitable and tested. Replace or harden shortcuts that fail production requirements; rewrite only where the evidence justifies it. Record the decision and remaining work in `decisions.md`, rather than treating all prototype code as disposable or all working code as ready to deploy.
+
+Production work includes the actual data path, permissions, failure recovery, realistic load, observability, ownership, and required AI evaluations. Use the existing ship gates for those checks.
+
 ## Artifact
 
 **`prototype-log.md`** - what was built, shown, the actual reaction, what was learned (including kills - a killed prototype that saved three weeks is a win worth recording).
@@ -38,7 +46,7 @@ Tell the FDE: did the riskiest assumption hold · what the customer's reaction a
 
 ## Principles
 
-- Speed of learning beats code quality. Never more than a day.
+- Optimize for a bounded learning outcome. Agree a timebox and revisit scope if access or evidence blocks it; never skip necessary safeguards to meet an arbitrary duration.
 - Write pass/fail before you build. A demo with no kill line is a show.
 - Show it rough. Polish misleads.
 - Prototype the killer assumption, not the demo.

package/skills/fde/references/ship.md

@@ -12,7 +12,9 @@ Do not ask them to pick a mode. Name where you are, then start at the matching s
 
 If going live, opening question: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
 
-A same-day throwaway that kills an assumption is `poc`. This skill is the real change on a repo they will own, then production.
+A bounded experiment that tests an assumption is `poc`. This skill turns a validated direction into a maintainable change on a repo they will own, then production. Inspect existing prototype code and retain suitable tested parts; replace unsafe shortcuts based on evidence. A successful demo alone does not satisfy the readiness gates below.
+
+**Before committing a plan or building:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint.
 
 ## Field (name it once, then the same loop)