fdeops 4.0.4 → 4.1.0

package/skills/fde-evaluate/references/ship.md

@@ -0,0 +1,73 @@
+# ship - Deliver and release with evidence
+
+**Enter when:** an implemented increment needs a delivery checkpoint, deployment, or wider rollout. Use [build](build.md) for implementation; an untested business or technical assumption needs an experiment before a release claim.
+
+Start from [task context](task-context.md). Standalone work uses supplied permitted context and a release receipt; it does not require `.fde/` initialization. In engagement mode, use privacy-safe views of confirmed context, decisions, terrain, success, delivery, applicable trust constraints, and AI evaluation evidence. Never load raw `<private>` blocks into a model. The `fde` CLI remains local-only; deployment uses the customer's authorized tools, never a new network capability inside `fde`.
+
+## Establish the delivery contract
+
+Identify the exact outcome, acceptance check, scope, affected users/systems, target environment, recovery mechanism, and who or what is authorized to accept and release it. Reuse confirmed authority and checks for routine work. Do not invent missing signers, permissions, measurements, or acceptance.
+
+For an initialized engagement, run `fde doctor --ready` before a new delivery plan or material scope change. Missing binary success or a named customer-side signer blocks that planning progression until resolved. A passing doctor validates record structure, not connectivity, release readiness, or customer acceptance. Standalone work evaluates the supplied contract directly.
+
+A customer delivery checkpoint must let the agreed decision-maker replay and reject the acceptance check through an interface they operate. Prefer their staging; otherwise use an agreed representative environment and disclose its owner and limitations. Local green proves only the local run. Routine fixes may share an agreed checkpoint; no fixed number of changes forces a ceremony.
+
+## Prepare a reviewable increment
+
+1. Inspect repository instructions, working tree, overlapping work, and the complete intended release diff. Include working-tree changes when testing an uncommitted candidate. Preserve unrelated work; separate unintended behavior before release.
+2. Identify applicable before-state evidence and the changed outcome. Name dependencies, stop conditions, and irreversible effects. Existing applicable evidence may be reused with attribution, never represented as a fresh run.
+3. Complete [verification](verification.md) and [review](review.md), proportional to the change and repository requirements. A self-check is not an independent review. Record command, revision, environment, date, result, and unrun checks. Exercise relevant operating exceptions and fallback paths, not just the happy path.
+4. For AI behavior, obtain a scoped [eval verdict](eval-pack.md) for the candidate and applicable controls. A permitted bounded automation workflow remains permitted within its documented limits. A missing evaluation, failed critical case, or unknown action authority prevents release of that path; non-AI changes record eval as not applicable.
+
+## Release gate
+
+Before deployment, establish these facts from existing evidence or a necessary check. Missing material evidence blocks the dependent release step; continue independent preparation. Do not ask again for approval already provided within the same scope.
+
+| Dimension | Required evidence |
+|-----------|-------------------|
+| Candidate | Exact revision/artifact, intended diff, dependencies, applicable required checks passing; no skipped failure presented as green |
+| Target and access | Service/account/region, environment, authorized deployment identity and mechanism, secret provisioning without revealing values |
+| Acceptance | Replayable check and agreed decision-maker/mechanism; record actual acceptance separately from readiness |
+| Data and policy | Permitted data, applicable security/residency/change-window requirements, necessary approvals already recorded or obtained |
+| Recovery | Applicable tested rollback, restore, compensation, or roll-forward within agreed recovery-time/data-loss limits; explicit authority for irreversible effects |
+| Operations | Named release/recovery owner, runbook appropriate to risk, health and business signals, stop thresholds, observation coverage |
+| AI, when applicable | Current applicable SHIP eval evidence, critical failures zero, enforced action boundary and required human review or documented bounded automation |
+
+Check migration compatibility, old/new version coexistence, delayed jobs, caches, and already-emitted side effects where relevant. A code revert does not undo data loss or external writes. Reuse drill evidence only when the mechanism and relevant conditions are unchanged, explaining applicability. If recovery is only a plan, exercise it in a permitted representative environment before release.
+
+Use the repository's existing secret scanning and security checks; avoid diagnostic commands that print credential matches. Retain sanitized references to results. Resolve material evidence gaps or obtain an explicit, authorized narrowing of the release; do not average critical blockers into a readiness score.
+
+For a coordinated engagement, also connect the release to the agreed value bucket and baseline/target, and record a dated receipt for the affected operating path. An unmeasured result remains pending with a measurement next step; do not invent realized value to pass a gate.
+
+## Deploy within authority
+
+Execute only when the requested workflow authorizes deployment to this target and the applicable gates are met. Otherwise leave a concrete release candidate, exact deployment/recovery instructions, evidence, and the remaining authorization for review. A permission to implement or test is not permission to publish.
+
+Use the customer's established pipeline and rollout mechanism. Select canary, staged exposure, blue/green, or direct rollout according to actual risk and platform capabilities; do not impose a universal cohort sequence. Define advance/abort thresholds and observation window before starting. If another operator must execute, record their handoff and report deployment pending until there is evidence it happened.
+
+During rollout inspect health, errors, key user behavior, and side-effect integrity. Halt expansion on breached thresholds or critical harm and apply authorized containment/recovery. Do not continue merely because the deploy command exited successfully.
+
+## Verify operation and hand off
+
+Run permitted smoke and acceptance checks against the deployed candidate. Record deployment identity/time, observed signals, sample/window, failures, recovery actions, and remaining gaps. Define the pulse: metric, cadence, threshold, owner, and response. For AI, include permitted output sampling and drift/action-boundary monitoring.
+
+Before wider exposure, verify expected load/cost, data pipeline behavior, ownership, support, and applicable governance for the proposed audience. Choose expansion conditions from evidence; a successful pilot does not establish readiness for an arbitrary larger scale. Measure adoption against the eligible users, expected workflow frequency, and agreed observation window; investigate misses without guessing their cause.
+
+## Receipt and completion
+
+Keep these claims separate: implemented, verified, deployed, measured outcome, and accepted. Include the candidate, target, command/pipeline, applicable checks and unrun checks, review source, evaluation where needed, authority source, recovery evidence, observation, and next owner/action. Attribute acceptance to its actual source and scope. A staging measurement is not production value, and a commit is not deployment.
+
+In engagement mode, write confirmed implementation/decisions and delivery receipts under the existing record rules. Standalone work returns the same receipt or uses the repository's permitted release record. Committing, pushing, opening a PR, publishing, and notifying others are actions governed by the user's workflow, not mandatory steps imposed by this method.
+
+## Worked example
+
+A freight team agrees that dispatchers can retry a failed export once without creating a duplicate shipment. The change uses the existing queue and ops screen. The developer records a failing duplicate-delivery case, implements idempotency, and passes the relevant checks on a named candidate. QA observes both the retry status and the single downstream record on permitted staging fixtures. A separate reviewer examines the queue race; the receipt names that review and the revision.
+
+The export service has an approved staged-release workflow. Its owner reuses a recent recovery drill because the queue format and recovery mechanism are unchanged, recording that applicability. Deployment stops if duplicate records appear or the agreed error threshold is crossed. The authorized rollout completes, production smoke checks pass, and the dispatcher accepts the specified retry behavior with a dated source. The operating-cost benefit remains pending until the agreed measurement window closes. Implementation, deployment, acceptance, and measured value have different evidence. In the existing engagement, `decisions.md` records the agreed behavior and `delivery.md` holds the release receipt; standalone work returns those facts directly.
+
+## Principles
+
+- Release the reviewed candidate with applicable evidence and documented authority.
+- Test recovery against the effects that actually persist beyond a code revert.
+- Keep missing evidence visible and distinguish local, staging, and production claims.
+- Expansion follows observed acceptance and operating limits; fixed ceremonies cannot replace them.

