fdeops 4.0.4 → 4.1.0

package/skills/fde/references/ship.md

@@ -1,318 +1,73 @@
-# ship - Deliver the increment
+# ship - Deliver and release with evidence
 
-**Enter when:** you are writing or updating on their codebase, they need to see something real, or you are going live.
+**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.
 
-**Read first:** `context.md`, `decisions.md`, `delivery.md`, `success.md`. Load `terrain.md` before you touch their code. Load `trust-profile.md` if the deploy touches regulated data or needs an approval chain. Load `evals.md` when the work touches AI/ML/LLM/RAG/agents.
+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`.
 
-Do not ask them to pick a mode. Name where you are, then start at the matching section:
+## Establish the delivery contract
 
-- Nothing on their staging yet → **one change they can see**
-- On staging, the signer in `success.md` can reject it → **go-live**
-- Prod is the question → **go-live**. Do not start a second change.
+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.
 
-If going live, check the evidence for the recovery path: has rollback, restore, compensation, or roll-forward been exercised under representative conditions? If only planned, validate it before release. Reuse applicable drill evidence when the mechanism and relevant conditions are unchanged; record why it applies.
+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 bounded experiment that tests an assumption is `poc`. This skill turns a validated direction into a maintainable change on a repo they will own, then production. Inspect existing prototype code and retain suitable tested parts; replace unsafe shortcuts based on evidence. A successful demo alone does not satisfy the readiness gates below.
+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.
 
-**Before a new delivery plan or material scope change:** run `fde doctor --ready`. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer and acceptance check; record verification without restarting approval. New judgment in the record still requires confirmation.
+## Prepare a reviewable increment
 
-## Field (name it once, then the same loop)
+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.
 
-| | Brownfield | Greenfield |
-|--|------------|------------|
-| What you touch | Code they already run | A new path or empty tree they will own |
-| First move | Characterise their tests, their runner, the workaround in `terrain.md` | First path a user can click. Not the whole product. |
-| Proof | Agreed representative environment and replayable acceptance check | Agreed representative environment and replayable acceptance check; record what remains untested before release |
-| Undo | Revert this change on its own | Name rollback or tested recovery; identify irreversible effects and required authority. |
+## Release gate
 
-Skip POC only when the killer assumption already lives in the repo (typical brownfield). If the bet is unproven, `poc` first.
+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.
 
-**Customer delivery means:** the signer in `success.md` can replay and reject the agreed acceptance check in an environment they operate. A green check on your laptop proves only what ran there. Routine fixes can share a delivery checkpoint; distinguish implementation, verification, deployment, and acceptance.
+| 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 |
 
-If `terrain.md` **Data estate** lists a **Blocker** this change depends on (source or pipe): stop. That is discover, not ship. Do not build a path they cannot feed.
+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.
 
-## Method - one change they can see
+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.
 
-One change = one coherent outcome with observable verification and a bounded recovery path. Prefer vertical slices that can be reviewed and exercised independently. A PR is how this often lands. It is not the job. The job is the change they can see.
+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.
 
-```
-BAD (layers):
-  1: all database models
-  2: all API endpoints
-  3: all UI components
-  4: wire everything together (and pray)
+## Deploy within authority
 
