fdeops 5.0.0 → 5.1.1

package/skills/plan/references/plan.md

@@ -0,0 +1,167 @@
+# plan - Sequence the work
+
+**Context:** apply [task context and evidence](task-context.md). Standalone planning evaluates supplied facts directly; it does not require initialized engagement records.
+
+**Enter when:** scope is understood and the work needs breaking down - a slice, a phase, or the whole delivery.
+
+**Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if poc produced one. Not the full folder.
+
+**On an initialized engagement, before a new delivery plan or material scope change:** run `fde doctor --ready`. For standalone planning, check the supplied outcome, scope, acceptance and authority directly; do not initialize records to run this validator. Missing acceptance criteria or authority blocks the affected implementation commitment, not a provisional plan. Draft proposed checks and next steps, mark them pending, and ask only what changes the next action. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
+
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before planning, state what you're working from in 2-3 lines:
+
+> "Planning against: [success definition from success.md]. Scope boundary: [out-of-scope items]. Reality check: [brief aligns with reality.md / or note the delta]."
+
+Then check - probe ONLY if it prevents a bad plan:
+
+1. **Success is measurable.** If "done" is vague ("make it better") → rephrase it: "I'm reading success as: [specific measurable outcome]. That the target?"
+2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Here is the proposed adjustment; it remains unagreed until confirmed."
+3. **Out-of-scope exists.** If missing → one line: "I will keep this draft within the supplied request and mark proposed exclusions for confirmation."
+
+State your read, let the FDE correct, then plan.
+
+An FDE plan is not a sprint backlog. The technical sequence is the easy part. The hard part is when to show progress, who approves the next phase, and where trust is thin enough that two silent weeks read as failure. A technically correct plan that ignores engagement politics fails on schedule.
+
+## Method (you do this work)
+
+**0. Lock scope first.** Read `success.md`, `assumptions.md`, and the **Question** on `reality.md`. Make the boundary explicit using the supplied request; ask if an ambiguity changes the commitment. Investigate a critical open assumption before planning work that depends on it. If the problem itself is unclear, use discovery for that gap; absent filenames do not block a plan supported by supplied facts.
+
+**Reuse check.** Before sequencing a build, compare the requested solution with the smallest existing capability or operating change that could satisfy the same acceptance test. Cite the relevant repo/config/workaround evidence. Record why reuse is sufficient or insufficient in `decisions.md`; include “no new code” when supported. A request for AI does not establish that a model is needed. If a host engineering pack already has an approved implementation plan, reference it from `decisions.md`; do not generate a parallel user-story backlog.
+
+**1. Work backwards from success.** What's the last thing that must be true before done? And before that? That's the dependency chain - not a wish list.
+
+**2. Front-load the fragile.** Check `terrain.md` hotspots. Risky modules go early - fail fast, not in week three.
+
+**3. One user action per change.** Each task delivers something visible and testable ("user submits form, sees it saved"), never a layer ("build the database layer"). See `ship`.
+
+**4. Size to a coherent, verifiable outcome.** Split unrelated work and tasks too complex to review or recover safely. Use bounded review sections for large cohesive changes; elapsed time and line count are signals to examine, not universal limits.
+
+**5. AI components get explicit eval tasks.** "Output validated on 50 real production examples," "fallback tested under model unavailability," "inputs/outputs logging to <destination>" - these are pre-conditions of shipping, in the plan before build starts.
+
+**6. Stakeholder touchpoints every 2-3 tasks.** "Show progress to <name from stakeholders.md>." Not ceremony: a customer who sees small wins stays bought in; silence gets filled with doubt.
+
+**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Keep **Now** small enough to review and act on; split by independently verifiable outcomes.
+
+**Acceptance criteria gate:** no task moves to build without written happy-path AND unhappy-path criteria. Can't write them = the task isn't understood; the open question goes to the customer **before** the task starts. Vague criteria surface later as scope creep and rework.
+
+## Artifact
+
+For standalone planning, return the requested draft or save to the authorized project document. In a bound engagement, propose the plan for **`decisions.md`** under its confirmation rules, or link the existing approved plan; do not duplicate it.
+
+A plan is **not done** until all four blocks exist:
+
+```markdown
+## Plan - <date>
+### Now
+Task N: <outcome, not activity>
+Delivers: <what someone can see/test>
+Accepts: <happy path> / <unhappy path>
+Touches: <files/systems - blast radius declared upfront>
+Risk: <what could go wrong + fallback>
+Kill if: <the observation that voids this slice - copy from assumptions.md How we test, or the check that means stop>
+Verify: <specific check>
+Value promised: <business unit change this slice claims>
+Baseline: <value + source/date/window/environment, or pending + measurement owner>
+Acceptance owner: <name + authority source, or unknown - ask: who can accept?>
+Evidence to collect: <before/after check, sample/window, environment, and receipt location>
+Reuse: <existing capability used, or evidence it cannot satisfy the criteria>
+
+### Next
+- ...
+
+### Later
+- ...
+
+### Kill list (explicitly not this phase)
+| Item | Why killed / deferred | Who accepted |
+|------|----------------------|--------------|
+| <rewrite / nice-to-have / political ask> | <evidence> | <name, date> |
+```
+
+In `Who accepted`, distinguish a proposed deferral from an agreement: use `pending` until a named person accepted this scope with a dated source. Sponsorship alone is not approval of every plan detail.
+
+No kill list → not a finished plan. Reopen with the FDE until the deferrals are written.
+## Checkpoint
+
+Walk the FDE through: sequence + why this order, where the fragile work sits, where the touchpoints land, the acceptance gate and **Kill if** on task 1, and the kill list. One question: "Which stakeholder sees the first visible slice, and when?" Second: "Who accepted what we are not doing?" Third: "What observation stops task 1 this week?"
+
+## Method - estimation (when the sponsor asks "how long, how much?")
+
+Every FDE gets asked this in week one. The honest answer is a range, not a number. A single-point estimate is a promise; a range is a professional assessment.
+
+**The 3-point method:**
+1. **Best case** - everything goes right, no surprises, team has capacity. This is what the sponsor wants to hear.
+2. **Expected case** - normal friction: one discovery changes the plan, one integration takes longer, one approval cycle stalls. This is what to plan against.
+3. **Worst case** - a major unknown surfaces, a dependency fails, a key person is unavailable. This is what to protect against.
+
+**Present as:** "2-4 weeks expected, could stretch to 6 if [named risk]." Never give one number.
+
+**The sizing table:**
+
+| Slice | Complexity | Dependencies | Unknowns | Estimate (expected) |
+|-------|-----------|--------------|----------|---------------------|
+| _per vertical slice from the plan_ | Low/Med/High | Named | Named | X days/weeks |
+
+**Rules:**
+- Estimate in weeks for engagements > 1 month. Days for < 1 month.
+- Add 30% buffer for integration work (it always takes longer).
+- Add 50% buffer for AI/ML work (eval cycles are unpredictable).
+- Name assumptions explicitly: "assumes API docs are accurate", "assumes staging environment exists."
+- Each named assumption needs a **kill observation**: the result that voids the estimate. Copy it from `assumptions.md` → How we test. No kill observation = it is not an assumption, it is hope.
+- Revisit estimates every 2 weeks. An estimate that never updates is fiction.
+
+Write estimates to `decisions.md` under `## Sizing`. Include the assumptions - when they break, the estimate changes and the FDE has evidence for the conversation.
+
+## Method - migration strategy (when the engagement is "move from X to Y")
+
+Migrations are the most common enterprise FDE engagement. The strategy precedes the plan:
+
+**Step 1: Classify the migration type.**
+
+| Type | What it means | Risk profile |
+|------|---------------|-------------|
+| **Rehost** (lift-and-shift) | Same code, different infrastructure | Low code risk, high ops risk |
+| **Replatform** | Minor code changes to use new platform features | Medium risk, clear scope |
+| **Refactor** | Rewrite components to fit the new architecture | High risk, scope creep magnet |
+| **Replace** | Buy/build new, retire old | Highest risk, requires parallel running |
+| **Retire** | Turn off, nobody uses it | Politically hard, technically easy |
+
+**Step 2: Map the dependency graph.** What calls what. What breaks if this moves first. The migration order is the reverse of the dependency chain - leaf nodes first, core last.
+
+**Step 3: Define the cutover strategy.**
+- **Big bang** - everything moves at once. Fast but catastrophic on failure. Only for small systems.
+- **Strangler fig** - new traffic to new system, old traffic drains. Safe but slow. Preferred for anything load-bearing.
+- **Parallel run** - both systems run, outputs compared. Expensive but safest for data-critical systems.
+
+**Step 4: Write the rollback before the migration starts.** "If we move service X and it fails, we route back to old within [time]." No rollback = no migration.
+
+**Step 5: Define success metrics per phase.** Not "migration complete" - that's a project plan. "Error rate same or lower, latency within 10%, zero data loss, team can operate without FDE." Measurable, per service.
+
+Write migration strategy to `decisions.md` under `## Migration`. Each service gets a row: type, order, cutover method, rollback, success metric.
+
+## When the plan changes mid-engagement
+
+Never quietly update tasks. Name the reset: update `reality.md` and `success.md`, one paragraph in `decisions.md` - what changed, why, new sequence. An undocumented reset looks like drift; a documented one looks like the FDE caught something important.
+
+## Worked example
+
+Acme, after discover: the reconciliation job is unowned, Marco's spreadsheet is the real fallback.
+
+**Now** is three tasks, not eight. Task 1 is *failures reach a named human* - delivers a page to a rota, accepts "kill the job mid-run → the on-call is paged within 15 min", touches the job wrapper and the alert config, rollback is re-disable the route, **Kill if:** a real failure page is acked by nobody on the rota (the *finance would act* assumption, DISPROVED if Marco is the only name that answers), verify by killing it in staging. Value promised: `risk-mitigation - a silent failure becomes a 15-minute one`.
+
+The kill list in `decisions.md` is where the plan earns its keep: the rewrite of the reconciliation service that Tom keeps proposing goes there - *deferred, the failure mode is ownership not architecture (Priya accepted, Jun 12)* - along with the finance dashboard finance asked for directly. Both stay visible so the same argument is not re-litigated in week 4 without a receipt.
+
+First visible slice goes to Marco, not Priya: he is the one whose morning changes, and his confirmation is what makes the sponsor update true.
+
+## Principles
+
+- Plan from success backwards, not from today forwards.
+- Fragile zones early. Fail fast.
+- Every 2-3 tasks, a stakeholder touchpoint. Trust decays without visibility.
+- No written acceptance criteria, no build.
+- No kill list, no finished plan.
+- No **Kill if** on a Now PR, that PR is hope.
+- Estimates are ranges, not promises. Name the assumptions and the observation that voids them.
+- Migrations: leaf nodes first, core last. Rollback before cutover.

