fdeops 5.0.0 → 5.1.1

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

@@ -3,7 +3,7 @@
   "version": 1,
   "files": {
     "SKILL.md": "13640b029f34068b08f2b0532ad7d2bae2d1063eeff17ec85a840bfbf832311e",
-    "references/hold-scope.md": "42b3823f6b49b87b432f81208b0a61115f22340f6a922a4e858012e908c6643d",
-    "references/task-context.md": "8ec90708522e512a50a57ab2a377a7472e93bae169c6f075a93fa603ce2ad780"
+    "references/hold-scope.md": "7779188df1d7f5aef9f878719499f9c0e974deba45289329ae8fa3d62e6c5090",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
   }
 }

package/skills/scope/references/hold-scope.md

@@ -6,51 +6,52 @@
 
 **Read first:** `success.md` (the agreed boundary), `decisions.md`, `context.md`. Load `stakeholders.md` to know who's asking and their signal.
 
-Scope creep is the leading cause of FDE engagement failure - not technical complexity, not timeline pressure. It's silent: no single request feels unreasonable, but twenty reasonable requests add three months. The skill is saying "that's phase two" without the customer hearing "no."
+Small requests can accumulate into material changes to cost, timing or acceptance. Compare the request with the actual agreement before classifying it; an adjacent request may already be in scope, and a clarification is not automatically an addition.
 
 ## Method (you do this work)
 
-**1. Detect before it compounds.** Three patterns that signal creep before it's named:
+**1. Detect before it compounds.** Patterns worth checking against the agreement:
 
-| Pattern | What it sounds like | What's actually happening |
+| Pattern | What it sounds like | What to check |
 |---------|--------------------|--------------------------|
-| **The friendly addition** | "While you're in there, could you also…" | Adjacent work getting absorbed without timeline adjustment |
-| **The evolved requirement** | "Oh, what I actually meant was…" | The original scope was never clear enough - `success.md` needs updating |
-| **The stakeholder swap** | A new person starts requesting features the original sponsor didn't | Power shifted; the real scope is being rewritten informally |
+| **The friendly addition** | "While you're in there, could you also…" | Whether the work is already covered and what it changes |
+| **The evolved requirement** | "Oh, what I actually meant was…" | Whether this clarifies existing acceptance or proposes a change |
+| **The stakeholder swap** | A new person starts requesting features the original sponsor didn't | The requester's authority and whether the request changes the agreed outcome |
 
-**2. The scope receipt.** Every request gets logged with its origin and cost - not as bureaucracy, but as evidence for the conversation that's coming:
+**2. The scope receipt.** Record consequential proposed changes and cumulative impact in the existing task or engagement record. Routine clarifications within confirmed scope can share a concise update; do not add a separate ceremony for each request. Distinguish estimates from measured effort and proposals from decisions:
 
 ```markdown
 ## Scope change - <date>
 Requested by: <who>
 Request: <what, in their words>
-Impact: <hours/days added, what gets pushed>
-Status: absorbed / deferred to phase 2 / needs conversation
+Impact: <estimate with assumptions, or unknown; affected work/risk/acceptance>
+Authority: <applicable agreement/decision source or unknown>
+Status: proposed / confirmed in scope / agreed change / deferred / declined / disputed
 ```
 
-Log via `fde log decision "scope change: <summary> - requested by <who>, impact: <estimate>"` or direct append to `decisions.md`.
+Show consequential judgments and uncertainties for confirmation before saving unless already explicitly confirmed. Use the existing task or `decisions.md` workflow; label an unapproved request as proposed rather than logging it as an agreed scope change.
 
-**3. The three-bucket response.** Never say "no" - say "here's where it fits":
+**3. Recommend a disposition.** Explain the fit and tradeoffs; use the relevant authority for any change:
 
 | Bucket | What you say | When to use |
 |--------|-------------|-------------|
-| **This phase** | "That fits - I'll add it to the current plan. Timeline stays the same." | The request is small and genuinely within the agreed scope |
-| **Next phase** | "That's real - let me capture it properly so it doesn't get lost. It's phase-two work because <reason>." | The request is valid but adds to the timeline |
-| **Separate engagement** | "That's a different problem - it deserves its own brief and its own timeline." | The request is a new project wearing a small-ask costume |
+| **This phase** | "That is covered by the current agreement. Here is its impact on the plan." | The request is within confirmed scope and authority; do not promise unchanged timing without evidence |
+| **Next phase** | "This adds <impact>. I recommend deferring it or agreeing a tradeoff." | The request changes current commitments; a future phase is proposed, not promised |
+| **Separate engagement** | "That's a different problem - it deserves its own brief and its own timeline." | The request requires a materially different outcome, access or commercial agreement |
 