-GOOD (one user action each):
-  1: User can create a payment (schema + endpoint + minimal UI) - testable
-  2: User can view payment status (query + endpoint + UI) - testable
-  3: Payment retry on failure (logic + endpoint + UI feedback) - testable
-  4: Admin can void a payment (auth + logic + UI) - testable
-```
+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.
 
-Prefer independently revertible changes. When data or external effects cannot be undone, name the dependency, containment, tested recovery, and authorized owner before release.
+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.
 
-**Before you start this change:**
+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.
 
-- [ ] It is in `decisions.md` with acceptance criteria (happy + unhappy path)
-- [ ] Blast radius declared: which files, which systems, which users affected
-- [ ] Rollback named: revert this change, or something more specific
-- [ ] No dependency on an unmerged change (if dependent, state it and land in order)
-- [ ] `Kill if` is written - the observation that stops this change
-- [ ] Before-state evidence identified: the relevant failing output, number, or behavior, with its source and date. For a routine fix within confirmed scope, reference applicable existing evidence and batch the delivery receipt; capture new evidence when the relevant behavior or conditions changed. Never imply an old check was rerun.
-- [ ] Open PRs and uncommitted work in the area checked (`gh pr list`, `gh pr diff <n> --name-only`); overlap goes to `decisions.md` before you start
+## Verify operation and hand off
 
-Your coding pack writes the function. This skill owns done. When they disagree with this repo, the repo wins.
+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.
 
-**The loop.** In this order:
+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.
 
-```
-Read existing code in the area (search before creating)
-  → Characterise what is already there (their tests, their runner; greenfield: the empty tree)
-    → Implement the smallest path that works
-      → Verify the change; demonstrate at the agreed delivery checkpoint (below)
-        → Cleanup pass (dedupe, simplify - behaviour unchanged)
-          → Self-review against acceptance criteria
-            → Commit with a message the client's team can read
-              → Update decisions.md + delivery.md
-```
+## Receipt and completion
 
-**Verify the change and prove customer delivery.** Match evidence to the reviewed revision, environment, and acceptance criteria.
+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.
 
-- Use **their** test commands, fixtures, and CI. Record the command, result, revision, environment, and run date in `delivery.md`. Reuse existing evidence only when the relevant code and conditions are unchanged, citing why it still applies; never claim it was rerun. Run affected checks for changed behavior and required release checks before deployment. Missing evidence means unproven, not an observed failure.
-- At the agreed delivery checkpoint, the signer in `success.md` must be able to replay and reject the acceptance check using an interface they operate (screen, API, report, or equivalent). Routine fixes can share that checkpoint; passing tests alone does not establish customer acceptance.
-- Prefer staging they operate. When unavailable, use an agreed, permitted representative test environment, record its owner and limitations, and resolve material release-evidence gaps before production. A local demonstration is not deployment.
-- **Representative data.** Use permitted sanitized or synthetic fixtures that exercise relevant volumes, edge cases, and operating paths. Before go-live, record gaps such as batch timing, distribution, or production-only dependencies and their impact on the acceptance and abort checks. Resolve material gaps or explicitly narrow the release; never load sensitive production data merely to make a demo realistic.
-- Model in the path: `eval-pack` until `evals.md` says SHIP. Do not skip because "it looked right in chat."
-- A model drafts. A named human on their side ships. No unsupervised loop on their production. If the brief demands lights-out write-access, that is `who-decides` / `hold-scope`, not ship.
-
-The proof is whatever this client already believes, plus one new receipt they can replay.
-
-**Size by reviewability and risk.** Keep one coherent intent, bounded context, and observable acceptance checks. Split unrelated behavior or work whose recovery and review cannot be understood together. Diff size and elapsed time are warning signals, not hard gates: generated changes may be large and low risk; a one-line permission change may be critical. Use the repository’s checks and add meaningful coverage for changed behavior, rather than a test-count quota.
-
-**Show it.** Every 2-3 changes, something the customer can see: an endpoint they can hit, a UI they can click, a metric that moved, a risk that was retired. Technical progress invisible to stakeholders is trust decay. `delivery.md` gets updated after every visible change.
-
-**The scope trap.** Mid-change discoveries ("this module also needs updating," "I should refactor this while I'm here"):
-
-- If it's in `decisions.md`: do it as a separate change.
-- If it's NOT in `decisions.md`: log it as a scope receipt (see `hold-scope.md`), don't touch it.
-- Ugly code outside this change stays ugly. That is discipline, not laziness.
-
-After each change: required checks pass with applicable evidence, acceptance criteria evaluated, blast radius as declared, `Kill if` still false. At the agreed delivery checkpoint: what did they see, and what is their signal? Before production, complete the go-live gates below.
-
----
-
-## Deployment readiness gate (confirm the target before building the runway)
-
-Before scoring readiness, confirm WHERE this is going. State it in 2-3 lines - brief playback that invites correction:
-
-> "Deploying to: [target]. Pipeline: [how it gets there]. Rollback mechanism: [how to undo]. Any constraint I should know about?"
-
-**The checklist (confirm, don't assume):**
-
-| Dimension | Question | Status |
-|-----------|----------|--------|
-| **Target** | Cloud provider + service (ECS/Lambda/K8s/VM/on-prem)? | |
-| **Pipeline** | CI/CD exists? Manual? Who triggers prod deploy? | |
-| **Environments** | Dev → staging → prod path clear? Or deploying direct? | |
-| **Secrets** | Where do they live? (vault/SSM/env vars) Who provisions? | |
-| **Access** | Do YOU have deploy permissions, or does someone else push? | |
-| **Compliance** | Region constraints? Data residency? Encryption requirements? CAB/change window? | |
-| **Infra-as-code** | Terraform/Pulumi/CDK/manual? State file location? | |
-
-**If anything is blank:** ask now. Discovering deployment constraints after the change is where timelines slip. If the client hasn't defined these yet, that's a conversation before you write the runbook - not after.
-
-Write confirmed deployment context to `delivery.md` under a `## Deployment target` section.
-
----
-
-## Method - readiness gate (score before touching the deploy button)
-
-Score each dimension green/amber/red. This is the gate, not a suggestion:
-
-| Dimension | Green | Amber | Red |
-|-----------|-------|-------|-----|
-| Tests | All pass on deploy branch | Flaky tests skipped with justification | Failures present or tests not run |
-| Recovery | Applicable tested rollback/restore/compensation/roll-forward meets agreed recovery and data-loss limits | Documented; drill evidence needs refresh | No viable recovery, failed drill, or irreversible effects lack explicit authority |
-| Sign-off | Stakeholder approval in `decisions.md` with date | Verbal approval, not logged | No approval sought |
-| Runbook | Exists and someone other than you has read it | Exists but unreviewed | Missing |
-| Monitoring | Alerts configured, owner named, dashboard live | Alerts configured, no named owner | No monitoring |
-
-### Value + receipts gate (score with the table above)
-
-| Dimension | Green | Amber | Red |
-|-----------|-------|-------|-----|
-| **Value bucket** | `success.md` names primary bucket (`cost-save` \| `risk-mitigation` \| `revenue-uplift`) and a baseline→target metric; this change's value-ledger row has **Bucket** + **Promised** | Bucket named; **Measured** still `pending` with a pulse date | No bucket, or Promised empty / ticket-theater only |
-| **Audit receipt** | Dated line in `delivery.md` (`## Ship receipts` or ledger Evidence) proving exceptions/operating path were walked - cite `terrain.md` / `reality.md` / `audit.md` | Path described, not verified this ship | No audit receipt for this change |
-| **Eval receipt** | **n/a** (no AI on this change) **or** `evals.md` Verdict SHIP with dated golden run + HITL gate named | Eval pack exists; known fails open with owner + date | AI in scope and no eval receipt |
-| **AI eval pack** | `.fde/evals.md` Verdict SHIP; goldens run this change; critical fails 0; HITL filled if policy requires | Pack exists; run stale vs change log | AI-touching deploy and pack missing / NO-SHIP / HITL required but empty |
-
-**Any RED = stop. Do not deploy. Fix the red dimension first.**
-**2+ AMBER = sponsor conversation before deploying.** Present the ambers and get explicit "proceed" or "fix first."
-
-**AI-touching deploys (model, embeddings, RAG, agent, or inference path):**
-1. Read `.fde/evals.md`. If missing → **RED. Do not deploy.** Create the pack (`eval-pack` / `ai` overlay) and re-score.
-2. If Verdict is not **SHIP**, or Last run is older than the latest change-log row → **RED.**
-3. If `trust-profile.md` requires human-in-the-loop and the HITL gate has no reviewer → **RED.**
-4. Log in `delivery.md` → `## Ship receipts` before deploy: audit cite + eval receipt.
-5. Non-AI deploys: Eval = **n/a** - do not invent an empty pack.
-
-Write the readiness score (including value + receipts) to `delivery.md` before deploying. The score is the evidence if anything goes wrong.
-
-## Intent vs diff (before pre-blast)
-
-Ship the change you intended - not the drift that snuck in. Run this on the deploy branch against the **one-line intent** from `decisions.md` / `success.md` (the change you said you were building).
-
-```bash
-git diff <base>...HEAD --stat
-git diff <base>...HEAD
-```
-
-Score every touched path (or logical hunk):
-
-| Path / change | Verdict | Rule |
-|---------------|---------|------|
-| | **KEEP** | Directly required for the stated intent |
-| | **JUSTIFY** | Adjacent but load-bearing - one sentence why it must ship *now*, or split |
-| | **SPLIT** | Real work, wrong change - park in `decisions.md` kill/Next; do not deploy with this one |
-| | **DROP** | Noise (format-only, drive-by rename, unrelated tidy) - revert before ship |
-
-**Any SPLIT or DROP still in the tree = fix-first.** JUSTIFY without a written sentence = treat as SPLIT. Log a one-line receipt in `delivery.md`: `intent vs diff: KEEP n · JUSTIFY n · SPLIT n · DROP n - <intent>`.
-
-This is **code drift**, not stakeholder "also can you…" (that is `hold-scope`). Same family as review Stage 1 - ship refuses green when the diff outgrew the claim.
-
-## Pre-blast challenge (before the deploy button)
-
-For any non-trivial go-live (shared infra, regulated data, irreversible migration, or first prod touch), run this once before canary - not as theater, as a stop-the-line check:
-
-```
-CLAIM: <what you are about to ship, in one sentence>
-WHY IT MATTERS: <blast radius / who feels pain if wrong>
-CHALLENGE: <the strongest argument this is not ready - grounded in delivery.md / risks.md / trust-profile.md>
-VERDICT: proceed | fix-first | sponsor conversation
-```
-
-Rules: no invented stakeholders; if evidence is missing, the verdict is **fix-first** or **sponsor conversation**, not "probably fine." Log the CLAIM + VERDICT as a dated line in `delivery.md`. Skip for mechanical one-line config with an already-tested rollback.
-
-## Method - pre-flight (you verify each, confirmed not assumed)
-
-- All tests pass - state the command and result.
-- No hardcoded secrets/credentials (repeat `--include` per extension - brace globs silently match nothing):
-```bash
-grep -rnE "(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][^'\"]{8,}" \
-  --include="*.js" --include="*.ts" --include="*.py" --include="*.env" \
-  --include="*.yaml" --include="*.json" . | grep -vE "example|template|test" | head
-```
-- DB migrations checked for compatibility, data loss, and old/new application coexistence. Prefer expand/contract for destructive changes. Irreversible steps require explicit authority and a tested restore, compensation, or roll-forward plan.
-- Recovery documented **and tested**, with acceptable recovery time and data loss.
-- Monitoring alerts configured, someone watching.
-- Team knows the deploy is happening.
-- Deploy window has staffed observation and recovery coverage appropriate to the risk; respect the client’s change calendar and business-critical periods.
-- **Change approval (CAB) environments:** window open, ticket approved. In banking/healthcare/gov, deploying outside an approved window is a compliance finding even when the deploy succeeds. "We didn't know there was a CAB process" is not a defence - find out before the deploy date.
-
-## Method - the deploy
-
-**Rollout:** Choose canary, blue/green, staged cohorts, or the client’s proven release mechanism based on isolation, traffic, and failure cost. For a canary, set cohort size, exposure cap, observation duration, minimum sample, and advance/abort thresholds before starting; allow for delayed and batch effects. Watch errors, latency, and **the business metric this change affects**. Breached thresholds or critical harm → halt expansion and execute the tested recovery/containment plan; investigate after exposure is controlled. Advance only with sufficient evidence and a named operator.
-
-**Canary receipt** (write it, or the canary did not happen): what was watched, on whose dashboard, for how long, and that the next change did not start in the window. If prod is a CAB console, vendor button, or their pipeline, write the owner and the click path - the host agent does not get to pretend it shipped.
-
-**Programme-scale rollout (transformations)** - different problem from one service:
-1. **Pilot** - one team, one use case; success metrics defined *before* it starts (after = fitting metrics to results).
-2. **Limited release** - 3-5 teams, real load; this is where the failure modes the pilot hid show up.
-3. **Broad release** - self-serve onboarding; if teams still need the FDE to start, onboarding isn't finished.
-4. **Enterprise standard** - the FDE is no longer needed for this use case. That's the end state.
-Straight from pilot to standard = a high-profile failure at scale.
-
-## Method - after
-
-Keep implementation, test results, deployment, measured outcome, and customer acceptance separate in the receipt. Record the environment, observation window/sample, source, and remaining gaps. A commit is not a deploy; a staging measurement is not realized production value. When the baseline is missing or incomparable, record the observed result and the measurement next step without claiming an improvement. Record acceptance only for what the named person actually accepted, with a dated source; an engineer's summary remains attributed to that summary.
-
-Smoke tests against production. Verify the business metric moved the right way. Then **define the pulse before closing the laptop** - a deploy without a pulse is one you'll hear about only when it breaks:
-
-1. **Metric:** the number that says it's working - "p99 on payment endpoint < 800ms", not "errors low."
-2. **Frequency:** daily week one, weekly after, monthly when stable.
-3. **Threshold:** the exact value that triggers incident response. Nobody knows the number → nobody acts until too late.
-
-AI components: also define what *normal output* looks like and check a weekly sample of real production outputs - drift is technically-valid-but-wrong, and no exception will fire.
-
-## Method - scale readiness (pilot proved it, now deploy enterprise-wide)
-
-A successful pilot does not establish readiness for wider use. Check organizational ownership, governance, and infrastructure alongside technical performance before expanding.
-
-**The scale-readiness gate (all must be YES before broad rollout):**
-
-| Dimension | Question | Ready? |
-|-----------|----------|--------|
-| **Infra** | Can the system handle 10× current load without architectural change? | |
-| **Ops** | Can someone other than the FDE operate it at 2am? (runbook exists, tested) | |
-| **Data** | Is the data pipeline automated, not manual? Does it handle upstream schema changes? | |
-| **Security** | Has infosec signed off for production data at scale? | |
-| **Cost** | Is the cost model viable at 10× volume? (AI inference costs scale non-linearly) | |
-| **Governance** | Is there an owner, a review cadence, and an escalation path? | |
-| **Support** | Can users get help without the FDE? (docs, training, L1 support path) | |
-| **Measurement** | Are success metrics automated and dashboarded, not manually calculated? | |
-
-**If any dimension is "No":** that's the work before scaling. Name it, size it, put it in the plan. Scaling without readiness = a high-profile failure that kills the entire programme.
-
-**The scale sequence:**
-1. **Pilot** (1 team, controlled) → prove value, find failure modes
-2. **Limited** (3-5 teams, real load) → prove operability, find scale bugs
-3. **Broad** (self-serve onboarding) → prove the team doesn't need the FDE
-4. **Standard** (enterprise default) → the FDE exits this workstream
-
-Never skip a step. The sponsor always wants to skip from pilot to standard - that's the conversation the FDE protects.
-
-## Method - progressive adoption (built it, now people need to use it)
-
-Adoption isn't a handoff-stage problem - it starts while you are still writing the change. Software that launches to silence is software that gets decommissioned.
-
-**During the change:**
-- **Controlled exposure.** Use a feature flag or equivalent isolation when it reduces rollout risk. Choose cohorts and expansion criteria from traffic and impact; name the flag owner and removal point.
-- **Feedback loops built in.** A thumbs-up/down, a "was this helpful?", a usage counter. Instrument adoption, don't assume it.
-- **Resistance signals.** Watch for: workaround creation (they built a spreadsheet instead of using the tool), drop-off after day 3 (onboarding fails), vocal detractors (one influential skeptic can kill adoption). Address these before launch, not after.
-
-**At launch:**
-- **Champion network.** Identify 2-3 power users per team who adopt early. Support them intensely - they become your multiplier.
-- **Adoption targets agreed before launch.** Define the eligible users, expected usage frequency, observation window, baseline, and owner. A weekly workflow needs a different measure from a quarterly one. Investigate misses with users; usage alone does not establish whether onboarding, access, or value is the cause.
-- **The "switching cost" test.** If users can still do it the old way, they will. Adoption requires either: the old way is removed, the new way is dramatically better, or management mandates the switch. Know which lever applies.
-
-**Write adoption metrics to `delivery.md`:** active users, frequency, drop-off points, resistance signals. This is the evidence for renewal.
-
-## Artifact
-
-**`decisions.md`** - each change: what was implemented, what was tested, what was deferred, `Kill if`.
-
-**`delivery.md`** - each visible change in business language; then the deployment record: what shipped, when, recovery procedure, pulse definition, **scale-readiness assessment, and adoption metrics**. Written for whoever inherits the system.
-
-## Checkpoint
-
-After each change: required checks pass, acceptance criteria evaluated, blast radius as declared, `Kill if` still false. Batch routine fixes at the agreed delivery checkpoint; record staging and customer acceptance separately.
-
-Before full exposure: the chosen rollout’s advance criteria are met with sufficient observation and business-metric evidence, and the pulse is written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**, **intent vs diff clean** (no unresolved SPLIT/DROP). Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
+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
 
