fdeops 4.1.1 → 5.1.0

package/skills/rollback/references/rollback.md

@@ -0,0 +1,102 @@
+# rollback - Rehearse rollback
+
+**Enter when:** a deploy is planned for the next 48 hours, the FDE says "we can always revert," a previous rollback failed or took too long, or the engagement involves regulated/critical systems.
+
+**Read first:** `delivery.md` (the deployment record), `terrain.md`, `trust-profile.md` (for change-approval requirements), `context.md`.
+
+"We can always revert" is the most dangerous sentence in deployment. A rollback plan that hasn't been tested is a wish, not a plan. The drill proves the escape route works before you need it at 2am.
+
+## Method (you do this work)
+
+**1. Map the rollback path for every change type:**
+
+| Change type | Rollback method | Complication | Test |
+|-------------|----------------|--------------|------|
+| **Code deploy** | Revert the PR / redeploy previous version | Feature flags, cache invalidation | Deploy previous version to staging, verify function |
+| **Database migration** | Compatible rollback, restore, or roll-forward | Irreversible transforms, concurrent writes, old/new schema compatibility | Rehearse on representative staging data; verify integrity, elapsed time, and possible data loss |
+| **Config change** | Restore previous config | Propagation delay, dependent service restarts | Flip config, verify all services pick it up |
+| **Infrastructure** | Terraform/Pulumi rollback or manual | State drift, dependent resources | Plan the rollback, review the diff |
+| **Data backfill** | Restore from backup or reverse script | Mixed old/new data states | Run reverse on a 100-row sample |
+
+**2. Identify the irreversible components.** Some changes can't be rolled back:
+
+- Column drops after data migration
+- Encryption key rotations after old key is destroyed
+- External API version deprecations
+- Emails/notifications already sent
+- Published API changes consumed by third parties
+
+For each irreversible component: **what's the compensating action?** Not "undo" but "what do we do to recover the same effect?"
+
+**3. Run the drill.** On staging or a test environment - never on production:
+
+```
+DRILL PROTOCOL:
+1. Deploy the change (confirm it works)
+2. Start a timer
+3. Execute the documented rollback procedure - exactly as written, no shortcuts
+4. Measure: time to complete, services affected, data state after
+5. Verify: can users still do the critical path?
+6. Record: what worked, what was unclear, what failed
+```
+
+**4. The drill report.** Honest, specific, actionable:
+
+```markdown
+## Rollback drill - <date>
+Change: <what was deployed>
+Environment: staging
+Rollback method: <what was executed>
+Time to rollback: <minutes:seconds>
+Result: PASS / FAIL / PARTIAL
+
+What worked:
+- Code revert completed in 45s
+- Feature flag disabled correctly
+
+What didn't:
+- Database down migration left orphan rows in junction table
+- Cache took 3 minutes to invalidate (stale data served)
+
+Actions before production deploy:
+- [ ] Fix down migration to clean junction table
+- [ ] Add cache-bust step to rollback procedure
+- [ ] Verify cache invalidation time is acceptable
+```
+
+**5. The "acceptable rollback time" conversation.** With the FDE and the team:
+
+> "If this deploy fails in production, how long can the system be in a degraded state before it's a business problem?"
+
+| Answer | Implication |
+|--------|-------------|
+| "Minutes" | Automated rollback trigger needed - human decision loop is too slow |
+| "An hour" | Manual rollback is acceptable if the procedure is tested and documented |
+| "A day" | Gradual rollback is fine - feature flag off, monitor, clean up next morning |
+| "It can't fail" | Blue/green deployment with instant traffic switch - test both environments |
+
+**6. Change-approval environments (CAB).** In regulated industries:
+
+- The rollback procedure is part of the change ticket - filed before the approval window.
+- The drill evidence goes with the change request: "Rollback tested on <date>, completed in <time>, no issues."
+- A drill that fails → the change ticket isn't ready. Better to discover that now than during the CAB.
+
+## Artifact
+
+**`delivery.md`** - the drill report, attached to the deployment record for this change. The evidence that the rollback works.
+
+**`risks.md`** - any irreversible components identified, with the compensating action.
+
+**`decisions.md`** - if the drill failed and the deployment is delayed: what failed, the fix, the revised timeline.
+
+## Checkpoint
+
+One statement: "Rollback tested on staging. Time: <N minutes>. Result: <pass/fail>. Production deploy is / is not ready." If not ready: the specific blocker and when it'll be resolved.
+
+## Principles
+
+- A rollback plan that hasn't been tested is a wish.
+- Time the drill and account for differences in production scale and operating conditions; do not assume a fixed multiplier.
+- Identify the irreversible components and name the compensating action.
+- The drill report is evidence for the change ticket and the team's confidence.
+- A drill that fails is a success - you found the problem before production did.

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

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

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

