fdeops 5.0.0 → 5.1.1

package/skills/what-breaks/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: what-breaks
+description: Assess the impact of a proposed change on dependencies and shared infrastructure. Use before touching unfamiliar or consequential systems.
+---
+
+# what-breaks
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Assess the impact of a proposed change on dependencies and shared infrastructure. Use before touching unfamiliar or consequential systems.
+
+Read [the task context contract](references/task-context.md), then [the method](references/what-breaks.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/what-breaks/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/what-breaks/references/what-breaks.md

@@ -0,0 +1,91 @@
+# what-breaks - Assess impact
+
+**Enter when:** about to make a change on a system you don't fully understand, touching a high-churn module from `terrain.md`, modifying shared infrastructure (auth, database, messaging), or the FDE asks "what could go wrong?"
+
+**Read first:** `terrain.md`, `decisions.md`, `trust-profile.md` (for sacred systems), `context.md`.
+
+On your own codebase, you know what breaks. On someone else's, you discover it in production. Blast-radius analysis is the discipline of mapping the damage before making the change - not after.
+
+## Method (you do this work)
+
+**1. Trace the dependency chain.** For the file/module/system you're about to change, answer:
+
+| Question | How to find it |
+|----------|---------------|
+| Who calls this? | `grep -rn "function_name\|module_name" --include="*.ts" --include="*.py" .` |
+| Who does this call? | Read the imports and external calls in the module |
+| What data flows through? | Trace inputs to outputs - especially user data and money |
+| What breaks if this returns differently? | Check every caller's assumptions about the return value |
+| What breaks if this is slow? | Timeouts, queues, user-facing latency |
+| What breaks if this is down? | Circuit breakers? Fallbacks? Or cascade failure? |
+
+**2. Classify the blast radius:**
+
+```
+CONTAINED  → Only the module you're changing is affected
+             Rollback: revert the PR
+             Example: changing a utility function with no external callers
+
+ADJACENT   → 2-5 callers or one downstream system affected
+             Rollback: revert the PR + verify downstream
+             Example: changing an API response format used by the frontend
+
+SYSTEMIC   → Multiple systems, shared infrastructure, or data integrity
+             Rollback: may require data migration or coordinated rollback
+             Example: changing the auth token format, modifying a shared database schema
+
+IRREVERSIBLE → Cannot be rolled back without data loss or manual intervention
+               Example: data migration, dropping a column, changing encryption keys
+```
+
+**3. The what-breaks declaration.** Before writing any code, state it explicitly in `decisions.md`:
+
+```markdown
+## Blast radius: <change name>
+Classification: ADJACENT
+Affected: payment-service, billing-dashboard, reconciliation-job
+Data impact: none (read-only change to response format)
+Rollback: revert PR; frontend falls back to previous format handler
+Monitoring: error rate on /api/payments endpoint, billing dashboard load time
+Time to detect: <5 minutes via error rate alert
+```
+
+**4. Match the change to the blast radius:**
+
+| Blast radius | Required before merge |
+|-------------|----------------------|
+| CONTAINED | Unit tests + self-review |
+| ADJACENT | Unit + integration tests + team review + monitoring plan |
+| SYSTEMIC | Full test suite + team review + staged rollout + incident playbook |
+| IRREVERSIBLE | All of the above + sponsor approval + tested rollback of the rollback + go/no-go checkpoint |
+
+**5. The invisible integration.** The most dangerous blast radius is the one you can't see in the code:
+
+- A webhook endpoint that an external system calls - not in your repo's imports
+- A cron job that reads the table you're modifying - runs at midnight, fails silently
+- A reporting pipeline that depends on the exact column format
+- An monitoring alert that triggers on a metric your change affects
+
+**Ask the team:** "Is anything outside this repo reading from or writing to <the thing you're changing>?" The answer is almost always "yes, and here's one we forgot about."
+
+**6. The 2am test.** For any SYSTEMIC or IRREVERSIBLE change, ask: "If this fails at 2am on Saturday, who gets woken up, what do they see, and what can they do?" If the answer is "they see nothing until Monday" - the monitoring plan needs work before the change ships.
+
+## Artifact
+
+**`decisions.md`** - the what-breaks declaration, filed before the change starts. Updated if the blast radius grew during implementation.
+
+**`risks.md`** - new risks discovered during the trace (the invisible integrations, the midnight cron job).
+
+**`terrain.md`** - update if the dependency trace revealed connections the map didn't know about.
+
+## Checkpoint
+
+Before merge: blast radius declared and still accurate, monitoring in place for the affected scope, rollback tested (not just planned). If the blast radius grew during implementation: re-classify, update the declaration, adjust the review/rollout requirements.
+
+## Principles
+
+- Declare the blast radius before writing code, not after.
+- The invisible integration is always there. Ask the team.
+- Match the process to the blast radius - contained gets speed, systemic gets ceremony.
+- "We can always revert" is not a rollback plan. Test the rollback.
+- If the 2am failure is invisible until Monday, the monitoring isn't ready.

package/skills/who-decides/.fde-generated.json

@@ -0,0 +1,9 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "33a822a1e10824461543e296f93e07ed3f8e2eab7a719bcde4bb3bbef597859c",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490",
+    "references/who-decides.md": "fa1f65d921943e76f42284570004a603488905417d96b4bd52dc6c4a11dd5a97"
+  }
+}