-Acme, brownfield. Plan Now has three changes, not "the payments rewrite."
-
-Change 1 is *user sees retry status on a failed payment* - schema + endpoint + the existing ops screen, 180 lines, their `pytest -k payments` green, revert is this change. `Kill if:` the signer cannot reject it on the screen they already use. Ugly retry-queue code two files over stays ugly. `decisions.md` logs the change; `delivery.md` says ops can see a retry without opening the spreadsheet. Marco sees it on staging they operate. That is the proof. Local green was not.
-
-Then Thursday go-live of the failure-routing change. Readiness scoring catches two things the diff does not. The audit receipt is missing: the operating map says Marco's manual re-run is the fallback, and nobody has checked whether the new page fires *before* his morning run or after - if after, the alert changes nothing. That gets walked and cited before deploy. Second, the intent-vs-diff read shows the PR also touches the settlement retry that was deferred; it comes out.
-
-Pre-blast challenge: "what does this break if it fires at 3am and nobody acks?" Answer: nothing breaks, but the rota is not yet agreed - so the deploy waits on a name, not on code. That is a one-day slip that prevents a fake green.
-
-After deploy: `delivery.md` ship receipt with the audit cite, the kill test evidence, and the rollback line. Eval receipt: n/a, no AI in this path.
+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.
 
