fdeops 5.1.7 → 5.1.8

package/README.md

@@ -4,183 +4,154 @@
 
 <a name="why-use-it"></a>
 
-Work through a customer project from the first conversation to a system their team can run. FDEOps helps your agent clarify the problem, compare solutions, write and test code, connect customer systems, and prepare delivery and handover evidence.
+The codebase does not tell your agent what the customer agreed to last week, why an approach was rejected or who can approve the next release.
 
-A **skill** is a set of instructions your AI coding agent follows. FDEOps includes **35 task skills + one coordinator, `fde`**. Use any skill directly, or ask `fde` to select the relevant skills as a customer project progresses.
+FDEOps brings that context into the work, from the first meeting to a system the customer can run. Use a skill for one task, or let `fde` coordinate the project and keep its record.
 
-Use it for a single integration, a small client project, or work within a larger enterprise team. You bring the customer context, repository tools and access. FDEOps supplies the working method; you and the responsible teams make the decisions.
+**35 task skills + one coordinator, `fde`**. Use your existing tools and processes. You and the customer keep control of the decisions.
 
-[Get started](#quick-start) · [Choose a task](#task-skills) · [Keep a customer record](#keep-a-customer-record) · [Documentation](docs/README.md)
+[Get started](#quick-start) · [What it helps with](#three-things-it-helps-with) · [Choose a skill](#task-skills) · [Data boundaries](#your-records-your-control) · [Docs](docs/README.md)
 
-<img width="1000" height="586" alt="fdeops-flow" src="https://github.com/user-attachments/assets/12bbec6a-d0b3-4d03-81aa-4b842731a044" />
+<img width="1000" height="586" alt="FDEOps engagement flow from customer discovery through delivery and handover" src="https://github.com/user-attachments/assets/12bbec6a-d0b3-4d03-81aa-4b842731a044" />
 
 ## Quick start
 
-**Use customer-approved data and AI tools.** The CLI runs locally, but your AI agent may send what it reads to its provider. Masking is partial and does not protect direct file reads or pasted text. If approval is unclear, start with synthetic data. Anonymised customer material still needs permission. See [safe setup and limits](SECURITY.md#before-customer-work).
+**Use customer-approved data and AI tools.** Your agent may send what it reads to its provider, even though the FDEOps CLI runs locally. If approval is unclear, use fictional data. [Safe setup](SECURITY.md#before-customer-work).
 
-Use FDEOps with an AI coding agent that supports skills. Start with one task, or let `fde` coordinate a customer project.
+### Let `fde` coordinate a customer project
 
-Try the fictional engagement first with `npx fdeops demo` (requires Node.js 18+ and Git; may download the package). It creates or resets a separate `.demo` workspace and does not need customer data.
-
-### Work on a customer project
-
-Run this in the terminal where your coding agent runs, then select your agent in the installer:
+Install in the terminal where your AI coding agent runs, then select your agent:
 
 ```bash
 npx skills add suboss87/fdeops --skill fde
 ```
 
-This installation method uses Node.js (which includes `npx`) and Git. If either is missing, ask your agent to help with setup. The FDEOps CLI requires Node.js 18 or later. See [installation options](docs/install.md) for your agent.
-
-Then select `fde` in your agent and start a conversation. In agents that support `@fde`, use:
+Select `fde` in your agent, or use `@fde` where supported:
 
 ```text
 @fde this is client01. Their support team reads incoming requests,
 checks internal documents, then assigns each request to another team.
-Help me prepare for the first meeting. Here is the brief: …
+Help me prepare for the first meeting. Here is the brief: ...
 ```
 
-`fde` asks for the information needed next and uses the relevant instructions. As work progresses, it can help you investigate delays, compare approaches, implement a change, test it, and prepare a customer update. You do not have to choose a skill at each step.
-
-For an ongoing project, naming the customer starts a local record at `~/fde-engagements/client01/.fde/`. It keeps the brief, decisions, evidence and next actions together. Review proposed agreements and corrections before saving them. [How customer records work](#keep-a-customer-record).
+The coordinator uses the relevant instructions as the work changes. You do not need to choose a skill at each step. For an ongoing project, it keeps decisions, evidence and next actions in a local customer record.
 
-### Use just one task
-
-For example, install only `discover`:
+### Use one skill for one task
 
 ```bash
-npx skills add suboss87/fdeops --skill discover
+npx skills add suboss87/fdeops --skill debrief
 ```
 
 Then ask your agent:
 
 ```text
-Use FDEOps discover with these meeting notes. Show how the team handles
-an incoming request today, where time goes, and what we still need to ask.
+Use FDEOps debrief to review these meeting notes.
+Separate decisions, requests and open questions. Return a draft only.
 [Paste notes you are permitted to share.]
 ```
 
-The agent works from your notes and returns its findings. You do not need to create a customer record for this task. Each task skill includes the instructions it needs and works without installing `fde` or another skill pack.
+No customer record is needed for this draft. Each task includes its required instructions; you do not need to install `fde` or another pack.
 
-**Want every task available by name?** Install the full pack using the [installation guide](docs/install.md#individual-skills-and-the-full-pack). Installing `fde` alone gives the coordinator all the underlying instructions; it does not add the 35 separate names to your agent's skill menu.
+These installation commands use Node.js and Git; the optional record CLI requires Node.js 18+. See [installation and upgrades](docs/install.md) for host-specific invocation, the full pack and alternatives. Installing `fde` includes all underlying instructions, but does not add the 35 separate task names to your agent's menu.
 
-Skill invocation differs between agents. Ask for the FDEOps skill by name or select it in your agent's skill picker. For Claude Code plugin installs, use `/fdeops:fde` or `/fdeops:discover`. See [host setup and name conflicts](docs/install.md#individual-skills-and-the-full-pack).
+**Try it with fictional data:** `npx fdeops demo` runs sample notes through review and creates a fieldbook without calling an AI model. It requires Node.js 18+ and Git, may download the package, and creates or resets only its separate `.demo` workspace. [Five-minute walkthrough](docs/USAGE.md#new-here-5-minutes).
 
-## Choose a skill
+## Three things it helps with
 
-<a name="task-skills"></a>
+### 1. Starting the next session without starting over
 
-Use the skill that matches the work in front of you. All skills are individually installable; the [complete catalog](docs/skills-reference.md) lists the input and result for each one.
-
-| You need to… | Start with |
-|---|---|
-| Clarify a new customer request | `brief` or `discover` |
-| Understand who can approve the change | `who-decides` |
-| Decide what to build and what to leave out | `options`, `scope` or `plan` |
-| Implement or connect customer systems | `build` or `integrate` |
-| Find a failure or test the result | `debug`, `review`, `evaluate` or `qa` |
-| Prepare an authorized release | `ship` |
-| Review meeting notes or report progress | `debrief` or `readout` |
-| Prepare the team to run the system | `runbook` or `handoff` |
-
-These examples are starting points, not a required sequence. The catalog also covers inherited projects, business cases, incidents, recovery, source connections and multiple customer records. `fde` uses the same instructions and loads additional detail only when needed.
-
-**Which mode should I choose?** Use an individual skill for a specific task. Use `fde` when you want help selecting the next task or maintaining a continuing customer record. You can also ask it for a one-off result without creating records. Installing a skill makes it available independently; it does not remove its real input requirements. For example, `dashboard` needs records to display, while `debrief` can review pasted notes without saving anything.
+A repository tells you where the code lives. It may not tell you why the customer rejected an approach, which access is still blocked or what the team promised on Tuesday.
 
+<a name="keep-a-customer-record"></a>
 <a name="how-skills-work"></a>
 
-## Keep a customer record
+For an ongoing engagement, FDEOps keeps a separate plain-Markdown record at `~/fde-engagements/<customer>/.fde/`. The coordinator retrieves a bounded summary and looks up details when needed. A saved implementation checkpoint points back to the current task record; the agent checks it before continuing.
 
-An **engagement** is your ongoing project with a customer. Its record lives in a separate folder on your machine, outside the customer's application code:
+Use [debrief](skills/debrief/SKILL.md) after a meeting and [switch-clients](skills/switch-clients/SKILL.md) when changing customers. [How records work](docs/USAGE.md).
 
-```text
-~/fde-engagements/client01/.fde/
-```
+### 2. Keeping a request from becoming an agreement
 
-The files are readable Markdown. They track what the customer asked for, who can decide, what success means, what changed, and the evidence behind each result. You can inspect, copy or keep them if you stop using FDEOps.
+A stakeholder asks for more scope. A demo looks promising. Neither establishes a new commitment or an accepted result.
 
-After a meeting, paste permitted notes into the same agent conversation. It proposes the new requests, decisions, unresolved questions and next actions. Correct anything it misunderstood, then confirm the update.
+FDEOps separates requests, confirmed decisions, reported results and unresolved questions. You review proposed record changes before confirming them. Dates and sources make a claim traceable; they do not authenticate customer approval.
 
-A request is not automatically an agreement. A passing test is not a production deployment. A measured improvement is not customer acceptance. FDEOps keeps those distinctions in the record.
+For example, these fictional notes:
 
-At the next session, the coordinator retrieves a short summary rather than loading the full history. The default summary is capped at 16 KiB; older evidence is retrieved when needed. For interrupted implementation, it also surfaces a saved checkpoint when one exists, then checks the current task record before continuing. This cap applies to FDEOps output, not everything your agent loads.
+> Mara agreed to keep CSV upload this phase. Devon asked for real-time sync; Mara has not answered. Two staging runs took 12 minutes. Production has not been measured.
 
-If your agent cannot start the record, run this in your terminal from the workspace where you work on that customer:
+A review should keep those distinctions:
 
-```bash
-npx fdeops resume --init client01
-```
+| Record | What the notes support |
+|---|---|
+| Decision | Keep CSV upload this phase; attributed to Mara in the supplied notes |
+| Request | Real-time sync remains unapproved |
+| Evidence | Two staging runs took 12 minutes; production benefit is unmeasured |
+| Next step | Resolve the scope request with Mara before changing the commitment |
 
-This links that workspace to the customer's record. [Daily use and meeting walkthrough](docs/USAGE.md) · [Record format](docs/schema.md).
+This is a draft, not a saved agreement. Use [who-decides](skills/who-decides/SKILL.md), [scope](skills/scope/SKILL.md) or [readout](skills/readout/SKILL.md) for the decision in front of you.
 
-<a name="what-a-working-day-looks-like"></a>
+### 3. Knowing what is actually ready
 
-## Your daily fieldbook
+A local test, a deployed change and a customer-accepted result answer different questions.
 
-The fieldbook is a read-only browser view of your customer records. It shows next actions, open risks, missing evidence and results waiting for acceptance.
+FDEOps carries the agreed checks into implementation and binds verification to the relevant revision and environment. Release guidance asks for operating limits, recovery evidence and an owner. Missing access or evidence stays visible; a passing local test does not fill that gap.
 
-![FDEOps fieldbook showing next actions and delivery gaps across fictional customers](media/fieldbook-preview.png)
+Use [build](skills/build/SKILL.md), [integrate](skills/integrate/SKILL.md), [review](skills/review/SKILL.md), [ship](skills/ship/SKILL.md) and [handoff](skills/handoff/SKILL.md) as needed. [See the tests and their limits](docs/verification.md).
 
-Run this in your terminal to view all your customers:
+## Choose a skill
 
-```bash
-npx fdeops dashboard --all --open
-```
+<a name="task-skills"></a>
 
-Open a customer's record and copy an action into your agent to continue. Run the command again after updates to refresh the view.
+| Work in front of you | Start with |
+|---|---|
+| An unclear customer request | `brief`, `discover` |
+| Unclear ownership or access | `who-decides`, `earn-trust` |
+| A decision about scope or approach | `scope`, `options`, `plan` |
+| An implementation or system connection | `build`, `integrate` |
+| A failure or a result to verify | `debug`, `review`, `qa`, `evaluate` |
+| A release or operating handover | `ship`, `runbook`, `handoff` |
+| Meeting notes or a customer update | `debrief`, `readout` |
 
-**Try a fictional example first:** `npx fdeops demo` runs sample meeting notes through review and produces a fieldbook without using an AI model. It creates or resets its demo folder under `~/fde-engagements/.demo/`. Remove that example with `npx fdeops demo --clean`.
+These are entry points, not a required sequence. Every task can be called directly or selected by `fde`. Some tasks need records to work with: `dashboard` displays saved records, while `debrief` can review supplied notes without saving them. [Full skill catalog](docs/skills-reference.md).
 
-## Fit it to the project
+<a name="what-a-working-day-looks-like"></a>
 
-Start with the work in front of you:
+<details>
+<summary><strong>View your customer records in the fieldbook</strong></summary>
 
-| Project | How to use FDEOps |
-|---|---|
-| Small fix or analysis | Give a task skill the relevant notes or code. Get the result and its verification; no customer record is required. |
-| Customer integration or ongoing delivery | Use `fde` to connect discovery, implementation, tests and updates in one continuing record. |
-| Enterprise engagement | Work within the customer’s existing access, change-control and operating processes. Record who can approve each decision and what evidence they require. |
+The fieldbook is a read-only browser view of next actions, risks, evidence gaps and results awaiting acceptance.
 
-The pack includes implementation, integration, debugging and QA instructions. It uses the repository's existing tools. It does not supply customer credentials, infrastructure, specialist approvals or production authority.
+![Fieldbook showing fictional customer records](media/fieldbook-preview.png)
 
-Optional setup:
+```bash
+npx fdeops dashboard --all --open
+```
 
-- **Personal preferences:** `npx fdeops setup` records how you work and what to mask before sharing context.
-- **Repository reconnaissance:** `npx fdeops scan` reads local files and returns an initial assessment and questions. It does not change the repository.
-- **Other agent hosts:** [Adapters](adapters/README.md) add a pointer to the coordinator in your workspace.
-- **External sources:** [Connection recipes](mcp/recipes/) explain how to pull permitted material from tools you already use.
+Copy an action into your agent to continue. Regenerate the view after record updates. [Daily use](docs/USAGE.md).
 
-Use the [installation guide](docs/install.md) for the full pack, Claude Code hooks, offline setup and upgrading from earlier versions.
+</details>
 
 <a name="your-records-your-control"></a>
+<a name="your-data-stays-yours"></a>
 
-## Your data stays yours
-
-The CLI reads local files and Git, with no network calls or telemetry. Installation through `npx` may download packages. Your AI host may send material it reads to its configured model.
+## Local records, explicit data boundaries
 
-FDEOps masks common sensitive patterns and excludes `<private>` blocks from CLI, dashboard and hook outputs. This is not complete sensitive-data detection. Do not ask the agent to read private blocks directly, and use only material allowed by the customer's AI policy.
+The CLI reads local files and Git without network calls or telemetry. Installation may download packages. Your AI host controls model connections and may transmit what it reads.
 
-You review proposed decisions. Enabled session hooks can save mechanical session progress automatically; direct CLI write commands update records when you run them.
+CLI and hook outputs mask common identifier patterns. `<private>` blocks are redacted from those outputs and the dashboard. Local reports retain unmarked identifiers by default. Masking is partial; raw file reads and pasted text bypass it. Anonymisation does not grant permission to use customer material.
 
-[Privacy](PRIVACY.md) · [Security](SECURITY.md) · [What has been tested and its limits](docs/verification.md)
+You review consequential record updates. Enabled hooks can save mechanical session progress; direct CLI write commands update records when run. [Privacy](PRIVACY.md) · [Security](SECURITY.md) · [Local-model results](docs/verification.md#local-model-results).
 
 ## Who this is for
 
-Forward deployed engineers, consultants and small delivery teams working with customers across meetings, codebases and operating environments. The pack supports the engineering and customer work together. Its checks help expose missing evidence; they do not replace professional judgment or prove every deployment safe.
+Forward deployed engineers, consultants and delivery teams working across customer meetings, codebases and operating environments. Start with one task or coordinate an ongoing engagement. The skills use your existing tools and processes; they do not provide infrastructure, access rights or customer approval.
 
-## Find your way around
+## Go deeper
 
-| You want to… | Start here |
-|---|---|
-| Install or upgrade | [Installation](docs/install.md) |
-| Work through your first customer project | [Usage](docs/USAGE.md) and [examples](examples/) |
-| Explore the instructions | [Skill reference](docs/skills-reference.md) |
-| Understand the repository | [Repository layout](docs/REPO_LAYOUT.md) |
-| Check the test evidence | [Verification](docs/verification.md) |
-| Improve the pack | [Contributing](CONTRIBUTING.md) |
+[Install or upgrade](docs/install.md) · [Daily use](docs/USAGE.md) · [Worked examples](examples/) · [Skill catalog](docs/skills-reference.md) · [Source connections](mcp/recipes/) · [Repository layout](docs/REPO_LAYOUT.md) · [Verification](docs/verification.md) · [Contribute](CONTRIBUTING.md)
 
-Built by [Subash Natarajan](https://www.linkedin.com/in/subashn/). [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions)
+Built and maintained by [Subash Natarajan](https://www.linkedin.com/in/subashn/). [Issues](https://github.com/suboss87/fdeops/issues) · [Discussions](https://github.com/suboss87/fdeops/discussions).
 
 ## License
 
-MIT. Use FDEOps in your customer work. See [LICENSE](LICENSE).
+[MIT](LICENSE). Use FDEOps in your customer work.

package/mcp/fdeops-ingest/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "5.1.7",
+  "version": "5.1.8",
   "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
   "bin": {
     "fdeops": "bin/install.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "5.1.7",
+  "version": "5.1.8",
   "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
   "author": {
     "name": "Subash Natarajan",

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

@@ -3,11 +3,11 @@
   "version": 1,
   "files": {
     "SKILL.md": "245c53b404549ed73fd6ef532e48c002de7d20a6a93eaca6c0714c4e4d14ba92",
-    "references/build.md": "7634abd02b70011b7443a65ea3aaf3cb536ed5b051312aed188f46523deea7f9",
-    "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
+    "references/build.md": "03c52eda90642c62053b53ef1e85c97b4e647600f454aee9da0e415c9d98903e",
+    "references/debug.md": "3273a921a98522431ae821a283814897270c719cbfab83d14b99175537d869e5",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
-    "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
-    "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
+    "references/integrate.md": "1cb7a60d7545b0bf224fce678a04ce6ccdf368c47877d9c8e4dc4272bb0d5b0c",
+    "references/qa.md": "41de4d70827c83291efa217e97d777f62ec2849827687fbba7e4b1d17484b87e",
     "references/review.md": "55733ca868c00fb22110bc7b3ec7bb6c6451366c795073b19a2bccd30d2764c8",
     "references/ship.md": "95f51772b29de6f7d174f1f7678f15d46a3a5327dcb8facb94288e27907ae92c",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",

package/skills/build/references/build.md

@@ -1,22 +1,33 @@
 # build - Implement a verifiable increment
 
-**Enter when:** an agreed behavior needs implementation in an existing or new repository. For a broken behavior, start with [debug](debug.md); for a system boundary, use [integrate](integrate.md).
+Build the smallest complete change that demonstrates the agreed customer outcome through the real entry point.
 
-Use the permitted context and authority in [task context](task-context.md). This method works without `.fde/`; an existing engagement record can supply the same contract. Do not initialize memory just to write code.
+**Use when:** agreed behavior needs implementation in a new or existing repository. Use [debug](debug.md) for broken behavior and [integrate](integrate.md) for a system boundary.
 
-## Method
+Follow [task context](task-context.md). Supplied permitted context or an existing engagement record can provide the contract; do not initialize `.fde/` merely to write code.
 
-1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Follow the repository's branch policy and choose any needed checkout isolation according to that policy and overlapping work. 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. When changing dependencies, inspect the package source, requested version, lockfile changes and repository install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or apply unrelated dependency upgrades.
-5. Add or update automated coverage for changed behavior when meaningful and feasible, including the relevant failure path. Existing tests must actually exercise the change; explain manual-only coverage and its limits. Run focused checks, then required repository checks. Exercise the actual affected journey with [QA](qa.md) when appropriate. For uncertain model behavior, use [eval-pack](eval-pack.md). Record results with [verification](verification.md), including checks that could not run.
-6. Inspect the final diff against the agreed outcome. If public behavior, interfaces, configuration or operating steps changed, update affected existing documentation and examples; exercise relevant commands or clearly mark checks that could not run. For substantial or risky work, seek [review](review.md) using an actual separate reviewer when available; identify a self-check honestly. Reverify affected behavior after fixes.
+## Understand the repository and outcome
 
-## Deliverable and acceptance
+Inspect repository instructions, working tree, relevant callers, examples, and test commands. Preserve unrelated edits. Follow its branch policy and choose checkout isolation according to overlapping work. Identify the dependencies and interfaces the change touches. Before changing an untested legacy path, use targeted characterization checks to capture undocumented behavior callers rely on; separate that behavior from the intended change.
 
-For substantial work, maintain the [recoverable checkpoint](verification.md#recoverable-checkpoint) in the existing task record as slices complete or work pauses.
+State the observable outcome, constraints, and acceptance checks, reusing agreed criteria for routine fixes. Surface unresolved consequential product choices while continuing independent investigation; do not invent acceptance.
 
-Return the implemented behavior, relevant paths, evidence, remaining limitations, and any decision needed. Done means the agreed checks have applicable evidence and the change is reviewable; passing tests does not imply deployment or customer acceptance. Committing, opening a PR, merging, and publishing happen only when the requested workflow authorizes those actions.
+## Build one complete slice
 
-When coordinated through `@fde`, record implementation and verification in the existing decisions/delivery records under their write rules. Standalone work can return the same receipt directly or use the repository's task record.
+Choose a coherent path through the real entry point, including its necessary storage, error handling, and interface behavior. Name the failure that would stop expansion and the recovery path for stateful changes.
+
+Use existing services, fixtures, validation, and repository conventions before adding alternatives. Limit cleanup to making the changed path understandable. For dependency changes, inspect the package source, requested version, lockfile changes, and install-script policy before executing package code. Use the approved package manager and bootstrap controls; do not blanket-enable scripts or include unrelated upgrades.
+
+## Demonstrate the behavior
+
+Add or update automated coverage when meaningful and feasible, including the relevant failure path. Check that existing tests actually exercise the change. Explain manual-only coverage and its limits. Run focused checks, then required repository checks; use [QA](qa.md) for the affected journey when appropriate and [eval-pack](eval-pack.md) for uncertain model behavior. Record evidence and unrun checks with [verification](verification.md).
+
+Inspect the final diff against the agreed outcome. Update affected existing documentation and examples when public behavior, interfaces, configuration, or operating steps change. Exercise relevant commands or state what could not run. For substantial or risky work, use [review](review.md) with a separate reviewer when available; label a self-check honestly. Reverify affected behavior after repairs.
+
+*Fictional example:* Northstar needs failed imports to be recoverable. A useful first slice takes one failed import through the existing retry action to a persisted result, including the retry's failure behavior. A new button alone does not demonstrate recovery.
+
+## Completion
+
+Return implemented behavior, relevant paths, evidence, limitations, and any decision needed. The change is ready when agreed checks have applicable evidence and the work is reviewable. Passing tests does not establish deployment or customer acceptance. Commit, open a PR, merge, or publish only when the requested workflow authorizes it.
+
+For substantial work, maintain a [recoverable checkpoint](verification.md#recoverable-checkpoint) in the existing task record as slices finish or work pauses. When coordinated through `@fde`, record implementation and verification in existing decisions/delivery records under their write rules. Standalone work can return the receipt directly or use the repository's task record.

package/skills/build/references/debug.md

@@ -1,18 +1,33 @@
 # debug - Find and repair the cause
 
-**Enter when:** a reproducible failure, regression, incident symptom, or misleading output needs investigation.
+A useful repair explains the customer's failure and shows why the changed path now behaves correctly.
 
-Use [task context](task-context.md). Work from supplied permitted evidence without requiring `.fde/`. During an active incident, follow the authorized containment procedure before diagnosis; investigation authority alone does not authorize production writes.
+**Use when:** a failure, regression, incident symptom, or misleading output needs investigation, whether or not it can yet be reproduced.
 
-## Method
+Follow [task context](task-context.md); permitted supplied evidence is enough without `.fde/`. During an incident, follow authorized containment procedures before diagnosis. Investigation authority does not authorize production writes.
 
-1. Capture expected and observed behavior, exact input or trigger, affected revision/environment, and the last known working state. Preserve useful errors and timestamps without copying secrets or raw private data. Mark reports you have not reproduced as reports.
-2. Inspect the failing path, callers, recent relevant changes, and existing tests. Reproduce in a permitted environment with the smallest representative case. If reproduction is unavailable, identify what observation would distinguish causes and gather safe evidence; do not claim a hypothesis is proven.
-3. Keep a short hypothesis list. For each, name the predicted observation and a discriminating check. Change one relevant variable at a time. Trace values and control flow across the actual boundary instead of repeatedly changing code until the symptom disappears.
-4. Fix the cause at the appropriate layer. Check whether the proposed fix changes behavior for other callers, stale data, retries, concurrency, or permissions. Preserve evidence of the original failure and avoid unrelated cleanup.
-5. Add a regression check when it can meaningfully reproduce the bug; show that it fails before the fix and passes after when practical. If the check cannot run against the before-state, say so. Run affected adjacent and required checks using [verification](verification.md).
-6. Review the final diff and exercise the original journey. For substantial or risky fixes use [review](review.md). After two unsuccessful repair cycles, reassess the hypothesis and evidence instead of repeating the same attempt; continue useful investigation and isolate the missing decision or access.
+## Establish what failed
 
-## Deliverable and acceptance
+Capture expected and observed behavior, the trigger or input, revision, environment, and last known working state. Keep useful errors and timestamps, without secrets or raw private data. Label unverified reports as reports.
 
-Report the cause with its evidence, the fix, the original reproducer's result, adjacent checks, and unresolved uncertainty. A disappearing symptom with no discriminating evidence is a mitigation, not a demonstrated root cause. In engagement mode record the incident/fix receipt in the appropriate existing record; standalone work may return it directly. Release or rollback requires the existing operational authority and [ship](ship.md) or recovery procedure.
+Inspect the affected path, callers, relevant changes, and existing tests. Reproduce with the smallest representative case in a permitted environment when practical. If reproduction is unavailable, state the gap and use traces or other safe observations to distinguish causes. Keep investigating without promoting a hypothesis to a finding.
+
+## Test the explanation
+
+Keep a short hypothesis list with a predicted observation and a discriminating check for each. Trace values and control flow across the actual boundary. Change one relevant variable at a time so the result tells you something.
+
+After two unsuccessful repair cycles, reassess the evidence and approach. That is a signal to reconsider, not proof that a hypothesis is false. Continue useful investigation and identify any missing decision or access.
+
+## Repair and verify the affected path
+
+Fix the cause at the appropriate layer, preserving evidence of the original failure. Consider other callers, stale data, retries, concurrency, and permissions; leave unrelated cleanup out.
+
+Add a regression check when it can meaningfully reproduce the bug. Show failure before and success after when practical, and disclose when the before-state could not be checked. Exercise the original journey and run affected adjacent and required checks using [verification](verification.md). Review the diff; use [review](review.md) for substantial or risky fixes.
+
+*Fictional example:* Northstar's imports sometimes duplicate orders. A lost-response trace suggests a retry after a committed write. If staging cannot reproduce it, report the supported hypothesis and missing evidence rather than calling a longer timeout a root-cause fix.
+
+## Completion
+
+Return the cause and evidence, repair, original journey or reproducer result, adjacent checks, and unresolved uncertainty. A disappearing symptom without discriminating evidence establishes a mitigation, not a demonstrated root cause.
+
+In an engagement, put the incident/fix receipt in the appropriate existing record under its write rules; standalone work can return it directly. Release or rollback needs the existing operational authority and [ship](ship.md) or recovery procedure.

package/skills/build/references/integrate.md

@@ -1,28 +1,43 @@
 # integrate - Prove the system boundary
 
-**Enter when:** connecting an API, data source, SDK, event stream, tool, or service, or changing its contract.
+An integration works when an input crosses the real boundary and produces the agreed downstream result.
 
-Start from [task context](task-context.md). Permitted supplied context is enough; `.fde/` is optional. Use the customer's existing clients, authentication, fixtures, and diagnostic tools. Do not create another integration platform to make one connection.
+**Use when:** connecting or changing an API, data source, SDK, event stream, tool, or service contract.
 
-## Method
+Follow [task context](task-context.md); `.fde/` is optional. Use the customer's existing clients, authentication, fixtures, and diagnostics. One connection does not call for a new integration platform.
 
-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 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.
+## Define the boundary and evidence
 
-## When a write outcome is uncertain
+Map producer, consumer, owner, direction, and side effects. Inspect the installed version and local implementation; check uncertain behavior against current official documentation. Identify schemas, authentication scopes, network boundaries, and the permitted test environment. Before changing an untested boundary, characterize mappings, ordering, and other behavior its callers depend on.
 
-Use the existing storage and worker mechanisms; do not introduce a new platform for these rules.
+Write a real input and expected downstream result, plus a rejection or failure example. Keep configuration validity, authentication, connectivity, contract compatibility, and end-to-end behavior separate: evidence for one does not prove the next.
 
-- 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.
+Inspect credentials by presence and scope without printing values; use existing secret storage. Check classification and retention before moving data. Never load raw `<private>` blocks into a model. Prefer sanitized or synthetic cases approved for the target environment.
 
-## Deliverable and acceptance
+## Implement the narrow adapter
 
-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.
+Use native repository patterns. Validate external inputs and model outputs, bound timeouts and retries, and handle cancellation. Preserve error codes and the failure phase without leaking payloads. Keep explicit authentication or permission rejection distinguishable from transport uncertainty.
+
+For writes, establish idempotency or duplicate detection before retries and apply the uncertain-write rules below. For events, address ordering, replay, and poison messages where relevant.
+
+## Resolve uncertain writes safely
+
+Use existing storage and worker mechanisms for these rules:
+
+- **Identify the attempt before dispatch.** For a replayable write, persist a tenant-scoped operation identity, payload identity, and enough state to recover after restart. Establish ownership of in-flight attempts so workers cannot independently replay them. Verify any upstream deduplication guarantee, including key, payload rules, and retention window; sending a key proves nothing by itself.
+- **Preserve ambiguity.** A timeout, cancellation, or lost response after dispatch can hide a completed side effect. Keep that uncertainty across restart. Stopping the caller is not rollback; do not silently create a fresh operation from an uncertain attempt.
+- **Reconcile before replay.** Use an authoritative receipt or lookup matching the operation and payload. One verified result can confirm completion; conflicting or multiple matches need resolution. An empty stale, partial, or eventually consistent lookup proves neither absence nor permission to replay. Retry only under the verified deduplication contract or evidence that repeating the write is safe.
+- **Keep a resolution owner.** Leave unresolved attempts visible with safe error context, a next action, and a known owner or explicit ownership gap. Manual corrective writes still need authority. Do not invent completion to clear a queue.
+- **Exercise the failure boundary.** Test a committed write with a lost response, cancellation or restart before success is recorded, and stale lookup or concurrent replay where applicable. Record what was exercised and what remains unproven.
+
+## Prove the result and recovery
+
+Exercise a permitted success case and relevant failures, such as denied access, malformed data, rate limits, timeout, duplicate delivery, or partial completion. Trace correlation IDs or other safe evidence on both sides. Check cleanup and recovery for test side effects. A mock proves client behavior only; missing live access is a verification gap.
+
+Use [verification](verification.md) for receipts and [review](review.md) for security or data-contract changes. Deploy through [ship](ship.md) only when authorized.
+
+*Fictional example:* Northstar's ERP accepts an order but the response is lost. An empty, delayed search result does not justify resubmission. Keep the attempt unresolved until an authoritative receipt or verified deduplication contract supports the next action.
+
+## Completion
+
+Return the contract, changed paths, environment, evidence at each tested layer, and remaining dependencies with owners when known. Completion requires the agreed end-to-end result or an explicitly agreed narrower scope; never silently replace live acceptance with a stub. In engagement mode, update existing terrain/delivery records with confirmed facts under their write rules; otherwise return the receipt directly.

package/skills/build/references/qa.md

@@ -1,18 +1,31 @@
 # qa - Exercise the changed journey
 
-**Enter when:** a feature or fix needs behavioral verification through its real interface, especially UI, API, and multi-step workflows.
+Verify what the customer can do through the real interface, including the state the journey leaves behind.
 
-Use [task context](task-context.md) and the customer's existing browser, API, fixtures, and test tooling. `.fde/` is not a prerequisite. Respect the permitted environment and authority for every side effect.
+**Use when:** a feature or fix needs behavioral verification, especially a UI, API, or multi-step workflow.
 
-## Method
+Follow [task context](task-context.md) and use existing browser, API, fixture, and test tooling. `.fde/` is optional. Every side effect must stay within the permitted environment and authority.
 
-1. Identify the changed journey, user roles, acceptance checks, and risk-bearing neighboring paths. Record the revision and environment. Use synthetic or sanitized fixtures with understood cleanup; do not borrow production data without permission.
-2. Run the normal journey from its real entry point through the expected result. Verify persisted or downstream state when the requirement includes it; a success toast alone does not prove a write succeeded.
-3. Select negative and boundary cases from the change: invalid input, empty/loading/error states, refresh/back navigation, retries, duplicates, permissions, or interrupted work. For UI changes, inspect relevant viewport sizes, keyboard access, focus, labels, and errors. Use a real browser for the affected journey.
-4. Inspect relevant console and network evidence. Distinguish a UI defect from a failed API or unavailable environment. Retain only privacy-safe screenshots and logs. Do not claim visual verification from code inspection or a generated screenshot that was not viewed.
-5. Report failures with steps, expected/actual result, revision/environment, evidence, and impact. If repair is authorized, use [debug](debug.md), then rerun the failed journey and affected neighbors. Keep unrelated findings separate from the change.
-6. Produce a [verification receipt](verification.md). State which roles, devices, environments, or data conditions remain untested. Do not weaken acceptance checks to make the run pass.
+## Choose the journey and conditions
 
-## Deliverable and acceptance
+Identify the changed journey, user roles, acceptance checks, and neighboring paths at risk. Record revision and environment. Use synthetic or sanitized fixtures with understood cleanup; do not borrow production data without permission.
 
-Return checked journeys and observed results, reproducible defects, limitations, and remaining blockers. Done means the agreed behavioral checks passed under the stated conditions. A browser smoke test does not establish load capacity, security assurance, accessibility conformance, deployment, or customer acceptance by itself. When coordinated, append the evidence to the existing delivery record; standalone QA can return it directly.
+## Exercise the real interface
+
+Run the normal journey from entry point to expected result. Verify persisted or downstream state when required; a success toast alone does not prove a write succeeded.
+
+Choose negative and boundary cases relevant to the change: invalid input, empty/loading/error states, refresh/back navigation, retries, duplicates, permissions, or interruptions. For UI changes, use a real browser and inspect relevant viewport sizes, keyboard access, focus, labels, and errors.
+
+Inspect relevant console and network evidence to distinguish UI defects from API failures or an unavailable environment. Keep only privacy-safe screenshots and logs. Code inspection or an unviewed generated screenshot does not establish visual verification.
+
+## Resolve findings and repeat affected checks
+
+Report defects with reproduction steps, expected and actual results, revision/environment, evidence, and impact. If repair is authorized, use [debug](debug.md), then rerun the failed journey and affected neighbors. Keep unrelated findings separate. Do not weaken acceptance to make a run pass.
+
+*Fictional example:* Northstar's operator sees “Import complete,” but refreshing shows no new records. Check the downstream state and network response before reporting success or deciding whether the defect is in the page or the import service.
+
+## Completion
+
+Return a [verification receipt](verification.md) with checked journeys, observed results, reproducible defects, limitations, and blockers. Name roles, devices, environments, and data conditions that remain untested. Completion means agreed behavioral checks passed under the stated conditions.
+
+A browser smoke test alone does not establish load capacity, security assurance, accessibility conformance, deployment, or customer acceptance. When coordinated, append evidence to the existing delivery record under its write rules; standalone QA can return the receipt directly.

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

@@ -3,11 +3,11 @@
   "version": 1,
   "files": {
     "SKILL.md": "4a5cb9e98910f043bd8f4482540fd68387b45878946379514d4d581cc813c61f",
-    "references/build.md": "7634abd02b70011b7443a65ea3aaf3cb536ed5b051312aed188f46523deea7f9",
-    "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
+    "references/build.md": "03c52eda90642c62053b53ef1e85c97b4e647600f454aee9da0e415c9d98903e",
+    "references/debug.md": "3273a921a98522431ae821a283814897270c719cbfab83d14b99175537d869e5",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
-    "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
-    "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
+    "references/integrate.md": "1cb7a60d7545b0bf224fce678a04ce6ccdf368c47877d9c8e4dc4272bb0d5b0c",
+    "references/qa.md": "41de4d70827c83291efa217e97d777f62ec2849827687fbba7e4b1d17484b87e",
     "references/review.md": "55733ca868c00fb22110bc7b3ec7bb6c6451366c795073b19a2bccd30d2764c8",
     "references/ship.md": "95f51772b29de6f7d174f1f7678f15d46a3a5327dcb8facb94288e27907ae92c",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",