package/skills/who-decides/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: who-decides
+description: Map stakeholders, decision rights, influence and blockers from supplied evidence. Use when ownership is unclear or the stakeholder landscape changes.
+---
+
+# who-decides
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Map stakeholders, decision rights, influence and blockers from supplied evidence. Use when ownership is unclear or the stakeholder landscape changes.
+
+Read [the task context contract](references/task-context.md), then [the method](references/who-decides.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/who-decides/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/who-decides/references/who-decides.md

@@ -0,0 +1,63 @@
+# who-decides - Map decision rights
+
+**Enter when:** a consequential decision has unclear authority, ownership is disputed, stakeholders change, or observed communication changes affect the next action.
+
+**Read first:** apply [task context](task-context.md), then permitted `stakeholders.md` and `context.md` evidence. Retrieve relevant trust constraints only when access or disclosure is involved.
+
+Titles, influence and responsiveness can help you find the right conversation. They do not establish approval authority or explain someone's motives.
+
+## Method (you do this work)
+
+**1. Resolve the decisions in front of you.** Reuse the customer's existing agreement, delegation or decision process. For each relevant decision, identify who or what can decide, the scope of that right, its source, and whether it is confirmed, proposed, disputed or unknown. Distinguish budget/scope approval, data/AI-policy approval, release authority, customer acceptance, and operating/recovery responsibility when they differ. Do not require separate people or a full matrix for a routine decision already covered by confirmed authority.
+
+A sponsor naming an operating team is a proposal until that team accepts responsibility. If accounts conflict, record both attributed positions and the unresolved decision; ask the applicable authority to resolve it. Do not choose an owner from seniority, authorship, repository access or silence. Continue authorized work that does not depend on the disputed right.
+
+**2. Understand participation.** Identify the sponsor, people helping the work, access/process owners, people raising concerns, and required participants not yet consulted. One person may fill several roles; none must exist merely to complete a taxonomy. Capture their stated concerns and useful knowledge. Opposition may identify a real defect or unaccepted obligation. Being absent does not prove hidden authority or disengagement.
+
+**3. Track observable changes.** Compare communication and decisions with the agreed cadence and the person's usual pattern. A delayed reply, shortened meeting or new participant may merit a check; holidays, workload, delegation and scheduling are alternative explanations to escalation. Record the observation separately from any hypothesis. Use green/amber/red only when supported by attributed evidence and its effect on the work; do not derive motives or authority from a color.
+
+Choose follow-up timing from the decision deadline and potential impact. An imminent release with a missing owner warrants prompt resolution; an ordinary delayed reply does not have an automatic 48-hour escalation clock. Offer a neutral question such as “Has anything changed in the decision or timing we should account for?” Messages and outreach still require authorization.
+
+**4. Learn from the existing team.** Ask what they tried, what constraints remain and what they expect to own. Use established terminology and credit actual contributions. Do not assume the team was passed over, resents outside help, or knows every cause. Verify consequential technical claims through the relevant evidence.
+
+**5. Prepare the decision conversation.** For a decision involving several parties, identify unresolved questions, relevant decision rights and needed evidence. Address dependencies in a useful order through existing channels. Record stated objections faithfully; label any possible motivation as an unverified hypothesis only when it matters to the next action. A short pre-mortem can ask “What missing evidence or unresolved responsibility could prevent this decision?” It must not invent an opponent or predict agreement.
+
+**6. Keep identities consistent.** Use one confirmed spelling per person across the table and contact records. `fde doctor` can flag possible identity clusters; verify that they are the same person before consolidating. Do not erase historical evidence to tidy the display.
+
+## Artifact
+
+Return the relevant decision rights directly, or update the existing `stakeholders.md` under the confirmed record rules. Link an existing authoritative record instead of duplicating its full contents.
+
+```markdown
+| Decision / responsibility | Person or mechanism | Scope | Source | Status / next action |
+|---------------------------|---------------------|-------|--------|----------------------|
+| <relevant decision> | <confirmed person/mechanism or unknown> | <system, environment, limit> | <actual agreement/policy/reference> | <confirmed / proposed / disputed / unknown; next step> |
+```
+
+Keep a compact participation/signal table where it helps:
+
+```markdown
+| Who | Role | Signal | Last evidence | Notes |
+|-----|------|--------|---------------|-------|
+| <name> | <observed role> | <supported signal or unknown> | <source and date> | <stated concern / unresolved question> |
+```
+
+Preserve the existing `## Signal history` section and its dated `[signal:...]` entries. CLI status, receipts and dashboard read that history; changing the display table alone does not update those signals. Use the existing confirmed contact/debrief workflow for signal changes. Never delete or overwrite history while refreshing the tables.
+
+## Checkpoint
+
+State the decision that can proceed under confirmed authority and any dependent action still blocked by an unknown or disputed right. Include material observed changes and the next evidence or conversation needed. If nothing relevant changed, reuse the map; no calendar interval alone requires a new review.
+
+## Worked example
+
+A sponsor requests release on Thursday and names Platform as operator. The Platform lead says the team has not accepted on-call responsibility. The sponsor's slower replies and a new finance participant are observed, but their cause is unknown.
+
+Return the map as a draft; when bound and confirmed, save it in `stakeholders.md` and the next action in `context.md`. Record the sponsor's request and Platform's objection with their sources. Existing policy confirms who approves production releases; it does not establish that Platform accepted recovery duties. The release authority row cites that policy; the operating responsibility row remains disputed. Acceptance and data-policy rights are checked only to the extent required by this change, reusing existing evidence. Prepare verification and the release receipt while the responsible parties resolve coverage. Do not infer escalation, assign Platform by title, or turn the sponsor's deadline into deployment permission.
+
+## Principles
+
+- Resolve scoped authority from evidence; influence is not delegation.
+- Separate observed behavior, stated concerns and possible explanations.
+- Ownership requires applicable agreement, not an unchallenged name in a table.
+- Reuse confirmed decisions and scale follow-up to impact.
+- Preserve attributed history and unknowns; never fabricate agreement.