-Greenfield is the same loop with an empty tree: first path a user can click, on an environment they will operate, then this go-live. Not the whole product in one dump.
+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
 
-- One user action per change. Layers are untestable until assembled.
-- Prove the agreed outcome in their environment and test recovery. Local green is not customer delivery.
-- The ugly code outside this change stays ugly. That's discipline, not laziness.
-- A deployment needs tested recovery within agreed time and data-loss limits; irreversible effects require explicit authority.
-- Halt expansion on breached thresholds or critical harm; contain exposure with the tested recovery plan before investigating.
-- Verify the business metric, not just the technical one.
-- No value bucket, no green ship. No pulse, no done.
-- Diff larger than the stated intent without KEEP/JUSTIFY receipts = fix-first.
-- AI path without eval receipt = fix-first; non-AI ships leave eval as n/a.
-- Scale readiness is organizational, not just technical. Check all 8 dimensions.
-- Adoption is measured from day one, not hoped for at launch.
+- 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/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/references/test-assumptions.md

@@ -34,10 +34,10 @@ Then classify blast radius:
 ```
 CRITICAL - if wrong, the engagement fails or the approach changes fundamentally
   → Must be validated before plan starts
-  
+
 LOAD-BEARING - if wrong, significant rework or timeline change
   → Must be validated before build starts
-  
+
 CONVENIENCE - if wrong, a task changes but the approach holds
   → Validate when you get there
 ```