-**The key phrase: "Let me place it."** Not "that's out of scope" (adversarial) or "sure" (absorbed). "Let me place it" signals you're taking it seriously while buying time to assess the real cost.
+Decline a request clearly when it conflicts with policy or the applicable authority rejects it. No wording can substitute for a real scope decision.
 
 **4. The accumulation conversation.** When the scope receipts show a pattern - a material cumulative impact on delivery, cost, risk, or acceptance - the FDE needs a conversation with the sponsor:
 
 Frame it as **protection, not complaint:**
 > "We've absorbed five changes since the original agreement. Each one made sense individually. Together, they've added roughly two weeks. I want to make sure the timeline expectation still matches - should we adjust the delivery date, or reprioritise to keep the original date?"
 
-Evidence-based: point to `decisions.md` scope receipts with dates and requesters. The sponsor who sees the pattern is an ally; the sponsor who discovers the delay at the end is a problem.
+Evidence-based: point to `decisions.md` scope receipts with dates and requesters. Use the actual scope decision-maker; sponsorship alone does not establish delegated authority.
 
 **5. The commercial boundary.** In paid engagements, scope creep silently moves billing and liability:
 
 - If the engagement is time-and-materials: scope creep is the client's money, but flag it - they deserve to know what they're buying.
-- If the engagement is fixed-price: every absorbed scope change is a gift the FDE's company didn't agree to. Surface it to whoever owns the commercials.
+- If the engagement is fixed-price: check the change terms and contingency; material changes may affect margin or commitments. Surface the evidence to whoever owns the commercials.
 - If the engagement has a success fee: scope changes that move the success criteria affect compensation. Log it.
 
 ## Artifact
@@ -69,15 +70,15 @@ Acme, week 5. Nothing has been formally added, and the slice is a week late.
 
 The pattern shows in three requests: a "quick" finance CSV export (Jun 20, half a day, from Denise directly), retry-logic cleanup asked for mid-build (Jun 24, one day, Tom), and a dashboard tile "while you're in there" (Jun 27, half a day). Each sounds reasonable; their cumulative estimates explain part of the slip and need a scope decision.
 
-Three-bucket response, applied while the requests can still be placed: the CSV export fits this phase only with an accepted trade (it displaces the runbook polish), the retry cleanup goes to the kill list in `decisions.md` with the what-breaks reason, and the tile is absorbed because it is genuinely twenty minutes - logged anyway, since an unlogged absorption is the one that gets forgotten in the accumulation conversation.
+Three-bucket response, applied while the requests can still be placed: the CSV export fits this phase only with an accepted trade (it displaces the runbook polish), the retry cleanup goes to the kill list in `decisions.md` with the what-breaks reason, and the tile is absorbed because it is genuinely twenty minutes - included in the existing progress receipt so cumulative impact remains visible.
 
-That conversation happens with Priya when the added work threatens the date, with the receipts on screen: "here are the asks, their estimated impact, and what moved." Not a complaint - a decision she gets to make, with evidence, before the deadline makes it for her.
+That conversation happens with Priya when the added work threatens the date, with the receipts on screen: "here are the asks, their estimated impact, and what moved." Confirm Priya holds the relevant scope authority before treating her response as agreement.
 
 ## Principles
 
-- "Let me place it" is the phrase. Not "no," not "sure."
-- Every scope change gets a receipt. The receipt is the evidence.
+- Compare requests with the agreement before classifying them.
+- Record consequential changes with their source, authority and status; batch routine work.
 - Escalate material impact, not an arbitrary count of requests.
-- Scope creep kills engagements that technical failure couldn't.
-- `success.md` is a contract - update it explicitly or defend it.
-- The FDE who absorbs everything is liked for three weeks and blamed for three months.
+- Missing boundaries do not grant permission to expand scope.
+- `success.md` records agreed scope; it does not replace the governing agreement.
+- Make tradeoffs visible without inventing motives, approval or future commitments.

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

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

package/skills/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.