package/skills/plan/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/poc/.fde-generated.json

@@ -4,18 +4,18 @@
   "files": {
     "SKILL.md": "bceae7ba11c006b3d1e93e330a80cc58eeef55d863cc374653eef8fd124c3056",
     "references/audit.md": "ed32ea78cbccb100742dd838e8cf4cd4b6f33ad44b3de7424fc624670d571dbc",
-    "references/build.md": "3dfeed619eeb1c8401f5cdf65e6f803fb209c70cb464dac4e60a1c890fd3a6f7",
+    "references/build.md": "6fa07b15b682119de53c38950f94942a58e4680ab58b24319d77c54a27cd9697",
     "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/discover.md": "f65aa11a539b4dbbed70cfaa94ec2a35595aa9a2d0282790510b933ac9c721ce",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
-    "references/integrate.md": "107a50bddf6cb0ba7f2bc006dfe9851800c6868e43f785a33ae4b737aeb74c95",
-    "references/plan.md": "a096831ea7afdde1fe954541ad854a99d2d118c1abbf8826f2332e695a802ae1",
+    "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
+    "references/plan.md": "a86e42f4c35897d48e863b7b00e287c14fe835fc034b729bacadc0401fe4ff45",
     "references/poc.md": "818dc90c2d401819735233ab9d69df171675d75abf8644c403dab7dd1dcf9199",
     "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
-    "references/task-context.md": "8ec90708522e512a50a57ab2a377a7472e93bae169c6f075a93fa603ce2ad780",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490",
     "references/test-assumptions.md": "bf60d8bb4c0701fcffb196d78f7f6c8b1c472fc877fb2caf41058fbf8e2415a1",
     "references/three-options.md": "168fab9fb8ac8de85b0d1fa58e1db17deaa244cdef8c99623a04a0a6c70fe52c",
     "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"

package/skills/poc/references/build.md

@@ -6,7 +6,7 @@ Use the permitted context and authority in [task context](task-context.md). This
 
 ## Method
 
-1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches.
+1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
 4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.

package/skills/poc/references/integrate.md

@@ -6,13 +6,23 @@ Start from [task context](task-context.md). Permitted supplied context is enough
 
 ## Method
 
-1. Map producer, consumer, owner, direction, and side effects. Inspect the actual installed version and local implementation; verify uncertain behavior against current official documentation. Identify the relevant schema, authentication scopes, network boundary, and permitted test environment.
+1. Map producer, consumer, owner, direction, and side effects. Inspect the actual installed version and local implementation; verify uncertain behavior against current official documentation. Identify the relevant schema, authentication scopes, network boundary, and permitted test environment. Before changing an untested existing boundary, characterize the mappings, ordering or other observable behavior its callers depend on.
 2. Write the acceptance example: an input at the real boundary and the observable downstream result. Include a rejection or failure example. Separate configuration validity, successful authentication, transport connectivity, contract compatibility, and end-to-end behavior; none proves the next.
 3. Inspect credentials by presence and required scope without printing values. Use existing secret storage. Check data classification and retention before moving data; never pass raw `<private>` blocks into a model. Prefer sanitized or synthetic cases approved for the target environment.
-4. Implement the narrow adapter using native repository patterns. Validate external inputs and model outputs, bound timeouts and retries, preserve error context without leaking payloads, and handle cancellation. For writes, establish idempotency or duplicate detection before retries; for events, check ordering, replay, and poison messages as applicable.
+4. Implement the narrow adapter using native repository patterns. Validate external inputs and model outputs, bound timeouts and retries, preserve error codes and failure phase without leaking payloads, and handle cancellation. Keep explicit authentication or permission rejections distinguishable from transport uncertainty. For writes, establish idempotency or duplicate detection before retries and apply the uncertain-write rules below when outcomes can be ambiguous; for events, check ordering, replay, and poison messages as applicable.
 5. Exercise a permitted success case and relevant failures: denied access, malformed data, rate limit, timeout, duplicate delivery, or partial completion. Trace correlation IDs or safe evidence across both sides. A mock proves client behavior only; if live access is unavailable, report that gap instead of claiming an integration works.
 6. Check cleanup and recovery for test side effects. Use [verification](verification.md) for receipts and [review](review.md) for security or data-contract changes. Route deployment through [ship](ship.md) only when authorized.
 
+## When a write outcome is uncertain
+
+Use the existing storage and worker mechanisms; do not introduce a new platform for these rules.
+
+- Before a replayable write, persist its tenant-scoped operation identity and payload identity, with enough state to recover after restart. Establish who owns an in-flight attempt so concurrent workers cannot independently replay it. Establish whether upstream deduplication is guaranteed, including its key, payload rules and retention window; sending a key alone proves nothing.
+- A timeout, cancellation or lost response after dispatch may leave a completed side effect. Preserve that uncertainty across restart; stopping the caller is not rollback. Do not silently turn an uncertain attempt into a fresh operation.
+- Reconcile against an authoritative receipt or lookup that matches the operation and payload. One verified result can confirm completion; conflicting or multiple matches require resolution. An empty stale, partial or eventually consistent lookup does not prove absence or authorize replay. Retry only under the verified deduplication contract or evidence establishing that repeating the write is safe.
+- Keep unresolved attempts visible with safe error context, a next action and a known resolution owner, or an explicit ownership gap. Manual resolution still needs authority for any corrective write; do not manufacture completion to clear a queue.
+- Test the relevant failure boundary: committed write with lost response, cancellation or restart before recording success, and stale lookup or concurrent replay where applicable. Record which were exercised and which remain unproven.
+
 ## Deliverable and acceptance
 
 Return the boundary contract, changed paths, environment, evidence at each tested layer, and remaining dependencies with owners when known. Done requires the agreed end-to-end result or an explicit narrower agreed scope. Do not silently replace live acceptance with a stub. In engagement mode, update the terrain/delivery record with confirmed facts; otherwise return the receipt directly.

package/skills/poc/references/plan.md

@@ -6,7 +6,7 @@
 
 **Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if poc produced one. Not the full folder.
 
-**On an initialized engagement, before a new delivery plan or material scope change:** run `fde doctor --ready`. For standalone planning, check the supplied outcome, scope, acceptance and authority directly; do not initialize records to run this validator. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
+**On an initialized engagement, before a new delivery plan or material scope change:** run `fde doctor --ready`. For standalone planning, check the supplied outcome, scope, acceptance and authority directly; do not initialize records to run this validator. Missing acceptance criteria or authority blocks the affected implementation commitment, not a provisional plan. Draft proposed checks and next steps, mark them pending, and ask only what changes the next action. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
 
 ## Validation gate (confirm understanding, clarify where it elevates)
 
@@ -17,8 +17,8 @@ Before planning, state what you're working from in 2-3 lines:
 Then check - probe ONLY if it prevents a bad plan:
 
 1. **Success is measurable.** If "done" is vague ("make it better") → rephrase it: "I'm reading success as: [specific measurable outcome]. That the target?"
-2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Planning against reality unless you say otherwise."
-3. **Out-of-scope exists.** If missing → one line: "Nothing's marked out-of-scope yet. That means every new request is implicitly in. Worth defining now or after the first plan draft?"
+2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Here is the proposed adjustment; it remains unagreed until confirmed."
+3. **Out-of-scope exists.** If missing → one line: "I will keep this draft within the supplied request and mark proposed exclusions for confirmation."
 
 State your read, let the FDE correct, then plan.
 
@@ -42,19 +42,19 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 
 **6. Stakeholder touchpoints every 2-3 tasks.** "Show progress to <name from stakeholders.md>." Not ceremony: a customer who sees small wins stays bought in; silence gets filled with doubt.
 
-**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Cap **Now** at 3 PRs (same discipline as pick-three).
+**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Keep **Now** small enough to review and act on; split by independently verifiable outcomes.
 
 **Acceptance criteria gate:** no task moves to build without written happy-path AND unhappy-path criteria. Can't write them = the task isn't understood; the open question goes to the customer **before** the task starts. Vague criteria surface later as scope creep and rework.
 
 ## Artifact
 
-The plan goes to **`decisions.md`** - always. Build reads the plan from `decisions.md`; anywhere else and the build starts blind.
+For standalone planning, return the requested draft or save to the authorized project document. In a bound engagement, propose the plan for **`decisions.md`** under its confirmation rules, or link the existing approved plan; do not duplicate it.
 
 A plan is **not done** until all four blocks exist:
 
 ```markdown
 ## Plan - <date>
-### Now (max 3)
+### Now
 Task N: <outcome, not activity>
 Delivers: <what someone can see/test>
 Accepts: <happy path> / <unhappy path>

package/skills/poc/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/prioritize/.fde-generated.json

@@ -0,0 +1,10 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "b58e4c788ad2c3e83d8266556023b4046bdc489d3050e3fcb414504825082210",
+    "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
+    "references/pick-three.md": "fa5a5f6db94c72c5a1c6419276d0f7c13ff3067ce075a074af020f736fe3fad8",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/prioritize/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: prioritize
+description: Choose up to three immediate priorities from competing initiatives. Use when everything is urgent and the customer needs a defensible order with explicit deferrals.
+---
+
+# prioritize
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Choose up to three immediate priorities from competing initiatives. Use when everything is urgent and the customer needs a defensible order with explicit deferrals.
+
+Read [the task context contract](references/task-context.md), then [the method](references/pick-three.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/prioritize/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.

package/skills/prioritize/references/pick-three.md

@@ -0,0 +1,95 @@
+# pick-three - Prioritize three
+
+**Enter when:** a transformation engagement with a long list of initiatives, the customer's roadmap has more items than weeks, competing teams want different things, or the FDE needs to recommend what to do *first* across a complex programme.
+
+**Read first:** `reality.md`, `success.md`, `stakeholders.md`, `context.md`. Load `business-case.md` if individual initiative cases exist.
+
+Every enterprise engagement generates more work than any timeline can hold. Triage is the discipline of saying "not now" to real work with real sponsors - and making it stick. Without it, the FDE drowns in parallel efforts and ships nothing well.
+
+## Method (you do this work)
+
+**1. Collect the full list.** From the customer's roadmap, from discovery, from stakeholder requests, from `decisions.md` scope receipts. No filtering yet - everything goes on the board:
+
+```markdown
+| # | Initiative | Requested by | Stated priority | Current status |
+|---|-----------|-------------|----------------|----------------|
+| 1 | Payment API rewrite | CTO | P1 | Blocked on schema decision |
+| 2 | Customer dashboard | Product | P1 | Design phase |
+| 3 | SOC2 compliance | CISO | P0 | Not started |
+| ... | ... | ... | ... | ... |
+```
+
+Notice: every stakeholder's initiative is P0 or P1. That's the problem this skill solves.
+
+**2. Apply the triage matrix.** Each initiative scores on three axes:
+
+| Axis | Question | Scale |
+|------|----------|-------|
+| **Impact** | If this ships, what changes for the business in 90 days? | 1 (marginal) → 5 (transformative) |
+| **Dependency** | How many other initiatives are blocked waiting for this? | 0 (standalone) → 5 (critical path for 3+ others) |
+| **Cost of delay** | What happens each week this doesn't ship? | 1 (nothing) → 5 (measurable loss or regulatory exposure) |
+
+**Triage score = Impact + Dependency + Cost of delay** (simple sum, 3-15 range).
+
+**3. Sort into three lanes:**
+
+| Lane | Score | Action |
+|------|-------|--------|
+| **Now** (max 3) | 11-15 | Active work this phase. FDE and team capacity allocated. |
+| **Next** (max 5) | 7-10 | Sequenced for the following phase. Dependencies tracked but not started. |
+| **Later** (unlimited) | 3-6 | Captured, not committed. Revisit at next triage. |
+
+**The cap matters.** "Now" has exactly 3 slots. Not 4, not "3 plus this small one." Discipline is the product.
+
+**4. Handle the political override.** When a powerful stakeholder pushes a low-scoring initiative into "Now":
+
+- Show the displacement: "Adding X to Now means Y drops to Next. Y is currently blocking Z and W."
+- Let them choose: "Which of the current three should Y replace?" Making the trade-off visible makes the conversation honest.
+- If they override without trading: log it. `decisions.md`: "Initiative X added to Now without displacement by <who>. Capacity impact: <what slows>."
+
+**5. Set the triage cadence.** Triage is not a one-time event:
+
+| Engagement type | Triage frequency | Trigger for emergency re-triage |
+|----------------|-----------------|-------------------------------|
+| Sprint (1-2 weeks) | Once, at plan | Crisis or sponsor change |
+| Standard (1-4 weeks) | Weekly | New P0 from sponsor |
+| Programme (months) | Bi-weekly | Quarterly review, team change, market shift |
+
+**6. Communicate the triage result.** The output is not just a priority list - it's a commitment:
+
+> "We're committing to these three initiatives this phase: [A, B, C]. Here's why, here's what they deliver, and here's what's explicitly deferred: [D, E, F, ...]. If priorities change, we re-triage - we don't add without removing."
+
+## Artifact
+
+**`decisions.md`** - the triage table with scores, lanes, **and an explicit Kill / Later commitment**. Dated. Updates the same Now/Next/Later plan already uses; do not open a second plan section. Referenced by plan and status.
+
+Required closing block (plan will not treat triage as done without it):
+
+```markdown
+## Triage - <date>
+### Now (max 3)
+| # | Initiative | Score | Why now |
+...
+### Next
+...
+### Kill / defer (not this phase)
+| Initiative | Why not now | Who accepted |
+|------------|-------------|--------------|
+| ... | ... | <name, date> |
+
+Commitment: we ship only Now. Additions require a removal.
+```
+
+**`reality.md`** - if triage revealed that the engagement scope is larger than the timeline supports, update the assessment.
+
+## Checkpoint
+
+Walk the FDE through: the 3 "Now" initiatives and why, the top "Next" items and what triggers their promotion, and the one initiative that will generate the most political pushback for being in "Later." Prepare the FDE for that conversation.
+
+## Principles
+
+- "Now" has 3 slots. Not 4. Discipline is the product.
+- Every addition requires a removal. Visible trade-offs beat invisible overload.
+- Triage is recurring, not one-time. The list changes; the discipline doesn't.
+- A logged override protects the FDE. An unlogged override blames them.
+- The initiative everyone wants but nobody will trade for is the one to watch.

package/skills/prioritize/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/qa/.fde-generated.json

@@ -3,14 +3,14 @@
   "version": 1,
   "files": {
     "SKILL.md": "65b965474e847f240138c1ada0ee7d982affc421a24a0a7a37970021f8269a03",
-    "references/build.md": "3dfeed619eeb1c8401f5cdf65e6f803fb209c70cb464dac4e60a1c890fd3a6f7",
+    "references/build.md": "6fa07b15b682119de53c38950f94942a58e4680ab58b24319d77c54a27cd9697",
     "references/debug.md": "c3bb344d38cc3552cb4e230c601a9be3fe173af2b2efb89aab6b7b04339f24f4",
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
-    "references/integrate.md": "107a50bddf6cb0ba7f2bc006dfe9851800c6868e43f785a33ae4b737aeb74c95",
+    "references/integrate.md": "d0de35a783902ca8b4762e3a42a14f467766d56a928c3a5cf11adac2a6ba90ba",
     "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
-    "references/task-context.md": "8ec90708522e512a50a57ab2a377a7472e93bae169c6f075a93fa603ce2ad780",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490",
     "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
   }
 }

package/skills/qa/references/build.md

@@ -6,7 +6,7 @@ Use the permitted context and authority in [task context](task-context.md). This
 
 ## Method
 
-1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches.
+1. Identify the repository, its instructions, working tree, relevant callers, and test commands. Inspect examples before creating abstractions. Preserve unrelated edits and state which dependencies or interfaces the change touches. Before changing an untested legacy path, capture the undocumented behavior callers depend on with targeted characterization checks; distinguish behavior to preserve from the intended change.
 2. State the observable outcome, constraints, and acceptance checks. Reuse agreed criteria for routine fixes. If a consequential product choice is unresolved, surface that choice while continuing independent investigation; do not invent acceptance.
 3. Choose the smallest coherent path that demonstrates the outcome through the real entry point. Include the necessary storage, error handling, and interface behavior in that slice. Name the failure that stops expansion and the recovery path for stateful changes.
 4. Implement using the repository's tools and conventions. Search for existing services, fixtures, and validation before adding alternatives. Keep cleanup limited to what makes the changed path understandable; do not expand scope to repair unrelated code.