package/skills/fde/references/three-options.md

@@ -1,10 +1,12 @@
 # three-options - Generate options
 
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
 **Enter when:** a significant technical or strategic decision needs to be made, the FDE is asked "what should we do?", the team is stuck between approaches, or a fork in the engagement requires the sponsor's input.
 
 **Read first:** `reality.md`, `terrain.md`, `assumptions.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
 
-One option is a request for trust. Two options is a false choice. Three options is a conversation between professionals. The FDE who presents three genuine options earns the decision-maker's respect - and their protection when things get hard.
+Compare materially different, defensible alternatives. Three is a useful presentation shape when three viable paths exist; do not pad the set to meet a quota. Include keeping the current approach or deferring when those are credible choices.
 
 ## Method (you do this work)
 
@@ -12,26 +14,26 @@ One option is a request for trust. Two options is a false choice. Three options
 
 > "Decision: approach for the payment migration. Decided by: CTO. Needed by: Friday. Deferral cost: blocks the next sprint and delays the pilot by two weeks."
 
-**2. Generate three genuine options from what survived.** Read `assumptions.md` (CONFIRMED / DISPROVED) and `terrain.md` `## Parts`. The playbook is unavailable. Assemble from those blocks only.
+**2. Generate genuine options from the evidence.** Use confirmed assumptions and known system parts; exclude disproved assumptions. If those records are absent, identify the supplied facts and unknowns. Use [test-assumptions](test-assumptions.md) only when a consequential assumption needs investigation.
 