package/skills/fde-evaluate/references/task-context.md

@@ -0,0 +1,12 @@
+# 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. 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.
+
+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/fde-evaluate/references/verification.md

@@ -0,0 +1,31 @@
+# verification - Make a claim replayable
+
+**Enter when:** reporting completion, evaluating an acceptance check, handing work to a reviewer, or preparing a release.
+
+Use [task context](task-context.md). This method returns evidence directly or writes an existing permitted task/engagement record; it never requires `.fde/` initialization.
+
+## Method
+
+1. Translate each claim into the observation that would support or reject it. Reuse agreed acceptance criteria and required repository checks. Select focused checks for changed behavior before broadening to release requirements.
+2. Identify the actual repository commands, fixtures, runtime, and environment. Read command behavior before executing it, especially when it can write externally. Use authorized environments and avoid leaking secrets through logs or diagnostic commands.
+3. Run the checks and inspect results, including exit status and relevant output. A running job, test discovery, a mocked response, and a successful real request are different evidence. Record asynchronous completion before claiming success.
+4. Bind evidence to the tested revision and working tree. For uncommitted changes record the base revision plus changed paths and an available diff digest or snapshot identifier. For browser/manual checks record the steps, inputs, observed result, and inspected evidence.
+5. After a change, rerun checks whose behavior or assumptions were affected. Reuse prior evidence only when the relevant code, dependencies, data, and environment remain applicable; cite the original run and reason. Never imply reused evidence was rerun.
+6. Label every required check **passed**, **failed**, **blocked**, or **not run**. Include why blocked/not run, impact, and next step. Missing evidence is unproven; it is not an observed failure or a pass.
+
+## Receipt
+
+Use one compact entry per check or a table with these fields:
+
+- Claim / acceptance check and expected result.
+- Exact command and working directory, or manual journey and inputs.
+- Environment, runtime/tool versions when relevant, and fixture/data source.
+- Revision plus working-tree identity; run date/time.
+- Observed result and exit status where available; safe evidence location.
+- Status, limitations, unrun checks, and next step.
+
+Keep implementation, verification, deployment, measured outcome, and customer acceptance distinct. A local pass supports the tested local behavior. An acceptance claim needs an attributed source from the agreed decision-maker or agreed acceptance mechanism. Record no raw `<private>` blocks, credentials, or hidden reasoning.
+
+## Acceptance
+
+A completion statement cites applicable evidence for its claims and explicitly names material gaps. If required checks fail, investigate or report the blocker; never skip them, edit expectations, or relabel the scope without authority to obtain a green result.

