fdeops 5.0.0 → 5.1.1

package/skills/brief/references/land.md

@@ -0,0 +1,136 @@
+# land - Interrogate the brief
+
+**Enter when:** new customer, first meeting, just got the brief, nothing started yet.
+
+**Read first:** apply [task context](task-context.md), then permitted `context.md` evidence if it exists and the supplied brief. Once the engagement type and AI/access policy are known, inspect the supplied repo/docs relevant to the ask before asking questions they can answer. This is a bounded evidence check, not a full discovery scan.
+
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before landing, state what you know in 2-3 lines:
+
+> "New engagement: [client name]. Timeline: [days/weeks/months or 'not clear yet']. Starting with: [what the FDE has told you so far - the brief, the context, the ask]."
+
+Then check - probe ONLY if it prevents a bad start:
+
+1. **Engagement speed.** If timeline is unclear → weave it in naturally: "Is this days, weeks, or months? That shapes how much structure we set up now."
+2. **Existing context.** If `.fde/` already exists → one line: "There's existing engagement memory here. Continuing this or starting fresh?"
+3. **Access.** If the FDE is about to start work → one line: "Got repo and environment access sorted, or is that still pending?"
+
+State your read, let the FDE correct, then land.
+
+## Brief interrogation (only when the brief is thin)
+
+Use this when the ask is conventional or underspecified - missing who decides, why now, what success looks like, or the binding constraint. **Do not** run it when the FDE already gave a clear brief, is mid-flow, or asked for speed over verification.
+
+Format - one question at a time, with a guess the FDE can correct:
+
+```
+READ: <one sentence - what you think they actually need>
+MISSING: <fact or authority that changes the next action>
+Q: <one focused question>
+POSSIBLE READ: <clearly labeled interpretation, if useful; never guessed authority>
+```
+
+Wait for the reaction before the next question. Stop when the next authorized action is clear, or when the FDE says move on; unanswered material gaps remain visible. Every answer that is still unknown stays `unknown - ask:` in the artifact - never fill the gap with a plausible stakeholder.
+
+## Method - part 1: interrogate the brief (you do this work)
+
+Read the brief the FDE gives you. Separate **observed** (source/path and date), **reported** (who said it), and **hypothesis** (how to test it). A requested solution such as “build an agent” is not evidence of the cause. Ask only about gaps that change scope, access, acceptance, or the next investigation. What is **not** in the brief matters as much as what is. Produce the gap list yourself:
+
+- **No named decision-maker** → identify who or what can accept the outcome and the source of that authority; keep it unknown until established.
+- **"Straightforward cleanup" on an 8-year-old system** → inspect permitted relevant history and tests for prior attempts and constraints; age alone proves neither complexity nor a previous failure.
+- **Very tight timeline** → establish the deadline, its source and which commitments are actually agreed.
+- **No out-of-scope section** → clarify material boundaries against the existing agreement. An omission does not authorize additional work.
+
+Write these into `brief.md` as **questions to answer**, not problems - they're what the FDE is walking in to resolve.
+
+Pre-arrival checks to run through with the FDE:
+- Access confirmed for the next task? Repo, environment and docs may have different permissions; identify gaps before dependent work.
+- Has someone tried this before? Establish what happened and what evidence remains; do not assume the attempt failed.
+- Other vendors/teams in scope? Then the FDE is not the only one in the room, even when alone in the meeting.
+- Tech stack recon: job postings, GitHub org - know the stack before they say it.
+
+## Method - part 2: the first conversation (you coach, the FDE asks)
+
+Intent: coach the FDE's first *customer* conversation - what keeps the sponsor up at night, personally, not the project charter. You already inspected the supplied brief and any authorized repo/docs. This is before *their* laptop in the room / before a deep build, not before you read evidence. Failure talk surfaces truth faster than "requirements." Angles in the FDE's own words:
+
+- "Before you open the laptop - what would make this a bad engagement for *them*, not just a delayed project?"
+- "What are they afraid you'll miss?"
+- "Who loses credibility if this goes wrong?"
+- "If nothing changes over the agreed timeframe, what happens, and who bears it?" Record the consequence and its source in `brief.md`; distinguish reported impact from measured cost. Unknown cost stays unknown, not an invented ROI.
+
+Allow time for an answer. If a stated concern differs from the brief, record the difference and clarify whether it changes the agreed outcome; neither statement automatically supersedes the other.
+
+**Listen for, and capture as you hear it:**
+- **Decision rights** - who can approve scope, accept the result and authorize release, as relevant. A frequently mentioned person may be influential; confirm their actual authority and scope.
+- **The previous attempt** - "we tried something similar last year" identifies evidence to investigate. Who was involved, what happened, and which constraints still apply? Do not infer why someone left.
+- **The existing internal team** - ask what they tried, what they know and what they expect to own. Use established terminology and credit their work. Do not assume resentment, displacement or complete knowledge of the problem.
+- **The sacred thing** - "Is there anything in this environment I should treat as untouchable?" Capture the stated boundary and applicable policy; hesitation alone does not identify a restriction.
+- **Exception path (operating map seed)** - "When the happy path breaks this week, what do people actually do - who do they call, what spreadsheet opens, what do they skip?" Capture the break → workaround → who owns it. Do not build a full map on day 1; seed rows later in `terrain.md` → `## Operating map (exception-led)` during discover. Unknowns stay `unknown - ask:`.
+- **AI posture and policy** - tools already in use (sanctioned or shadow), and: "Does your organisation have a policy on AI-generated code? Are there decisions where you would not be comfortable with AI involvement?"
+- **Future operator** - "Who will run this after we leave, and have they agreed?" Record the proposed operator and unresolved ownership in `success.md`, separately from the signer. A sponsor naming a team is not that team accepting responsibility; verify with the operator during discover.
+- **Boundaries in multi-vendor rooms** - who owns what surface, who signs off before a change crosses it.
+
+## An early deliverable
+
+Choose an early useful result within confirmed scope: a verified small fix, a permitted diagnostic, or a concise map of an unresolved problem. Reuse the existing outcome and authority for routine work. A first-day deadline does not grant deployment permission or waive verification; use `ship` for a release. If a missing signer blocks a consequential decision, keep it visible and continue independent preparation.
+
+## Artifact (write as the conversation is debriefed)
+
+**`brief.md`** - what they said, who sent the FDE, the timeline, **and the gap list**.
+
+**`success.md`** - what done looks like, **primary value bucket** (`cost-save` | `risk-mitigation` | `revenue-uplift`), baseline → target, who actually signs off, what is explicitly out of scope. Record agreement only with its source and scope; otherwise label the target proposed. For each baseline, record source, date/window, environment, and sample size when relevant. An operator recollection is reported, not measured. If no baseline exists, name the measurement owner and cheapest way to obtain it; do not manufacture a number.
+
+For every target number, run the **gaming check** before it is written down: *how could this metric hit its target without the customer being any better off?* Identify plausible failure modes without predicting that the customer will exploit them. Write a relevant guard next to the metric:
+
+```markdown
+| Metric | Baseline → target | Gamed by | Guard |
+|--------|-------------------|----------|-------|
+| reconciliation alert latency | 4h → 15min | alerting on everything, so nobody reads them | alerts acked by a named owner, ≤2/week |
+```
+
+If a proposed guard is disputed, capture the stated reason and assess its cost and effect on the outcome. Do not infer that the customer values the number over the result.
+
+**`stakeholders.md`**:
+```markdown
+| Who | Role | Signal | Notes |
+|-----|------|--------|-------|
+| <name> | <observed participation role; authority recorded separately> | green/amber/red | <evidence, day> |
+```
+If `stakeholders.md` already has a `## Signal history` section (it does from the template), **never delete or overwrite it** when you rewrite this file - it holds the dated `[signal:...]` tokens `fde log contact --signal` and `fde debrief` write, and `fde status`/`fde receipts`/the dashboard read only from that section. Edit the table above it freely; keep the section below intact.
+
+**`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: skip for status reads; use CLI/redacted surfaces; never paste raw `<private>` into prompts or subagents.
+
+**`assumptions.md`** - seed consequential unverified claims from the brief (and the initial hypothesis) as rows with Kind `UNKNOWN` (or `CONVENTION` if they said "we always"), blast radius CRITICAL / LOAD-BEARING / CONVENIENCE, and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
+
+```markdown
+| # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
+|---|------------|------|--------------|-------------|--------|----------|
+| 1 | <claim from brief> | UNKNOWN | CRITICAL | <cheapest falsifying test> | OPEN | (stated, unverified) |
+```
+
+One falsifiable hypothesis about the real problem also goes at the bottom of `brief.md` - discover / test-assumptions will test it.
+
+## Checkpoint
+
+One page back to the FDE: success + value bucket + sign-off owner, out-of-scope boundary, sacred data, stakeholder map with veto power, AI posture, the hypothesis, the top CRITICAL assumptions still OPEN, and any exception-path seeds heard (break → workaround → owner) for discover to map into `terrain.md`. Keep the summary short and link necessary detail; a complex engagement may need supporting evidence.
+
+If remote: agree how progress and blockers will be shared; use a short call when asynchronous context is insufficient.
+
+## Worked example
+
+Kickoff at Acme payments. Priya (VP Eng) sponsors; the brief says "add monitoring to the reconciliation service."
+
+Asking what happens the week after a perfect delivery gets: "I stop hearing about it from finance." That suggests a concern to clarify alongside the monitoring request. The previous attempt surfaces too: the platform team built alerting last year, it was turned off. Raj, who built it, is still there and was not in the kickoff. Ask for his account of the earlier attempt; his absence does not explain his views.
+
+In this example Priya reports a four-hour baseline and proposes the following target; her acceptance authority still needs its source. What gets written: `success.md` with proposed bucket `risk-mitigation`, `reconciliation failures reach a named owner within 15 min (baseline: 4h, found by finance)`, gaming check `alerting on everything so nobody reads them` → guard `≤2 alerts/week, acked by name`, proposed sign-off Priya until confirmed. `brief.md` carries the gap list and the hypothesis: *the job is not unmonitored, it is unowned*. `assumptions.md` seeds `"finance would act on an alert" - CRITICAL - OPEN - (stated, unverified)`. `trust-profile.md` records the boundary Priya explicitly names, through the permitted privacy-safe workflow.
+
+Early deliverable: verify and fix the log line that swallows the job's exit code within the existing scope. Deployment remains subject to the established release authority and checks.
+
+## Principles
+
+- Establish the outcome and authority needed for the next action; missing record files do not block useful standalone work.
+- Sacred data tagged `<private>` stays out of model context: use CLI/redacted reads; never paste raw private blocks.
+- Treat unverified parts of the brief as hypotheses; discovery may support or overturn them. Record consequential assumptions.
+- Learn from the existing team and verify consequential claims without guessing motives.
+- If the customer cannot define success, that is the first problem to solve.

package/skills/brief/references/task-context.md

@@ -0,0 +1,18 @@
+# Task context and evidence
+
+Use this contract for standalone methods and methods routed through `@fde`.
+
+- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite for work on supplied context. Tasks that inspect actual records need those records; staging or saving requires a selected customer. Never fabricate records to make an operational task appear complete. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
+- **Artifact names are destinations:** names such as `success.md`, `decisions.md`, and `delivery.md` identify relevant evidence and, when bound, record destinations. If absent, use supplied facts and return the requested draft or result in the current workspace or conversation. Do not invent files or require initialization to complete useful work.
+- **Bound engagement:** honor the current client binding and constraints. Before reading records, run `fde privacy` to verify masking support. Obtain a fresh, identity-matching sanitized `fde resume` packet for this task (or reuse a fresh session-hook packet); retrieve missing evidence with targeted `fde recall <topic>`. Use bounded `fde handoff` for transfer work. Refresh after binding, masking, or record changes. Never substitute raw `.fde/` reads, private blocks, masking dictionaries, or full transcripts. If the CLI is unavailable, use only permitted supplied excerpts and report the context limitation.
+- **Authority:** continue reversible work within authorized scope. Reuse prior authorization when it covers the specific action. Show consequential engagement-record judgments and uncertainties for confirmation before saving unless already explicitly confirmed. New scope, acceptance changes, production actions, exports, and external messages need the applicable authority; a method invocation alone does not supply it. Keep one customer's writes in that customer's record.
+- **Evidence:** distinguish supplied facts, estimates, hypotheses, and unknowns. Cite actual sources; a log date is not attribution. Never invent a source, signer, signature, customer reaction, or acceptance. Keep outcomes **promised → measured → accepted** distinct, and implementation, verification, deployment, and customer acceptance separate. Missing evidence means unproven, not an observed failure.
+- **Data boundary:** use only data permitted by the customer's AI policy; clarify unknown policy before loading their code or data. Never load `<private>` content into a model. Cross-client comparison and exporting reusable material require permission and removal of customer-identifying or confidential content; anonymization alone does not grant permission.
+
+## CLI availability
+
+Only locate the CLI when the selected task needs it. Check `fde` on PATH and its `fde privacy` capability before reading records. If unavailable, use `node ~/.claude/fdeops/fde.js` when the disk installer placed it there, or `npx --yes fdeops <command>` when package downloads are permitted. Respect local installation and network rules. Run commands for the user; do not turn a missing bare `fde` command into unnecessary manual setup.
+
+If no permitted executable is available, explain the missing capability. Continue any useful draft from supplied excerpts, but do not claim to have read, switched, staged, saved or rendered real records. Do not read raw private record files as a fallback.
+
+Apply the selected method to this context. Follow its linked supporting methods only when needed; do not restart discovery or repeat already answered questions.

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

@@ -3,14 +3,14 @@
   "version": 1,
   "files": {
     "SKILL.md": "19f32ecae72b96ee19cb87658ddd998cce96ec2e3960255d13fcc2906c6d0b6b",
-    "references/build.md": "3dfeed619eeb1c8401f5cdf65e6f803fb209c70cb464dac4e60a1c890fd3a6f7",
+    "references/build.md": "6fa07b15b682119de53c38950f94942a58e4680ab58b24319d77c54a27cd9697",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
-    "references/integrate.md": "107a50bddf6cb0ba7f2bc006dfe9851800c6868e43f785a33ae4b737aeb74c95",
+    "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
     "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
-    "references/task-context.md": "8ec90708522e512a50a57ab2a377a7472e93bae169c6f075a93fa603ce2ad780",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490",
     "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
   }
 }

package/skills/build/references/build.md

@@ -6,7 +6,7 @@ Use the permitted context and authority in [task context](task-context.md). This
 
 ## Method
 
-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.
+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.

package/skills/build/references/integrate.md

@@ -6,13 +6,23 @@ Start from [task context](task-context.md). Permitted supplied context is enough
 
 ## Method
 
-1. Map producer, consumer, owner, direction, and side effects. Inspect the actual installed version and local implementation; verify uncertain behavior against current official documentation. Identify the relevant schema, authentication scopes, network boundary, and permitted test environment.
+1. Map producer, consumer, owner, direction, and side effects. Inspect the actual installed version and local implementation; verify uncertain behavior against current official documentation. Identify the relevant schema, authentication scopes, network boundary, and permitted test environment. Before changing an untested existing boundary, characterize the mappings, ordering or other observable behavior its callers depend on.
 2. Write the acceptance example: an input at the real boundary and the observable downstream result. Include a rejection or failure example. Separate configuration validity, successful authentication, transport connectivity, contract compatibility, and end-to-end behavior; none proves the next.
 3. Inspect credentials by presence and required scope without printing values. Use existing secret storage. Check data classification and retention before moving data; never pass raw `<private>` blocks into a model. Prefer sanitized or synthetic cases approved for the target environment.
-4. Implement the narrow adapter using native repository patterns. Validate external inputs and model outputs, bound timeouts and retries, preserve error context without leaking payloads, and handle cancellation. For writes, establish idempotency or duplicate detection before retries; for events, check ordering, replay, and poison messages as applicable.
+4. Implement the narrow adapter using native repository patterns. Validate external inputs and model outputs, bound timeouts and retries, preserve error codes and failure phase without leaking payloads, and handle cancellation. Keep explicit authentication or permission rejections distinguishable from transport uncertainty. For writes, establish idempotency or duplicate detection before retries and apply the uncertain-write rules below when outcomes can be ambiguous; for events, check ordering, replay, and poison messages as applicable.
 5. Exercise a permitted success case and relevant failures: denied access, malformed data, rate limit, timeout, duplicate delivery, or partial completion. Trace correlation IDs or safe evidence across both sides. A mock proves client behavior only; if live access is unavailable, report that gap instead of claiming an integration works.
 6. Check cleanup and recovery for test side effects. Use [verification](verification.md) for receipts and [review](review.md) for security or data-contract changes. Route deployment through [ship](ship.md) only when authorized.
 
+## When a write outcome is uncertain
+
+Use the existing storage and worker mechanisms; do not introduce a new platform for these rules.
+
+- Before a replayable write, persist its tenant-scoped operation identity and payload identity, with enough state to recover after restart. Establish who owns an in-flight attempt so concurrent workers cannot independently replay it. Establish whether upstream deduplication is guaranteed, including its key, payload rules and retention window; sending a key alone proves nothing.
+- A timeout, cancellation or lost response after dispatch may leave a completed side effect. Preserve that uncertainty across restart; stopping the caller is not rollback. Do not silently turn an uncertain attempt into a fresh operation.
+- Reconcile against an authoritative receipt or lookup that matches the operation and payload. One verified result can confirm completion; conflicting or multiple matches require resolution. An empty stale, partial or eventually consistent lookup does not prove absence or authorize replay. Retry only under the verified deduplication contract or evidence establishing that repeating the write is safe.
+- Keep unresolved attempts visible with safe error context, a next action and a known resolution owner, or an explicit ownership gap. Manual resolution still needs authority for any corrective write; do not manufacture completion to clear a queue.
+- Test the relevant failure boundary: committed write with lost response, cancellation or restart before recording success, and stale lookup or concurrent replay where applicable. Record which were exercised and which remain unproven.
+
 ## Deliverable and acceptance
 
 Return the boundary contract, changed paths, environment, evidence at each tested layer, and remaining dependencies with owners when known. Done requires the agreed end-to-end result or an explicit narrower agreed scope. Do not silently replace live acceptance with a stub. In engagement mode, update the terrain/delivery record with confirmed facts; otherwise return the receipt directly.

package/skills/build/references/task-context.md

@@ -2,11 +2,17 @@
 
 Use this contract for standalone methods and methods routed through `@fde`.
 
-- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
+- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite for work on supplied context. Tasks that inspect actual records need those records; staging or saving requires a selected customer. Never fabricate records to make an operational task appear complete. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
 - **Artifact names are destinations:** names such as `success.md`, `decisions.md`, and `delivery.md` identify relevant evidence and, when bound, record destinations. If absent, use supplied facts and return the requested draft or result in the current workspace or conversation. Do not invent files or require initialization to complete useful work.
 - **Bound engagement:** honor the current client binding and constraints. Before reading records, run `fde privacy` to verify masking support. Obtain a fresh, identity-matching sanitized `fde resume` packet for this task (or reuse a fresh session-hook packet); retrieve missing evidence with targeted `fde recall <topic>`. Use bounded `fde handoff` for transfer work. Refresh after binding, masking, or record changes. Never substitute raw `.fde/` reads, private blocks, masking dictionaries, or full transcripts. If the CLI is unavailable, use only permitted supplied excerpts and report the context limitation.
 - **Authority:** continue reversible work within authorized scope. Reuse prior authorization when it covers the specific action. Show consequential engagement-record judgments and uncertainties for confirmation before saving unless already explicitly confirmed. New scope, acceptance changes, production actions, exports, and external messages need the applicable authority; a method invocation alone does not supply it. Keep one customer's writes in that customer's record.
 - **Evidence:** distinguish supplied facts, estimates, hypotheses, and unknowns. Cite actual sources; a log date is not attribution. Never invent a source, signer, signature, customer reaction, or acceptance. Keep outcomes **promised → measured → accepted** distinct, and implementation, verification, deployment, and customer acceptance separate. Missing evidence means unproven, not an observed failure.
 - **Data boundary:** use only data permitted by the customer's AI policy; clarify unknown policy before loading their code or data. Never load `<private>` content into a model. Cross-client comparison and exporting reusable material require permission and removal of customer-identifying or confidential content; anonymization alone does not grant permission.
 
+## CLI availability
+
+Only locate the CLI when the selected task needs it. Check `fde` on PATH and its `fde privacy` capability before reading records. If unavailable, use `node ~/.claude/fdeops/fde.js` when the disk installer placed it there, or `npx --yes fdeops <command>` when package downloads are permitted. Respect local installation and network rules. Run commands for the user; do not turn a missing bare `fde` command into unnecessary manual setup.
+
+If no permitted executable is available, explain the missing capability. Continue any useful draft from supplied excerpts, but do not claim to have read, switched, staged, saved or rendered real records. Do not read raw private record files as a fallback.
+
 Apply the selected method to this context. Follow its linked supporting methods only when needed; do not restart discovery or repeat already answered questions.

package/skills/business-case/.fde-generated.json

@@ -0,0 +1,9 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "79249fd92c3c0437954f52c6ff07a0b0e351a588ef84cd1bcc810a9fb3ab7b77",
+    "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/business-case/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: business-case
+description: Develop a business case for an initiative using costs, benefits, risks and evidence. Use when a sponsor needs budget or timeline justification.
+---
+
+# business-case
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Develop a business case for an initiative using costs, benefits, risks and evidence. Use when a sponsor needs budget or timeline justification.
+
+Read [the task context contract](references/task-context.md), then [the method](references/business-case.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.
+
+## Principles
+
+- Work directly from the supplied permitted context. Standalone work does not require an engagement folder or initialization. Record filenames in the method are optional persistence destinations when no engagement is bound.
+- If called by @fde, reuse its current sanitized packet and scope. Do not restart setup, discovery or questions already answered.
+- The task context contract controls persistence and authority in both modes. Preserve unknowns and distinguish implementation, verification, deployment and acceptance.
+- Use the customer's repository instructions and available tools. Report a missing capability or unrun check honestly; do not claim that installing a skill provisions infrastructure.

package/skills/business-case/references/business-case.md

@@ -0,0 +1,90 @@
+# business-case - Build the business case
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**Enter when:** the sponsor needs justification for the next phase, the FDE needs to defend budget or timeline, a feature decision needs cost/benefit evidence, or poc produced a direction that needs funding.
+
+**Read first:** `reality.md`, `success.md`, `delivery.md`, `context.md`. Load `business-case.md` from poc if it exists - extend it, don't restart.
+
+Technical FDEs lose engagements by shipping good code without business justification. The sponsor's boss doesn't ask "is the code clean?" - they ask "what did we get for the money?" A business case translates technical work into the language that keeps the engagement alive.
+
+## Method (you do this work)
+
+**1. Name the cost of doing nothing.** This is the anchor. Every business case starts not with what you'll build, but with what it costs them to leave the problem unsolved:
+
+| Cost type | How to find it | Example |
+|-----------|---------------|---------|
+| **Labor capacity / direct spend** | Ask: "What does this problem cost per month in money?" | Manual reconciliation hours × loaded rate = capacity value; separately identify reducible spend |
+| **Opportunity cost** | Ask: "What can't you do because of this problem?" | Can't onboard enterprise clients because the API can't handle their volume |
+| **Risk cost** | Ask: "What happens if this breaks at the worst time?" | A payment processing outage during Black Friday = $X/hour in lost sales |
+| **Velocity cost** | Measure: deployment frequency, lead time, change failure rate | Team ships once/month instead of once/week; each delay = N features not reaching customers |
+
+**2. Build the driver model.** Not a spreadsheet - a logic chain the sponsor can trace:
+
+```
+Investment: <hours × rate, or fixed cost>
+  → Delivers: <specific outcome from success.md>
+    → Benefit: <capacity released, avoidable cash spend, revenue, or risk reduction>
+      → Net cash: realizable incremental cash benefit - full costs over <time horizon>
+```
+
+Keep drivers, units, sources, and ranges explicit. For example, 3 people × 8h/week × $75/h × 52 weeks = $93.6K/year of labor capacity value. It is cash savings only if spend actually falls (for example, paid overtime or a contractor cost ends). Name who can realize the benefit and how. Include build, ongoing operation, adoption, and transition costs; avoid double-counting capacity and revenue enabled by the same hours. Do not calculate cash payback from capacity value alone.
+
+**3. Sensitivity check - name the two drivers that swing the result:**
+
+Every business case has 1-2 variables where a small change flips the outcome. Name them explicitly:
+
+> "The capacity case assumes the team reclaims 6 hours/week per person. At 3 hours, that benefit halves. Cash payback remains unproven until finance identifies avoidable spend. Validate time-spent before and after the pilot with representative team members."
+
+The sponsor who sees you've identified where the case could break trusts the case more, not less.
+
+**4. Frame for the audience.** Different stakeholders need different lenses on the same case:
+
+| Audience | Lead with | Avoid |
+|----------|----------|-------|
+| **CFO / finance** | ROI, payback period, cash flow impact | Technical architecture, feature lists |
+| **CTO / engineering** | Technical debt retired, velocity improved, risk reduced | Revenue projections they can't verify |
+| **CEO / founder** | Strategic enablement, competitive edge, customer impact | Detailed calculations (give the summary, offer the detail) |
+| **Product** | User impact, adoption metrics, feature velocity | Cost structures that aren't their domain |
+
+**5. The one-page format.** The business case fits one page or it isn't understood:
+
+```markdown
+## Business case: <initiative name>
+
+**The problem costs:** <one line, quantified>
+**The investment:** <hours and cost>
+**The return:** <quantified, with time horizon>
+**Payback:** <months from realizable cash benefits, or not established>
+**Sensitivity:** <the 1-2 drivers that swing it, with thresholds>
+**Risks:** <what must be true for this to hold>
+**Recommendation:** <proceed / proceed-with-conditions / defer>
+```
+
+## Artifact
+
+**`business-case.md`** - the one-page case. Lives alongside `success.md` and `reality.md` as a first-class engagement artifact. Referenced by plan, status, and close.
+
+**`decisions.md`** - log the sponsor's response: approved, modified, deferred. With the date.
+
+## Checkpoint
+
+Walk the FDE through: the cost of doing nothing (anchor), the investment, the return, and the one sensitivity that matters most. If the FDE says "the sponsor won't buy the ROI number," inspect the disputed inputs and sources, test plausible ranges, and identify what measurement would resolve the disagreement. Never reverse-engineer assumptions to hit a desired number.
+
+## Worked example
+
+Acme phase 2 needs funding. The case starts with the cost of doing nothing, not the cost of building.
+
+Anchor: two silent failures since March, each one day of finance reconciliation by hand plus a late close (`reality.md`, Marco's sheet). That is the number the sponsor already believes because her own team reported it.
+
+Driver model the sponsor can trace: incidents/quarter × hours of manual reconciliation × loaded cost, plus the tail risk of a late regulatory close - stated separately, because mixing a certain small number with an uncertain large one is how a case loses credibility.
+
+Sensitivity names the two drivers that swing it: incident frequency (2/quarter → 1/quarter and the case halves) and whether the manual re-run continues in parallel (if Marco keeps re-running every morning, the saving is theoretical). The second one is the honest weakness, so it is in the case rather than waiting to be found in the room - with the condition that makes it hold: the morning re-run stops after two clean cycles, agreed with Marco.
+
+## Principles
+
+- The cost of doing nothing is always the opening move. Anchor before proposing.
+- Driver models with visible arithmetic beat magic spreadsheets.
+- Name the sensitivity. The case that admits its weakness earns more trust.
+- One page. If it doesn't fit, you don't understand it yet.
+- A business case the FDE can't explain in 60 seconds won't survive the sponsor's boss.

package/skills/business-case/references/task-context.md

@@ -0,0 +1,18 @@
+# Task context and evidence
+
+Use this contract for standalone methods and methods routed through `@fde`.
+
+- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite for work on supplied context. Tasks that inspect actual records need those records; staging or saving requires a selected customer. Never fabricate records to make an operational task appear complete. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
+- **Artifact names are destinations:** names such as `success.md`, `decisions.md`, and `delivery.md` identify relevant evidence and, when bound, record destinations. If absent, use supplied facts and return the requested draft or result in the current workspace or conversation. Do not invent files or require initialization to complete useful work.
+- **Bound engagement:** honor the current client binding and constraints. Before reading records, run `fde privacy` to verify masking support. Obtain a fresh, identity-matching sanitized `fde resume` packet for this task (or reuse a fresh session-hook packet); retrieve missing evidence with targeted `fde recall <topic>`. Use bounded `fde handoff` for transfer work. Refresh after binding, masking, or record changes. Never substitute raw `.fde/` reads, private blocks, masking dictionaries, or full transcripts. If the CLI is unavailable, use only permitted supplied excerpts and report the context limitation.
+- **Authority:** continue reversible work within authorized scope. Reuse prior authorization when it covers the specific action. Show consequential engagement-record judgments and uncertainties for confirmation before saving unless already explicitly confirmed. New scope, acceptance changes, production actions, exports, and external messages need the applicable authority; a method invocation alone does not supply it. Keep one customer's writes in that customer's record.
+- **Evidence:** distinguish supplied facts, estimates, hypotheses, and unknowns. Cite actual sources; a log date is not attribution. Never invent a source, signer, signature, customer reaction, or acceptance. Keep outcomes **promised → measured → accepted** distinct, and implementation, verification, deployment, and customer acceptance separate. Missing evidence means unproven, not an observed failure.
+- **Data boundary:** use only data permitted by the customer's AI policy; clarify unknown policy before loading their code or data. Never load `<private>` content into a model. Cross-client comparison and exporting reusable material require permission and removal of customer-identifying or confidential content; anonymization alone does not grant permission.
+
+## CLI availability
+
+Only locate the CLI when the selected task needs it. Check `fde` on PATH and its `fde privacy` capability before reading records. If unavailable, use `node ~/.claude/fdeops/fde.js` when the disk installer placed it there, or `npx --yes fdeops <command>` when package downloads are permitted. Respect local installation and network rules. Run commands for the user; do not turn a missing bare `fde` command into unnecessary manual setup.
+
+If no permitted executable is available, explain the missing capability. Continue any useful draft from supplied excerpts, but do not claim to have read, switched, staged, saved or rendered real records. Do not read raw private record files as a fallback.
+
+Apply the selected method to this context. Follow its linked supporting methods only when needed; do not restart discovery or repeat already answered questions.

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

@@ -0,0 +1,12 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "b2d112f09f663a1f0a7e9bb0fa7cd065ab81e22be6a385cb6afef77b2dd66b08",
+    "references/connect.md": "37ad703ece7fe3596be4d5d3697cc4ba5e6062615f9576733c20d055fc3e4927",
+    "references/debrief.md": "2d2db9a177f5341a9a2721a9d6ea32a6d07e7e982e621429ca408a38bc5617c1",
+    "references/ingest.md": "24880bc3d95cda09ec6c2f5edebd17fba99deb912f93e15c8b715a287283da84",
+    "references/source-setup.md": "a28ae7c6dbb2573a66f31b30b7abca34bc52573fe34d48fff4c7490e4dc85d3e",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/connect/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: connect
+description: Configure or diagnose access to a requested source using available host tools. Use for source MCP setup; source configuration needs no engagement record and credentials stay with the host.
+---
+
+# connect
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Configure or diagnose access to a requested source using available host tools. Use for source MCP setup; source configuration needs no engagement record and credentials stay with the host.
+
+Read [the task context contract](references/task-context.md), then [the method](references/connect.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.
+
+## Principles
+
+- Source configuration and capability checks do not require an engagement record. Use available host tools and source documentation. Any later record staging or application follows the ingest method and its binding and confirmation requirements.
+- If called by @fde, reuse its current sanitized packet and scope. Do not restart setup, discovery or questions already answered.
+- The task context contract controls persistence and authority in both modes. Preserve unknowns and distinguish implementation, verification, deployment and acceptance.
+- Use the customer's repository instructions and available tools. Report a missing capability or unrun check honestly; do not claim that installing a skill provisions infrastructure.

package/skills/connect/references/connect.md

@@ -0,0 +1,24 @@
+# connect - Connect a source
+
+**Enter when:** the user asks to connect a notes, chat or document source, or an expected source cannot be read.
+
+Apply [task context](task-context.md). Source setup can run independently of a customer record. Follow [source setup](source-setup.md) for permitted tools, credentials, connectivity checks and export alternatives.
+
+## Method
+
+1. Identify the source and the material the user wants to read. Inspect the host's actual available tools before recommending setup.
+2. If the source already works, use a narrowly scoped requested read. Do not install another connector.
+3. If setup is needed, verify current provider and host documentation, explain the required access, and make only authorized configuration changes. Never put credentials into prompts or customer records.
+4. Test the selected source and distinguish configuration from successful retrieval. If access is blocked, report the specific limitation and an available file or paste alternative.
+5. If the user also wants to update a customer record, continue with [ingest](ingest.md) after selecting that record. Otherwise stop after the requested setup or read.
+
+## Checkpoint
+
+Return what is connected, what read was verified, any access gap, and how to request the next pull. Do not claim an integration works from configuration alone or write customer records during setup.
+
+## Principles
+
+- Existing source tools first; configuration only when needed.
+- Minimum requested read, no ambient synchronization.
+- Credentials stay in supported secret storage.
+- Record updates require their own review and confirmation.

package/skills/connect/references/debrief.md

@@ -0,0 +1,91 @@
+# debrief - Capture the meeting
+
+**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". Highest-frequency moment in FDE life. Capture within the hour.
+
+**Standalone review:** apply [task context](task-context.md). If the user supplies notes and wants a summary or review, interpret them using **Prepare one update** below and return a draft. Keep requests, confirmed decisions, reported results and unknowns distinct. No CLI or customer record is needed; do not claim anything was saved. Use the bound-record path below only when updating an existing record or when the user asks to start one.
+
+**Large transcripts or emails** sitting in Granola/Gmail/Notion → prefer **`fde ingest stage`** first (via source MCPs the FDE configured), then the same propose → confirm → **`fde ingest apply`** path. See `references/ingest.md`. Pasted short notes stay on this debrief verb.
+
+**Read first:** the bounded `fde resume` packet for the bound client. Use `fde recall` for the specific prior decision, action, or delivery result needed to reconcile this update. Do not reload the whole engagement.
+
+**Who runs the CLI:** you (the agent). Never tell the FDE to type `fde debrief …`.
+
+## Honest contract (read once)
+
+- The `fde` CLI is **local, deterministic, no AI**. `--smart` is a **gate + writer**, not a brain.
+- It keeps lines that already have `decision:` / `risk:` / `delivery:` / `contact:` / `next:` / `signer:` prefixes, plus a thin keyword pass (e.g. "we agreed", person+verb lines, "open question", "X signs off").
+- `signer: Priya` fills **Stakeholder who signs off** in `success.md` and logs Priya as a contact. The CLI proposes it when a sentence says someone signs off / approves / has final say. If the notes name who can say yes and the proposal does not carry a `signer:` line, add one - that is the most expensive sentence in the meeting.
+- Heuristics can miss facts **and mislabel prefixed lines**. You interpret every candidate against the sanitized source, not just unprefixed lines. Split distinct decisions, requests, actions, and results; keep uncertainty. The user reviews meaning, never prefix syntax.
+- `.debrief-propose` is raw lines only (no routing annotations). "Edit if mis-routed" means **rewrite the line with the right prefix**, not leave a comment in the file.
+
+## Method (you do this work)
+
+### Preferred path - smart debrief (messy notes)
+
+1. Save the FDE's notes to a temp `.md` file in the workspace (or pipe stdin).
+2. Run `fde debrief --smart <notes.md>` (or `npx fdeops debrief --smart …`).
+3. Run `fde debrief --review` before opening an existing proposal so legacy identifiers are masked. Open the proposal only after review succeeds. Never open a proposal containing manually inserted raw private blocks. Prepare the pending proposal using **Prepare one update** below. Read only the sanitized `.debrief-propose`, never the sealed private sidecars or raw private source. Preserve privacy markers, source metadata, and complete identifier aliases such as `[[email:...]]`. The CLI restores known aliases locally on apply. Never read `.privacy/` or try to recover an identity with file tools. If an alias is truncated, retrieve a narrower excerpt; never guess or edit the token.
+4. Run `fde debrief --review` after editing. Treat the CLI REVIEW and routing output as your validation, not a second presentation to the user. Resolve errors and replay warnings before asking for confirmation.
+5. Show **one** concise review in chat: name the client, then the consequential changes in plain English. Include decisions, requests still unagreed, actions, reported delivery, signer or contact changes, and unresolved conflicts when present. Show the previous value only where it changes the meaning. Omit empty categories and CLI routing details; do not impose a fixed four-row card that hides other changes. If the proposal is too large to show faithfully, split the review into explicit batches; never approve hidden changes.
+6. Ask **Save this update?** This confirms the engineer's record, not customer acceptance. On confirmation, apply precisely that proposal with `fde debrief --apply`. A material correction requires a revised review and renewed confirmation. On rejection, leave the proposal pending and do not apply.
+7. Verify the changed facts through bounded `fde resume` / targeted `fde recall`. If a fieldbook is part of the current task, regenerate it using the existing command and destination after the confirmed save; do not make the user run it. End with a brief saved/not-saved result and the next action, not another full summary.
+
+### Prepare one update (shared with ingest)
+
+Do this work yourself before the human review:
+
+- **Check meaning, not keywords.** “We settled on delaying the rewrite” is a decision; “Mara will request access” is an action, even if the heuristic calls it a contact. A wish or suggestion remains a request, not agreement. Do not infer authority, approval, a calendar date from an unanchored relative date, or production value from staging.
+- **Make interpretation visible in the same review.** For messy or dictated input, separate consequential statements supplied by the user from your proposed interpretation. Leave a missing model, date, owner, or scope explicitly unknown; do not fill it from what seems usual. Include only interpretation calls that could change the work, not a second recap or extra approval step.
+- **Handle changed minds without erasing history.** If the same speaker clearly corrects their own instruction ("send it Friday; actually, wait for Monday's review"), show the superseded instruction and the replacement together. Different speakers, uncertain chronology, or a new request conflicting with recorded authority remain a conflict to resolve, not permission to choose the last sentence. Keep consequential parked requests pending; omit conversational tangents. Never mark an inferred change as agreed.
+- **Keep facts traceable.** Preserve supplied source locators on each consequential fact, using `[source: ...]`. If only a local file or staged item exists, cite that actual locator as a note source, not a customer receipt. Do not invent a meeting date or speaker. A source label is not authenticated approval.
+- **Reconcile only what changed.** Compare affected facts with the current record using targeted retrieval. Leave unchanged sourced statements out of an accidental re-import. Preserve earlier history; record changed or conflicting claims explicitly. If everything is already recorded, say so and leave the pending proposal unapplied. If it blocks a later capture, explain that no new facts were saved and ask permission to replace that pending review; use `--replace-proposal` with the new notes only after that authorization. Do not delete proposal files or private sidecars manually. Do not use `--allow-replay` without explicit approval of an intentional repeat.
+- **Protect the current next action.** A late meeting note does not automatically supersede a newer action. Keep older actions as dated context unless their current priority is established; show a conflict when it needs a decision. Use exactly one physical `next:` line for the current action. If multiple current actions are explicitly agreed, include them on that same line separated by semicolons; the CLI retains only the last `next:` line. Keep other dated commitments in context. Do not silently discard other commitments.
+- **Keep memory useful.** Retain consequential facts and indispensable context; remove chatter and repetition from the proposal, not from the source. Preserve the raw input outside `.fde/` (staged material stays in `.inbox/`). Never remove privacy placeholders or modify sealed sidecars. Ask only about a consequential ambiguity that cannot remain explicitly unknown.
+- **Structure the result.** Use `decision:` / `risk:` / `delivery:` / `contact:` / `next:` / `signer:`. Preserve `ask:` / `scope:` as explicitly proposed context when appropriate. Prepare the seven-field delivery row yourself for a reported result (see below); unknown fields stay `pending`. The human should not have to fill out a ledger to capture a meeting.
+
+Before showing the review, check that every consequential fact in the sanitized source is represented, already recorded, or explicitly unresolved. Check classified lines as carefully as unclassified ones. Nothing is saved simply because this preparation is complete.
+
+### Fallback - you structure, then route
+
+If `--smart` is unavailable or you already have clean prefixes:
+
+1. Extract into buckets - **only what was actually said**:
+   - **Decisions** - agreed, by whom, in their words where possible
+   - **Action items** - owner + due; unowned → `owner: unknown - ask`
+   - **Stakeholder signals** - tone shifts with evidence → green/amber/red
+   - **Risks** - new / confirmed / retired
+   - **Open questions** - what to chase next
+2. Format lines as `decision:` / `risk:` / `delivery:` / `contact:` / `next:` / `signer:` (contacts may end with `[signal:green|amber|red]`).
+3. Follow **Prepare one update** and show the same single plain-English review as the preferred path. Include every consequential change and ask **Save this update?**.
+4. On confirm, pipe to `fde debrief` (or write a file and run it).
+
+Ask at most one focused question at a time when ambiguity would change the record. Otherwise preserve the unknown and include it in the review. Never treat silence as confirmation.
+
+## Artifact
+
+- Smart apply / debrief CLI writes the dated routes into the right `.fde/` files.
+- `next:` updates the existing `## Next action` in `context.md` (collapses duplicates). Do not append a second `## Next action` heading by hand.
+- If you must write directly: decisions → `decisions.md`; signals → `stakeholders.md` Signal history; risks → `risks.md`; next actions → fill under the template `## Next action` in `context.md`. Prefer the CLI.
+
+## Checkpoint
+
+Use the single pre-save review above. After saving, report verification and the next action briefly; do not ask for a second approval or repeat the review.
+
+## Principles
+
+- Capture within the hour or lose the nuance.
+- Verbatim quote outranks paraphrase; hesitation outranks quote.
+- Signals move on evidence, never on vibe alone.
+- A meeting with no decisions and no actions - say so; that is a finding.
+
+## Delivery rows and repeated updates
+
+For a measured or promised slice, use a reviewed structured line:
+
+```text
+delivery: Replay|risk-mitigation|zero duplicates|zero duplicates on staging|pending|[source: transcript:42]|pending
+```
+
+The seven fields are Slice, Bucket, Promised, Measured, Accepted by, Evidence, Rollback. Keep unknowns `pending`; never infer approval. This lands in the value ledger during the same confirmed apply. A `delivery:` line without pipes stays a narrative note. Incorrect field counts refuse the write rather than shifting the meaning of cells.
+
+A sourced statement already in the record triggers a replay warning. Before applying, compare newer facts and the current next action. Remove repeated statements from the proposal if this is an accidental re-import. Only after the engineer explicitly confirms an intentional repeat, apply with `fde debrief --apply --allow-replay`. This does not silently deduplicate history and does not authenticate sources.