-Not "good / medium / bad." Not three speeds of the same plan (Conservative / Pragmatic / Ambitious of one architecture). Three approaches that differ in **structure** - rearrange the same surviving parts.
+Alternatives should differ materially in architecture, operating model, scope, cost, or reversibility. Do not label the same plan good / medium / bad or manufacture an unsafe option to favor your recommendation.
 
 Each option must be one the FDE would genuinely recommend under different circumstances. If you cannot defend an option, replace it - padding is visible.
 
 For each option, name:
 - which surviving blocks it is built from
-- which CONVENTION it refuses to obey
+- which constraint or convention it changes, if any
 - its single biggest point of failure
 - any new building block, labelled as a new assumption (`UNKNOWN` in `assumptions.md`) - do not smuggle one in as a fact
 
-If all three are the same system at different risk levels, you wrote the playbook. Start over.
+If only one viable path remains, explain what ruled out the alternatives and what evidence could reopen them.
 
 **3. Structure each option identically.** Same dimensions, same format - so comparison is instant:
 
 ```markdown
 ### Option A: <name>
 - **Blocks:** <which surviving assumptions / parts it is built from>
-- **Convention refused:** <the "we just…" it will not obey>
+- **Constraint changed:** <constraint or convention changed, if any>
 - **What:** <the approach in one paragraph>
 - **Timeline:** <estimate with basis>
 - **Cost:** <effort, infrastructure, external>
@@ -40,19 +42,11 @@ If all three are the same system at different risk levels, you wrote the playboo
 - **Best when:** <the condition that makes this the right choice>
 ```
 