@@ -0,0 +1,11 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "5488cddb607cb05face73ad1a838dd87babb00716544793f36997ca15dcb1560",
+    "references/close.md": "095266722624e4bc647628243c8be0e69b02017ef6b4e3a7e7790ec1f53ab7c0",
+    "references/encode-pattern.md": "3be7bf9d0f69af31659423c54d6023a4af1556e2ce200fb025bf64d0757de4d8",
+    "references/runbook.md": "1233aa1943da8db6d3c7624b7a54b3a1afc340b97e16f95d70b42cdbf521b63c",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/runbook/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: runbook
+description: Write an operating runbook from the delivered system and verified procedures. Use when the customer team or a successor needs to operate without the original engineer.
+---
+
+# runbook
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Write an operating runbook from the delivered system and verified procedures. Use when the customer team or a successor needs to operate without the original engineer.
+
+Read [the task context contract](references/task-context.md), then [the method](references/runbook.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/runbook/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:** for standalone work, use the supplied permitted operating notes, evidence and ownership; no engagement binding or CLI command is required. For a bound engagement, use bounded `fde handoff` or `fde resume`, then targeted `fde recall` for missing evidence. Never initialize records merely to draft a handoff. Build the picture through relevant excerpts, not a full-directory load. Consult `terrain.md` only for 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/runbook/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/runbook/references/runbook.md

@@ -0,0 +1,73 @@
+# runbook - Write an operating guide
+
+**Enter when:** the team needs instructions to operate, diagnose or recover a system, or an engineer is preparing to transfer responsibility.
+
+Apply [task context](task-context.md). Use supplied operational facts, relevant code and verified procedures. For a bound engagement, retrieve relevant sanitized delivery, dependency and ownership evidence; do not load the full customer record or raw private material.
+
+## Match the request
+
+- **Draft a guide:** write what is known, mark unverified procedures and missing evidence, and return the requested document. No customer record, live access, drill or closure ceremony is required.
+- **Verify an operating guide:** agree the permitted environment and checks, exercise relevant procedures, and record what happened. Do not run a destructive or production drill from a documentation request alone.
+- **Complete a handoff:** use [handoff](close.md) for the wider ownership and acceptance decision. A written guide is one part of that decision, not proof of readiness.
+
+## Build the guide from evidence
+
+Identify the system, the intended reader and the decisions that reader can make. Follow the actual operating path and include only relevant sections:
+
+```markdown
+# Operating guide - <system>
+Status: Draft / Verified for <environment and scope>
+Evidence: <code, observed run, operator statement or existing document>
+Operating owner: <confirmed role/person and source, or proposed/unconfirmed>
+
+## Normal operation
+What should happen, how often, and how to check it.
+
+## Known failure modes
+Symptom: <what the operator sees>
+Evidence: <what establishes this behavior>
+Cause: <verified cause or explicit unknown>
+Action: <supported steps, constraints and stop conditions>
+Validation: <tested environment/date/result, or unverified>
+Escalation: <confirmed role/channel, or missing>
+
+## Deploy and recover
+Procedure: <verified commands or a source link; do not invent commands>
+Permissions and prerequisites: <required access and safety conditions>
+Check: <expected observable result>
+Recovery: <tested procedure or the missing recovery evidence>
+
+## Monitor and escalate
+Signal: <existing alert or check>
+Meaning: <known interpretation>
+Response: <authorized action and when to escalate>
+
+## Open readiness gaps
+Missing evidence, owner to confirm, and proposed next check.
+```
+
+Do not pad the document with an arbitrary number of failures, contacts or commands. A stated retry problem without a known cause should remain an investigation item, not become a fabricated repair procedure. A suggested owner is not an accepted operating responsibility.
+
+For AI components, include relevant model and configuration versions, evaluation checks, failure limits and the supported way to pause actions. Do not assume retraining or autonomous operation is required.
+
+## Verify when requested
+
+Select checks based on the system's actual consequences. For example, the receiving operator may demonstrate normal operation, diagnose a known failure, or recover a failed release in a permitted test environment.
+
+Record each critical capability separately as verified, failed or untested, with evidence. A successful walkthrough cannot compensate for an untested recovery path. Avoid an averaged confidence score that hides a critical gap.
+
+If a procedure fails, correct the guide or system within scope and repeat the affected check. If verification is unavailable, deliver the draft with its limits and propose the next check; do not claim the handoff complete or indefinitely extend the engagement yourself.
+
+## Deliver and retain ownership boundaries
+
+Return the guide, its verification status and any remaining operating decisions. Save it to the requested location. In a bound engagement, propose updates to `handoff.md` and relevant current-state records under their confirmation rules.
+
+Access changes, exports of customer records, sponsor messages and closure decisions require their own authorization. A request for a runbook does not authorize these actions. Transfer only the material the recipient is entitled to receive.
+
+## Principles
+
+- Write for the person handling the actual failure.
+- Supported procedures beat plausible commands.
+- Draft, tested procedure and accepted ownership remain distinct.
+- Verify critical capabilities individually.
+- Keep private relationship notes and credentials out of an operating guide.

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

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

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

@@ -0,0 +1,9 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "13640b029f34068b08f2b0532ad7d2bae2d1063eeff17ec85a840bfbf832311e",
+    "references/hold-scope.md": "42b3823f6b49b87b432f81208b0a61115f22340f6a922a4e858012e908c6643d",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/{fde-scope → scope}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: fde-scope
+name: scope
 description: Assess a new customer request against agreed scope, trade-offs and ownership. Use when an engagement expands or a custom feature needs a commitment decision.
 ---
 
-# fde-scope
+# scope
 
 <!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
 

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

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

package/skills/score-use-cases/.fde-generated.json

@@ -0,0 +1,10 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "d201fe1d784eea04ce25bde63fb3e6beb129ac4924b8f654b7c4fd5b3022f2d1",
+    "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
+    "references/score-use-cases.md": "bb304cf2de26a2df0b9f2a299e3a6b2760ebce15b8b523d9cb4a584cc26038f8",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/score-use-cases/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: score-use-cases
+description: Compare competing customer use cases by value, feasibility and evidence. Use when several problems compete for delivery capacity.
+---
+
+# score-use-cases
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Compare competing customer use cases by value, feasibility and evidence. Use when several problems compete for delivery capacity.
+
+Read [the task context contract](references/task-context.md), then [the method](references/score-use-cases.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/score-use-cases/references/business-case.md

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