package/skills/fde-feedback/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: fde-feedback
+description: Assess a field lesson for reuse or product feedback without exposing customer context. Use for recurring deployment lessons; distinguish a hypothesis from a validated pattern.
+---
+
+# fde-feedback
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Assess a field lesson for reuse or product feedback without exposing customer context. Use for recurring deployment lessons; distinguish a hypothesis from a validated pattern.
+
+Read [the task context contract](references/task-context.md), then [the method](references/encode-pattern.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/fde-feedback/references/encode-pattern.md

@@ -0,0 +1,96 @@
+# encode-pattern - Encode the pattern
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**Enter when:** the engagement is closing and reusable patterns exist, a technique worked well and will apply to future clients, the FDE notices themselves doing the same thing on a second engagement, or close identified a pattern worth preserving.
+
+**Read first:** `decisions.md`, `reality.md`, `delivery.md`, `retrospectives/`, `context.md`. Patterns live in what was *done*, not what was planned.
+
+The difference between a 5-year FDE and a 15-year FDE is not talent - it's encoded patterns. The 15-year FDE walks into a new engagement and recognises the situation in minutes because they've seen it before, named it, and know the move. Pattern extraction turns experience into reusable intelligence.
+
+## Method (you do this work)
+
+**1. Identify the pattern candidates.** Scan the engagement for things that:
+
+| Signal | Example |
+|--------|---------|
+| Worked well and would work again in a similar situation | The "show the workaround first" approach to earning ops team trust |
+| Failed and the failure mode is predictable | The "refactor before understanding" mistake on legacy codebases |
+| Was discovered late and should have been discovered early | The hidden cron job that broke the migration - always ask about cron jobs |
+| Required a workaround that others would face too | The compliance dance for getting AI tools approved in regulated environments |
+| Involved a political dynamic that repeats | The passed-over internal team dynamic - present in every engagement with external FDEs |
+
+**2. Write the pattern in a transferable format.** Each pattern must be usable by a future FDE who has never heard of this engagement:
+
+```markdown
+## Pattern: <name>
+
+### Situation
+<When does this pattern apply? What does the FDE see/hear that triggers recognition?>
+
+### The move
+<What to do, specifically. Not advice - steps.>
+
+### Why it works
+<The mechanism - why this approach succeeds where the obvious approach fails.>
+
+### Watch out for
+<The failure mode or edge case that makes the pattern not apply.>
+
+### Evidence
+<Permitted source, what happened, measured result, and limits. Keep identifying evidence in its original customer record.>
+```
+
+**3. The pattern quality test.** Before encoding:
+
+| Test | Pass | Fail |
+|------|------|------|
+| **Transferable?** | Another FDE could apply this without context from this engagement | Only makes sense if you know the specific client |
+| **Specific enough?** | Contains concrete steps, not just principles | "Build trust" / "Communicate well" - too vague to act on |
+| **Repeatable?** | Applies to a class of situations, not just this one | Only worked because of a unique circumstance |
+| **Falsifiable?** | You can tell when the pattern is working or not | No way to measure whether applying it helped |
+| **Monday bag?** | You would refuse the next similar embed without this in your bag - a named move plus an artifact you can drop on day one (pipe questions, CAB dance, eval golden shape, floor-drill script) | "We learned to communicate." Patterns that only live in this client's `.fde/` do not compound |
+
+**4. Classify by stage.** Patterns sort into the same stages as the skills:
+
+| Stage | Pattern type | Example |
+|--------|-------------|---------|
+| **Land** | Political / relational | "The passed-over team warm-up protocol" |
+| **Discover** | Investigative / analytical | "The cron-job discovery checklist for legacy systems" |
+| **Plan** | Structural / strategic | "The three-option presentation for nervous sponsors" |
+| **Ship** | Technical / safety | "The Strangler Fig on financial transaction code" |
+| **Outcome** | Operational / process | "The regulated-environment change-approval timeline buffer" |
+| **Close** | Knowledge / handoff | "The 2am document format that actually gets used" |
+
+**5. Version and evolve.** Patterns are living documents:
+
+- First use: **v0.1** - hypothesis based on one engagement
+- Later uses: record context, observed results, failures, and refinements. Repetition supplies evidence; it does not automatically validate the pattern. Promote a version when a substantive revision warrants it, not at a fixed use count.
+- After modification: increment minor version with what changed and why
+- After contradiction: note the counter-example, adjust the "watch out for" section
+
+**6. Cross-engagement pattern mining.** Only when explicitly authorized for the named engagements and permitted by each customer's data policy. Keep records separate; use sanitized CLI packets or targeted recall in each authorized context, never raw file comparisons. Otherwise extract a candidate from the current permitted context only.
+
+- Compare permitted problem summaries - do the same problems recur?
+- Compare permitted decision summaries - are the same decisions being made?
+- Compare permitted lessons - are the same lessons being learned twice?
+
+A pattern learned twice is a process failure. Encoding it prevents the third time.
+
+## Artifact
+
+**`patterns.md`** - candidates and evidence for this engagement, indexed by stage and situation trigger. A shared library is a separate, authorized export: remove names, identifiers, distinctive operational details, secrets, and confidential code or data. Keep source receipts in the original record and export only permitted generalizations.
+
+**`retrospectives/YYYY-MM-DD-<engagement>.md`** - reference to which patterns were extracted from this engagement.
+
+## Checkpoint
+
+Present the extracted patterns to the FDE: "From this engagement, I've identified N patterns worth encoding. The highest-value one is <name> because <it will apply to future engagements in these situations>." Confirm the pattern is accurate - the FDE's field judgment outranks the analysis.
+
+## Principles
+
+- If you did it twice, encode it. The same lesson learned three times is a failure.
+- Patterns are steps, not principles. "Build trust" isn't a pattern; "fix a small visible bug on day one" is.
+- Every pattern needs a situation trigger - the FDE must recognise when it applies.
+- Version substantive changes. State the evidence and limits; repeated use is not automatic confirmation.
+- The pattern library is the FDE's compound interest. It's what separates 5 years of experience from 1 year repeated 5 times.

package/skills/fde-feedback/references/task-context.md

@@ -0,0 +1,12 @@
+# 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. 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.
+
+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/fde-handoff/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: fde-handoff
+description: Transfer operation of a customer deployment with ownership, evidence and a tested support path. Use for handoff or an engineer rotation, not merely code delivery.
+---
+
+# fde-handoff
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Transfer operation of a customer deployment with ownership, evidence and a tested support path. Use for handoff or an engineer rotation, not merely code delivery.
+
+Read [the task context contract](references/task-context.md), then [the method](references/close.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/fde-handoff/references/close.md

@@ -0,0 +1,66 @@
+# close - Transfer operations
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**Enter when:** the engagement is ending - the customer team must run this without the FDE.
+
+**Read first:** bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Build the full picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for the code paths needed by the successor.
+
+The engagement doesn't end at ship. It ends when the customer can maintain what was built without calling.
+
+## Method (you do this work, with the FDE's answers)
+
+**0. The opening question:** "What will bite them when you're gone?" Their answer shapes everything written below.
+
+**1. The retrospective.** Work through, blame-free and specific:
+- Did the real problem match the brief? (Compare `brief.md` vs `reality.md` - you have the receipts.)
+- Which trust moments mattered?
+- What did the codebase teach that `terrain.md` didn't know at the start?
+- Which risk almost became real?
+- AI components: did they behave in production? What failure modes did the prototype hide? Is the team equipped to maintain them?
+
+**1b. Value + receipts close gate (refuse green close if any fail):**
+- Primary value bucket in `success.md` matches what the sponsor funded; at least one ledger row has **Measured** (not forever-`pending`) with evidence **and a named customer-side owner in Accepted by** for that bucket - or the retrospective explicitly records “not measured; sponsor accepted pending.” A measured-but-unaccepted number closes as `claimed`; say so in the retrospective rather than closing green on arithmetic nobody signed.
+- Audit receipt exists for the final shipped path (exceptions/operating map walked; cite file).
+- Eval receipt: **n/a if no AI**, else final scoped eval result + operating owner and required human-review or bounded-automation authority recorded; kill switch / fallback named in `handoff.md`.
+- One line in the retrospective: which bucket moved, by how much, vs baseline.
+
+**2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. Use [encode-pattern](encode-pattern.md) to distinguish candidate patterns from supported ones and protect customer data.
+
+**3. The handoff.** Operational knowledge for the person woken at 2am, not technical documentation: the 3 things that will break and the fix for each · who holds the tribal knowledge · what each alert means · deploy and rollback in plain language. AI components additionally: model version, what normal output looks like (so drift is recognisable), fallback behaviour, who owns retraining, **how to disable the AI path without taking down the feature** - without this the team turns it off at the first misbehaviour and it stays off.
+
+**4. Transformation engagements - four extra answers in `handoff.md`:**
+- Who owns AI governance after the FDE leaves? (Who can pull a model from production?)
+- The retraining trigger, exactly: "precision < 0.82 on validation for 3 consecutive weeks → <owner> retrains." A number, a condition, an owner - not "when performance drops."
+- The operating model at scale: who coordinates twenty use cases across five teams?
+- Decision authority for new use cases: intake, risk assessment, approver.
+
+## Artifact
+
+**`retrospectives/YYYY-MM-DD-<engagement>.md`** - one file per close (separate files make cross-engagement patterns scannable). **`patterns.md`** - reusable patterns extracted. **`handoff.md`** - the 2am document.
+
+## Checkpoint
+
+**Check the handoff as a lookup tool.** Give the intended operator one realistic task, such as finding the owner and recovery steps for a failed run. Can they locate the answer and its source in the permitted handoff without your explanation? A reader finding the instructions is not proof they can execute them; verify operation separately in the agreed safe environment. Correct the passage they could not use, rather than adding a longer introduction.
+
+If the operator is unavailable, a fresh reviewer can attempt the same lookup using only the permitted draft and task. Report this as a simulated clarity check, not operator validation, customer approval, or a green close. Claim independent review only if a separate reviewer actually performed it; identify the reviewer and evidence available. If none is available, perform a labeled self-check and report independent review as unperformed. Use one focused pass for a consequential handoff; do not add a committee or a second approval ritual.
+
+Direct assessment to the FDE: did the engagement achieve `success.md` · 2-3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Also: value bucket + audit receipt green; eval **n/a or green**. Pending Measured without sponsor acceptance = gap, not green close. Honest - a gap named now is cheaper than a callback in six weeks.
+
+## Worked example
+
+Acme, twelve weeks in, the FDE is rolling off.
+
+Retrospective against the receipts: `brief.md` asked for monitoring, `reality.md` proved it was ownership - and the delta is the most useful paragraph in the file, because it is exactly the argument the next engagement will need.
+
+The close gate bites in a useful way. The ledger shows detection at 12 minutes measured across two real incidents, but **Accepted by** is empty - Marco confirmed it in Slack, Denise (finance) never did, and Denise is whose escalation started the engagement. So it closes as `claimed` with a one-line retrospective note and a named next step, rather than a green close on a number nobody with budget agreed to.
+
+`handoff.md` is written for the person woken at 2am: the three things that break, what the page means, how to re-run manually the way Marco does, and who holds the tribal knowledge (Raj, who built the original job - credited, because he protects it now). `patterns.md` gets *"unowned job" presents as "unmonitored job"* - it has now happened twice.
+
+## Principles
+
+- Done = the customer operates without you.
+- No named value bucket moved (or sponsor-accepted pending) = not a green close.
+- The retrospective is an investment in the next engagement, not a post-mortem.
+- Encode what repeated. The same lesson learned twice is a process failure.
+- Write the handoff for 2am.

package/skills/fde-handoff/references/encode-pattern.md

@@ -0,0 +1,96 @@
+# encode-pattern - Encode the pattern
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**Enter when:** the engagement is closing and reusable patterns exist, a technique worked well and will apply to future clients, the FDE notices themselves doing the same thing on a second engagement, or close identified a pattern worth preserving.
+
+**Read first:** `decisions.md`, `reality.md`, `delivery.md`, `retrospectives/`, `context.md`. Patterns live in what was *done*, not what was planned.
+
+The difference between a 5-year FDE and a 15-year FDE is not talent - it's encoded patterns. The 15-year FDE walks into a new engagement and recognises the situation in minutes because they've seen it before, named it, and know the move. Pattern extraction turns experience into reusable intelligence.
+
+## Method (you do this work)
+
+**1. Identify the pattern candidates.** Scan the engagement for things that:
+
+| Signal | Example |
+|--------|---------|
+| Worked well and would work again in a similar situation | The "show the workaround first" approach to earning ops team trust |
+| Failed and the failure mode is predictable | The "refactor before understanding" mistake on legacy codebases |
+| Was discovered late and should have been discovered early | The hidden cron job that broke the migration - always ask about cron jobs |
+| Required a workaround that others would face too | The compliance dance for getting AI tools approved in regulated environments |
+| Involved a political dynamic that repeats | The passed-over internal team dynamic - present in every engagement with external FDEs |
+
+**2. Write the pattern in a transferable format.** Each pattern must be usable by a future FDE who has never heard of this engagement:
+
+```markdown
+## Pattern: <name>
+
+### Situation
+<When does this pattern apply? What does the FDE see/hear that triggers recognition?>
+
+### The move
+<What to do, specifically. Not advice - steps.>
+
+### Why it works
+<The mechanism - why this approach succeeds where the obvious approach fails.>
+
+### Watch out for
+<The failure mode or edge case that makes the pattern not apply.>
+
+### Evidence
+<Permitted source, what happened, measured result, and limits. Keep identifying evidence in its original customer record.>
+```
+
+**3. The pattern quality test.** Before encoding:
+
+| Test | Pass | Fail |
+|------|------|------|
+| **Transferable?** | Another FDE could apply this without context from this engagement | Only makes sense if you know the specific client |
+| **Specific enough?** | Contains concrete steps, not just principles | "Build trust" / "Communicate well" - too vague to act on |
+| **Repeatable?** | Applies to a class of situations, not just this one | Only worked because of a unique circumstance |
+| **Falsifiable?** | You can tell when the pattern is working or not | No way to measure whether applying it helped |
+| **Monday bag?** | You would refuse the next similar embed without this in your bag - a named move plus an artifact you can drop on day one (pipe questions, CAB dance, eval golden shape, floor-drill script) | "We learned to communicate." Patterns that only live in this client's `.fde/` do not compound |
+
+**4. Classify by stage.** Patterns sort into the same stages as the skills:
+
+| Stage | Pattern type | Example |
+|--------|-------------|---------|
+| **Land** | Political / relational | "The passed-over team warm-up protocol" |
+| **Discover** | Investigative / analytical | "The cron-job discovery checklist for legacy systems" |
+| **Plan** | Structural / strategic | "The three-option presentation for nervous sponsors" |
+| **Ship** | Technical / safety | "The Strangler Fig on financial transaction code" |
+| **Outcome** | Operational / process | "The regulated-environment change-approval timeline buffer" |
+| **Close** | Knowledge / handoff | "The 2am document format that actually gets used" |
+
+**5. Version and evolve.** Patterns are living documents:
+
+- First use: **v0.1** - hypothesis based on one engagement
+- Later uses: record context, observed results, failures, and refinements. Repetition supplies evidence; it does not automatically validate the pattern. Promote a version when a substantive revision warrants it, not at a fixed use count.
+- After modification: increment minor version with what changed and why
+- After contradiction: note the counter-example, adjust the "watch out for" section
+
+**6. Cross-engagement pattern mining.** Only when explicitly authorized for the named engagements and permitted by each customer's data policy. Keep records separate; use sanitized CLI packets or targeted recall in each authorized context, never raw file comparisons. Otherwise extract a candidate from the current permitted context only.
+
+- Compare permitted problem summaries - do the same problems recur?
+- Compare permitted decision summaries - are the same decisions being made?
+- Compare permitted lessons - are the same lessons being learned twice?
+
+A pattern learned twice is a process failure. Encoding it prevents the third time.
+
+## Artifact
+
+**`patterns.md`** - candidates and evidence for this engagement, indexed by stage and situation trigger. A shared library is a separate, authorized export: remove names, identifiers, distinctive operational details, secrets, and confidential code or data. Keep source receipts in the original record and export only permitted generalizations.
+
+**`retrospectives/YYYY-MM-DD-<engagement>.md`** - reference to which patterns were extracted from this engagement.
+
+## Checkpoint
+
+Present the extracted patterns to the FDE: "From this engagement, I've identified N patterns worth encoding. The highest-value one is <name> because <it will apply to future engagements in these situations>." Confirm the pattern is accurate - the FDE's field judgment outranks the analysis.
+
+## Principles
+
+- If you did it twice, encode it. The same lesson learned three times is a failure.
+- Patterns are steps, not principles. "Build trust" isn't a pattern; "fix a small visible bug on day one" is.
+- Every pattern needs a situation trigger - the FDE must recognise when it applies.
+- Version substantive changes. State the evidence and limits; repeated use is not automatic confirmation.
+- The pattern library is the FDE's compound interest. It's what separates 5 years of experience from 1 year repeated 5 times.

package/skills/fde-handoff/references/task-context.md

@@ -0,0 +1,12 @@
+# 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. 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.
+
+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/fde-integrate/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: fde-integrate
+description: Build or change a customer-system integration with explicit data mapping, permissions, retries and reconciliation. Use for connectors, imports, write-back and upstream APIs.
+---
+
+# fde-integrate
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Build or change a customer-system integration with explicit data mapping, permissions, retries and reconciliation. Use for connectors, imports, write-back and upstream APIs.
+
+Read [the task context contract](references/task-context.md), then [the method](references/integrate.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/fde-integrate/references/build.md

@@ -0,0 +1,20 @@
+# 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).
+
+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.
+
+## 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.
+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.
+5. 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. 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.
+
+## Deliverable and 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.
+
+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.

package/skills/fde-integrate/references/debug.md

@@ -0,0 +1,18 @@
+# debug - Find and repair the cause
+
+**Enter when:** a reproducible failure, regression, incident symptom, or misleading output needs investigation.
+
+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.
+
+## Method
+
+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.
+
+## Deliverable and acceptance
+
+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.

package/skills/fde-integrate/references/eval-pack.md

@@ -0,0 +1,26 @@
+# eval-pack - Evaluate the model's allowed behavior
+
+**Enter when:** AI, LLM, RAG, or agent behavior needs evidence before an experiment, release, or material expansion. Non-AI work skips this method.
+
+Use [task context](task-context.md). Supplied permitted context and an evaluation report are sufficient without `.fde/`. In a coordinated engagement, use the existing trust/terrain context and keep the report in `evals.md`; read only privacy-safe views.
+
+## Method
+
+1. **Define the evaluated surface.** Name the model judgment, inputs, outputs, downstream actions, environment, and relevant failure impact. Separate model quality from deterministic tool authorization and application checks. Document the actual allowed action boundary and its source; missing authority remains unknown.
+2. **Choose cases by risk and coverage.** Use permitted historical examples, expert-labeled cases, or clearly marked synthetic fixtures. Cover relevant segments, boundary conditions, known failure modes, and critical harms. Record input, expected outcome/rubric, provenance, and critical-failure rule per case. Keep evaluation cases separate from tuning where possible; no fixed case count proves safety.
+3. **Agree the pass rule before the run.** Define quality thresholds, critical failures, coverage expectations, and acceptable uncertainty for this use. Use deterministic checks where possible and inspect subjective labels or judge reliability. Propose missing criteria for agreement; do not manufacture acceptance from the observed scores.
+4. **Run the actual evaluated path.** Record model/provider version, prompts/configuration, retrieval corpus or tools, application revision, environment, fixtures, and run date. Repeat where variability matters. Report totals, per-segment results, critical failures, and limitations using [verification](verification.md). A model-only run does not prove the agent's tool boundary works.
+5. **Verify action authority and controls.** Human approval is required where the user's policy or task requires it. Already agreed bounded automation may run within its documented actions, identities, environments, and limits; do not require fresh approval for every authorized action. Check enforcement outside the model, least privilege, input/output validation, cost/rate limits, stop conditions, observability, and recovery as applicable. Unknown or exceeded authority blocks those actions. Evaluation success never grants new authority.
+6. **Make a scoped verdict.** Report **SHIP** only when agreed criteria pass, critical failures are zero, applicable authority/control checks pass, and material coverage gaps are resolved or the release is explicitly narrowed by the responsible decision-maker. Otherwise report **NO-SHIP** with the smallest corrective step: fix, gather evidence, descope, or reconsider the judgment surface. A SHIP verdict is technical evidence for the stated scope, not permission to deploy.
+
+## Deliverable and acceptance
+
+Return the suite/source, thresholds, counts and segments, top failure modes, control evidence, human-review gate or bounded automation authority, limitations, and dated verdict. Record unknown values honestly. Reevaluate after changes that affect model behavior, retrieval, tool permissions, or data conditions; cite why unchanged evidence remains applicable rather than implying a rerun.
+
+When coordinated, append a concise eval receipt to delivery records. For release use [ship](ship.md). For ongoing use define the drift signals, sample policy permitted by data handling rules, owner, and conditions that suspend or narrow automation. Do not store secrets, raw `<private>` data, or hidden chain-of-thought in reports.
+
+## Principles
+
+- Thresholds and authority come from the agreed contract, never from a convenient observed result.
+- Critical failures block the evaluated release scope; disclose coverage and uncertainty.
+- Bound automation with enforceable controls, and require human review where the policy requires it.

package/skills/fde-integrate/references/integrate.md

@@ -0,0 +1,18 @@
+# integrate - Prove the system boundary
+
+**Enter when:** connecting an API, data source, SDK, event stream, tool, or service, or changing its contract.
+
+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.
+
+## 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.
+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.
+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.
+
+## 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/fde-integrate/references/qa.md

@@ -0,0 +1,18 @@
+# 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.
+
+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.
+
+## Method
+
+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.
+
+## Deliverable and acceptance
+
+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.