-**4. Add the comparison matrix.** Visually scannable:
-
-| Dimension | Option A | Option B | Option C |
-|-----------|----------|----------|----------|
-| Timeline | 6 weeks | 4 weeks | 3 weeks |
-| Risk | Low | Medium | High |
-| Reversibility | Easy rollback | Partial rollback | Difficult to reverse |
-| Team impact | Minimal | Moderate retraining | Significant ramp-up |
-| Long-term cost | Highest (tech debt) | Moderate | Lowest |
+**4. Make comparison easy.** Use consistent dimensions: expected outcome, evidence, build and operating cost, time with estimate basis, reversibility, owner, and the most consequential uncertainty. A compact table helps when alternatives need comparison; do not fill it with invented numbers or label one path universally cheapest.
 
-**5. State your recommendation - and why.** The options are objective; the recommendation is your professional judgment:
+**5. State your recommendation - and why.** Separate supplied facts and estimates from your judgment:
 
-> "I recommend Option B. The timeline pressure makes the conservative approach too slow, but the system fragility (see terrain.md hotspots) makes the ambitious approach reckier than the reward justifies. Option B gets us to pilot in 4 weeks with a tested rollback."
+> "I recommend Option B. The limited team availability rules out a full rewrite this quarter, and the current hotspot makes keeping the job unchanged costly. Option B gets us to pilot in 4 weeks with a tested rollback."
 
 **6. Handle the override gracefully.** If the sponsor picks a different option:
 
@@ -66,9 +60,9 @@ If all three are the same system at different risk levels, you wrote the playboo
 ```markdown
 ## Decision: <name> - <date>
 Decided by: <who>
-Options presented: A (<name>), B (<name>), C (<name>)
+Options presented: <viable alternatives>
 Recommended: B - <one line why>
-Chosen: <A/B/C> by <who>
+Chosen: <option or pending> by <actual decision-maker or unknown>
 Trade-off accepted: <what the choice gives up>
 ```
 
@@ -76,22 +70,20 @@ The full option details in the same entry or linked to a section in `reality.md`
 
 ## Checkpoint
 
-Present the three options and the recommendation. One question to the FDE: "Which option matches what the sponsor can hear right now?" (A risk-averse sponsor after an incident → conservative. A founder pre-fundraise → ambitious.) If unsure: present all three and let the sponsor decide.
+Present the viable alternatives, recommendation, and the evidence or constraint that would change it. Reuse known decision authority; if a decision remains pending, record it as pending.
 
 ## Worked example
 
-Acme: the reconciliation job needs to survive the FDE leaving. Priya asks "so what should we do?"
-
-Three real paths, not a strawman set. **Safe:** keep the job, add the rota and runbook - two weeks, no new failure modes, does nothing about the 47-commits/90d hotspot. **Pragmatic:** extract the settlement-matching step behind a tested interface - six weeks, retires the untested hotspot, needs Raj's time and he currently opposes it. **Aggressive:** rewrite the service - a quarter, fixes everything, and the same team already abandoned this once.
+Fictional example: a support team needs completed requests written back to its service system. Its product can export a file today. A supported connector is expected in six weeks; the customer wants automation in two. A custom API adapter looks feasible, but nobody has accepted its maintenance.
 
-Same dimensions on each, so comparison is instant, and every cost carries a source: the six-week figure is churn-based, not felt.
+Two defensible paths remain. Continue the approved export while checking the supported connector's fit, or investigate a bounded adapter whose delivery depends on a named owner and tested API behavior. The export is a bridge within the first path, not a third option invented for the slide. Compare manual effort, engineering effort, ongoing support, and the effect of waiting. Time released is capacity unless spending actually falls.
 
-Recommendation: pragmatic, conditional - *if* Raj is on the design, otherwise safe, because the aggressive path failed here before for exactly the reason it would fail again. `decisions.md` records the decision, who chose it, and the condition, so week 10's "why aren't we rewriting it" has an answer with a date on it.
+Recommend the bridge while resolving native fit and the value of earlier automation. Reconsider the adapter if that value justifies full costs and an owner accepts it. `decisions.md` (or a standalone decision note) records the recommendation, evidence, unknowns, and pending decision. It does not claim that a sponsor chose it or that the adapter can meet the date.
 
 ## Principles
 
-- Three options, never one. One option is a request for trust; three is a real decision.
-- Assemble from surviving blocks. Three speeds of the same plan is the playbook - start over.
+- Compare defensible alternatives; the number follows the evidence.
+- Build from known facts and label new assumptions. Material differences make the comparison useful.
 - Each option must be genuinely defensible - no straw men.
 - Same structure for each option. Comparison should take 30 seconds.
 - Recommend one. State why. Accept the override gracefully.

package/skills/fde/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-build/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: fde-build
+description: Implement a scoped customer-facing software change in the existing repository and verify its behavior. Use for delivery work with an understood outcome, not incident response.
+---
+
+# fde-build
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Implement a scoped customer-facing software change in the existing repository and verify its behavior. Use for delivery work with an understood outcome, not incident response.
+
+Read [the task context contract](references/task-context.md), then [the method](references/build.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.